Type safety em boundaries: Zod, io-ts e validação runtime

⏱ 12 min·⭐ 55 XP

Pré-requisitos (0/1)0%

⬜🧰 Tipos utilitários (Partial, Pick, Omit...) e quando NÃO usar(TypeScript Profissional)

Recomendamos completar os pré-requisitos antes de seguir, mas nada te impede de continuar.

O mito: "TypeScript garante que não quebra"

É o engano mais comum de devs júnior em TS. Veja:

interface User { id: string; email: string; age: number; }
const res = await fetch('/api/users/1');
const user: User = await res.json();  // 👀 PERIGOSO
console.log(user.email.toUpperCase()); // 💥 se email vier null em runtime

O cast as User (implícito no : User) é uma asserção falsa no runtime. A API pode mudar; campo pode vir null; servidor pode ter bug. TS não sabe de nada disso.

⚠️

Todo boundary (API, form, localStorage, URL param, env var) é uma fronteira onde tipos TS param de valer. Precisa de validação runtime.

Zod: schema é código, tipo é derivado

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  age: z.number().int().nonnegative(),
});

// Tipo inferido — ÚNICA fonte de verdade
type User = z.infer<typeof UserSchema>;

async function fetchUser(id: string): Promise<User | null> {
  const res = await fetch(`/api/users/${id}`);
  const raw = await res.json();
  const parsed = UserSchema.safeParse(raw);
  if (!parsed.success) {
    console.error('API shape divergiu:', parsed.error);
    return null;
  }
  return parsed.data; // agora é User com garantia runtime
}

Padrão: parse em toda porta de entrada

No FFV Academy, este site usa Zod em:

Onde o tipo estático deixa de valer

Fora do seu build

Resposta de API

Formulário

Armazenamento localpode ter sido adulterado

Variável de ambientepode simplesmente faltar

A fronteira

Validação em runtimeo único ponto que confere de verdade

Tipo derivado do schemauma fonte de verdade, não duas

Dentro

Seu domínioaqui o tipo estático finalmente vale

A ilusãoanotar sem validar é afirmação sua, não verificação

→ validado
→ derivado
→ sem validar

Rede e entrega
Fora da AWS
Banco de dados
Gestão e governança
Segurança e identidade
Conceito de arquitetura
Compute

A linha vertical do desenho é a fronteira: à esquerda, promessas; à direita, garantias. Todo o trabalho de tipagem só vale de verdade depois de alguém ter validado em tempo de execução.

— JSON importado pelo usuário
— param da URL
— leitura de localStorage (pode ter tamper)
— attempts restaurados após refresh

Cada um desses é um "boundary". Zod garante que a partir dali, o código roda em terreno sólido.

Quiz rápido

`const user: User = await res.json()` compila sem erro. Por que isso é perigoso?

Zod vs io-ts vs Valibot: escolha

Zod: DX mais amiga, ecossistema enorme, bundle maior (~25kb). Default recomendado.Valibot: API parecida, bundle ~10x menor (tree-shakable). Boa escolha pra frontend crítico de bundle.io-ts: baseado em fp-ts, academicamente correto mas DX pesada. Use só se o time já pratica FP.

💡

No Next.js com static export, bundle importa. Se este site fosse refeito hoje, provavelmente migrava pra Valibot. Por ora, Zod é o pragmático.

Perguntas frequentes

❓ Onde a validação em execução é obrigatória?

Em toda fronteira externa: resposta de API, corpo de requisição, variável de ambiente, arquivo de configuração, mensagem de fila, resposta de modelo de linguagem. O tipo compilado não protege nada disso, e é aí que o dado inesperado entra.

❓ Validar duplica o trabalho de declarar o tipo?

Não, quando o esquema é a fonte e o tipo é inferido dele — uma declaração, duas garantias. Declarar tipo e esquema separadamente é que duplica, e o pior é que eles divergem em silêncio na primeira alteração.

❓ O que fazer quando a validação falha em produção?

Falhar de forma explícita e observável no ponto da fronteira, com o campo problemático no registro — não seguir com valor padrão. Preencher silenciosamente transforma dado inválido em comportamento estranho três camadas adiante, onde a causa já se perdeu.

Fixando

Quiz rápido

