TypeScript switch case: Narrowing und vollständige Prüfung

Eine switch-Anweisung in TypeScript ist das switch von JavaScript mit Typprüfung. Sie vergleicht einen Wert mit === gegen jeden case, führt den passenden Zweig aus und hört bei break oder return auf. TypeScript engt den geprüften Wert in jedem case ein und kann prüfen, dass jeder mögliche Wert behandelt wird.

type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";

function describe(day: Weekday): string {
    switch (day) {
        case "sat":
        case "sun":
            return "weekend";
        case "fri":
            return "almost weekend";
        default:
            return "workday";
    }
}

console.log(describe("sun")); // weekend
console.log(describe("fri")); // almost weekend
console.log(describe("tue")); // workday

Gestapelte Labels (case "sat": case "sun":) teilen sich einen Zweig. return beendet die Funktion, danach ist also kein break nötig.

Syntax

switch (expression) {
    case value1:
        // runs when expression === value1
        break;
    case value2:
    case value3:
        // runs for value2 or value3
        break;
    default:
        // runs when nothing else matched
}

• Der Vergleich nutzt strikte Gleichheit, ===: case 1 passt nicht auf den String "1".
• Ohne break, return oder throw läuft die Ausführung in den nächsten case weiter (Fallthrough).
• default ist optional und kann überall stehen, üblich ist aber am Ende.
• Ein case-Wert, von dem TypeScript beweisen kann, dass er nie passt, ist der Fehler TS2678. Bei einem Parameter vom Typ "a" | "b" meldet case "c": den Text Type '"c"' is not comparable to type '"a" | "b"'., was Tippfehler in case-Labels abfängt.

Narrowing in jedem case

In jedem case weiß TypeScript, welcher Wert gepasst hat, und engt den Typ ein. Am nützlichsten ist das bei einer Discriminated Union: Du prüfst im switch die gemeinsame Tag-Eigenschaft, und jeder case sieht die passende Variante mit ihren eigenen Eigenschaften.

type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "rect"; width: number; height: number }
    | { kind: "square"; side: number };

function area(shape: Shape): number {
    switch (shape.kind) {
        case "circle":
            return Math.PI * shape.radius ** 2; // shape: circle variant
        case "rect":
            return shape.width * shape.height;  // shape: rect variant
        case "square":
            return shape.side ** 2;             // shape: square variant
    }
}

console.log(area({ kind: "circle", radius: 1 }).toFixed(2)); // 3.14
console.log(area({ kind: "rect", width: 2, height: 3 }));    // 6
console.log(area({ kind: "square", side: 4 }));              // 16

shape.radius kompiliert nur im case "circle". Außerhalb davon könnte shape ein Rechteck sein, das kein radius hat. Es gibt kein default, und die Funktion besteht trotzdem die Typprüfung mit Rückgabetyp number, weil TypeScript sieht, dass die drei cases jede kind abdecken. Weitere Muster darauf aufbauend stehen auf der Seite zu Discriminated Unions.

Vollständiger switch mit never

Die Funktion oben kompiliert nicht mehr, wenn eine vierte Form ohne case hinzukommt (TS2366, ein fehlendes return). Das funktioniert nur, wenn die Funktion einen Wert zurückgibt. Für eine Garantie, die auch in void-Code greift und eine klarere Meldung liefert, fügst du ein default hinzu, das den Wert never zuweist:

// This does not compile: the "triangle" case is missing.
type Shape =
    | { kind: "circle"; radius: number }
    | { kind: "square"; side: number }
    | { kind: "triangle"; base: number; height: number };

function area(shape: Shape): number {
    switch (shape.kind) {
        case "circle":
            return Math.PI * shape.radius ** 2;
        case "square":
            return shape.side ** 2;
        default: {
            const unreachable: never = shape;
            throw new Error(`Unknown shape: ${JSON.stringify(unreachable)}`);
        }
    }
}

console.log(area({ kind: "square", side: 3 }));

index.ts(14,19): error TS2322: Type '{ kind: "triangle"; base: number; height: number; }' is not assignable to type 'never'.

Nach den behandelten cases bleibt für shape nur noch die Dreiecksvariante übrig, und die lässt sich never nicht zuweisen. Der Fehler nennt genau, was fehlt. Ergänze case "triangle": return (shape.base * shape.height) / 2;, dann sieht das default den Typ never, und der Block kompiliert und gibt 9 aus. Das throw schützt zur Laufzeit weiterhin vor fehlerhaften Daten, etwa einer kind aus JSON, die die Typen nicht vorhergesehen haben.

