Docs executáveis de TypeScript: Switch

Q: Como escrever uma instrução switch no TypeScript?

Exatamente como no JavaScript: switch (value) { case "a": ...; break; default: ... }. Os cases são comparados com ===. O TypeScript acrescenta verificações: um valor de case que nunca pode corresponder ao tipo avaliado é erro (TS2678), e dentro de cada case a variável avaliada é estreitada para aquele case.

Q: Como tornar um switch exaustivo no TypeScript?

Adicione um default que atribui o valor a uma variável do tipo never: default: { const unreachable: never = value; throw new Error(...) }. Quando todos os membros da union são tratados, o valor ali é never e compila. Quando falta um, o compilador aponta o membro ausente (TS2322).

Q: Como tratar vários cases com o mesmo código em um switch no TypeScript?

Empilhe os labels sem código entre eles: case "sat": case "sun": return "weekend";. Cases vazios passam direto para o próximo. A opção noFallthroughCasesInSwitch só aponta cases que têm código e não têm break nem return, então labels empilhados continuam permitidos.

Q: switch (true) faz narrowing de tipos no TypeScript?

Sim, desde o TypeScript 5.3. Em switch (true) { case typeof x === "string": ... }, x é estreitado para string dentro daquele case, assim como seria em um if. É uma alternativa legível a uma sequência de if/else if com verificações de faixa ou de tipo.

Uma instrução switch em TypeScript é o switch do JavaScript com verificação de tipos. Ele compara um valor com cada case usando ===, executa o ramo correspondente e para em break ou return. O TypeScript estreita o valor avaliado dentro de cada case e pode verificar se todos os valores possíveis foram tratados.

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

Labels empilhados (case "sat": case "sun":) compartilham um ramo. return encerra a função, então não é preciso break depois dele.

Sintaxe

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
}

A comparação usa igualdade estrita, ===: case 1 não corresponde à string "1".
Sem break, return ou throw, a execução continua no case seguinte (fallthrough).
default é opcional e pode ficar em qualquer posição, embora o normal seja no fim.
Um valor de case que o TypeScript consegue provar que nunca corresponde é o erro TS2678. Para um parâmetro do tipo "a" | "b", case "c": gera Type '"c"' is not comparable to type '"a" | "b"'., o que pega erros de digitação nos labels.

Narrowing dentro de cada case

Em cada case, o TypeScript sabe qual valor correspondeu e estreita o tipo. Isso é mais útil com uma discriminated union: faça o switch na propriedade de tag compartilhada, e cada case enxerga a variante correspondente com suas próprias propriedades.

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 só compila no case "circle". Fora dele, shape pode ser um retângulo, que não tem radius. Não há default, e mesmo assim a função é aceita como retornando number, porque o TypeScript vê que os três cases cobrem todos os valores de kind. Mais padrões construídos sobre isso estão na página de discriminated unions.

Switch exaustivo com never

A função acima deixa de compilar se uma quarta forma for adicionada sem um case (TS2366, falta de return). Isso só funciona quando a função retorna um valor. Para uma garantia que também funcione em código void e dê uma mensagem mais clara, adicione um default que atribui o valor a 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'.

Depois dos cases tratados, o único tipo que sobra para shape é a variante do triângulo, que não pode ser atribuída a never. O erro diz exatamente o que está faltando. Adicione case "triangle": return (shape.base * shape.height) / 2; e o default passa a ver never, então o bloco compila e imprime 9. O throw continua protegendo contra dados ruins em tempo de execução, como um kind vindo de um JSON que os tipos não previam.

Muitos projetos colocam essa verificação em uma função auxiliar:

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

A mesma técnica funciona com enums: faça o switch no valor do enum e passe-o para assertNever no default.

switch (true) para faixas e condições

switch compara valores, então faixas exigem um truque: faça o switch em true e escreva uma condição em cada case. Desde o TypeScript 5.3, essas condições estreitam tipos do mesmo jeito que as instruções 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

Os cases são testados em ordem, então coloque os mais específicos primeiro. Se isso fica mais legível que if / else if é questão de gosto; o comportamento é o mesmo.

Fallthrough e break

Um case com código, mas sem break, return ou throw, passa direto para o case seguinte. Isso quase sempre é um bug. A opção de compilador noFallthroughCasesInSwitch (que não faz parte de strict) transforma isso no erro TS7029, Fallthrough case in switch., mas continua permitindo labels vazios empilhados.

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

Um fallthrough proposital como este funciona, mas com noFallthroughCasesInSwitch ativada ele precisa ser reescrito, por exemplo com verificações if separadas. Em geral isso fica mais claro de qualquer forma.

Variáveis dentro dos cases

O corpo inteiro do switch é um único bloco, então um const declarado em um case é visível nos outros (e declarar de novo é erro). Envolva um case em chaves para dar a ele seu próprio escopo:

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

Sem as chaves, o segundo const unit é o erro de compilação TS2451, Cannot redeclare block-scoped variable 'unit'.

switch vs busca em objeto

Quando cada case só mapeia um valor para outro, um objeto tipado com Record é mais curto, e o TypeScript verifica se todas as chaves estão presentes:

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]

Omitir uma chave é erro de compilação, o que dá a mesma exaustividade de uma verificação com never. Use switch para cases que executam lógicas diferentes, estreitam variantes de uma union ou retornam antes.

Perguntas frequentes

Como escrever uma instrução switch no TypeScript?

Exatamente como no JavaScript: switch (value) { case "a": ...; break; default: ... }. Os cases são comparados com ===. O TypeScript acrescenta verificações: um valor de case que nunca pode corresponder ao tipo avaliado é erro (TS2678), e dentro de cada case a variável avaliada é estreitada para aquele case.

Como tornar um switch exaustivo no TypeScript?

Adicione um default que atribui o valor a uma variável do tipo never: default: { const unreachable: never = value; throw new Error(...) }. Quando todos os membros da union são tratados, o valor ali é never e compila. Quando falta um, o compilador aponta o membro ausente (TS2322).

Como tratar vários cases com o mesmo código em um switch no TypeScript?

Empilhe os labels sem código entre eles: case "sat": case "sun": return "weekend";. Cases vazios passam direto para o próximo. A opção noFallthroughCasesInSwitch só aponta cases que têm código e não têm break nem return, então labels empilhados continuam permitidos.

switch (true) faz narrowing de tipos no TypeScript?

Sim, desde o TypeScript 5.3. Em switch (true) { case typeof x === "string": ... }, x é estreitado para string dentro daquele case, assim como seria em um if. É uma alternativa legível a uma sequência de if/else if com verificações de faixa ou de tipo.

Conceitos relacionados