Tratamento exaustivo de erros com uniões discriminadas
Escreva manipuladores exaustivos para uniões discriminadas usando switch+never, utilitários auxiliares e verificações de cobertura em tempo de compilação entre módulos.
Tratamento exaustivo de erros com uniões discriminadas é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 2 de 2. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 2 aulas no total.
Introdução
Objetivo: Garantir que todos os membros da união sejam tratados. Você usará switch + never, um pequeno utilitário exhaustiveCheck e verá como manter a cobertura entre arquivos.
- Discriminantes (campos tag)
- Estruturas switch exaustivas
- Padrões padrão de falha imediata
União discriminada
Uma união discriminada tem uma tag compartilhada (aqui, kind). Cada variante contém seus próprios dados.
export type Payment =
| { kind: "Card"; last4: string }
| { kind: "Cash" }
| { kind: "Wire"; iban: string }Switch + never
O default atribui p a never. Se você adicionar uma nova variante mais tarde, o compilador emitirá um erro até que você a trate.
export function describe(p: Payment): string {
switch (p.kind) {
case "Card": return `Card ••••${p.last4}`
case "Cash": return "Cash"
case "Wire": return `Wire ${p.iban}`
default: {
const _exhaustive: never = p
return _exhaustive
}
}
}Auxiliar exhaustiveCheck
Use um pequeno auxiliar para tornar a intenção evidente. O parâmetro never transforma os casos não tratados em um erro de tipo, não apenas em uma exceção em tempo de execução.
export function exhaustiveCheck(x: never): never {
throw new Error(`Unhandled case: ${JSON.stringify(x)}`)
}
export function pay(p: Payment): string {
switch (p.kind) {
case "Card": return "charged card"
case "Cash": return "took cash"
case "Wire": return "initiated wire"
default: return exhaustiveCheck(p)
}
}Cobertura entre módulos
Quando as uniões são definidas em um arquivo e tratadas em outro, adicionar um ramo ainda interrompe as compilações até que todas as estruturas switch sejam atualizadas — exatamente o que queremos.
// errors.ts
export type AppError =
| { tag: "Auth"; reason: "Unauthorized" | "Forbidden" }
| { tag: "NotFound"; resource: string }
| { tag: "Conflict"; resource: string }
// handler.ts
import type { AppError } from "./errors"
import { exhaustiveCheck } from "./exhaustive"
export function toStatus(e: AppError): number {
switch (e.tag) {
case "Auth": return e.reason === "Unauthorized" ? 401 : 403
case "NotFound": return 404
case "Conflict": return 409
default: return exhaustiveCheck(e)
}
}Dicas e armadilhas
Dicas:
- Prefira tags de literais de string (por exemplo,
tag/kind). - Mantenha as variantes pequenas; componha os dados por meio de objetos aninhados em vez de uniões enormes.
- Nunca use
defaultsem uma proteção denever; isso oculta casos ausentes.
Verificação de exaustividade
Verificação rápida: O que impõe o tratamento exaustivo?
Recapitulação
Recapitulação: Use um discriminante, escreva um switch e, no ramo padrão, atribua a never (ou chame exhaustiveCheck) para garantir a cobertura completa à medida que as uniões evoluem.
Aprenda TypeScript com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 101
- Aulas
- 352
Perguntas Frequentes
A aula “Tratamento exaustivo de erros com uniões discriminadas” é grátis?
Sim — o texto completo de “Tratamento exaustivo de erros com uniões discriminadas” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 2 aulas no total.
O que vou aprender em “Tratamento exaustivo de erros com uniões discriminadas”?
Escreva manipuladores exaustivos para uniões discriminadas usando switch+never, utilitários auxiliares e verificações de cobertura em tempo de compilação entre módulos. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar TypeScript Academy?
Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 2.
Quanto tempo leva a aula “Tratamento exaustivo de erros com uniões discriminadas”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de TypeScript Academy?
Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Tipos no estilo Result/Either
- Tratamento exaustivo de erros com uniões discriminadas