Viele Codebasen verpacken die Prüfung in eine Hilfsfunktion:

function assertNever(value: never): never {
    throw new Error(`Unhandled value: ${JSON.stringify(value)}`);
}

type Status = "idle" | "loading" | "done";

function label(status: Status): string {
    switch (status) {
        case "idle": return "Waiting";
        case "loading": return "Loading...";
        case "done": return "Finished";
        default: return assertNever(status);
    }
}

console.log(label("loading")); // Loading...

Dieselbe Technik funktioniert mit Enums: Prüfe im switch den Enum-Wert und übergib ihn im default an assertNever.

switch (true) für Bereiche und Bedingungen

switch vergleicht Werte, Bereiche brauchen also einen Trick: Prüfe auf true und schreibe in jeden case eine Bedingung. Seit TypeScript 5.3 engen diese Bedingungen Typen genauso ein wie if-Anweisungen.

function grade(score: number): string {
    switch (true) {
        case score >= 90: return "A";
        case score >= 80: return "B";
        case score >= 70: return "C";
        default: return "F";
    }
}

function format(value: string | number | boolean): string {
    switch (true) {
        case typeof value === "string":
            return value.toUpperCase();   // value: string
        case typeof value === "number":
            return value.toFixed(2);      // value: number
        default:
            return value ? "yes" : "no";  // value: boolean
    }
}

console.log(grade(85), grade(42));                     // B F
console.log(format("hi"), format(3.14159), format(true)); // HI 3.14 yes

Die cases werden der Reihe nach geprüft, also kommt der spezifischste zuerst. Ob das besser lesbar ist als if / else if, ist Geschmackssache; das Verhalten ist dasselbe.

Fallthrough und break

Ein case mit Code, aber ohne break, return oder throw fällt in den nächsten case durch. Das ist fast immer ein Fehler. Die Compileroption noFallthroughCasesInSwitch (nicht Teil von strict) macht daraus den Fehler TS7029, Fallthrough case in switch., erlaubt aber weiterhin gestapelte leere Labels.

function permissions(role: "admin" | "editor" | "viewer"): string[] {
    const result: string[] = [];
    switch (role) {
        case "admin":
            result.push("delete");
        // intentional fallthrough: admins can also edit
        case "editor":
            result.push("edit");
        // intentional fallthrough: editors can also view
        case "viewer":
            result.push("view");
    }
    return result;
}

console.log(permissions("admin"));  // [ 'delete', 'edit', 'view' ]
console.log(permissions("viewer")); // [ 'view' ]

Absichtlicher Fallthrough wie dieser funktioniert, muss mit aktivem noFallthroughCasesInSwitch aber umgeschrieben werden, zum Beispiel mit getrennten if-Prüfungen. Das ist meist ohnehin klarer.

Variablen in cases

Der gesamte Rumpf von switch ist ein Block, eine in einem case deklarierte const ist also in den anderen sichtbar (und eine erneute Deklaration ist ein Fehler). Setze einen case in geschweifte Klammern, um ihm einen eigenen Scope zu geben:

function price(item: "tea" | "cake", qty: number): number {
    switch (item) {
        case "tea": {
            const unit = 2.5;
            return unit * qty;
        }
        case "cake": {
            const unit = 4; // fine: a different block
            return unit * qty;
        }
    }
}

console.log(price("tea", 2), price("cake", 3)); // 5 12

Ohne die Klammern ist das zweite const unit der Compilerfehler TS2451, Cannot redeclare block-scoped variable 'unit'.

switch vs Objekt-Lookup

Wenn jeder case nur einen Wert auf einen anderen abbildet, ist ein mit Record typisiertes Objekt kürzer, und TypeScript prüft, dass jeder Schlüssel vorhanden ist:

type Level = "debug" | "info" | "warn" | "error";

const icons: Record<Level, string> = {
    debug: "[D]",
    info: "[I]",
    warn: "[W]",
    error: "[E]",
};

console.log(icons.warn, icons["error"]); // [W] [E]

Einen Schlüssel wegzulassen ist ein Compilerfehler, was dieselbe Vollständigkeit wie eine never-Prüfung ergibt. Behalte switch für Fälle, die unterschiedliche Logik ausführen, Union-Varianten einengen oder früh zurückkehren.