Type Guards und Narrowing in TypeScript

1. Einordnung: Compile-Zeit-Typen vs. Laufzeit-Realität

TypeScript-Typen existieren ausschließlich zur Compile-Zeit. Der Compiler prüft jede Typannotation, entfernt sie danach vollständig und erzeugt reines JavaScript ohne jede Typinformation. Wer im Node-Debugger den Typ einer Variable inspiziert, findet dort nichts von interface oder type wieder, nur den nackten Laufzeitwert. Diese Typauslöschung ist der Kern eines Missverständnisses, das viele Einsteiger teuer bezahlen: Ein als string deklarierter Parameter ist zur Laufzeit nur dann tatsächlich ein String, wenn niemand einen falschen Wert übergeben hat, etwa aus einem JSON-Response, einem Formularfeld oder einer externen Bibliothek ohne eigene Typen.

Type Guards und Narrowing schließen genau diese Lücke: Sie verbinden eine Laufzeitprüfung mit einer Compile-Zeit-Garantie, sodass der Compiler innerhalb eines geprüften Codeblocks einen präziseren, engeren Typ annehmen darf. Narrowing ist dabei kein optionales Feature, sondern der Mechanismus, mit dem der TypeScript-Compiler Union-Typen, unknown und optionale Felder überhaupt benutzbar macht, ohne dass Entwickler ständig auf as-Casts zurückgreifen müssen, die die eigentliche Prüfung nur vortäuschen.

2. Eingebautes Narrowing: typeof, instanceof, in, Array.isArray

Der TypeScript-Compiler analysiert den Kontrollfluss einer Funktion und schränkt den Typ einer Variablen automatisch ein, sobald eine Bedingung diesen Typ eindeutig einschränkt. typeof funktioniert zuverlässig für primitive Typen wie string, number, boolean und function, während instanceof für Klassen und eingebaute Objekte wie Date oder Error greift. Der in-Operator prüft, ob eine Eigenschaft in einem Objekt existiert, und eignet sich damit besonders für Union-Typen aus mehreren Objektformen ohne gemeinsames Diskriminierungsfeld.

Truthiness-Checks wie if (value) narrowen zuverlässig null und undefined heraus, schließen aber auch 0, den leeren String und NaN aus, was bei numerischen Werten leicht zu Fehlern führt. Array.isArray() ist die einzige robuste Methode, um zwischen einem einzelnen Wert und einem Array zu unterscheiden, da typeof für Arrays nur "object" liefert. Gleichheitsvergleiche mit Literalen, etwa value === 'ok', narrowen Literal-Union-Typen ebenso präzise wie switch-Anweisungen über ein Diskriminierungsfeld.

// Built-in narrowing: typeof, instanceof, in, Array.isArray, truthiness
type Input = string | number | Date | { code: string } | null;

function describe(value: Input): string {
  if (value === null) {
    return 'no value';
  }

  if (typeof value === 'string') {
    // narrowed to string
    return value.toUpperCase();
  }

  if (typeof value === 'number') {
    // narrowed to number
    return value.toFixed(2);
  }

  if (value instanceof Date) {
    // narrowed to Date
    return value.toISOString();
  }

  if ('code' in value) {
    // narrowed to { code: string }
    return `code:${value.code}`;
  }

  // exhaustive: TypeScript knows nothing is left here
  return 'unreachable';
}

function sumNumbers(values: (number | null)[]): number {
  return values
    .filter((v): v is number => v !== null) // equality narrowing inside a guard
    .reduce((total, v) => total + v, 0);
}

function joinIds(ids: string | string[]): string {
  return Array.isArray(ids) ? ids.join(',') : ids;
}

3. Eigene Type-Guard-Funktionen mit "value is Type"

Sobald die eingebauten Prüfungen nicht ausreichen, etwa bei komplexeren Objektformen oder bei der Validierung von unknown-Werten, kommen eigene Type-Guard-Funktionen ins Spiel. Eine Funktion wird zum Type Guard, indem ihr Rückgabetyp nicht boolean, sondern die spezielle Signatur value is Type ist. Der Funktionsrumpf muss weiterhin einen echten boolean zurückgeben, aber der Compiler interpretiert das Ergebnis an jeder Aufrufstelle als Narrowing-Signal für den geprüften Parameter.

