TypeScript Generic Constraints: extends und keyof T

Ein Generic Constraint begrenzt, was ein Typparameter sein kann. <T extends { length: number }> akzeptiert nur Typen mit numerischem length (Strings, Arrays, deine eigenen Objekte), und dank dieses Versprechens darf die Funktion .length lesen.

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

Der Rückgabetyp ist weiterhin T, nicht { length: number }: Zwei Arrays von Zahlen ergeben wieder number[], und die Objekte behalten ihr tag. Der Constraint beschreibt das Minimum; der Typ des Aufrufers bleibt erhalten.

Warum Constraints nötig sind

In einer generischen Funktion könnte ein T ohne Constraint alles sein: ein String, eine Zahl, null, eine Funktion. Also erlaubt TypeScript nur, was mit jedem Typ funktioniert, und das ist fast nichts.

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

Der Compiler gibt aus:

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

Die Lösung ist, zu sagen, was du brauchst: <T extends { length: number }>. Constraints machen aus „jeder Typ“ „jeder Typ, der das hat“, und das meint eine generische Funktion meistens.

Auf ein Interface einschränken

Der Constraint kann jeder Typ sein, auch ein vorhandenes Interface oder ein Typalias. Die Funktion arbeitet dann mit allem, was mindestens diese Member hat, und gibt trotzdem den vollen Typ des Aufrufers zurück.

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

Vergleiche mit einem einfachen Parametertyp: function byId(items: HasId[], id: number): HasId | undefined akzeptiert dieselben Arrays, aber das Ergebnis ist nur HasId, also wäre found.name ein Fehler. Die generische Version reicht den vollen Typ durch.

K extends keyof T: sicherer Eigenschaftszugriff

Der häufigste Constraint verbindet zwei Typparameter. K extends keyof T sagt, dass K einer der Eigenschaftsnamen von T sein muss, und T[K] ist der Typ dieser Eigenschaft.

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

Ein falsch geschriebener oder fehlender Schlüssel ist ein Compilerfehler, und der Rückgabetyp folgt dem Schlüssel: "year" ergibt number, "title" ergibt string. Die Seite zu keyof behandelt keyof selbst, auch sein Verhalten bei Index-Signaturen.

Auf primitive Typen einschränken

Ein Constraint kann ein primitiver Typ oder eine Union davon sein. Ein nützlicher Nebeneffekt: Bei T extends string (oder number) leitet TypeScript den Literaltyp des Arguments ab, statt ihn zu erweitern.

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

Ohne den Constraint gibt createEvent("user.saved") { type: string } zurück: Hier erweitert TypeScript das für T abgeleitete Literal zu string. Mit T extends string bleibt das Literal erhalten, und so bekommen typisierte Helfer für Events und Routing genaue Namen aus einfachen String-Argumenten.

Häufige Fehler

Etwas zurückgeben, das nur zum Constraint passt. Eine Funktion, die T zurückgibt, muss ein T zurückgeben, nicht irgendeinen Wert, der zum Constraint passt:

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

Ist T gleich { id: number; name: string }, hat das neue Objekt kein name und ist daher kein T. Gib einen Spread der Eingabe zurück, return { ...item, id: 0 };, der jede Eigenschaft behält, oder deklariere den Rückgabetyp als HasId, wenn das alles ist, was du erzeugst.

Ein Typargument übergeben, das den Constraint verletzt. Auch ausdrückliche Typargumente werden geprüft: Bei function scale<T extends number>(x: T) scheitert der Aufruf scale<string>("2") mit Type 'string' does not satisfy the constraint 'number'. (TS2344).

Einschränken, wenn du gar kein Generic brauchst. Kommt T nur im Parameter vor, ist function print<T extends HasId>(item: T): void nichts anderes als function print(item: HasId): void mit zusätzlicher Syntax. Constraints zählen, wenn T auch im Rückgabetyp oder in einem anderen Parameter vorkommt.

Constraints mit Standardwerten

Ein Typparameter kann sowohl einen Constraint als auch einen Standardwert haben. Der Standardwert muss den Constraint erfüllen.

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

Dasselbe Schlüsselwort extends taucht auch in Conditional Types auf, T extends string ? A : B, wo es ein Test statt einer Einschränkung ist; die Seite zu Conditional Types behandelt diese Form.