Generic Constraints: Typen sinnvoll einschränken

1. Warum uneingeschränkte Generics zu freizügig sind

Ein generischer Typparameter wie <T> ohne jede Einschränkung akzeptiert praktisch alles: Strings, Zahlen, Arrays, Klassen-Instanzen, sogar undefined. Genau diese Offenheit macht T im Rumpf einer Funktion fast nutzlos, denn der Compiler kennt keine einzige Eigenschaft oder Methode, die auf jedem beliebigen Typ garantiert existiert. Ein Aufruf wie value.length oder value.toUpperCase() schlägt fehl, weil TypeScript zu Recht nicht annehmen darf, dass irgendein T diese Eigenschaft besitzt. Wer diesen Zustand mit any oder unknown umgeht, verliert die Typsicherheit komplett oder muss bei jedem Zugriff manuell prüfen und casten.

In der Praxis zeigt sich das Problem besonders bei generischen API-Clients, Formular-Hilfsfunktionen oder State-Management-Utilities: Eine Funktion soll für viele verschiedene Datentypen funktionieren, muss aber trotzdem auf bestimmte Felder zugreifen können. Genau hier setzen Generic Constraints an. Mit dem extends Schlüsselwort, mit Einschränkungen auf Objekt-Formen und mit keyof lässt sich ein Typparameter so weit eingrenzen, dass er einerseits flexibel bleibt und andererseits genau die Eigenschaften garantiert, die eine Funktion tatsächlich benötigt.

2. Das extends Schlüsselwort: Syntax und Wirkung

Die Syntax <T extends SomeShape> begrenzt die Menge der zulässigen Typen für T auf alle Typen, die strukturell mit SomeShape kompatibel sind. Wichtig ist dabei die strukturelle Typisierung von TypeScript: SomeShape muss keine Klasse und keine explizit implementierte Schnittstelle sein, es reicht, dass der übergebene Typ die passenden Eigenschaften besitzt. extends funktioniert dabei anders als bei Klassenvererbung, es beschreibt eine Ober- und Untermenge von Typen, keine Objekthierarchie zur Laufzeit.

Im folgenden Beispiel garantiert die Constraint HasLength, dass value innerhalb der Funktion eine Eigenschaft length vom Typ number besitzt. Strings, Arrays und eigene Objekte mit passender Form werden akzeptiert, eine Zahl wird dagegen vom Compiler zurückgewiesen, noch bevor der Code überhaupt ausgeführt wird.

// Without constraint: T could be anything, .length is unavailable
function logLength<T>(value: T): void {
  console.log(value.length); // Error: Property 'length' does not exist on type 'T'
}

// With extends: T is now guaranteed to have a length property
interface HasLength {
  length: number;
}

function logLengthSafe<T extends HasLength>(value: T): void {
  console.log(value.length); // OK, TypeScript knows T has .length
}

logLengthSafe("hello");        // OK, string has .length
logLengthSafe([1, 2, 3]);      // OK, array has .length
logLengthSafe({ length: 10 }); // OK, matches the shape
// logLengthSafe(42);          // Error: number has no .length

Constraints sind nicht auf Objekt-Formen beschränkt. <T extends string | number> erlaubt zum Beispiel nur primitive Schlüsselwerte, <T extends Function> nur aufrufbare Werte. Die Regel bleibt immer gleich: Innerhalb der Funktion darf der Compiler nur mit den Eigenschaften und Operationen rechnen, die durch die Constraint garantiert sind, unabhängig davon, wie konkret der tatsächlich übergebene Typ ist.

3. Einschränkung auf Objekt-Formen: object und Record

<T extends object> schließt primitive Typen wie string, number und boolean aus und lässt nur Objekte, Arrays, Funktionen und Klassen-Instanzen zu. Das ist nützlich, wenn eine Funktion grundsätzlich mit referenzierbaren Strukturen arbeiten soll, aber noch keine Aussage über konkrete Eigenschaften trifft. Der Nachteil: object allein garantiert keinerlei Zugriff auf bestimmte Felder, der Compiler weiß nur, dass es sich um irgendein Objekt handelt.

<T extends Record<string, unknown>> geht einen Schritt weiter und beschreibt ein Objekt mit beliebigen String-Schlüsseln und Werten vom Typ unknown. Das eignet sich gut für generische Funktionen, die Objekte iterieren oder zusammenführen, ohne die konkreten Feldnamen zu kennen. Wichtig: Arrays erfüllen Record<string, unknown> nicht in jeder Situation zuverlässig, deshalb lohnt sich bei gemischten Eingaben ein zusätzlicher Array.isArray-Check oder eine präzisere Constraint wie ein konkretes Interface.

4. Einschränkung mit keyof: sichere Property-Zugriffe

