Исполняемые доки TypeScript: Оператор switch

Q: Как написать оператор switch в TypeScript?

Точно так же, как в JavaScript: switch (value) { case "a": ...; break; default: ... }. Значения case сравниваются через ===. TypeScript добавляет проверки: значение case, которое никогда не совпадёт с типом выражения, даёт ошибку (TS2678), а внутри каждого case переменная сужается до этого случая.

Q: Как сделать switch исчерпывающим в TypeScript?

Добавьте default, который присваивает значение переменной типа never: default: { const unreachable: never = value; throw new Error(...) }. Если обработаны все члены объединения, значение там имеет тип never, и код компилируется. Если какой-то пропущен, компилятор назовёт пропущенный член (TS2322).

Q: Как обработать несколько case одним кодом в switch TypeScript?

Поставьте метки подряд без кода между ними: case "sat": case "sun": return "weekend";. Пустые case проваливаются в следующий. Опция noFallthroughCasesInSwitch сообщает только о case, в которых есть код и нет break или return, так что метки подряд остаются разрешены.

Q: Сужает ли switch (true) типы в TypeScript?

Да, начиная с TypeScript 5.3. В switch (true) { case typeof x === "string": ... } внутри этого case x сужается до string, так же как в if. Это читаемая альтернатива цепочке if/else if с проверками диапазонов или типов.

Оператор switch в TypeScript это switch из JavaScript с проверкой типов. Он сравнивает значение с каждым case через ===, выполняет совпавшую ветку и останавливается на break или return. TypeScript сужает значение внутри каждого case и умеет проверять, что обработано каждое возможное значение.

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

Метки подряд (case "sat": case "sun":) разделяют одну ветку. return завершает функцию, поэтому break после него не нужен.

Синтаксис

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
}

Сравнение использует строгое равенство, ===: case 1 не совпадёт со строкой "1".
Без break, return или throw выполнение продолжается в следующем case (проваливание).
default необязателен и может стоять где угодно, хотя обычно его ставят последним.
Значение case, про которое TypeScript может доказать, что оно никогда не совпадёт, даёт ошибку TS2678. Для параметра с типом "a" | "b" строка case "c": выдаёт Type '"c"' is not comparable to type '"a" | "b"'., и это ловит опечатки в метках case.

Сужение внутри каждого case

В каждом case TypeScript знает, какое значение совпало, и сужает тип. Особенно полезно это с размеченным объединением: делайте switch по общему свойству-метке, и каждый case увидит соответствующий вариант с его собственными свойствами.

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 компилируется только в case "circle". За его пределами shape может оказаться прямоугольником, у которого нет radius. default отсутствует, а функция всё равно проходит проверку как возвращающая number, потому что TypeScript видит, что три case покрывают каждое значение kind. Другие приёмы на этой основе описаны на странице размеченные объединения.

Исчерпывающий switch через never

Функция выше перестанет компилироваться, если добавить четвёртую фигуру без case (TS2366, пропущенный return). Но это работает, только когда функция возвращает значение. Чтобы гарантия работала и в void-коде и давала более понятное сообщение, добавьте default, который присваивает значение типу never:

// 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'.

После обработанных case для shape остаётся только вариант треугольника, а его нельзя присвоить never. Ошибка называет ровно то, что пропущено. Добавьте case "triangle": return (shape.base * shape.height) / 2;, и default увидит never, так что блок скомпилируется и напечатает 9. throw по-прежнему защищает от плохих данных во время выполнения, например от kind из JSON, которого типы не предусмотрели.

Во многих кодовых базах проверку оборачивают во вспомогательную функцию:

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...

Тот же приём работает для enum: делайте switch по значению enum и передавайте его в assertNever в default.

switch (true) для диапазонов и условий

switch сравнивает значения, поэтому для диапазонов нужен трюк: switch по true и условие в каждом case. Начиная с TypeScript 5.3 такие условия сужают типы так же, как операторы if.

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

Case проверяются по порядку, поэтому самые конкретные ставьте первыми. Читается ли это лучше, чем if / else if, дело вкуса; поведение одинаковое.

Проваливание и break

Case с кодом, но без break, return или throw проваливается в следующий case. Почти всегда это ошибка. Опция компилятора noFallthroughCasesInSwitch (не входит в strict) превращает это в ошибку TS7029, Fallthrough case in switch., но по-прежнему разрешает пустые метки подряд.

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' ]

Такое намеренное проваливание работает, но с включённой noFallthroughCasesInSwitch его придётся переписать, например отдельными проверками if. Обычно так и понятнее.

Переменные внутри case

Всё тело switch это один блок, поэтому const, объявленная в одном case, видна в остальных (а повторное объявление даёт ошибку). Оберните case в фигурные скобки, чтобы дать ему собственную область видимости:

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

Без скобок второе const unit даёт ошибку компиляции TS2451, Cannot redeclare block-scoped variable 'unit'.

switch или поиск по объекту

Когда каждый case просто отображает одно значение в другое, объект с типом Record короче, и TypeScript проверяет, что присутствует каждый ключ:

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]

Пропуск ключа даёт ошибку компиляции, то есть ту же полноту, что и проверка через never. Оставьте switch для случаев, где выполняется разная логика, сужаются варианты объединения или нужен ранний возврат.

Часто задаваемые вопросы

Как написать оператор switch в TypeScript?

Точно так же, как в JavaScript: switch (value) { case "a": ...; break; default: ... }. Значения case сравниваются через ===. TypeScript добавляет проверки: значение case, которое никогда не совпадёт с типом выражения, даёт ошибку (TS2678), а внутри каждого case переменная сужается до этого случая.

Как сделать switch исчерпывающим в TypeScript?

Добавьте default, который присваивает значение переменной типа never: default: { const unreachable: never = value; throw new Error(...) }. Если обработаны все члены объединения, значение там имеет тип never, и код компилируется. Если какой-то пропущен, компилятор назовёт пропущенный член (TS2322).

Как обработать несколько case одним кодом в switch TypeScript?

Поставьте метки подряд без кода между ними: case "sat": case "sun": return "weekend";. Пустые case проваливаются в следующий. Опция noFallthroughCasesInSwitch сообщает только о case, в которых есть код и нет break или return, так что метки подряд остаются разрешены.

Сужает ли switch (true) типы в TypeScript?

Да, начиная с TypeScript 5.3. В switch (true) { case typeof x === "string": ... } внутри этого case x сужается до string, так же как в if. Это читаемая альтернатива цепочке if/else if с проверками диапазонов или типов.

Связанные концепции