Validação de dados com Zod no TypeScript: Como garantir segurança em runtime

Resumo rápido

O TypeScript oferece segurança em tempo de compilação, mas desaparece completamente após o build JavaScript. Para validar dados dinâmicos recebidos de APIs externas, formulários ou bancos de dados, o Zod é a solução ideal. Ele valida os dados em tempo de execução (runtime) e infere os tipos estáticos do TypeScript automaticamente. Isso evita erros comuns de valores inesperados que quebram o código em produção.

Por que a tipagem estática não basta?

Muitos desenvolvedores acreditam erroneamente que usar interface ou type no TypeScript é suficiente para proteger sua aplicação. No entanto, o TypeScript é apenas um superconjunto de tipagem estática. Quando o código é compilado para JavaScript, todas as anotações de tipo são removidas.

Se a sua API retornar um campo nulo que o TypeScript acreditava ser uma string, sua aplicação irá quebrar silenciosamente ou com o infame erro Cannot read properties of null. Para manter o seu código limpo em TypeScript, precisamos de uma validação em runtime que confirme se a estrutura dos dados reais corresponde à estrutura esperada.

O que é o Zod e como ele funciona

O Zod é uma biblioteca de declaração e validação de esquemas voltada para o TypeScript. Com ele, você define um “esquema” e a biblioteca gera a validação em runtime e o tipo estático de forma síncrona.

import { z } from 'zod';

// Definindo o esquema
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string().min(3),
  email: z.string().email(),
  role: z.enum(['admin', 'user']).optional(),
});

// Inferindo o tipo TypeScript automaticamente
type User = z.infer<typeof UserSchema>;

Ao fazer isso, você elimina a duplicação de escrever uma interface estática e um validador manual, mantendo apenas uma única fonte de verdade. Se você deseja adotar as melhores práticas em seus projetos, o Zod se integra perfeitamente a ferramentas modernas como o Biome para formatar e lintar seu código.

Casos de uso práticos no Brasil

No desenvolvimento de aplicações web no Brasil, o Zod se destaca principalmente na validação de entradas personalizadas. Por exemplo, a validação de formatos locais como CPF, CNPJ e telefones pode ser feita utilizando expressões regulares com o método .refine() do Zod:

const TelefoneSchema = z.string().refine((val) => {
  // Valida formatos (11) 99999-9999 ou 11999999999
  const regex = /^\(?\d{2}\)?\s?\d{4,5}-?\d{4}$/;
  return regex.test(val);
}, {
  message: "Número de telefone brasileiro inválido",
});

Esse nível de controle protege formulários de cadastro e conexões com APIs de pagamento locais, onde dados inconsistentes causam falhas catastróficas de transação.

Minha recomendação para seus projetos

Se você está criando novos projetos em 2026, inclua o Zod desde o primeiro dia na camada de infraestrutura e controladores de entrada de dados. Ele reduz drasticamente o uso de blocos try/catch genéricos e garante contratos de dados extremamente robustos. Combinando isso com os recursos avançados do TypeScript moderno, sua aplicação ficará imune a surpresas de runtime.