Zod para TypeScript: guia completo com exemplos

Introdução ao Zod: o que é e para que serve

No desenvolvimento web moderno com TypeScript, um dos problemas-chave é garantir a integridade dos dados. Mesmo com tipagem estrita, o TypeScript não pode garantir que os dados provenientes de fontes externas (API, formulários, localStorage, WebSocket) realmente correspondam aos tipos declarados. O compilador TypeScript funciona na fase de desenvolvimento, mas durante a execução do programa os tipos são apagados. É aqui que o Zod entra em ação.

Zod é uma biblioteca para validação declarativa e tipagem de dados para TypeScript e JavaScript. Ela permite criar esquemas (schemas) que servem simultaneamente como validador de dados em tempo de execução e como fonte de verdade para tipos estáticos do TypeScript. A filosofia principal do Zod é "um esquema, dois propósitos": você escreve o esquema uma vez e obtém tanto a validação quanto o tipo inferido automaticamente.

Principais vantagens do Zod:

\n
• Segurança de tipos: inferência automática de tipos TypeScript a partir dos esquemas.
\n
• Declaratividade: sintaxe legível e concisa.
\n
• Composicionalidade: esquemas podem ser combinados e estendidos.
\n
• Erros detalhados: mensagens de erro de validação claras.
\n
• Zero dependências: a biblioteca não requer pacotes adicionais.
\n

Instalação do Zod

Zod é um pacote npm, portanto a instalação é feita através do gerenciador de pacotes do Node.js. A biblioteca é escrita em TypeScript e vem com arquivos de declaração de tipos prontos, portanto não é necessária instalação adicional de @types/zod.

# Instalação via npm\nnpm install zod\n\n# Instalação via yarn\nyarn add zod\n\n# Instalação via pnpm\npnpm add zod

Após a instalação, você pode importar o Zod para o seu projeto:

import { z } from "zod";

Observe: Zod não é instalado via pip, pois é uma biblioteca para o ecossistema JavaScript/TypeScript, e não Python.

Início rápido com exemplo de código

Vamos criar um esquema simples para validação de dados de usuário e ver imediatamente como o Zod une validação e tipagem.

import { z } from "zod";\n\n// 1. Definimos o esquema\nconst UserSchema = z.object({\n    id: z.number().positive(),\n    name: z.string().min(2, "O nome deve conter no mínimo 2 caracteres"),\n    email: z.string().email("Email inválido"),\n    age: z.number().int().min(18, "A idade deve ser no mínimo 18 anos").optional(),\n});\n\n// 2. Inferimos automaticamente o tipo a partir do esquema\ntype User = z.infer<typeof UserSchema>;\n\n// 3. Validamos os dados\nconst validData = {\n    id: 1,\n    name: "Ana",\n    email: "ana@exemplo.com",\n    age: 25,\n};\n\nconst result = UserSchema.safeParse(validData);\n\nif (result.success) {\n    // result.data tem o tipo User\n    console.log("Validação bem-sucedida:", result.data);\n} else {\n    // result.error contém informações detalhadas sobre os erros\n    console.log("Erros de validação:", result.error.errors);\n}\n\n// Exemplo com dados inválidos\nconst invalidData = {\n    id: -1,\n    name: "A",\n    email: "não-email",\n};\n\nconst invalidResult = UserSchema.safeParse(invalidData);\nif (!invalidResult.success) {\n    console.log("Erros:", invalidResult.error.errors);\n    // Exibirá:\n    // - id: deve ser um número positivo\n    // - name: O nome deve conter no mínimo 2 caracteres\n    // - email: Email inválido\n}

Principais métodos e funções do Zod

Nesta seção, veremos detalhadamente 10 métodos-chave do Zod que cobrirão 90% das suas tarefas de validação.

1. z.string() — Validação de strings

O que faz: Cria um esquema para validação de valores string. Fornece uma cadeia de métodos para impor restrições adicionais.

Parâmetros: Não aceita parâmetros na criação