Vincoli generici in TypeScript: extends e keyof T

Un vincolo generico limita ciò che un parametro di tipo può essere. <T extends { length: number }> accetta solo tipi che hanno un length numerico (stringhe, array, i tuoi oggetti), e grazie a questa promessa la funzione può leggere .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);

Il tipo di ritorno resta T, non { length: number }: passando due array di numeri ottieni number[], e gli oggetti conservano il loro tag. Il vincolo descrive il minimo; il tipo di chi chiama viene preservato.

Perché servono i vincoli

Dentro una funzione generica, un T senza vincoli potrebbe essere qualsiasi cosa: una stringa, un numero, null, una funzione. Quindi TypeScript permette solo ciò che funziona su ogni tipo, cioè quasi nulla.

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

Il compilatore stampa:

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

La soluzione è dire cosa ti serve: <T extends { length: number }>. I vincoli trasformano "qualsiasi tipo" in "qualsiasi tipo che abbia questo", che di solito è ciò che intende una funzione generica.

Vincolare a un'interfaccia

Il vincolo può essere qualsiasi tipo, anche un'interfaccia o un alias di tipo che hai già. La funzione lavora allora con qualunque cosa abbia almeno quei membri, e restituisce comunque il tipo completo di chi chiama.

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

Confrontalo con un normale tipo di parametro: function byId(items: HasId[], id: number): HasId | undefined accetta gli stessi array, ma il risultato è solo HasId, quindi found.name sarebbe un errore. La versione generica fa passare il tipo completo.

K extends keyof T: accesso sicuro alle proprietà

Il vincolo più comune mette in relazione due parametri di tipo. K extends keyof T dice che K deve essere uno dei nomi di proprietà di T, e T[K] è il tipo di quella proprietà.

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

Una chiave scritta male o inesistente è un errore di compilazione, e il tipo di ritorno segue la chiave: "year" dà number, "title" dà string. La pagina su keyof spiega keyof in sé, compreso il suo comportamento con le index signature.

Vincolare ai primitivi

Un vincolo può essere un primitivo o un'unione di primitivi. Un effetto collaterale utile: quando T extends string (o number), TypeScript deduce il tipo letterale dell'argomento invece di allargarlo.

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

Senza il vincolo, createEvent("user.saved") restituisce { type: string }: qui TypeScript allarga a string il letterale dedotto per T. Con T extends string il letterale viene mantenuto, ed è così che gli helper tipizzati per eventi e routing ottengono nomi esatti da semplici argomenti stringa.

Errori comuni

Restituire qualcosa che corrisponde solo al vincolo. Una funzione che restituisce T deve restituire un T, non un valore qualsiasi che rispetti il vincolo:

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

Se T è { id: number; name: string }, il nuovo oggetto non ha name, quindi non è un T. Restituisci uno spread dell'input, return { ...item, id: 0 };, che conserva tutte le proprietà, oppure dichiara HasId come tipo di ritorno se è tutto ciò che produci.

Passare un argomento di tipo che viola il vincolo. Anche gli argomenti di tipo espliciti vengono controllati: con function scale<T extends number>(x: T), la chiamata scale<string>("2") fallisce con Type 'string' does not satisfy the constraint 'number'. (TS2344).

Usare un vincolo quando non serve un generic. Se T compare solo nel parametro, function print<T extends HasId>(item: T): void è solo function print(item: HasId): void con sintassi in più. I vincoli contano quando T compare anche nel tipo di ritorno o in un altro parametro.

Vincoli con valori di default

Un parametro di tipo può avere sia un vincolo sia un default. Il default deve rispettare il vincolo.

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

La stessa parola chiave extends compare anche nei conditional types, T extends string ? A : B, dove è un test invece che una restrizione; la pagina sui conditional types spiega questa forma.