Top & Bottom Types no TypeScript: any, unknown, never e void
Compreenda os extremos da hierarquia de tipos do TypeScript: entenda por que o any desativa a segurança do compilador, como o unknown oferece uma alternativa segura para dados externos, o papel do void em funções e como o never viabiliza checagens exaustivas invioláveis.
📑 Índice do Conteúdo
1. A Teoria dos Tipos: A Pirâmide Hierárquica do TypeScript
Para dominar o sistema de tipos do TypeScript em nível sênior, é essencial enxergar os tipos não como rótulos isolados, mas como uma hierarquia de conjuntos matemáticos organizada em uma pirâmide:
- Top Types (Superconjuntos Universais no Topo): Tipos que englobam todos os valores possíveis da linguagem. Qualquer dado (string, número, função, objeto ou array) pode ser atribuído a um Top Type. No TypeScript, existem dois Top Types:
anyeunknown. - Tipos Intermediários: Todos os tipos comuns de domínio que utilizamos no dia a dia: tipos primitivos (
string,number,boolean), uniões, classes, interfaces e arrays. - Bottom Types (Subconjuntos Vazios na Base): Tipos que não contêm nenhum valor possível. Nenhum valor de qualquer tipo pode ser atribuído a um Bottom Type. No TypeScript, o Bottom Type é o
never.
2. O Tipo any: A Válvula de Escape Perigosa
O tipo any instrui o compilador a desistir completamente da verificação estática de tipos. Quando uma variável é tipada como any, você pode atribuir qualquer valor a ela, acessar qualquer propriedade arbitrária e invocar qualquer método, exista ele ou não:
TypeScript
let dadoInseguro: any = "Texto inicial";
dadoInseguro = 100; // Válido
dadoInseguro = { usuario: "Lucas" }; // Válido
// O TypeScript NÃO emite erro de compilação na linha abaixo,
// mas em tempo de execução no navegador disparará:
// Uncaught TypeError: dadoInseguro.metodoInexistente is not a function
dadoInseguro.metodoInexistente();
any é o equivalente a voltar ao JavaScript Vanilla sem nenhuma proteção. O any “contamina” o código ao seu redor, propagando a ausência de tipagem para outras variáveis e reintroduzindo bugs graves de produção. Use-o exclusivamente em migrações graduais de sistemas legados.
3. O Tipo unknown: O Top Type com Segurança Estrita (Type-Safe)
Introduzido no TypeScript 3.0, o unknown é a contraparte segura e profissional do any. Assim como o any, você pode atribuir qualquer valor a uma variável do tipo unknown. No entanto, o TypeScript impede que você leia propriedades, execute métodos ou repasse a variável até que você comprove o seu tipo real através de estreitamento (Type Narrowing):
TypeScript
let respostaServidor: unknown = "Resposta da API com sucesso";
// ❌ ERRO DE COMPILAÇÃO TS18046:
// 'respostaServidor' is of type 'unknown'.
// console.log(respostaServidor.toUpperCase());
// ✅ CORRETO: Comprove o tipo antes de utilizar (Type Narrowing):
if (typeof respostaServidor === "string") {
// Aqui dentro, o TypeScript sabe com 100% de certeza que é string!
console.log(respostaServidor.toUpperCase()); // Seguro e funcional!
}
4. O Tipo void: Ausência Intencional de Retorno
O tipo void é utilizado quase que exclusivamente como tipo de retorno de funções que executam ações, mutações ou efeitos colaterais (side effects), mas que não produzem nenhum resultado observável para o chamador:
TypeScript
function registrarLogAuditoria(mensagem: string): void {
console.log(`[AUDIT] ${new Date().toISOString()}: ${mensagem}`);
// Sem declaração "return" ou return sem valor
}
// Se alguém tentar capturar o resultado para usar em cálculos, o compilador avisa:
const resultado = registrarLogAuditoria("Usuário logado");
// Erro TS1345 se tentar usar "resultado" como número ou string!
5. O Tipo never: O Bottom Type Inalcançável
O never representa um estado que nunca pode ocorrer. Ele surge em dois cenários fundamentais da engenharia de software:
Cenário 1: Funções que Nunca Chegam ao Fim Normalmente
Funções que lançam exceções intencionais ou que executam loops infinitos nunca produzem um retorno bem-sucedido:
TypeScript
// A função lança erro e interrompe o fluxo de execução da thread:
function lancarErroCritico(mensagem: string): never {
throw new Error(`[CRITICAL EXCEPTION] ${mensagem}`);
}
// Loop infinito de monitoramento:
function loopProcessamentoMensagens(): never {
while (true) {
// Escuta eventos indefinidamente sem retorno
}
}
Cenário 2: Checagem Exaustiva (Exhaustiveness Checking)
O uso mais elegante do never é no bloco default de estruturas condicionais para garantir que todas as opções possíveis de uma união de tipos foram tratadas em tempo de compilação:
TypeScript
type StatusPedido = "pendente" | "pago" | "cancelado";
function renderizarStatus(status: StatusPedido): string {
switch (status) {
case "pendente":
return "Aguardando pagamento do cliente.";
case "pago":
return "Pedido confirmado e em separação.";
case "cancelado":
return "Pedido cancelado pelo lojista.";
default:
// Se um desenvolvedor adicionar "enviado" ao type StatusPedido no futuro
// e esquecer de tratar aqui, a linha abaixo acusará ERRO DE COMPILAÇÃO!
const checagem: never = status;
return checagem;
}
}
6. Exemplo Prático Integrado: Parser Seguro de Payload de API
Veja como integrar unknown, void e never em um módulo real de consumo seguro de dados externos:
TypeScript
// 1. Função de tratamento de erro fatal tipada com retorno "never"
function dispararFalhaSeguranca(detalhe: string): never {
throw new Error(`[SECURITY ALERT] Falha no payload: ${detalhe}`);
}
// 2. Função de notificação com retorno "void"
function registrarEvento(evento: string): void {
console.log(`[EVENTO AUDITADO] -> ${evento}`);
}
// 3. Processador que recebe dado externo arbitrário como "unknown" (Type-Safe)
function processarRespostaExterna(dadosRecebidos: unknown): void {
// Validação estrita: se for nulo ou não for objeto, rejeita
if (typeof dadosRecebidos !== "object" || dadosRecebidos === null) {
dispararFalhaSeguranca("O payload recebido não é um objeto JSON válido.");
}
// Type Narrowing seguro verificando propriedades existentes
if ("codigoTransacao" in dadosRecebidos && "valor" in dadosRecebidos) {
const payload = dadosRecebidos as { codigoTransacao: unknown; valor: unknown };
if (typeof payload.codigoTransacao === "string" && typeof payload.valor === "number") {
registrarEvento(`Transação ${payload.codigoTransacao} processada no valor de R$ ${payload.valor.toFixed(2)}.`);
return;
}
}
dispararFalhaSeguranca("Campos obrigatórios ausentes ou com tipos incompatíveis.");
}
// Teste de execução com payload válido
processarRespostaExterna({ codigoTransacao: "TX-99014", valor: 350.00 });
7. Tabela Comparativa: any vs. unknown vs. void vs. never
| Tipo | Posição na Hierarquia | Aceita Qualquer Valor? | Permite Chamar Métodos Diretos? | Uso Recomendado |
|---|---|---|---|---|
any |
Top Type (Inseguro) | Sim | Sim (Desativa o compilador) | Migrações graduais de código JS legado. |
unknown |
Top Type (Seguro) | Sim | Não (Exige narrowing prévio) | Dados de APIs externas, JSON.parse e inputs do usuário. |
void |
Intermediário | Apenas undefined |
Não aplicável | Funções que executam procedimentos sem valor de retorno. |
never |
Bottom Type (Base) | Não (Nenhum valor aceito) | Não aplicável | Funções com throw/loop infinito e checagem exaustiva de switch. |
any por unknown ao consumir dados de origens externas (como respostas da fetch() ou dados parseados de JSON.parse()). Com unknown, o compilador obriga os desenvolvedores a validar os dados antes do uso, eliminando mais de 90% das falhas inesperadas em produção.
Aplique o que você aprendeu nesta lição
Utilize nossas ferramentas online gratuitas para experimentar os conceitos ou teste o código ao vivo no Playground IDE.
Editor de Códigos Web Online
Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.
Abrir Ferramenta OnlinePlayground Web Online
Escreva seu código HTML, CSS ou JavaScript e veja o resultado renderizado ao vivo no navegador com zero configuração.
⚡ Codificar no Playground IDE