TypeScript Academy · Aula

parse versus safeParse

Trate com elegância o sucesso e a falha da validação.

parse versus safeParse é uma aula grátis de TypeScript Academy no CoddyKit. Esta é a aula 3 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de TypeScript Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de TypeScript Academy inclui 4 aulas no total.

Duas formas de validar

O Zod oferece dois métodos de validação: parse, que lança uma exceção quando os dados são inválidos, e safeParse, que retorna um objeto de resultado.

import { z } from "zod";
const schema = z.string();
// schema.parse(x) throws on failure
// schema.safeParse(x) returns { success, ... }

parse lança uma exceção para dados inválidos

parse retorna o valor validado em caso de sucesso e lança um ZodError em caso de falha, sendo ideal quando dados inválidos representam uma situação realmente excepcional.

import { z } from "zod";
const schema = z.number();
const ok = schema.parse(42); // 42
// schema.parse("nope"); // throws ZodError

Capturando erros de parse

Envolva parse em try/catch para tratar o erro lançado, inspecionando-o em busca de detalhes sobre o que falhou.

import { z } from "zod";
const schema = z.number();
try {
  schema.parse("nope");
} catch (err) {
  if (err instanceof z.ZodError) {
    console.log("Invalid:", err.issues.length);
  }
}

safeParse retorna um resultado

safeParse nunca lança uma exceção. Ele retorna um objeto com success: true e data, ou com success: false e error.

import { z } from "zod";
const schema = z.number();
const result = schema.safeParse("nope");
// result is { success: false, error: ZodError }

Restringindo o resultado

O resultado é uma união discriminada em success. Verificá-lo restringe o tipo para data ou error.

import { z } from "zod";
const schema = z.object({ id: z.number() });
const result = schema.safeParse({ id: 1 });
if (result.success) {
  console.log(result.data.id); // typed
} else {
  console.log(result.error.issues);
}

Quando usar parse

Use parse quando uma entrada inválida for um erro ou dever interromper a operação, como ao ler uma config obrigatória na inicialização.

import { z } from "zod";
const configSchema = z.object({ port: z.number() });
const config = configSchema.parse({ port: 8080 });
// Fail fast if config is wrong.

Quando usar safeParse

Use safeParse quando uma entrada inválida for esperada e você quiser tratá-la de maneira adequada, como ao validar envios de formulários de usuários.

import { z } from "zod";
const formSchema = z.object({ email: z.string() });
const r = formSchema.safeParse({ email: 123 });
if (!r.success) {
  // Show a friendly validation message
}

Lendo os problemas de ZodError

Um ZodError contém uma matriz de issues que descreve cada problema: o caminho, uma mensagem e o código do erro.

import { z } from "zod";
const schema = z.object({ age: z.number() });
const r = schema.safeParse({ age: "x" });
if (!r.success) {
  for (const issue of r.error.issues) {
    console.log(issue.path, issue.message);
  }
}

Ambos retornam o tipo inferido

Em caso de sucesso, ambos os métodos fornecem o valor validado tipado como z.infer<typeof schema>, portanto o código posterior é totalmente tipado.

import { z } from "zod";
const userSchema = z.object({ name: z.string() });
type User = z.infer<typeof userSchema>;
const u: User = userSchema.parse({ name: "Ada" });
console.log(u.name);

Escolhendo o método certo

Regra prática: use parse em caminhos confiáveis ou críticos, nos quais uma falha deve interromper a execução; use safeParse para entradas não confiáveis que precisam ser tratadas sem causar uma falha.

import { z } from "zod";
const schema = z.string();
// Critical: schema.parse(value)
// User-facing: schema.safeParse(value)

Combinando os dois estilos

Um padrão comum envolve safeParse em um auxiliar que retorna dados tipados ou um erro formatado, reunindo a praticidade dos dois métodos.

import { z } from "zod";
function validate<T extends z.ZodType>(schema: T, value: unknown) {
  const r = schema.safeParse(value);
  return r.success ? { ok: true, data: r.data } : { ok: false, error: r.error };
}
// Reusable, no throwing.

Verificação rápida: parse versus safeParse

Teste sua compreensão sobre parse e safeParse.

Recapitulação: parse versus safeParse

Você aprendeu que parse lança uma exceção para dados inválidos, enquanto safeParse retorna um resultado de success/error, quando usar cada um e como ler os problemas de ZodError.

import { z } from "zod";
const schema = z.object({ id: z.number() });
const r = schema.safeParse({ id: 1 });
if (r.success) console.log(r.data.id);

Perguntas Frequentes

A aula “parse versus safeParse” é grátis?

Sim — o texto completo de “parse versus safeParse” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de TypeScript Academy, atualize para CoddyKit PRO. O curso de TypeScript Academy inclui 4 aulas no total.

O que vou aprender em “parse versus safeParse”?

Trate com elegância o sucesso e a falha da validação. Você pratica TypeScript Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar TypeScript Academy?

Nenhuma experiência prévia é necessária. TypeScript Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 3 de 4.

Quanto tempo leva a aula “parse versus safeParse”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de TypeScript Academy?

Sim. Cada aula de TypeScript Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para TypeScript Academy