TypeScript Academy · Lezione

parse e safeParse

Gestisca con eleganza il successo e il fallimento della validazione.

parse e safeParse è una lezione TypeScript Academy gratuita su CoddyKit. Questa è la lezione 3 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento TypeScript Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso TypeScript Academy include 4 lezioni in totale.

Due modi per convalidare

Zod offre due metodi di convalida: parse, che genera un errore in caso di dati non validi, e safeParse, che restituisce invece un oggetto risultato.

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

parse genera un errore per dati non validi

parse restituisce il valore convalidato in caso di successo e genera un ZodError in caso di errore; è ideale quando i dati non validi rappresentano un'eccezione reale.

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

Gestire gli errori di parse

Racchiuda parse in try/catch per gestire l'errore generato, esaminandolo per ottenere dettagli su ciò che non ha funzionato.

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 restituisce un risultato

safeParse non genera mai errori. Restituisce un oggetto con success: true e data, oppure con success: false e error.

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

Restringere il risultato

Il risultato è una union discriminata basata su success. Verificandolo, il tipo viene ristretto a data oppure a 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 utilizzare parse

Utilizzi parse quando l'input non valido è un bug o dovrebbe interrompere l'operazione, ad esempio leggendo la configurazione obbligatoria all'avvio.

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

Quando utilizzare safeParse

Utilizzi safeParse quando l'input non valido è previsto e desidera gestirlo in modo controllato, ad esempio convalidando l'invio di un modulo da parte dell'utente.

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
}

Leggere i problemi di ZodError

Un ZodError contiene un array issues che descrive ogni problema: il percorso, un messaggio e il codice dell'errore.

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);
  }
}

Entrambi restituiscono il tipo inferito

In caso di successo, entrambi i metodi forniscono il valore convalidato, tipizzato come z.infer<typeof schema>, quindi il codice successivo è completamente tipizzato.

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);

Scegliere il metodo corretto

Regola generale: parse per percorsi affidabili o critici, in cui un errore deve interrompere l'esecuzione; safeParse per input non affidabili che devono essere gestiti senza causare un arresto anomalo.

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

Combinare entrambi gli approcci

Un pattern comune consiste nel racchiudere safeParse in un helper che restituisce dati tipizzati o un errore formattato, offrendo i vantaggi ergonomici di entrambi i metodi.

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 rapida: parse e safeParse

Verifichi la Sua comprensione della differenza tra parse e safeParse.

Riepilogo: parse e safeParse

Ha imparato che parse genera un errore per i dati non validi, mentre safeParse restituisce un risultato success/error, quando utilizzare ciascun metodo e come leggere i problemi di 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);

Domande Frequenti

La lezione «parse e safeParse» è gratuita?

Sì — il testo completo di «parse e safeParse» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso TypeScript Academy, passa a CoddyKit PRO. Il corso TypeScript Academy include 4 lezioni in totale.

Cosa imparerò in «parse e safeParse»?

Gestisca con eleganza il successo e il fallimento della validazione. Eserciti TypeScript Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare TypeScript Academy?

Non è richiesta alcuna esperienza precedente. TypeScript Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 3 di 4.

Quanto tempo richiede la lezione «parse e safeParse»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione TypeScript Academy?

Sì. Ogni lezione TypeScript Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a TypeScript Academy