TypeScript Generics: generische Funktionen, Typen und Klassen

Generics sind Typparameter. Eine generische Funktion deklariert einen Platzhaltertyp, meist T genannt, und jeder Aufruf füllt ihn, sodass die Typen, die hineingehen, die Typen bestimmen, die herauskommen. Eine einzige Funktion funktioniert dann für Zahlen, Strings und deine eigenen Objekte, und jeder Aufruf ist trotzdem vollständig typisiert.

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> hinter dem Funktionsnamen deklariert den Typparameter. items: T[] verwendet ihn für die Eingabe und T | undefined für die Ausgabe, was beide verbindet. Du hast nie number oder string geschrieben: TypeScript hat T aus dem Argument abgeleitet.

Warum nicht any oder unknown?

Ohne Generics würdest du den Parameter als any oder unknown typisieren. Beide akzeptieren jedes Array, und beide verlieren die Verbindung zwischen Eingabe und Ausgabe:

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

Inferenz von Typargumenten

Meist leitet TypeScript die Typargumente aus den übergebenen Werten ab. Du kannst sie beim Aufruf auch ausdrücklich in spitzen Klammern angeben; das ist nötig, wenn kein Argument T erwähnt oder wenn die Inferenz etwas wählt, das du nicht willst.

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

Zwei Ergebnisse der Inferenz solltest du kennen. pair(1, "one") ohne ausdrückliches Argument ist ein Fehler: TypeScript leitet T = number aus dem ersten Argument ab und meldet dann Argument of type 'string' is not assignable to parameter of type 'number'. (TS2345). Und emptyList() ganz ohne Argument bekommt T = unknown, also unknown[], was selten gewollt ist.

Mehrere Typparameter

Eine Funktion kann so viele Typparameter deklarieren, wie sie braucht, durch Kommas getrennt. Jeder wird unabhängig abgeleitet.

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 leitet drei Dinge auf einmal ab: K ist "tea" | "cake", V ist number, und R ist string aus der Rückgabe des Callbacks. K extends string ist ein Constraint, das auf der nächsten Seite behandelt wird.

Generische Interfaces und Typaliasse

Auch Typen können Parameter nehmen. Du schreibst dann das Argument, wenn du den Typ verwendest: Box<number>, ApiResponse<User>. Die meisten eingebauten Collection-Typen funktionieren so: 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> zeigt auch einen Standard-Typparameter: Result<number> bedeutet Result<number, string>. Wie optionale Funktionsparameter müssen Parameter mit Standardwert nach den Pflichtparametern stehen.

Generische Klassen

Eine Klasse nimmt Typparameter hinter ihrem Namen, und jede Instanz legt sie fest. Felder, Methoden und Konstruktorparameter können sie alle verwenden.

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

Nimmt der Konstruktor ein T, kannst du das ausdrückliche Argument weglassen: new Box(5) leitet Box<number> ab. Statische Member gehören zur Klasse selbst, nicht zu einer Instanz, daher können sie den Typparameter der Klasse nicht verwenden (Static members cannot reference class type parameters., TS2302).

Generische Arrow Functions und Funktionstypen

Die Liste der Typparameter steht vor der Parameterliste. Dieselbe Syntax beschreibt einen generischen Funktionstyp.

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

Literaltypen mit const-Typparametern ableiten

Standardmäßig leitet ein Generic erweiterte Typen ab: pair("a", "b") ergibt [string, string]. Wenn die genauen Werte zählen (Routennamen, Eventnamen, Spaltenlisten), markiere den Parameter als const (ab TypeScript 5.0), dann wird er so abgeleitet, als wäre das Argument mit as const geschrieben:

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

Der Aufrufer schreibt ein gewöhnliches Array, und die Funktion behält die Literaltypen.

Wann man Generics nicht verwendet

Ein Typparameter lohnt sich, wenn er zwei Dinge verbindet: einen Parameter und den Rückgabetyp, zwei Parameter oder einen Parameter und einen Callback. Kommt T nur einmal vor, bringt es nichts, und ein einfacher Typ ist klarer.

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

Der letzte Fall ist häufig und irreführend: parseJson<User>(text) sieht typsicher aus, prüft aber nichts, genau wie JSON.parse(text) as User. Gib stattdessen unknown zurück und validiere. Weitere Zeichen für übertriebenen Einsatz: ein Typparameter, der immer dasselbe Argument bekommt, oder einer, den eine Union aus zwei bekannten Typen ersetzen könnte.

Für Generics, die etwas über T wissen müssen (dass es eine length hat oder dass K ein Schlüssel von T ist), sind Constraints mit extends der nächste Schritt.