Der große Vorteil gegenüber Inline-Prüfungen ist Wiederverwendbarkeit: Ein einmal geschriebener Guard wie isCustomer() lässt sich in beliebig vielen Funktionen einsetzen, ohne die Prüf-Logik zu duplizieren, und narrowed in if-Bedingungen, filter()-Aufrufen sowie while-Schleifen gleichermaßen zuverlässig. Wichtig ist, dass die Implementierung tatsächlich das prüft, was die Signatur behauptet: TypeScript verifiziert die Laufzeitlogik nicht, ein falsch implementierter Guard führt zu einer falschen Typsicherheit, die schwerer zu debuggen ist als gar kein Guard.

// Custom type guard: "value is Type" tells the compiler how to narrow
interface Customer {
  type: 'customer';
  email: string;
}

interface Guest {
  type: 'guest';
  sessionId: string;
}

type Visitor = Customer | Guest;

function isCustomer(visitor: Visitor): visitor is Customer {
  return visitor.type === 'customer';
}

function greet(visitor: Visitor): string {
  if (isCustomer(visitor)) {
    // narrowed to Customer, email is available
    return `Welcome back, ${visitor.email}`;
  }

  // narrowed to Guest by elimination
  return `Welcome, guest ${visitor.sessionId}`;
}

// Guard that works on unknown, not just a known union member
function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function hasStringProp(value: unknown, key: string): boolean {
  return isRecord(value) && typeof value[key] === 'string';
}

4. Assertion Functions mit "asserts value is Type"

Assertion Functions lösen ein anderes Problem als klassische Type Guards: Statt eine Bedingung zu prüfen und zwei Zweige (wahr/falsch) bereitzustellen, werfen sie bei einer Verletzung eine Exception und lassen den Rest der Funktion im positiven Fall weiterlaufen. Die Signatur asserts value is Type teilt dem Compiler mit, dass nach dem Aufruf der Funktion der übergebene Wert im restlichen Gültigkeitsbereich als der angegebene Typ behandelt werden darf, ganz ohne if-Verzweigung.

Die einfachere Variante asserts condition narrowed keinen bestimmten Wert, sondern signalisiert dem Compiler lediglich, dass die Funktion bei einer verletzten Bedingung nicht normal zurückkehrt. Das ist besonders nützlich für generische Prüfungen wie Division durch Null oder Array-Längen-Validierung. In der Praxis ersetzen Assertion Functions häufig Guard-Klauseln am Anfang einer Funktion und sorgen für lesbaren Code ohne verschachtelte if-Blöcke, allerdings mit der Einschränkung, dass sie eine Exception werfen müssen und keinen Fallback-Wert liefern können.

// Assertion functions: "asserts value is Type" and "asserts condition"
class ValidationError extends Error {}

function assertIsString(value: unknown, fieldName: string): asserts value is string {
  if (typeof value !== 'string') {
    throw new ValidationError(`${fieldName} must be a string`);
  }
}

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) {
    throw new ValidationError(message);
  }
}

function processOrderId(input: unknown): string {
  assertIsString(input, 'orderId');
  // input is narrowed to string for the rest of the function's scope
  return input.trim().toUpperCase();
}

function divide(a: number, b: number): number {
  assert(b !== 0, 'divisor must not be zero');
  // the runtime guarantee now matches the assumption in the line below
  return a / b;
}

5. Narrowing bei Arrays, unknown, Generics und diskriminierten Typen

Narrowing wird komplizierter, sobald mehrere Ebenen zusammenkommen: Arrays aus unknown-Werten, generische Typparameter und diskriminierte Unions mit mehr als zwei Varianten. Für Arrays gibt es kein eingebautes Pendant zu Array.isArray, das auch den Elementtyp prüft, weshalb value.every((item) => typeof item === 'string') in Kombination mit einem eigenen Type Guard der Standardweg ist, um unknown[] zuverlässig zu string[] zu narrowen.