keyof T erzeugt eine Union aus allen Eigenschaftsnamen von T als String- oder Symbol-Literale. Die Kombination <T, K extends keyof T> koppelt zwei Typparameter aneinander: K darf nur ein tatsächlicher Schlüssel von T sein. Diese Verbindung ist der Kern vieler typsicherer Utility-Funktionen, weil sie dem Compiler erlaubt, ungültige Feldnamen bereits zur Kompilierzeit abzulehnen, statt erst zur Laufzeit einen undefined-Wert zu liefern.

Im folgenden Beispiel liefert getProperty nicht irgendeinen Wert, sondern exakt den Typ T[K], also den indexierten Zugriffstyp für den übergebenen Schlüssel. Ruft man getProperty(product, 'price') auf, weiß TypeScript bereits beim Schreiben des Codes, dass das Ergebnis vom Typ number ist, und ein Tippfehler im Schlüsselnamen wird sofort als Fehler markiert.

// K extends keyof T restricts K to the actual property names of T
function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
  return obj[key];
}

interface Product {
  sku: string;
  price: number;
  inStock: boolean;
}

const product: Product = { sku: "MS-1001", price: 49.9, inStock: true };

const sku = getProperty(product, "sku");     // type: string
const price = getProperty(product, "price"); // type: number
// getProperty(product, "weight");           // Error: 'weight' is not in keyof Product

5. Default-Generic-Parameter: <T = DefaultType>

Ähnlich wie Funktionsparameter können auch Typparameter einen Standardwert erhalten: <T = DefaultType> verwendet DefaultType, wenn der Aufrufer keinen expliziten Typ angibt und der Compiler ihn auch nicht aus den Argumenten ableiten kann. Das reduziert Boilerplate an Aufrufstellen erheblich, besonders bei Funktionen oder Interfaces mit mehreren Typparametern, von denen die meisten Aufrufe nur einen wirklich benötigen.

Default-Werte lassen sich mit Constraints kombinieren, die Syntax lautet dann <T extends Constraint = DefaultType>, wobei DefaultType selbst die Constraint erfüllen muss. Eine wichtige Regel: Typparameter mit Default-Wert müssen in der Parameterliste nach den Typparametern ohne Default stehen, genau wie bei optionalen Funktionsparametern. Im folgenden Beispiel fällt TOptions automatisch auf Record<string, unknown> zurück, wenn keine speziellen Optionen benötigt werden, kann aber bei Bedarf explizit auf einen präziseren Typ gesetzt werden.

// Default generic parameter: TOptions defaults to Record<string, unknown>
interface FetchConfig<TResponse = unknown, TOptions extends object = Record<string, unknown>> {
  url: string;
  parse: (raw: unknown) => TResponse;
  options?: TOptions;
}

function createRequest<TResponse, TOptions extends object = Record<string, unknown>>(
  config: FetchConfig<TResponse, TOptions>
): FetchConfig<TResponse, TOptions> {
  return config;
}

// TOptions falls back to Record<string, unknown> here
const simpleRequest = createRequest({
  url: "/api/products",
  parse: (raw: unknown) => raw as Product[],
});

// TOptions is set explicitly here
const advancedRequest = createRequest<Product[], { retries: number }>({
  url: "/api/products",
  parse: (raw: unknown) => raw as Product[],
  options: { retries: 3 },
});

6. Praxisbeispiel Teil 1: die Signatur der pick-fields Funktion

Eine typsichere pick-fields Funktion soll aus einem Objekt eine Teilmenge von Feldern extrahieren, ähnlich wie die pick-Funktion aus Lodash, aber vollständig durch den Compiler geprüft statt nur zur Laufzeit korrekt. Die Signatur dafür kombiniert genau die bisher besprochenen Werkzeuge: <T extends object, K extends keyof T> stellt sicher, dass T ein Objekt ist und K nur echte Schlüssel von T sein können.

Der Parameter keys wird als readonly K[] typisiert statt als K[], weil Aufrufer häufig ein Literal-Array wie ['sku', 'price'] übergeben, das nicht mutiert werden soll. Der Rückgabetyp Pick<T, K> ist ein eingebauter Utility Type von TypeScript, der aus T genau die in K aufgeführten Eigenschaften herausfiltert. Damit kennt der Compiler bereits vor der Implementierung exakt, welche Form das Ergebnis jedes einzelnen Aufrufs haben wird.

7. Praxisbeispiel Teil 2: Implementierung und Nutzung mit Autocomplete

Die Implementierung selbst iteriert über keys und kopiert jedes Feld einzeln in ein neues Objekt. Innerhalb der Funktion ist ein einzelner Cast auf Pick<T, K> nötig, weil der Compiler die schrittweise Befüllung eines anfangs leeren Objekts nicht Zeile für Zeile nachvollziehen kann. Das ist ein bewusster, lokal begrenzter Kompromiss: Die interne Implementierung verzichtet an einer Stelle auf volle Typprüfung, die externe Signatur bleibt aber zu hundert Prozent typsicher.

// Constrained generic signature for a typed "pick fields" utility
function pickFields<T extends object, K extends keyof T>(
  source: T,
  keys: readonly K[]
): Pick<T, K> {
  const result = {} as Pick<T, K>;
  for (const key of keys) {
    result[key] = source[key];
  }
  return result;
}

