TypeScript Type Guard: den Typ eines Objekts prüfen

Ein Type Guard ist eine Prüfung zur Laufzeit, die TypeScript versteht, und damit engt er den Typ im geprüften Zweig ein. typeof, instanceof und in sind eingebaute Guards; für alles andere schreibst du eine Funktion, deren Rückgabetyp ein Type Predicate ist, value is Type.

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

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" && value !== null &&
    "name" in value && typeof value.name === "string" &&
    "age" in value && typeof value.age === "number"
  );
}

const inputs: unknown[] = [{ name: "Ada", age: 36 }, { name: "Bob" }, "Ada", null];

for (const input of inputs) {
  if (isUser(input)) {
    console.log(`${input.name} is ${input.age}`); // input: User
  } else {
    console.log("not a user:", input);
  }
}

isUser gibt zur Laufzeit ein einfaches Boolean zurück. Der Rückgabetyp value is User sagt dem Compiler, was ein Ergebnis true beweist, und jedes if (isUser(x)) engt x dann auf User ein.

Eingebaute Type Guards

Diese Prüfungen engen ohne Hilfsfunktion ein:

Alle laufen als gewöhnliches JavaScript. TypeScript ergänzt das Narrowing: Es liest die Prüfung und passt den Typ in jedem Zweig an. Die vollständige Liste der Formen steht auf der Seite zu Type Narrowing. Ein eigener Guard ist für Prüfungen gedacht, die nicht in einen Ausdruck passen oder die du wiederverwenden willst.

Ein Type Predicate schreiben

Ein Type Predicate hat die Form parameterName is Type und ersetzt boolean als Rückgabetyp. Das Narrowing wirkt in beide Richtungen: true engt auf Type ein, und false entfernt Type aus einer Union.

type Cat = { kind: "cat"; meow: () => string };
type Dog = { kind: "dog"; bark: () => string };
type Pet = Cat | Dog;

function isCat(pet: Pet): pet is Cat {
  return pet.kind === "cat";
}

function speak(pet: Pet): string {
  if (isCat(pet)) {
    return pet.meow(); // pet: Cat
  }
  return pet.bark();   // pet: Dog (Cat was ruled out)
}

const pets: Pet[] = [
  { kind: "cat", meow: () => "meow" },
  { kind: "dog", bark: () => "woof" },
];

console.log(pets.map(speak));             // [ 'meow', 'woof' ]
console.log(pets.filter(isCat).length);   // 1 (and the result is typed Cat[])

Übergibst du einen Guard an filter, bekommst du ein korrekt typisiertes Array. Seit TypeScript 5.5 leitet der Compiler ein Predicate auch aus einfachen Arrow Functions ab, sodass pets.filter((p) => p.kind === "cat") ohne benannten Guard Cat[] zurückgibt.

Der Typ des Predicates muss zum Typ des Parameters passen: function f(x: string): x is number ist der Fehler TS2677, A type predicate's type must be assignable to its parameter's type.

Der Compiler vertraut deinem Guard

TypeScript prüft, dass ein Guard ein Boolean zurückgibt. Es prüft nicht, ob das Boolean stimmt. Ein Guard, der für die falschen Werte true liefert, lässt die Typen lügen, und das Programm scheitert zur Laufzeit ohne Compilerfehler.

interface Product {
  title: string;
  price: number;
}

// Wrong: only checks title, never price
function isProduct(value: unknown): value is Product {
  return typeof value === "object" && value !== null && "title" in value;
}

const data: unknown = { title: "Lamp" };

if (isProduct(data)) {
  console.log(data.title); // Lamp
  try {
    console.log(data.price.toFixed(2)); // compiles, but throws at run time
  } catch (e) {
    console.log(e instanceof Error ? e.message : e);
    // Cannot read properties of undefined (reading 'toFixed')
  }
}

data.price.toFixed(2) wirft zur Laufzeit TypeError: Cannot read properties of undefined (reading 'toFixed'). Der Compiler hat data.price als number akzeptiert, weil der Guard es so gesagt hat. Prüfe jede Eigenschaft, auf die sich der restliche Code verlässt, und halte Guards klein, getestet und nah an dem Typ, den sie beschreiben.

