Assertion Functions: Funções de Afirmação com a Sintaxe asserts condicao no TypeScript
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.
📑 Índice do Conteúdo
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:
// ❌ 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:
// 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:
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:
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:
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.errore retornarvoidsem lançar umthrow 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
ifaninhados, permitindo que o caminho feliz da sua regra de negócio flua em linha reta.
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.
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