Como parar de reescrever validadores no Zod
Se você abrir a pasta validators/ do seu último projeto, é provável que encontre um regex de senha que veio de algum lugar, um refine de CPF, uma função que transforma "30m" em milissegundos e algum jeito de lidar com o fato de que z.coerce.boolean() devolve true para a string "false".
Depois de reescrever essa pasta em vários projetos, resolvi juntar tudo num pacote: o zod-toolkit. Ele roda em cima do Zod v4, o z que você importa é o mesmo de sempre, e o que ele traz a mais são validadores prontos e com testes.
import { z } from "zod-toolkit";
Cinco refine viram um método
Senha de cadastro com Zod puro costuma ficar assim:
const password = z
.string()
.min(8, "A senha deve ter pelo menos 8 caracteres")
.refine((v) => /[a-z]/.test(v), "Precisa de uma letra minúscula")
.refine((v) => /[A-Z]/.test(v), "Precisa de uma letra maiúscula")
.refine((v) => /\d/.test(v), "Precisa de um número")
.refine((v) => /[^A-Za-z0-9\s]/.test(v), "Precisa de um símbolo");
Quatro regexes e cinco mensagens que alguém precisa manter e traduzir. Com o toolkit:
const password = z.password();
z.password().safeParse("Abcdefg1");
// "Invalid password: must contain at least one symbol."
As regras são as mesmas, e cada uma falha na sua vez, com a mensagem certa. O CNPJ é um dos casos mais trabalhosos.
Escrever na mão o regex, rejeitar sequência repetida e calcular dois dígitos verificadores com pesos diferentes. Depois que o CNPJ virou alfanumérico, ainda é preciso converter as letras em número (código ASCII menos 48), e um erro nessa conversão passa despercebido. Aqui é uma chamada, e os dois formatos funcionam:
z.br.cnpj().parse("12.ABC.345/01DE-35"); // alfanumérico
z.br.cnpj().parse("12.345.678/0001-95"); // numérico, continua valendo
Variáveis de ambiente
É onde o ganho aparece mais rápido. Tudo que vem de process.env é string, então quase tudo precisa de coerção:
const Env = z.object({
NODE_ENV: z.nodeEnv(), // production | development | test | staging
PORT: z.coerce.port(), // "3000" -> 3000
DATABASE_URL: z.databaseUrl(), // postgres://, mysql://, mongodb://, redis://
DB_HOST: z.hostname(),
LOG_LEVEL: z.logLevel(),
DEBUG: z.coerce.boolean(), // "false" -> false, "1" -> true, "off" -> false
SESSION_TTL: z.duration(), // "30m" -> 1_800_000 (ms)
ALLOWED_ORIGINS: z.csv(z.url()), // "https://a.com, https://b.com" -> string[]
});
export const env = Env.parse(process.env);
Se alguém sobe o servidor com PORT=abc ou DATABASE_URL=http://..., ele cai na hora com uma mensagem que explica o problema, em vez de três horas depois num erro de conexão difícil de rastrear. E env.SESSION_TTL já chega como número, pronto para um setTimeout.
Dois desses schemas substituem os do Zod que têm o mesmo nome, então vale saber o que muda:
z.coerce.boolean()aceitatrue/false,1/0,yes/noeon/offe rejeita o resto. Com isso"false"virafalse, e"maybe"deixa de virartruee passa a falhar.z.hostname()continua aceitando nomes de domínio e IPv4, e passa a aceitar IPv6 (::1,[::1]). Em troca, rejeita número com pontos como256.1.1.1ou1.2.3, que o original deixa passar. Pela RFC 3696 o último rótulo de um hostname não pode ser só dígitos, e uma string assim é lida como IPv4, não como nome. Vale ficar de olho se você está migrando.
Erro que diz o que falhou
Os validadores maiores rodam em etapas e param na primeira que falha. O CNPJ, por exemplo, passa por format, repeated e checkDigit, a senha por length, lowercase, uppercase, number e symbol.
Dá para trocar a mensagem de uma etapa sem mexer nas outras:
z.br.cnpj({ errors: { checkDigit: "Confira os dois últimos dígitos" } });
E se você quer montar a interface em cima da etapa, e não do texto, passe uma função e leia issue.params?.step. Dá para acender um checklist de senha item por item sem parsear mensagem:
const result = z
.password({ error: (issue) => issue.params?.step as string })
.safeParse("abc"); // "length"
O nome da etapa é tipado: z.password({ errors: { symbl: "..." } }) nem compila. A ordem de prioridade é errors[etapa], depois error, depois a mensagem padrão do idioma, e o idioma é resolvido na hora do parse, então z.locale.set("pt") vale para schemas que você já criou.
Alguns outros que costumam aparecer no dia a dia:
z.duration().parse("1.5h"); // 5_400_000 (aceita ms, s, m, h, d, w)
z.csv(z.coerce.number()).parse("1, 2, 3"); // [1, 2, 3]
z.slug(); // "meu-primeiro-post"
z.hexColor(); // #fff, #ffffff, #ffffff80
z.semver(); // 1.2.3, 1.0.0-beta.1+build.5
z.username(); // 3–20 chars, letras, números, "." e "_"
z.fullname(); // exige nome e sobrenome
z.otp(6); // código de 6 dígitos
z.br.cpf();
z.br.cep();
E o agente de IA com isso?
Quando você pede para um agente validar um formulário, ele escreve tudo do zero: o regex, os refine, as mensagens, o módulo 11 do CNPJ. Isso é token de saída que você paga e código que você precisa ler. Com o toolkit instalado, o agente escreve z.password() e z.br.cnpj(). É menos código para gerar, menos para revisar, e menos chance de ele errar o peso de um dígito verificador, que é o tipo de detalhe que modelo acerta quase sempre e erra quando você menos espera.
Vale deixar uma linha no AGENTS.md ou no CLAUDE.md do projeto: “para schemas complexos, verifique se o zod-toolkit já não resolve antes de escrever refine na mão”. Assim ele consulta o catálogo antes de escrever do zero.
Quando não vale a pena
Se tudo que você precisa é z.string().min(3), fique no Zod puro. O toolkit compensa quando a regra é de domínio (documento, ambiente, credencial) e você não quer manter o regex nem pedir para um modelo reescrever o módulo 11 a cada projeto. As mensagens padrão existem em en e pt; para outro idioma, use error ou errors.
Ajude a biblioteca a crescer
O projeto é open source e aceita contribuições. A ideia é continuar trazendo mais validadores comuns, desses que todo projeto acaba reescrevendo. Cada um que entra é código a menos para copiar e colar e para o agente gerar.
Dá para ajudar de qualquer jeito: abrir uma issue com um validador que você sempre acaba escrevendo na mão (telefone, placa, chave Pix, boleto…), mandar um PR (cada validador tem um index.ts, um locale.ts com as mensagens e um teste), traduzir as mensagens para outro idioma ou avisar de um caso que está com problema, como um CNPJ válido que foi rejeitado.
E se o projeto te ajudou ou você achou a ideia útil, deixa uma ⭐ no GitHub. Ajuda mais gente a encontrar a biblioteca e incentiva a manter o projeto crescendo.