Prüfen, ob ein Objekt einen Typ hat

Das ist die Frage hinter den meisten eigenen Guards: Daten kommen als unknown an (aus JSON.parse, fetch, localStorage, einer Nachricht), und du musst wissen, ob sie zu deinem Interface passen. Das Rezept:

1. typeof value === "object" && value !== null (ein Objekt, nicht null).
2. "prop" in value für jede Pflichteigenschaft. Auf unknown fügt in die Eigenschaft dem Typ als unknown hinzu.
3. typeof value.prop === "..." (oder ein verschachtelter Guard) für den Typ jeder Eigenschaft.
4. Array.isArray(value.items) && value.items.every(isItem) für Arrays.

interface Order {
  id: string;
  lines: { sku: string; qty: number }[];
}

function isLine(v: unknown): v is Order["lines"][number] {
  return typeof v === "object" && v !== null &&
    "sku" in v && typeof v.sku === "string" &&
    "qty" in v && typeof v.qty === "number" && Number.isInteger(v.qty);
}

function isOrder(v: unknown): v is Order {
  return typeof v === "object" && v !== null &&
    "id" in v && typeof v.id === "string" &&
    "lines" in v && Array.isArray(v.lines) && v.lines.every(isLine);
}

const good: unknown = JSON.parse('{"id":"A1","lines":[{"sku":"pen","qty":2}]}');
const bad: unknown = JSON.parse('{"id":"A2","lines":[{"sku":"pen","qty":"2"}]}');

console.log(isOrder(good), isOrder(bad)); // true false
if (isOrder(good)) console.log(good.lines[0].qty * 3); // 6

Bei großen oder tief verschachtelten Formen wird das Schreiben von Hand mühsam. Schema-Bibliotheken wie Zod oder Valibot lassen dich die Form einmal beschreiben und liefern dir sowohl die Prüfung zur Laufzeit als auch den TypeScript-Typ.

Assertion-Funktionen: asserts value is Type

Eine Assertion-Funktion wirft, wenn die Prüfung scheitert, und kehrt sonst normal zurück. Ihr Rückgabetyp ist asserts value is Type (oder asserts condition), und alles nach dem Aufruf ist eingeengt, ohne dass ein if nötig ist.

function assertIsString(value: unknown, name: string): asserts value is string {
  if (typeof value !== "string") {
    throw new TypeError(`${name} must be a string, got ${typeof value}`);
  }
}

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

function greet(input: unknown, count: number | null): string {
  assertIsString(input, "input");
  assert(count !== null, "count is required");
  // input: string, count: number
  return input.toUpperCase().repeat(count);
}

console.log(greet("hi", 2)); // HIHI

try {
  greet(42, 1);
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // input must be a string, got number
}

Eine Regel bringt viele ins Stolpern: Eine Assertion-Funktion muss über einen Namen mit ausdrücklichem Typ aufgerufen werden. Eine const Arrow Function ohne Annotation, const check = (v: unknown): asserts v is string => {...}, ergibt beim Aufruf den Fehler TS2775, Assertions require every name in the call target to be declared with an explicit type annotation. Nimm eine function-Deklaration oder annotiere die Konstante mit einem Funktionstyp.

Guards vs Assertions vs Casts

Eine Typ-Assertion (as) ändert den Typ, ohne etwas zu prüfen. An einer Grenze, an der Daten von außen kommen, ist ein Guard oder eine Assertion-Funktion die sichere Variante derselben Idee.

Guards mit this in Klassen

Eine Methode kann das Objekt, auf dem sie aufgerufen wird, mit this is Type einengen. Das ist in Klassenhierarchien praktisch:

class FileNode {
  constructor(public name: string) {}
  isDirectory(): this is DirectoryNode {
    return this instanceof DirectoryNode;
  }
}

class DirectoryNode extends FileNode {
  children: FileNode[] = [];
}

function count(node: FileNode): number {
  return node.isDirectory() ? node.children.length : 0; // node: DirectoryNode in the true branch
}