Type Guards Nativos: typeof, instanceof e o Operador in no TypeScript
Para tomar decisões seguras em tempo de execução sem abrir mão da tipagem estática, o TypeScript aproveita operadores nativos da própria linguagem JavaScript como guardas de tipo. Aprenda a dominar o trio fundamental typeof, instanceof e o operador in, desarmando armadilhas clássicas como a do typeof null.
📑 Índice do Conteúdo
1. O Que São Type Guards Nativos
Um Type Guard (Guarda de Tipo) é uma expressão executável em tempo de execução que testa a natureza de um dado e garante ao compilador que, dentro daquele ramo condicional, a variável possui um tipo específico e seguro.
O JavaScript nativo oferece três operadores consagrados que o TypeScript reconhece de imediato para afunilar tipos sem necessidade de plugins ou utilitários externos: typeof, instanceof e in.
2. Guarda 1: O Operador typeof
O operador typeof é ideal para inspecionar tipos primitivos. Ele retorna uma string contendo um dos valores fundamentais do motor JS: "string", "number", "bigint", "boolean", "symbol", "undefined", "object" ou "function".
function multiplicarOuRepetir(valor: string | number, vezes: number): string | number {
if (typeof valor === "number") {
// ✨ O TypeScript sabe que é NUMBER:
return valor * vezes;
}
// ✨ Fora do if, o TypeScript sabe que sobrou apenas STRING:
return valor.repeat(vezes);
}
console.log(multiplicarOuRepetir(10, 3)); // 30
console.log(multiplicarOuRepetir("TS-", 3)); // ___WZW_STR_1___
typeof null === "object": Devido a um bug de implementação do JavaScript em 1995 que nunca pôde ser corrigido por retrocompatibilidade da web, o comando typeof null retorna a string "object"! Se você tiver uma união Usuario | null e fizer apenas if (typeof usuario === "object"), o valor null passará pelo filtro e quebrará sua aplicação ao tentar acessar usuario.nome. Sempre verifique contra nulidade antes: if (usuario !== null && typeof usuario === "object").
3. Guarda 2: O Operador instanceof
Enquanto o typeof lida com primitivos, o operador instanceof verifica se a função construtora de uma classe existe na cadeia de protótipos de um objeto. É a ferramenta perfeita para distinguir classes e instâncias complexas da API do JavaScript, como Date, RegExp, nós do DOM e Error:
function formatarDataIso(data: Date | string): string {
if (data instanceof Date) {
// ✨ Dentro deste bloco, "data" é garantidamente um objeto Date:
return data.toISOString();
}
// ✨ Aqui, data é estritamente uma string:
return new Date(data).toISOString();
}
Tratamento Seguro de Exceções com instanceof Error
Nas versões modernas do TypeScript, com a flag useUnknownInCatchVariables: true ativada por padrão, a variável de erro capturada em um bloco catch possui o tipo estrito unknown (já que em JavaScript é possível disparar qualquer coisa via throw "erro em texto" ou throw 404).
O instanceof Error é a solução padrão e profissional para lidar com exceções de forma tipada:
async function carregarDadosServidor(url: string) {
try {
const resposta = await fetch(url);
if (!resposta.ok) {
throw new Error(`Falha HTTP com status: ${resposta.status}`);
}
return await resposta.json();
} catch (erro: unknown) {
// ❌ erro.message geraria erro de compilação: Object is of type 'unknown'!
// ✅ Type Guard seguro com instanceof:
if (erro instanceof Error) {
console.error("Mensagem técnica do erro:", erro.message);
console.error("Stack trace:", erro.stack);
} else {
console.error("Erro inesperado sem estrutura nativa:", String(erro));
}
}
}
4. Guarda 3: O Operador in (Existência de Propriedades)
E quando temos uniões de objetos ou interfaces que não compartilham uma classe comum nem uma tag discriminante, mas possuem propriedades com nomes distintos? O operador in verifica a existência da chave no objeto sem lançar exceções:
interface Administrador {
id: string;
nome: string;
permissoesTotais: string[];
}
interface ColaboradorComum {
id: string;
nome: string;
departamento: string;
}
type MembroEquipe = Administrador | ColaboradorComum;
function autenticarAcesso(membro: MembroEquipe) {
// Testamos se a chave exclusiva "permissoesTotais" existe no objeto:
if ("permissoesTotais" in membro) {
// ✨ O TypeScript afunila "membro" para Administrador:
console.log(`Admin logado: ${membro.nome}. Acesso a: ${membro.permissoesTotais.join(", ")}`);
} else {
// ✨ O TypeScript afunila "membro" para ColaboradorComum:
console.log(`Colaborador logado: ${membro.nome} do setor ${membro.departamento}`);
}
}
5. Quadro Comparativo: Qual Guarda Nativo Escolher?
| Guarda de Tipo | Alvo Principal | Exemplos Comuns | Limitação Fundamental |
|---|---|---|---|
typeof |
Tipos Primitivos | "string", "number", "boolean" |
Não distingue interfaces ou objetos específicos; null retorna "object". |
instanceof |
Instâncias de Classes | Date, Error, RegExp, HTMLElement |
Só funciona com construtores que existem em runtime (não funciona com interface ou type). |
in |
Objetos e Dicionários | "campo" in obj |
Exige que as interfaces possuam chaves exclusivas distintas. |
interface e type só existem em tempo de compilação! Por isso, instruções como objeto instanceof MinhaInterface geram erro de sintaxe imediato porque interfaces não geram código no JavaScript final. Quando precisar validar a forma de interfaces sem construtores de classe, use o operador in ou crie um Custom Type Guard.
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