Restricciones genéricas en TypeScript: extends y keyof T

Una restricción genérica limita lo que puede ser un parámetro de tipo. <T extends { length: number }> solo acepta tipos que tengan un length numérico (strings, arrays, tus propios objetos), y gracias a esa promesa la función puede leer .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);

El tipo de retorno sigue siendo T, no { length: number }: si pasas dos arrays de números, recibes number[], y los objetos conservan su tag. La restricción describe el mínimo; el tipo de quien llama se conserva.

Por qué hacen falta las restricciones

Dentro de una función genérica, un T sin restricción podría ser cualquier cosa: un string, un número, null, una función. Así que TypeScript solo permite lo que funciona con todos los tipos, que es casi nada.

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

El compilador muestra:

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 solución es decir lo que necesitas: <T extends { length: number }>. Las restricciones convierten «cualquier tipo» en «cualquier tipo que tenga esto», que suele ser lo que quiere decir una función genérica.

Restringir a una interfaz

La restricción puede ser cualquier tipo, incluida una interfaz o un alias de tipo que ya tengas. La función funciona entonces con cualquier cosa que tenga al menos esos miembros, y sigue devolviendo el tipo completo de quien llama.

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

Compáralo con un tipo de parámetro normal: function byId(items: HasId[], id: number): HasId | undefined acepta los mismos arrays, pero el resultado es solo HasId, así que found.name sería un error. La versión genérica deja pasar el tipo completo.

K extends keyof T: acceso seguro a propiedades

La restricción más habitual relaciona dos parámetros de tipo. K extends keyof T dice que K debe ser uno de los nombres de propiedad de T, y T[K] es el tipo de esa propiedad.

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 clave mal escrita o que no existe es un error de compilación, y el tipo de retorno sigue a la clave: "year" da number, "title" da string. La página de keyof explica el propio keyof, incluido cómo se comporta con las firmas de índice.

Restringir a primitivos

Una restricción puede ser un primitivo o una unión de primitivos. Un efecto secundario útil: cuando T extends string (o number), TypeScript infiere el tipo literal del argumento en lugar de ensancharlo.

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

Sin la restricción, createEvent("user.saved") devuelve { type: string }: aquí TypeScript ensancha a string el literal que infirió para T. Con T extends string el literal se conserva, y así es como las funciones auxiliares tipadas de eventos y rutas obtienen nombres exactos a partir de argumentos string normales.

Errores habituales

Devolver algo que solo encaja con la restricción. Una función que devuelve T debe devolver un T, no cualquier valor que encaje con la restricción:

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

Si T es { id: number; name: string }, el objeto nuevo no tiene name, así que no es un T. Devuelve una expansión de la entrada, return { ...item, id: 0 };, que conserva todas las propiedades, o declara el tipo de retorno como HasId si eso es todo lo que produces.

Pasar un argumento de tipo que incumple la restricción. Los argumentos de tipo explícitos también se comprueban: con function scale<T extends number>(x: T), la llamada scale<string>("2") falla con Type 'string' does not satisfy the constraint 'number'. (TS2344).

Restringir cuando no hace falta un genérico. Si T solo aparece en el parámetro, function print<T extends HasId>(item: T): void es simplemente function print(item: HasId): void con sintaxis extra. Las restricciones importan cuando T también aparece en el tipo de retorno o en otro parámetro.

Restricciones con valores por defecto

Un parámetro de tipo puede tener a la vez una restricción y un valor por defecto. El valor por defecto debe cumplir la restricción.

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 misma palabra clave extends aparece también en los conditional types, T extends string ? A : B, donde es una prueba y no una restricción; la página de conditional types trata esa forma.