Contraintes génériques en TypeScript : extends et keyof T

Une contrainte générique limite ce que peut être un paramètre de type. <T extends { length: number }> n'accepte que les types qui ont une length numérique (chaînes, tableaux, vos propres objets), et grâce à cette promesse, la fonction a le droit de lire .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);

Le type de retour reste T, et non { length: number } : passer deux tableaux de nombres renvoie un number[], et les objets gardent leur tag. La contrainte décrit le minimum ; le type de l'appelant est préservé.

Pourquoi les contraintes sont nécessaires

Dans une fonction générique, un T sans contrainte peut être n'importe quoi : une chaîne, un nombre, null, une fonction. TypeScript n'autorise donc que ce qui fonctionne sur tous les types, c'est-à-dire presque rien.

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

Le compilateur affiche :

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 correction consiste à dire ce dont vous avez besoin : <T extends { length: number }>. Les contraintes transforment « n'importe quel type » en « n'importe quel type qui a ceci », ce que veut dire en général une fonction générique.

Contraindre à une interface

La contrainte peut être n'importe quel type, y compris une interface ou un alias de type que vous avez déjà. La fonction fonctionne alors avec tout ce qui possède au moins ces membres, et renvoie toujours le type complet de l'appelant.

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

Comparez avec un simple type de paramètre : function byId(items: HasId[], id: number): HasId | undefined accepte les mêmes tableaux, mais le résultat n'est qu'un HasId, donc found.name serait une erreur. La version générique transmet le type complet.

K extends keyof T : un accès sûr aux propriétés

La contrainte la plus courante relie deux paramètres de type. K extends keyof T indique que K doit être l'un des noms de propriétés de T, et T[K] est le type de cette propriété.

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

Une clé mal orthographiée ou absente est une erreur de compilation, et le type de retour suit la clé : "year" donne number, "title" donne string. La page keyof présente keyof lui-même, y compris son comportement avec les signatures d'index.

Contraindre à des primitives

Une contrainte peut être une primitive ou une union de primitives. Un effet de bord utile : quand T extends string (ou number), TypeScript infère le type littéral de l'argument au lieu de l'élargir.

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

Sans la contrainte, createEvent("user.saved") renvoie { type: string } : ici, TypeScript élargit en string le littéral qu'il a inféré pour T. Avec T extends string, le littéral est conservé, et c'est ainsi que les helpers typés d'événements et de routage obtiennent des noms exacts à partir de simples arguments de type chaîne.

Erreurs fréquentes

Renvoyer quelque chose qui ne correspond qu'à la contrainte. Une fonction qui renvoie T doit renvoyer un T, et pas seulement une valeur qui respecte la contrainte :

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 est { id: number; name: string }, le nouvel objet n'a pas de name : ce n'est donc pas un T. Renvoyez un étalement de l'entrée, return { ...item, id: 0 };, qui garde toutes les propriétés, ou déclarez le type de retour HasId si c'est tout ce que vous produisez.

Passer un argument de type qui viole la contrainte. Les arguments de type explicites sont vérifiés eux aussi : avec function scale<T extends number>(x: T), l'appel scale<string>("2") échoue avec Type 'string' does not satisfy the constraint 'number'. (TS2344).

Contraindre alors qu'aucun générique n'est nécessaire. Si T n'apparaît que dans le paramètre, function print<T extends HasId>(item: T): void n'est que function print(item: HasId): void avec une syntaxe en plus. Les contraintes comptent quand T apparaît aussi dans le type de retour ou dans un autre paramètre.

Contraintes avec valeurs par défaut

Un paramètre de type peut avoir à la fois une contrainte et une valeur par défaut. La valeur par défaut doit respecter la contrainte.

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

Le même mot-clé extends apparaît aussi dans les types conditionnels, T extends string ? A : B, où c'est un test plutôt qu'une restriction ; la page types conditionnels présente cette forme.