Type Guards Customizados: Predicados de Tipo com a Sintaxe valor is Tipo no TypeScript
Quando os operadores nativos não são suficientes para inspecionar objetos complexos ou validar dados brutos vindos de APIs externas, entra em cena o recurso mais elegante do controle de fluxo: os Type Guards Customizados e seus Predicados de Tipo (valor is Tipo).
📑 Índice do Conteúdo
1. A Limitação das Funções Tradicionais com Retorno Booleano
Imagine que você queira encapsular a lógica de verificação de um usuário administrador em uma função auxiliar reutilizável para não poluir seus controladores:
interface UsuarioComum {
id: string;
nome: string;
}
interface Administrador extends UsuarioComum {
permissoesTotais: string[];
painelMasterUrl: string;
}
type Usuario = UsuarioComum | Administrador;
// ❌ FUNÇÃO COM RETORNO BOOLEAN TRADICIONAL:
function verificarSeEhAdminRuim(usuario: Usuario): boolean {
return "permissoesTotais" in usuario;
}
function processarAcesso(usuario: Usuario) {
if (verificarSeEhAdminRuim(usuario)) {
// 💥 O TypeScript NÃO AFUNILA!
// O compilador apenas sabe que a função retornou "true",
// mas "usuario" continua sendo UsuarioComum | Administrador!
// console.log(usuario.painelMasterUrl); // ❌ Erro: Property 'painelMasterUrl' does not exist!
}
}
Para o compilador, uma função com retorno : boolean é uma caixa preta: ele não consegue correlacionar a resposta booleana com o tipo estático da variável testada. Para resolver isso, usamos um Predicado de Tipo.
2. A Anatomia do Predicado de Tipo (valor is Tipo)
Um Predicado de Tipo (Type Predicate) é uma declaração especial na assinatura de retorno de uma função, expressa no formato nomeDoParametro is TipoDesejado:
// ✅ TYPE GUARD CUSTOMIZADO COM PREDICADO DE TIPO:
function ehAdministrador(usuario: Usuario): usuario is Administrador {
return "permissoesTotais" in usuario && Array.isArray((usuario as Administrador).permissoesTotais);
}
function processarAcessoProfissional(usuario: Usuario) {
if (ehAdministrador(usuario)) {
// ✨ O COMPILADOR AFUNILA COM 100% DE CERTEZA:
// Aqui, "usuario" é estritamente Administrador!
console.log("URL do Painel:", usuario.painelMasterUrl);
console.log("Permissões:", usuario.permissoesTotais.join(", "));
} else {
// ✨ No else, o TypeScript sabe que é UsuarioComum:
console.log("Usuário padrão:", usuario.nome);
}
}
Se a função ehAdministrador retornar true em tempo de execução, o TypeScript reescreve o tipo da variável no escopo condicional para Administrador. Se retornar false, ele descarta Administrador da união no bloco else.
3. Validando Dados Desconhecidos (unknown) de APIs Externas
Um dos usos mais nobres dos Custom Type Guards é na barreira de entrada da sua aplicação, ao receber dados de uma API externa via fetch ou de um arquivo JSON. Em vez de recorrer ao perigoso as MeuTipo, criamos um guarda de validação estrito:
interface ProdutoCatalogo {
id: number;
titulo: string;
precoCentavos: number;
}
// Guarda de tipo recebendo "unknown" — segurança máxima:
function ehProdutoCatalogo(dado: unknown): dado is ProdutoCatalogo {
if (typeof dado !== "object" || dado === null) {
return false;
}
const obj = dado as Record<string, unknown>;
return (
typeof obj.id === "number" &&
typeof obj.titulo === "string" &&
typeof obj.precoCentavos === "number"
);
}
// Consumo real em uma chamada HTTP:
async function carregarProduto(id: number) {
const res = await fetch(`/api/produtos/${id}`);
const dadoBruto: unknown = await res.json();
if (ehProdutoCatalogo(dadoBruto)) {
// Totalmente seguro e tipado sem nenhuma asserção forçada:
console.log(`Produto: ${dadoBruto.titulo} | Preço: R$ ${(dadoBruto.precoCentavos / 100).toFixed(2)}`);
} else {
throw new Error("Payload da API corrompido ou fora do contrato esperado.");
}
}
4. O Poder dos Type Predicates com Array.prototype.filter
Quem nunca se deparou com a frustração de filtrar itens nulos de um array no TypeScript e perceber que o compilador continua considerando o array como contendo valores nulos?
const listaValores: (string | null | undefined)[] = ["TypeScript", null, "Web-ZoneWare", undefined, "Academy"];
// ❌ COM FILTER TRADICIONAL:
const resultadoRuim = listaValores.filter(item => item !== null && item !== undefined);
// O TypeScript AINDA infere resultadoRuim como: (string | null | undefined)[]!
// resultadoRuim[0].toUpperCase(); // ❌ Erro: Object is possibly 'null' or 'undefined'.
// ✅ COM TYPE PREDICATE NO CALLBACK DO FILTER:
function naoEhNuloNemIndefinido<T>(item: T | null | undefined): item is T {
return item !== null && item !== undefined;
}
const resultadoLimpo: string[] = listaValores.filter(naoEhNuloNemIndefinido);
// ✨ Tipo inferido perfeitamente como: string[]
console.log(resultadoLimpo.map(texto => texto.toUpperCase()));
// ["TYPESCRIPT", "WEB-ZONEWARE", "ACADEMY"]
5. Predicados em Métodos de Classes (this is Tipo)
O TypeScript também permite definir predicados diretamente no contexto da própria classe utilizando a sintaxe this is Tipo, ideal para arquiteturas orientadas a objetos e classes abstratas:
abstract class ArquivoSistema {
constructor(public nome: string) {}
ehArquivoTexto(): this is ArquivoTexto {
return this instanceof ArquivoTexto;
}
}
class ArquivoTexto extends ArquivoSistema {
conteudo: string = "";
}
class ArquivoBinario extends ArquivoSistema {
bytes: Uint8Array = new Uint8Array();
}
function processarArquivo(arq: ArquivoSistema) {
if (arq.ehArquivoTexto()) {
// ✨ Dentro deste if, "arq" é afunilado para ArquivoTexto:
console.log("Tamanho do texto:", arq.conteudo.length);
}
}
valor is Tipo. Se a sua lógica interna de validação tiver um bug e retornar true para um dado incorreto, o TypeScript assumirá que aquele dado é válido, e um erro de runtime fatal ocorrerá ao tentar ler propriedades inexistentes. Teste exaustivamente seus Type Guards com suítes de testes unitários!
src/utils/type-guards.ts contendo guardas genéricos reutilizáveis (como isNonNullable, isRecord, isString). Isso reduzirá a duplicação de validações defensivas em até 80% do seu código.
if. Mas e quando queremos uma função que simplesmente dispare uma exceção se a condição não for atendida, afunilando o tipo no restante do arquivo? Na Lição 22 dominaremos as Assertion Functions: Funções de Afirmação com a Sintaxe asserts condicao.
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