Bei generischen Funktionen wie ApiResult<T> funktioniert Narrowing über ein Diskriminierungsfeld wie status genauso wie bei konkreten Typen, weil TypeScript die Kontrollflussanalyse unabhängig vom generischen Parameter T durchführt. Diskriminierte Unions mit vielen Varianten profitieren besonders von switch-Anweisungen mit einem default-Zweig, der über never geprüft wird: Fehlt eine Variante in der Behandlung, meldet der Compiler beim Hinzufügen eines neuen Union-Mitglieds sofort einen Fehler, statt den Fall stillschweigend zu ignorieren.

// Narrowing discriminated unions, generics, and unknown arrays
type ApiResult<T> =
  | { status: 'ok'; data: T }
  | { status: 'error'; message: string };

function unwrap<T>(result: ApiResult<T>): T {
  if (result.status === 'error') {
    // narrowed to the error branch
    throw new Error(result.message);
  }

  // narrowed to the ok branch, data is T
  return result.data;
}

function isStringArray(value: unknown): value is string[] {
  return Array.isArray(value) && value.every((item) => typeof item === 'string');
}

function firstOrEmpty(value: unknown): string {
  if (!isStringArray(value)) {
    return '';
  }

  // value is string[], value[0] is string | undefined until checked
  const first = value[0];
  return first !== undefined ? first : '';
}

6. Grenzen des Narrowing: Closures, Index-Zugriffe, Aliasing

Narrowing hat klare Grenzen, die regelmäßig zu überraschenden Compiler-Fehlern führen. Innerhalb von Closures geht eine Narrowing-Information verloren, sobald TypeScript nicht ausschließen kann, dass sich der Wert zwischen der Prüfung und dem späteren Zugriff geändert hat, etwa wenn eine Callback-Funktion asynchron ausgeführt wird oder die geprüfte Variable ein let statt const ist. Auch nach einem Array-Index-Zugriff narrowed TypeScript standardmäßig nicht: array[0] liefert immer den Elementtyp, nie Elementtyp | undefined, es sei denn, noUncheckedIndexedAccess ist in der tsconfig.json aktiviert.

Ein weiteres Stolperfeld ist Aliasing: Wird ein geprüfter Wert einer Objekteigenschaft zugewiesen, etwa obj.value = checkedValue, geht die Narrowing-Information für obj.value bei künftigen Zugriffen verloren, weil der Compiler Objekteigenschaften nicht in gleicher Tiefe verfolgt wie lokale Variablen. In all diesen Fällen hilft es, den geprüften Wert in eine eigene, unveränderliche lokale Variable zu extrahieren, statt sich auf die fortlaufende Gültigkeit einer einmal durchgeführten Prüfung zu verlassen.

7. Dem Compiler helfen: satisfies, Const-Assertions, Kontrollfluss-Grenzen

Wo die automatische Kontrollflussanalyse an ihre Grenzen stößt, gibt es gezielte Werkzeuge, um dem Compiler zu helfen. Der satisfies-Operator, seit TypeScript 4.9 verfügbar, prüft, ob ein Literal zu einem Typ passt, ohne den inferierten Typ des Literals wie ein Cast zu überschreiben. Das ist besonders wertvoll bei Konfigurationsobjekten: const config = {...} satisfies Config behält die präzisen Literal-Typen der einzelnen Felder, während gleichzeitig sichergestellt ist, dass die Struktur zu Config passt.

Const-Assertions mit as const verhindern, dass TypeScript Literale zu ihrem breiteren Basistyp verallgemeinert, was insbesondere bei diskriminierten Unions und Tupeln wichtig ist. Wo weder satisfies noch Const-Assertions ausreichen, bleiben Assertion Functions das letzte Mittel: Sie erlauben es, Wissen, das der Compiler aus strukturellen Gründen nicht ableiten kann, etwa Invarianten aus der Geschäftslogik, explizit und geprüft in den Typ zu übertragen, statt es mit einem ungeprüften as Type-Cast zu erzwingen.

8. Praxisbeispiel: Unbekannte API-Antworten zur Laufzeit validieren

