Génériques en TypeScript : fonctions, types et classes génériques

Les génériques sont des paramètres de type. Une fonction générique déclare un type d'emplacement, généralement appelé T, et chaque appel le remplit : les types qui entrent décident des types qui sortent. Une même fonction marche alors pour les nombres, les chaînes et vos propres objets, et chaque appel reste entièrement typé.

function first<T>(items: T[]): T | undefined {
  return items[0];
}

const n = first([10, 20, 30]);        // T = number, n: number | undefined
const s = first(["ada", "grace"]);    // T = string, s: string | undefined
const u = first([{ id: 1 }]);         // T = { id: number }

console.log(n?.toFixed(1));           // 10.0
console.log(s?.toUpperCase());        // ADA
console.log(u?.id);                   // 1

<T> après le nom de la fonction déclare le paramètre de type. items: T[] l'utilise pour l'entrée et T | undefined pour la sortie, ce qui relie les deux. Vous n'avez jamais écrit number ni string : TypeScript a inféré T à partir de l'argument.

Pourquoi pas any ou unknown ?

Sans génériques, vous typeriez le paramètre en any ou en unknown. Les deux acceptent tous les tableaux, et les deux perdent le lien entre l'entrée et la sortie :

function firstAny(items: any[]): any {
  return items[0];
}

function firstUnknown(items: unknown[]): unknown {
  return items[0];
}

function firstGeneric<T>(items: T[]): T | undefined {
  return items[0];
}

const a = firstAny(["x"]);
console.log(typeof a.toFixed);         // undefined: a.toFixed(2) would compile, then throw

const b = firstUnknown(["x"]);
// b.toUpperCase();                    // error TS18046: 'b' is of type 'unknown'.
console.log(typeof b === "string" ? b.toUpperCase() : "?"); // X (after narrowing)

const c = firstGeneric(["x"]);
console.log(c?.toUpperCase());         // X, with no narrowing needed

L'inférence des arguments de type

En général, TypeScript infère les arguments de type à partir des valeurs passées. Vous pouvez aussi les écrire explicitement entre chevrons à l'appel, ce qui est nécessaire quand rien dans les arguments ne mentionne T, ou quand l'inférence choisit quelque chose que vous ne vouliez pas.

function pair<T>(a: T, b: T): [T, T] {
  return [a, b];
}

function emptyList<T>(): T[] {
  return [];
}

const p1 = pair(1, 2);                      // T inferred as number
const p2 = pair<string | number>(1, "one"); // explicit: mixing allowed
const names = emptyList<string>();          // nothing to infer from, so pass it
names.push("Ada");

console.log(p1, p2, names); // [ 1, 2 ] [ 1, 'one' ] [ 'Ada' ]

Deux résultats d'inférence méritent d'être connus. pair(1, "one") sans argument explicite est une erreur : TypeScript infère T = number à partir du premier argument, puis signale Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). Et emptyList() sans aucun argument reçoit T = unknown, ce qui donne unknown[], rarement ce que vous voulez.

Plusieurs paramètres de type

Une fonction peut déclarer autant de paramètres de type que nécessaire, séparés par des virgules. Chacun est inféré indépendamment.

function zip<A, B>(left: A[], right: B[]): [A, B][] {
  const length = Math.min(left.length, right.length);
  const out: [A, B][] = [];
  for (let i = 0; i < length; i++) out.push([left[i], right[i]]);
  return out;
}

function mapValues<K extends string, V, R>(obj: Record<K, V>, fn: (value: V) => R): Record<K, R> {
  const out = {} as Record<K, R>;
  for (const key of Object.keys(obj) as K[]) out[key] = fn(obj[key]);
  return out;
}

console.log(zip(["a", "b", "c"], [1, 2]));        // [ [ 'a', 1 ], [ 'b', 2 ] ]
const prices = mapValues({ tea: 2.5, cake: 4 }, (v) => `$${v.toFixed(2)}`);
console.log(prices);                               // { tea: '$2.50', cake: '$4.00' }

mapValues infère trois choses à la fois : K vaut "tea" | "cake", V vaut number, et R vaut string d'après le retour du callback. K extends string est une contrainte, présentée à la page suivante.

Interfaces et alias de type génériques

Les types peuvent aussi prendre des paramètres. Vous écrivez alors l'argument quand vous utilisez le type : Box<number>, ApiResponse<User>. La plupart des types de collections intégrés fonctionnent ainsi : Array<T>, Map<K, V>, Promise<T>, Record<K, V>.

