Assertion Functions no TypeScript: asserts condicao
⚡ Curso de TypeScript • Web-ZoneWare

Assertion Functions: Funções de Afirmação com a Sintaxe asserts condicao no TypeScript

Lição 22 de 50

Assertion Functions: Funções de Afirmação com a Sintaxe asserts condicao no TypeScript

⚡ Módulo 3 • Aula 22 de 50

E se em vez de escrever dezenas de blocos if/else você pudesse simplesmente afirmar que uma condição é verdadeira — disparando uma exceção se não for — e deixar o TypeScript afunilar o tipo no restante do seu arquivo? Conheça as Assertion Functions e a sintaxe asserts condicao.

1. O Que São Assertion Functions e Por Que Foram Criadas

Introduzidas no TypeScript 3.7, as Assertion Functions (Funções de Afirmação) resolvem um padrão muito comum no desenvolvimento JavaScript e em frameworks de teste como Jest, Node.js nativo (assert) e Chai: funções que verificam uma pré-condição e, caso ela seja violada, disparam um erro imediatamente (throw Error).

Antes do TS 3.7, se uma função disparasse uma exceção, o compilador não entendia que o código subsequente só seria alcançado se a condição fosse verdadeira. Com a palavra-chave asserts, o TypeScript agora sabe que se a função retornar normalmente sem lançar exceções, a premissa afirmada é 100% garantida para o restante do escopo:

typescript

JavaScript 12 linhas
// ❌ ANTES DO TS 3.7: O compilador não afunilava após a função de assert
function validarStringLegada(val: unknown) {
    if (typeof val !== "string") {
        throw new Error("Não é uma string!");
    }
}
 
function processarTextoLegado(texto: unknown) {
    validarStringLegada(texto);
    // 💥 Erro de compilação: texto ainda é "unknown"!
    // console.log(texto.toUpperCase()); 
}

2. A Sintaxe 1: asserts condicao

A primeira forma de declaração utiliza a sintaxe asserts condicao. Ela indica que o argumento passado como parâmetro da função deve ser avaliado como verdadeiro para que a execução continue:

typescript

JavaScript 20 linhas
// Definindo uma função global de asserção:
function afirmar(condicao: unknown, mensagem: string = "Falha de asserção"): asserts condicao {
    if (!condicao) {
        throw new Error(mensagem);
    }
}
 
function processarValorGenerico(valor: string | number | null) {
    // Afirmamos que "valor" não é nulo:
    afirmar(valor !== null, "O valor não pode ser nulo!");
 
    // ✨ A PARTIR DESTA LINHA, "valor" é estritamente string | number:
    console.log("Valor válido detectado.");
 
    // Podemos fazer asserções mais específicas:
    afirmar(typeof valor === "string", "Esperava-se uma string!");
 
    // ✨ A PARTIR DAQUI, "valor" é estritamente STRING:
    console.log("Texto em maiúsculas:", valor.toUpperCase());
}

3. A Sintaxe 2: asserts parametro is Tipo

A segunda variação — e a mais utilizada na arquitetura corporativa — combina a asserção com um Type Predicate explícito: asserts parametro is Tipo. Essa sintaxe deixa o código muito mais expressivo e auto-documentado:

typescript

JavaScript 22 linhas
function afirmarString(val: unknown, nomeCampo: string): asserts val is string {
    if (typeof val !== "string") {
        throw new TypeError(`O campo "${nomeCampo}" deve ser uma string, recebido: ${typeof val}`);
    }
}
 
function afirmarData(val: unknown): asserts val is Date {
    if (!(val instanceof Date) || isNaN(val.getTime())) {
        throw new TypeError("Data inválida ou formato incorreto.");
    }
}
 
