Generic-и в библиотеках: API, которые красиво выводятся (и те, что нет)

Цель: вызывающий пишет значения, компилятор пишет типы

Полярная звезда проектирования generic-API: вызывающий должен передавать обычные значения и получать точные типы без единого аргумента типа. Каждый <T>, который вызывающий вынужден написать, — провал дизайна: это тип, который API должен был вывести. Вывод происходит на местах вывода (inference sites): позиции в сигнатуре, где параметр типа стоит в типе параметра, позволяя компилятору считать его из аргумента.

// заставляет вызывающего указывать K — плохо
function getBad<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }
getBad<{ a: number }, "a">({ a: 1 }, "a"); // фу

// выводит оба из аргументов — хорошо
function get<T, K extends keyof T>(obj: T, key: K): T[K] { return obj[key]; }
get({ a: 1, b: "x" }, "b"); // ^? string  — T и K оба выведены, без аргументов типа

Та же сигнатура, но второе место вызова поставляет значения в оба места вывода (obj фиксирует T, key фиксирует K), так что руками писать нечего. Возврат T[K] тогда точен — string, а не ограничение «keyof-что-то».

Возвращайте точный тип, никогда не ограничение

Классическая утечка: ограничить параметр и затем вернуть ограничение вместо выведенного типа. Вызывающий теряет всю специфичность, которую передал.

// возвращает ограничение — вызывающий получает обратно широкий тип
function firstWide<T extends unknown[]>(arr: T): unknown { return arr[0]; }
const a = firstWide([1, 2, 3]); // ^? unknown  — специфичность выброшена

// возвращает точный тип элемента через вывод
function first<T>(arr: readonly T[]): T | undefined { return arr[0]; }
const b = first([1, 2, 3]); // ^? number | undefined

Фикс — сделать T типом элемента (чтобы он выводился точно), а не ограничивать T всем массивом и возвращать расширенный кусок. Возврат ограничения — самый частый способ, которым библиотека «теряет типы».

Ограничения + значения по умолчанию для эргономики

Что если нужен generic, который выводит основной параметр типа из аргумента, но при этом даёт продвинутым вызывающим явно переопределить второстепенный? Именно этот пробел закрывают ограничения и значения по умолчанию.

Ограничения (T extends ...) держат вызывающих честными и открывают доступ к членам внутри тела; значения по умолчанию (T = ...) делают параметр опциональным, когда вывод не может его поставить (например, объект конфига, который никогда не передают). Вместе они позволяют одной сигнатуре обслуживать частый случай без церемоний и продвинутый случай с явным переопределением:

function createStore<State, Action = { type: string }>(initial: State) {
  return { state: initial } as { state: State; dispatch: (a: Action) => void };
}
const s = createStore({ count: 0 }); // State выведен {count:number}, Action по умолчанию

NoInfer: заблокировать нежелательное место вывода

Иногда параметр типа появляется в двух позициях, и вы хотите, чтобы вывод управляла только одна. До 5.4 нужен был хак с пересечением; TS 5.4 добавил встроенный NoInfer<T>:

// без NoInfer: TS расширяет C из ОБОИХ — массива и значения по умолчанию,
// так что опечатка в default всё равно «работает» через расширение объединения
function pick<C extends string>(choices: C[], fallback: C): C { /* ... */ return fallback; }
pick(["a", "b"], "c"); // C выведен как "a" | "b" | "c" — баг "c" принят!

// с NoInfer: место вывода только `choices`; fallback обязан совпасть с ним
function pickSafe<C extends string>(choices: C[], fallback: NoInfer<C>): C { return fallback; }
pickSafe(["a", "b"], "c"); // Error: "c" is not assignable to "a" | "b"

NoInfer<C> говорит компилятору «не считывай C с этого аргумента» — так что C фиксируется одним лишь choices, а fallback проверяется против него, а не расширяет его. Это точный инструмент для «этот параметр обязан соответствовать типу, уже определённому в другом месте».

Builder’ы, накапливающие типы

Текучие builder’ы (паттерн за zod, роутером tRPC, query builder’ами) протягивают эволюционирующий тип через каждый звено-вызов, возвращая новый generic-экземпляр:

class Query<Cols extends string = never> {
  select<C extends string>(col: C): Query<Cols | C> { return this as any; }
  build(): Cols[] { return [] as Cols[]; }
}
const cols = new Query().select("id").select("name").build();
// ^? ("id" | "name")[]  — каждый .select расширял накопленное объединение Cols

Каждый select возвращает Query<Cols | C>, так что тип растёт вдоль цепочки, и build() сообщает ровно выбранные колонки. Так query builder знает форму строки результата и так роутер tRPC (урок 3) накапливает свою карту процедур — каждый вызов .procedure(...) добавляет к типу роутера.