Especialista em Validação Zod

Você é um especialista em Zod de nível de produção. Ajuda desenvolvedores a criar definições de schema e lógica de validação type-safe. Domina os fundamentos do Zod (primitivos, objetos, arrays, records), inferência de tipos (z.infer), validações complexas (.refine, .superRefine), transformações (.transform) e integrações em todo o ecossistema moderno do TypeScript (React Hook Form, Rotas de API do Next.js / Ações do App Router, tRPC e variáveis de ambiente).

Quando Usar Esta Habilidade

• Use ao definir schemas de validação TypeScript para entradas de API ou formulários
• Use ao configurar a validação de variáveis de ambiente (process.env)
• Use ao integrar Zod com React Hook Form (@hookform/resolvers/zod)
• Use ao extrair ou inferir tipos TypeScript de schemas de validação em tempo de execução
• Use ao escrever regras de validação complexas (por exemplo, validação entre campos, validação assíncrona)
• Use ao transformar dados de entrada (por exemplo, coerção de string para Date, string para number)
• Use ao padronizar a formatação de mensagens de erro

Conceitos Principais

Por que Zod?

Zod elimina a duplicação de escrever uma interface TypeScript e um schema de validação em tempo de execução. Você define o schema uma vez, e o Zod infere o tipo TypeScript estático. Note que Zod é para parsing, não apenas validação. safeParse e parse retornam dados limpos e tipados, removendo chaves desconhecidas por padrão.

Definição de Schema e Inferência

Primitivos e Coerção

import { z } from "zod";

// Basic primitives
const stringSchema = z.string().min(3).max(255);
const numberSchema = z.number().int().positive();
const dateSchema = z.date();

// Coercion (automatically casting inputs before validation)
// Highly useful for FormData in Next.js Server Actions or URL queries
const ageSchema = z.coerce.number().min(18); // "18" -> 18
const activeSchema = z.coerce.boolean(); // "true" -> true
const dobSchema = z.coerce.date(); // "2020-01-01" -> Date object

Objetos e Inferência de Tipo

const UserSchema = z.object({
  id: z.string().uuid(),
  username: z.string().min(3).max(20),
  email: z.string().email(),
  role: z.enum(["ADMIN", "USER", "GUEST"]).default("USER"),
  age: z.number().min(18).optional(), // Can be omitted
  website: z.string().url().nullable(), // Can be null
  tags: z.array(z.string()).min(1), // Array with at least 1 item
});

// Infer the TypeScript type directly from the schema
// No need to write a separate `interface User { ... }`
export type User = z.infer<typeof UserSchema>;

Tipos Avançados

// Records (Objects with dynamic keys but specific value types)
const envSchema = z.record(z.string(), z.string()); // Record<string, string>

// Unions (OR)
const idSchema = z.union([z.string(), z.number()]); // string | number
// Or simpler:
const idSchema2 = z.string().or(z.number());

// Discriminated Unions (Type-safe switch cases)
const ActionSchema = z.discriminatedUnion("type", [
  z.object({ type: z.literal("create"), id: z.string() }),
  z.object({ type: z.literal("update"), id: z.string(), data: z.any() }),
  z.object({ type: z.literal("delete"), id: z.string() }),
]);

Parsing e Validação

parse vs safeParse

const schema = z.string().email();

// ❌ parse: Throws a ZodError if validation fails
try {
  const email = schema.parse("invalid-email");
} catch (err) {
  if (err instanceof z.ZodError) {
    console.error(err.issues);
  }
}

// ✅ safeParse: Returns a result object (No try/catch needed)
const result = schema.safeParse("user@example.com");

if (!result.success) {
  // TypeScript narrows result to SafeParseError
  console.log(result.error.format()); 
  // Early return or throw domain error
} else {
  // TypeScript narrows result to SafeParseSuccess
  const validEmail = result.data; // Type is `string`
}

Personalizando a Validação

Mensagens de Erro Personalizadas

const passwordSchema = z.string()
  .min(8, { message: "Password must be at least 8 characters long" })
  .max(100, { message: "Password is too long" })
  .regex(/[A-Z]/, { message: "Password must contain at least one uppercase letter" })
  .regex(/[0-9]/, { message: "Password must contain at least one number" });

// Global custom error map (useful for i18n)
z.setErrorMap((issue, ctx) => {
  if (issue.code === z.ZodIssueCode.invalid_type) {
    if (issue.expected === "string") return { message: "This field must be text" };
  }
  return { message: ctx.defaultError };
});

…