interface ApiResponse<T> {
  status: number;
  data: T;
}

type Result<T, E = string> =
  | { ok: true; value: T }
  | { ok: false; error: E };

interface User {
  id: number;
  name: string;
}

function parseAge(text: string): Result<number> {
  const n = Number(text);
  return Number.isInteger(n) && n >= 0 ? { ok: true, value: n } : { ok: false, error: `bad age: ${text}` };
}

const res: ApiResponse<User[]> = { status: 200, data: [{ id: 1, name: "Ada" }] };
console.log(res.data[0].name);   // Ada

for (const input of ["36", "abc"]) {
  const r = parseAge(input);
  console.log(r.ok ? r.value + 1 : r.error); // 37, then bad age: abc
}

Result<T, E = string> montre aussi un paramètre de type par défaut : Result<number> signifie Result<number, string>. Comme les paramètres de fonction optionnels, les paramètres avec valeur par défaut doivent venir après les obligatoires.

Classes génériques

Une classe prend ses paramètres de type après son nom, et chaque instance les fixe. Les champs, les méthodes et les paramètres du constructeur peuvent tous les utiliser.

class Stack<T> {
  private items: T[] = [];

  push(item: T): void {
    this.items.push(item);
  }

  pop(): T | undefined {
    return this.items.pop();
  }

  peek(): T | undefined {
    return this.items.at(-1);
  }

  get size(): number {
    return this.items.length;
  }
}

const visited = new Stack<string>();
visited.push("/home");
visited.push("/docs");
console.log(visited.pop(), visited.size); // /docs 1

const numbers = new Stack<number>();
numbers.push(42);
// numbers.push("42"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.
console.log(numbers.peek()); // 42

Si le constructeur prend un T, vous pouvez omettre l'argument explicite : new Box(5) infère Box<number>. Les membres statiques appartiennent à la classe elle-même, pas à une instance : ils ne peuvent donc pas utiliser le paramètre de type de la classe (Static members cannot reference class type parameters., TS2302).

Fonctions fléchées génériques et types de fonctions

La liste des paramètres de type se place avant la liste des paramètres. La même syntaxe décrit un type de fonction générique.

const last = <T>(items: T[]): T | undefined => items[items.length - 1];

type Mapper = <T, R>(items: T[], fn: (item: T) => R) => R[];
const mapAll: Mapper = (items, fn) => items.map(fn);

// In a .tsx file, <T> looks like a JSX tag. Add a trailing comma:
const lastTsx = <T,>(items: T[]) => items[items.length - 1];

Inférer des types littéraux avec les paramètres de type const

Par défaut, un générique infère des types élargis : pair("a", "b") donne [string, string]. Quand les valeurs exactes comptent (noms de routes, noms d'événements, listes de colonnes), marquez le paramètre const (TypeScript 5.0 et ultérieurs) et il infère comme si l'argument était écrit as const :

function defineColumns<const T extends readonly string[]>(columns: T): T {
  return columns;
}

const loose = ["id", "name"];                  // string[]
const columns = defineColumns(["id", "name"]); // readonly ["id", "name"]

type Column = (typeof columns)[number];        // "id" | "name"
const sortBy: Column = "name";
console.log(columns, sortBy, loose.length);    // [ 'id', 'name' ] name 2

L'appelant écrit un tableau ordinaire, et la fonction garde les types littéraux.

Quand ne pas utiliser les génériques

Un paramètre de type se justifie quand il relie deux choses : un paramètre et le type de retour, deux paramètres, ou un paramètre et un callback. Si T n'apparaît qu'une fois, il n'apporte rien et un type simple est plus clair.

// Pointless: T is used once, so it is just a longer way to write unknown
function logValue<T>(value: T): void {
  console.log(value);
}

// Clearer
function logValueSimple(value: unknown): void {
  console.log(value);
}

// Also pointless: returns T but nothing connects T to an argument,
// so the caller is really just asserting a type
function parseJson<T>(text: string): T {
  return JSON.parse(text);
}

Le dernier cas est courant et trompeur : parseJson<User>(text) a l'air sûr au niveau des types mais ne vérifie rien, exactement comme JSON.parse(text) as User. Renvoyez plutôt unknown et validez. Autres signes d'abus : un paramètre de type qui reçoit toujours le même argument, ou qu'on pourrait remplacer par une union de deux types connus.

Pour les génériques qui ont besoin de savoir quelque chose sur T (qu'il a une length, ou que K est une clé de T), les contraintes avec extends sont l'étape suivante.