Ograniczenia generyczne w TypeScript: extends i keyof T

Ograniczenie generyczne zawęża, czym może być parametr typu. <T extends { length: number }> przyjmuje tylko typy z liczbowym length (napisy, tablice, twoje własne obiekty), a dzięki tej obietnicy funkcja może odczytać .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);

Typem zwracanym jest nadal T, a nie { length: number }: przekazanie dwóch tablic liczb zwraca number[], a obiekty zachowują swoje tag. Ograniczenie opisuje minimum; typ wywołującego zostaje zachowany.

Po co są ograniczenia

Wewnątrz funkcji generycznej nieograniczone T może być czymkolwiek: napisem, liczbą, null, funkcją. TypeScript pozwala więc tylko na to, co działa dla każdego typu, czyli prawie na nic.

// 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"));

Kompilator wypisuje:

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'.

Rozwiązanie to powiedzieć, czego potrzebujesz: <T extends { length: number }>. Ograniczenia zamieniają „dowolny typ” w „dowolny typ, który ma to”, a zwykle właśnie to ma na myśli funkcja generyczna.

Ograniczenie do interfejsu

Ograniczeniem może być dowolny typ, także interfejs lub alias typu, który już masz. Funkcja działa wtedy ze wszystkim, co ma co najmniej te składowe, i nadal zwraca pełny typ wywołującego.

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' }

Porównaj ze zwykłym typem parametru: function byId(items: HasId[], id: number): HasId | undefined przyjmuje te same tablice, ale wynik ma tylko typ HasId, więc found.name byłoby błędem. Wersja generyczna przekazuje pełny typ dalej.

K extends keyof T: bezpieczny dostęp do właściwości

Najczęstsze ograniczenie wiąże dwa parametry typu. K extends keyof T mówi, że K musi być jedną z nazw właściwości T, a T[K] to typ tej właściwości.

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");

Literówka lub brakujący klucz to błąd kompilacji, a typ zwracany podąża za kluczem: "year" daje number, "title" daje string. Samo keyof, łącznie z jego zachowaniem przy sygnaturach indeksu, opisuje strona o keyof.

Ograniczenie do prymitywów

Ograniczeniem może być prymityw albo ich unia. Przydatny efekt uboczny: gdy T extends string (lub number), TypeScript wnioskuje literalny typ argumentu, zamiast go poszerzać.

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

Bez ograniczenia createEvent("user.saved") zwraca { type: string }: TypeScript poszerza wtedy literał wywnioskowany dla T do string. Z T extends string literał zostaje zachowany i w ten sposób otypowane helpery zdarzeń i routingu wyciągają dokładne nazwy ze zwykłych argumentów napisowych.

Typowe błędy

Zwracanie czegoś, co pasuje tylko do ograniczenia. Funkcja, która zwraca T, musi zwrócić T, a nie dowolną wartość pasującą do ograniczenia:

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'.

Jeśli T to { id: number; name: string }, nowy obiekt nie ma name, więc nie jest T. Zwróć rozwinięcie wejścia, return { ...item, id: 0 };, które zachowuje każdą właściwość, albo zadeklaruj typ zwracany jako HasId, jeśli tylko tyle tworzysz.

Przekazanie argumentu typu, który łamie ograniczenie. Jawne argumenty typu też są sprawdzane: przy function scale<T extends number>(x: T) wywołanie scale<string>("2") kończy się błędem Type 'string' does not satisfy the constraint 'number'. (TS2344).

Ograniczenie tam, gdzie generyk nie jest potrzebny. Jeśli T występuje tylko w parametrze, function print<T extends HasId>(item: T): void to po prostu function print(item: HasId): void z dodatkową składnią. Ograniczenia mają znaczenie, gdy T pojawia się też w typie zwracanym albo w innym parametrze.

Ograniczenia z wartościami domyślnymi

Parametr typu może mieć jednocześnie ograniczenie i wartość domyślną. Wartość domyślna musi spełniać ograniczenie.

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'.

To samo słowo kluczowe extends pojawia się też w conditional types, T extends string ? A : B, gdzie jest testem, a nie ograniczeniem; tę formę opisuje strona o conditional types.