Der häufigste Praxisfall für Type Guards ist die Validierung von Daten, die von außerhalb des eigenen Typsystems kommen: API-Antworten, JSON.parse()-Ergebnisse, Formulareingaben oder Nachrichten aus einem Web Worker. fetch() liefert mit response.json() standardmäßig den Typ any zurück, was die eigentliche Typsicherheit komplett unterläuft, wenn das Ergebnis ungeprüft weiterverwendet wird. Der sichere Weg beginnt damit, das Ergebnis explizit als unknown zu typisieren und erst über einen eigenen Type Guard freizuschalten.

Ein Guard wie isProduct() prüft jedes erwartete Feld einzeln, inklusive verschachtelter Arrays, und gibt erst dann true zurück, wenn die gesamte Struktur der erwarteten Form entspricht. Diese Prüfung kostet zur Laufzeit etwas Rechenzeit, verhindert aber genau die Klasse von Fehlern, die sonst erst tief im Anwendungscode als undefined is not a function auftauchen. Für größere Projekte lohnt sich der Umstieg auf Validierungsbibliotheken wie Zod oder Valibot, die Schema-Definition und Type-Guard-Generierung automatisch koppeln.

// Practical example: validating an unknown API response at runtime
interface Product {
  id: number;
  name: string;
  price: number;
  tags: string[];
}

function isProduct(value: unknown): value is Product {
  if (typeof value !== 'object' || value === null) {
    return false;
  }

  const candidate = value as Record<string, unknown>;

  return (
    typeof candidate.id === 'number' &&
    typeof candidate.name === 'string' &&
    typeof candidate.price === 'number' &&
    Array.isArray(candidate.tags) &&
    candidate.tags.every((tag) => typeof tag === 'string')
  );
}

async function fetchProduct(url: string): Promise<Product> {
  const response = await fetch(url);
  const json: unknown = await response.json();

  if (!isProduct(json)) {
    throw new Error('API response does not match the Product shape');
  }

  // json is narrowed to Product from here on
  return json;
}

9. Vergleich: Unsichere Casts vs. sicheres Narrowing

Die folgende Tabelle stellt unsichere Casts den entsprechenden sicheren Narrowing-Techniken gegenüber. Der Unterschied ist in jeder Zeile derselbe: Ein as Type-Cast überschreibt die Typprüfung des Compilers, ohne zur Laufzeit irgendetwas zu garantieren, während die sichere Variante eine echte Prüfung durchführt und der Compiler die Garantie erst danach ausstellt.

In der Praxis zahlt sich diese Disziplin vor allem an den Rändern einer Anwendung aus, also überall dort, wo Daten das eigene Typsystem verlassen oder betreten: API-Grenzen, Formulare, Storage-APIs und Nachrichten zwischen Threads oder Fenstern. Innerhalb eines rein internen, durchgängig typisierten Codepfads ist Narrowing meist automatisch korrekt, ohne dass zusätzliche Guards nötig sind.

10. Zusammenfassung

Type Guards und Narrowing sind das Bindeglied zwischen TypeScripts Compile-Zeit-Typsystem und der tatsächlichen Laufzeit-Realität von JavaScript. Eingebautes Narrowing über typeof, instanceof, in und Array.isArray deckt die meisten alltäglichen Fälle ab, eigene Type-Guard-Funktionen mit der value is Type-Signatur erweitern das auf komplexe und unbekannte Datenformen, und Assertion Functions mit asserts value is Type ersetzen Guard-Klauseln durch geprüfte Annahmen im restlichen Funktionsrumpf.

Die Grenzen des automatischen Narrowing, etwa in Closures, nach Array-Index-Zugriffen oder bei Aliasing, lassen sich mit gezielten Werkzeugen wie satisfies, Const-Assertions und expliziten Assertion Functions überbrücken. Wer diese Techniken konsequent an den Rändern der eigenen Anwendung einsetzt, überall dort, wo Daten von außen ins Typsystem gelangen, gewinnt echte Typsicherheit zur Laufzeit statt nur eine Illusion davon zur Compile-Zeit.

11. FAQ: Type Guards und Narrowing in TypeScript