const product: Product = { sku: "MS-1001", price: 49.9, inStock: true };

// Editor autocomplete only suggests "sku" | "price" | "inStock" here
const summary = pickFields(product, ["sku", "price"]);
// summary has type: { sku: string; price: number }

// pickFields(product, ["sku", "weight"]);
// Error: "weight" is not assignable to keyof Product

An der Aufrufstelle zeigt sich der eigentliche Nutzen der Constraints: Der Editor schlägt beim Tippen des keys-Arrays ausschließlich gültige Feldnamen von Product vor, ein Tippfehler wie "weigth" wird sofort unterstrichen, und der Rückgabetyp von pickFields enthält exakt die ausgewählten Felder, nicht mehr und nicht weniger. In Headless- und API-Projekten reduziert dieses Pattern zuverlässig Bugs, wenn nur ein Teil eines großen Produkt- oder Kundenobjekts an eine Komponente oder einen Endpunkt weitergereicht werden soll.

8. Mehrfache Constraints und Constraint-Komposition

Mehrere strukturelle Anforderungen lassen sich mit dem Intersection-Operator & zu einer einzigen Constraint kombinieren: <T extends Identifiable & Timestamped> verlangt, dass T sowohl eine id-Eigenschaft als auch ein createdAt-Feld besitzt. Das ist besonders praktisch für generische Funktionen, die mit mehreren, unabhängig definierten Interfaces arbeiten müssen, ohne dass eines der beiden das andere erweitert.

// Combining extends with intersection types
interface Timestamped {
  createdAt: Date;
}

interface Identifiable {
  id: string;
}

// T must satisfy both Identifiable and Timestamped
function touch<T extends Identifiable & Timestamped>(entity: T): T {
  return { ...entity, createdAt: new Date() };
}

// A constraint that references another type parameter
function assignDefaults<T extends object, D extends Partial<T>>(
  target: T,
  defaults: D
): T {
  return { ...defaults, ...target };
}

interface Settings {
  theme: string;
  language: string;
}

const settings = assignDefaults<Settings, Partial<Settings>>(
  { theme: "dark", language: "de" },
  { language: "en" }
);

Fortgeschrittener ist eine Constraint, die sich auf einen bereits deklarierten Typparameter bezieht, etwa <T extends object, D extends Partial<T>>. Hier darf D nur ein Objekt sein, dessen Eigenschaften eine Teilmenge von T bilden, was sich hervorragend für Merge- oder Default-Funktionen eignet. TypeScript wertet Typparameter in der deklarierten Reihenfolge aus, sodass ein späterer Parameter jederzeit auf einen früheren verweisen kann, aber nicht umgekehrt.

9. Generic Constraints im direkten Vergleich

Die folgende Übersicht stellt unsichere oder unpraktische Muster den empfohlenen Generic-Constraint-Patterns gegenüber und zeigt, welchen konkreten Vorteil die jeweilige Lösung bringt.

Wie strikt eine Constraint sein sollte, hängt von der tatsächlich benötigten Struktur ab, nicht von der verfügbaren Klassenhierarchie. Ein häufiger Fehler ist das Overconstraining: <T extends ProductEntity> zwingt jeden Aufrufer, eine konkrete Klasse zu verwenden, obwohl die Funktion in Wirklichkeit nur ein einzelnes Feld wie sku benötigt. Die schlankere Constraint <T extends { sku: string }> ist wiederverwendbar für jede passende Form, unabhängig von Vererbung, und folgt damit dem strukturellen Typsystem von TypeScript konsequenter als eine an Klassen gebundene Einschränkung.

10. Zusammenfassung

Generic Constraints lösen das Grundproblem uneingeschränkter Typparameter: Ohne extends kennt der Compiler keine einzige Eigenschaft von T und verweigert jeden sinnvollen Zugriff. Mit extends, keyof und durchdachten Default-Werten lässt sich genau die Struktur einfordern, die eine Funktion tatsächlich braucht, nicht mehr und nicht weniger. Die pick-fields Funktion aus diesem Artikel zeigt, wie <T extends object, K extends keyof T> aus einer einfachen Signatur eine vollständig typsichere, autovervollständigungsfähige Utility macht.

Der wichtigste Grundsatz bleibt Zurückhaltung bei der Formulierung von Constraints: Je minimaler die geforderte Struktur, desto wiederverwendbarer die Funktion. Eine Constraint sollte immer nur genau die Eigenschaften verlangen, die im Funktionsrumpf tatsächlich verwendet werden, und niemals eine konkrete Klasse, wenn eine strukturelle Objekt-Form ausreicht. Wer dieses Prinzip konsequent anwendet, baut TypeScript-Utilities, die über Jahre und viele Projekte hinweg ohne Anpassung wiederverwendbar bleiben.

11. FAQ: Generic Constraints in TypeScript