TypeScript Type Narrowing: so funktioniert Control Flow Analysis

Type Narrowing bedeutet, dass TypeScript für einen Wert an einer bestimmten Stelle im Code einen spezifischeren Typ ermittelt, anhand der Prüfungen, die der Code bereits gemacht hat. Ein Parameter vom Typ string | number wird in if (typeof x === "string") zu string und im else zu number.

function pad(value: string | number): string {
  if (typeof value === "number") {
    // value: number
    return value.toFixed(2).padStart(8);
  }
  // value: string (number was handled above)
  return value.padStart(8);
}

console.log(`[${pad(3.14159)}]`); // [    3.14]
console.log(`[${pad("abc")}]`);   // [     abc]

value.toFixed(2) vor der Prüfung aufzurufen wäre ein Compilerfehler, weil toFixed auf string nicht existiert. Die Prüfung ist gewöhnliches JavaScript und läuft zur Laufzeit; das Narrowing ist der Compiler, der sie liest und den Typ anpasst. Es wird nichts zusätzlich erzeugt.

Control Flow Analysis

TypeScript folgt jedem Pfad durch eine Funktion: if/else, frühes return und throw, switch, Schleifen und die Kurzschlussoperatoren &&, ||, ?? und ?:. An jeder Stelle ist der Typ einer Variablen das, was dort noch möglich ist.

function firstWord(text: string | null | undefined): string {
  if (text == null) return "(none)";   // removes null and undefined
  // text: string
  const trimmed = text.trim();
  const space = trimmed.indexOf(" ");
  return space === -1 ? trimmed : trimmed.slice(0, space);
}

function lengthOrZero(list?: string[]): number {
  return list && list.length > 0 ? list.length : 0; // list: string[] after &&
}

console.log(firstWord("  hello typed world")); // hello
console.log(firstWord(undefined));             // (none)
console.log(lengthOrZero(["a", "b"]), lengthOrZero()); // 2 0

Der Stil mit frühem return („Guard Clauses“) ist die lesbarste Art einzuengen: Behandle die Sonderfälle zuerst, und der Rest der Funktion arbeitet mit dem sauberen Typ.

Alle Arten des Narrowing

Die letzten drei werden auf den Seiten zu Type Guards und Discriminated Unions behandelt. Die übrigen folgen hier.

Narrowing über Truthiness

if (x) entfernt null und undefined (sowie die Literaltypen false, 0 und ""). Das ist kurz und hat eine klassische Falle: 0 und "" sind falsy, gültige Werte werden also als fehlend behandelt.

function describeCount(count: number | undefined): string {
  if (!count) return "unknown";   // bug: 0 is falsy too
  return `${count} items`;
}

function describeCountFixed(count: number | undefined): string {
  if (count === undefined) return "unknown";
  return `${count} items`;
}

console.log(describeCount(0));      // unknown
console.log(describeCountFixed(0)); // 0 items

Bei Zahlen und Strings vergleichst du ausdrücklich mit undefined oder null (oder nimmst ??). Truthiness passt für Objekte, Arrays und Funktionen, die nie falsy sind.

Narrowing über Gleichheit

===, !==, == und != engen beide Seiten ein. Der Vergleich mit einem Literal engt auf dieses Literal ein; == null (lose Gleichheit) trifft in einer Prüfung sowohl null als auch undefined und ist die eine Stelle, an der lose Gleichheit üblich ist.

type Status = "active" | "paused" | "deleted";

function label(status: Status, note: string | null | undefined): string {
  if (status === "deleted") return "gone";
  // status: "active" | "paused"
  const suffix = note != null ? ` (${note})` : ""; // note: string in the true branch
  return status.toUpperCase() + suffix;
}

console.log(label("paused", "until Monday")); // PAUSED (until Monday)
console.log(label("active", undefined));      // ACTIVE
console.log(label("deleted", null));          // gone

Der Vergleich zweier Variablen engt beide auf das ein, was sie gemeinsam haben könnten: Wenn a: string | number und b: string | boolean den Test a === b bestehen, sind beide im if string.

Der Operator in

"key" in obj engt eine Union aus Objekttypen auf die Member ein, die diese Eigenschaft haben (oder haben könnten).

type Fish = { name: string; swim: () => string };
type Bird = { name: string; fly: () => string };

function move(pet: Fish | Bird): string {
  if ("swim" in pet) {
    return pet.swim(); // pet: Fish
  }
  return pet.fly();    // pet: Bird
}

console.log(move({ name: "Nemo", swim: () => "splash" })); // splash
console.log(move({ name: "Tweety", fly: () => "flap" }));  // flap

in funktioniert auch bei unknown, sobald du weißt, dass es ein Objekt ist: Nach typeof v === "object" && v !== null && "id" in v weiß TypeScript, dass v eine Eigenschaft id vom Typ unknown hat. Bei Unions, die du selbst entwirfst, ist eine gemeinsame Tag-Eigenschaft (kind: "fish") klarer, als nach Methoden zu tasten: Dieses Muster heißt Discriminated Union.

Narrowing durch Zuweisung

Eine Variable hat einen deklarierten Typ und einen eingeengten Typ, der ihren Zuweisungen folgt. Einen Wert zuzuweisen engt sie auf den Typ dieses Werts ein, bis hin zum deklarierten Typ.

let id: string | number = "a-17";
console.log(id.toUpperCase()); // id: string here, so string methods work

id = 42;
console.log(id.toFixed(1));    // id: number now

// id = true; would be an error: the declared type is still string | number

Wo Narrowing verloren geht

Narrowing ist lokal und vorsichtig. Einige Situationen setzen es zurück:

• Ein anderer Ausdruck. Eine Prüfung von obj.name engt obj.name (und obj["name"]) ein, aber nicht obj[key], wenn key eine string-Variable statt eines Literals ist, und auch keine Kopie, die vor der Prüfung angelegt wurde.
• Callbacks und Neuzuweisung. In einem Callback behält eine eingeengte let ihr Narrowing nur, wenn sie nach dem Erzeugen des Callbacks nicht erneut zugewiesen wird. Eine const oder ein Parameter, der nie neu zugewiesen wird, bleibt eingeengt.
• Prüfungen in Hilfsfunktionen. Eine Funktion isString(x: unknown): boolean sagt dem Compiler nichts. Gib ihr einen Type Predicate als Rückgabetyp, x is string, dann engen Aufrufe davon ein wie typeof.

// This does not compile: x is reassigned after the callback, so the callback loses the narrowing.
function run(flag: boolean): void {
  let x: string | undefined = flag ? "ready" : undefined;
  if (x !== undefined) {
    [1, 2].forEach(() => console.log(x.length));
  }
  x = undefined;
}

run(true);

Der Compiler meldet index.ts(5,38): error TS18048: 'x' is possibly 'undefined'. Der Callback könnte später laufen, nach x = undefined. Lösche diese letzte Zuweisung (oder kopiere den Wert im if in eine const), dann kompiliert es und gibt zweimal 5 aus.

Eine Hilfsfunktion, die boolean zurückgibt, lässt sich reparieren, indem sie deklariert, was sie beweist. Genau das ist ein Type Guard:

function isString(value: unknown): value is string {
  return typeof value === "string";
}

Seit TypeScript 5.5 leitet der Compiler solche Predicates für einfache Arrow Functions ab, deshalb gibt list.filter((x) => x !== undefined) jetzt ein Array ohne undefined zurück.