function registrarLog(dados: { autor: unknown; timestamp: unknown }) {
    // Aplicando as asserções logo na entrada da função:
    afirmarString(dados.autor, "autor");
    afirmarData(dados.timestamp);
 
    // ✨ A PARTIR DESTE PONTO:
    // dados.autor é STRING pura!
    // dados.timestamp é DATE puro!
    console.log(`Log por ${dados.autor.toUpperCase()} em ${dados.timestamp.toISOString()}`);
}

4. Caso Prático 1: Validação de Variáveis de Ambiente no Bootstrap

No backend com Node.js, é uma péssima prática espalhar verificações if (!process.env.CHAVE) por toda a base de código. Uma Assertion Function centralizada garante o *fail-fast* (falha imediata na inicialização do servidor) e afunila os tipos:

typescript

JavaScript 17 linhas
function assertDefinido<T>(valor: T, nome: string): asserts valor is NonNullable<T> {
    if (valor === undefined || valor === null) {
        throw new Error(`[CONFIG FATAL] A variável de ambiente "${nome}" é obrigatória e não foi definida!`);
    }
}
 
// No arquivo de inicialização do servidor (server.ts):
const dbUrl = process.env.DATABASE_URL; // Tipo inicial: string | undefined
const secretJwt = process.env.JWT_SECRET; // Tipo inicial: string | undefined
 
// Afirmamos a existência de ambas:
assertDefinido(dbUrl, "DATABASE_URL");
assertDefinido(secretJwt, "JWT_SECRET");
 
// ✨ O TypeScript agora sabe que ambas são STRING e JAMAIS undefined:
const conexaoBanco = conectarBancoDeDados(dbUrl); // Sem erros de compilação!
const autenticador = inicializarJwt(secretJwt);

5. Caso Prático 2: Proteção de Rotas Autenticadas (req.user)

Em controladores de APIs web, Assertion Functions eliminam o código repetitivo de verificação de autenticação:

typescript

JavaScript 25 linhas
interface UsuarioLogado {
    id: string;
    email: string;
    cargo: "admin" | "aluno";
}
 
interface RequisicaoHttp {
    caminho: string;
    usuario?: UsuarioLogado;
}
 
function assertAutenticado(usuario: UsuarioLogado | undefined): asserts usuario is UsuarioLogado {
    if (!usuario) {
        throw new Error("HTTP 401: Acesso não autorizado. Sessão expirada.");
    }
}
 
function painelAlunoController(req: RequisicaoHttp) {
    // Afirmação estrita:
    assertAutenticado(req.usuario);
 
    // Código linear e limpo — o TypeScript garante que req.usuario existe:
    console.log(`Bem-vindo ao painel, ${req.usuario.email}`);
    console.log(`Cargo: ${req.usuario.cargo.toUpperCase()}`);
}

6. Regras e Cuidados com Assertion Functions

  • Devem Ser Funções com Assinatura Explícita: Assertion functions devem ser declaradas com o modificador de retorno asserts ... explícito. Expressões de função ou arrow functions atribuídas sem anotação explícita de tipo geram erro de compilação.
  • Devem Disparar Exceções em Caso de Falha: Se sua função de asserção apenas logar uma mensagem com console.error e retornar void sem lançar um throw Error, a execução continuará com os tipos corrompidos, violando a premissa do compilador.
  • Código Linear (*Flat Code*): Assertion Functions eliminam a “pirâmide da perdição” de múltiplos if aninhados, permitindo que o caminho feliz da sua regra de negócio flua em linha reta.
💡

Dica Pro de Engenharia Web-ZoneWare: Use Type Guards (is) quando a falha for um cenário esperado de negócio que exige um tratamento alternativo no else. Use Assertion Functions (asserts) quando a falha representar uma anomalia grave ou violação de contrato de software que deve interromper imediatamente o fluxo com um erro.

🚀

Próximo Passo Prático: E quando você precisa garantir que todas as ramificações possíveis de uma união foram tratadas sem esquecer nenhum caso? Na Lição 23 aprenderemos a implementar a Checagem Exaustiva com o Tipo never (Exhaustiveness Checking).

🛠️ 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