Type Guards Customizados no TypeScript: Guia
⚡ Curso de TypeScript • Web-ZoneWare

Type Guards Customizados: Predicados de Tipo com a Sintaxe valor is Tipo no TypeScript

Lição 21 de 50

Type Guards Customizados: Predicados de Tipo com a Sintaxe valor is Tipo no TypeScript

⚡ Módulo 3 • Aula 21 de 50

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

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:

typescript

JavaScript 25 linhas
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:

typescript

JavaScript 16 linhas
// ✅ 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:

typescript

JavaScript 33 linhas
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?

typescript

JavaScript 16 linhas
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:

typescript

JavaScript 22 linhas
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);
    }
}
🛑

O Contrato Sagrado de Confiança: O compilador confia cegamente no predicado 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!

💡

Dica Pro de Engenharia Web-ZoneWare: Crie um arquivo centralizado de utilitários como 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.

🚀

Próximo Passo Prático: Type Guards retornam booleanos e exigem um 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.

🛠️ Laboratório Prático & Prática Imediata

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.

💻 Desenvolvedor & Código

Editor de Códigos Web Online

Ambiente com destaque de sintaxe para você testar tags, tabelas e scripts na hora.

Abrir Ferramenta Online
⚡ Live Code Studio

Playground 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
Foto de Web-Zoneware
✓ Verificado
🎓 Tutor & Coordenador da Web Academy

Web-Zoneware

Tutor Técnico & Desenvolvedor Full-Stack

Desenvolvedor web e instrutor focado na formação prática de novos programadores. Defensor ferrenho de código semântico, arquitetura limpa e acessibilidade W3C/WCAG, dedicando-se a construir cursos estruturados em metodologia passo a passo com execução ao vivo no Playground IDE.

Especialidades: HTML5 Semântico CSS3 & Flexbox/Grid JavaScript Moderno Acessibilidade WCAG 2.2 Didática Prática
Rolar para cima