No padrão com Zod, por que o tipo é derivado do schema com `z.infer` em vez de declarado à parte?

Quiz rápido

Quais entradas contam como boundary e exigem `parse`?

Terminou de ler?

Marcar como concluído registra o XP, mantém sua sequência e coloca 3 cartas deste módulo na fila de revisão espaçada.

Próximos passos sugeridos

⏳

Async/await sem pegadinha: promises, AbortController e cancelamento

TypeScript Profissional · 12 min · +50 XP

→

Temas deste módulo

Discussão

Carregando comentários…

Type safety em boundaries: Zod, io-ts e validação runtime

⏱ 12 min·⭐ 55 XP

Pré-requisitos (0/1)0%

⬜🧰 Tipos utilitários (Partial, Pick, Omit...) e quando NÃO usar(TypeScript Profissional)

Recomendamos completar os pré-requisitos antes de seguir, mas nada te impede de continuar.

O mito: "TypeScript garante que não quebra"

É o engano mais comum de devs júnior em TS. Veja:

interface User { id: string; email: string; age: number; }
const res = await fetch('/api/users/1');
const user: User = await res.json();  // 👀 PERIGOSO
console.log(user.email.toUpperCase()); // 💥 se email vier null em runtime

O cast as User (implícito no : User) é uma asserção falsa no runtime. A API pode mudar; campo pode vir null; servidor pode ter bug. TS não sabe de nada disso.

⚠️

Todo boundary (API, form, localStorage, URL param, env var) é uma fronteira onde tipos TS param de valer. Precisa de validação runtime.

Zod: schema é código, tipo é derivado

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  age: z.number().int().nonnegative(),
});

// Tipo inferido — ÚNICA fonte de verdade
type User = z.infer<typeof UserSchema>;

async function fetchUser(id: string): Promise<User | null> {
  const res = await fetch(`/api/users/${id}`);
  const raw = await res.json();
  const parsed = UserSchema.safeParse(raw);
  if (!parsed.success) {
    console.error('API shape divergiu:', parsed.error);
    return null;
  }
  return parsed.data; // agora é User com garantia runtime
}

Padrão: parse em toda porta de entrada

No FFV Academy, este site usa Zod em:

Onde o tipo estático deixa de valer

Fora do seu build

Resposta de API

Formulário

Armazenamento localpode ter sido adulterado

Variável de ambientepode simplesmente faltar

A fronteira

Validação em runtimeo único ponto que confere de verdade

Tipo derivado do schemauma fonte de verdade, não duas

Dentro

Seu domínioaqui o tipo estático finalmente vale

A ilusãoanotar sem validar é afirmação sua, não verificação

→ validado
→ derivado
→ sem validar

Rede e entrega
Fora da AWS
Banco de dados
Gestão e governança
Segurança e identidade
Conceito de arquitetura
Compute

A linha vertical do desenho é a fronteira: à esquerda, promessas; à direita, garantias. Todo o trabalho de tipagem só vale de verdade depois de alguém ter validado em tempo de execução.

— JSON importado pelo usuário
— param da URL
— leitura de localStorage (pode ter tamper)
— attempts restaurados após refresh

Cada um desses é um "boundary". Zod garante que a partir dali, o código roda em terreno sólido.

Quiz rápido

`const user: User = await res.json()` compila sem erro. Por que isso é perigoso?

Zod vs io-ts vs Valibot: escolha

💡

No Next.js com static export, bundle importa. Se este site fosse refeito hoje, provavelmente migrava pra Valibot. Por ora, Zod é o pragmático.

Perguntas frequentes

❓ Onde a validação em execução é obrigatória?

❓ Validar duplica o trabalho de declarar o tipo?

❓ O que fazer quando a validação falha em produção?

Fixando

Quiz rápido

No padrão com Zod, por que o tipo é derivado do schema com `z.infer` em vez de declarado à parte?

Quiz rápido

Quais entradas contam como boundary e exigem `parse`?

Terminou de ler?

Marcar como concluído registra o XP, mantém sua sequência e coloca 3 cartas deste módulo na fila de revisão espaçada.

Próximos passos sugeridos

⏳

Async/await sem pegadinha: promises, AbortController e cancelamento

TypeScript Profissional · 12 min · +50 XP

→

Temas deste módulo

Discussão

Carregando comentários…