Ограничения дженериков в TypeScript: extends и keyof T

Ограничение дженерика задаёт, каким может быть параметр типа. <T extends { length: number }> принимает только типы с числовым length (строки, массивы, ваши собственные объекты), и благодаря этому обещанию функции разрешено читать .length.

function longest<T extends { length: number }>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));        // apple
console.log(longest([1, 2, 3], [4]));        // [ 1, 2, 3 ]
console.log(longest({ length: 2, tag: "x" }, { length: 5, tag: "y" })); // { length: 5, tag: 'y' }

// @ts-expect-error: Argument of type 'number' is not assignable to parameter of type '{ length: number; }'.
longest(10, 20);

Возвращаемый тип по-прежнему T, а не { length: number }: если передать два массива чисел, вернётся number[], а объекты сохранят свой tag. Ограничение описывает минимум; тип вызывающего кода сохраняется.

Зачем нужны ограничения

Внутри обобщённой функции неограниченный T может быть чем угодно: строкой, числом, null, функцией. Поэтому TypeScript разрешает только то, что работает на любом типе, а это почти ничего.

// This does not compile: T could be number or undefined, which have no length.
function longest<T>(a: T, b: T): T {
  return a.length >= b.length ? a : b;
}

console.log(longest("apple", "fig"));

Компилятор выводит:

index.ts(3,12): error TS2339: Property 'length' does not exist on type 'T'.
index.ts(3,24): error TS2339: Property 'length' does not exist on type 'T'.

Исправление: сказать, что вам нужно, <T extends { length: number }>. Ограничения превращают «любой тип» в «любой тип, у которого есть это», а обычно обобщённая функция именно это и имеет в виду.

Ограничение интерфейсом

Ограничением может быть любой тип, включая уже существующий интерфейс или псевдоним типа. Функция тогда работает со всем, у чего есть как минимум эти члены, и по-прежнему возвращает полный тип вызывающего кода.

interface HasId {
  id: number;
}

function byId<T extends HasId>(items: T[], id: number): T | undefined {
  return items.find((item) => item.id === id);
}

function indexById<T extends HasId>(items: T[]): Map<number, T> {
  return new Map(items.map((item) => [item.id, item]));
}

const users = [
  { id: 1, name: "Ada", role: "admin" },
  { id: 2, name: "Grace", role: "editor" },
];

const found = byId(users, 2);
console.log(found?.name);              // Grace (found keeps name and role)
console.log(indexById(users).get(1));  // { id: 1, name: 'Ada', role: 'admin' }

Сравните с обычным типом параметра: function byId(items: HasId[], id: number): HasId | undefined принимает те же массивы, но результат будет только HasId, и found.name дал бы ошибку. Обобщённая версия пропускает полный тип насквозь.

K extends keyof T: безопасный доступ к свойствам

Самое частое ограничение связывает два параметра типа. K extends keyof T говорит, что K должен быть одним из имён свойств T, а T[K] это тип этого свойства.

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

function pluck<T, K extends keyof T>(items: T[], key: K): T[K][] {
  return items.map((item) => item[key]);
}

const book = { title: "Dune", year: 1965, tags: ["sci-fi"] };

const year = getProperty(book, "year");   // number
const title = getProperty(book, "title"); // string
console.log(year + 1, title.toUpperCase()); // 1966 DUNE

const books = [book, { title: "Emma", year: 1815, tags: [] }];
console.log(pluck(books, "year"));        // [ 1965, 1815 ]

// @ts-expect-error: Argument of type '"author"' is not assignable to parameter of type '"tags" | "title" | "year"'.
getProperty(book, "author");

Ключ с опечаткой или отсутствующий ключ даёт ошибку компиляции, а возвращаемый тип следует за ключом: "year" даёт number, "title" даёт string. Сам keyof, включая его поведение с индексными сигнатурами, описан на странице keyof.

Ограничение примитивами

Ограничением может быть примитив или их объединение. Полезный побочный эффект: когда T extends string (или number), TypeScript выводит литеральный тип аргумента, а не расширяет его.

function maxOf<T extends number | bigint>(values: T[]): T {
  return values.reduce((a, b) => (b > a ? b : a)); // < and > work on the constraint
}

function createEvent<T extends string>(name: T): { type: T } {
  return { type: name };
}

console.log(maxOf([3, 9, 4]));           // 9
console.log(maxOf([10n, 2n]));           // 10n

const evt = createEvent("user.saved");   // evt: { type: "user.saved" }
const same: "user.saved" = evt.type;     // the literal survived
console.log(same);                       // user.saved

Без ограничения createEvent("user.saved") возвращает { type: string }: здесь TypeScript расширяет выведенный для T литерал до string. С T extends string литерал сохраняется, и именно так типизированные помощники для событий и маршрутизации получают точные имена из обычных строковых аргументов.

Частые ошибки

Возврат того, что соответствует только ограничению. Функция, которая возвращает T, должна вернуть T, а не любое значение, подходящее под ограничение:

interface HasId {
  id: number;
}

function reset<T extends HasId>(item: T): T {
  return { id: item.id };
}
// error TS2322: Type '{ id: number; }' is not assignable to type 'T'.
//   '{ id: number; }' is assignable to the constraint of type 'T', but 'T' could be
//   instantiated with a different subtype of constraint 'HasId'.

Если T это { id: number; name: string }, у нового объекта нет name, поэтому он не является T. Верните развёрнутую копию входа, return { ...item, id: 0 };, которая сохраняет все свойства, или объявите возвращаемым типом HasId, если больше вы ничего не создаёте.

Аргумент типа, нарушающий ограничение. Явные аргументы типа тоже проверяются: при function scale<T extends number>(x: T) вызов scale<string>("2") падает с Type 'string' does not satisfy the constraint 'number'. (TS2344).

Ограничение там, где дженерик не нужен. Если T встречается только в параметре, function print<T extends HasId>(item: T): void это просто function print(item: HasId): void с лишним синтаксисом. Ограничения важны, когда T встречается ещё и в возвращаемом типе или в другом параметре.

Ограничения со значениями по умолчанию

У параметра типа может быть и ограничение, и значение по умолчанию. Значение по умолчанию должно удовлетворять ограничению.

interface Store<TState extends object = Record<string, unknown>> {
  get(): TState;
  set(next: Partial<TState>): void;
}

type AnyStore = Store;                              // Store<Record<string, unknown>>
type CounterStore = Store<{ count: number }>;       // fine
type BadStore = Store<number>;
// error TS2344: Type 'number' does not satisfy the constraint 'object'.

То же ключевое слово extends встречается и в условных типах, T extends string ? A : B, где это проверка, а не ограничение; эта форма описана на странице условные типы.