TypeScript Academy · Leçon

parse ou safeParse

Gérer avec élégance la réussite et l’échec de la validation.

parse ou safeParse est une leçon TypeScript Academy gratuite sur CoddyKit. Ceci est la leçon 3 sur 4. Tu peux lire la leçon complète ci-dessous gratuitement — puis la pratiquer en direct dans le navigateur avec un éditeur de code intégré et un tuteur IA 24/7. Elle fait partie du parcours d'apprentissage TypeScript Academy, et ta progression se synchronise sur le web et l'application CoddyKit. Le cours TypeScript Academy comprend 4 leçons au total.

Deux façons de valider

Zod vous propose deux méthodes de validation : parse, qui lève une exception lorsque les données sont invalides, et safeParse, qui renvoie plutôt un objet résultat.

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

parse lève une exception pour les données invalides

parse renvoie la valeur validée en cas de réussite et lève un ZodError en cas d’échec, ce qui convient lorsque des données invalides sont véritablement exceptionnelles.

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

Intercepter les erreurs de parse

Encapsulez parse dans try/catch pour gérer l’erreur levée et l’examiner afin d’obtenir des détails sur l’échec.

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 renvoie un résultat

safeParse ne lève jamais d’exception. Il renvoie un objet avec success: true et data, ou avec success: false et error.

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

Restreindre le résultat

Le résultat est une union discriminée basée sur success. Sa vérification le restreint à 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);
}

Quand utiliser parse

Utilisez parse lorsque des données d’entrée invalides signalent un bug ou doivent interrompre l’opération, par exemple lors de la lecture de la config requise au démarrage.

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

Quand utiliser safeParse

Utilisez safeParse lorsque des données d’entrée invalides sont attendues et que vous souhaitez les gérer correctement, par exemple lors de la validation de données envoyées par des formulaires utilisateur.

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
}

Lire les problèmes de ZodError

Un ZodError contient un tableau issues décrivant chaque problème : le chemin, un message et le code d’erreur.

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

Les deux renvoient le type inféré

En cas de réussite, les deux méthodes vous fournissent la valeur validée, typée comme z.infer<typeof schema> ; le code qui suit est donc entièrement typé.

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

Choisir la bonne méthode

Règle générale : utilisez parse pour les chemins fiables ou critiques, où un échec doit interrompre l’exécution ; utilisez safeParse pour les données d’entrée non fiables que vous devez gérer sans provoquer de plantage.

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

Combiner les deux styles

Un schéma courant consiste à encapsuler safeParse dans une fonction utilitaire qui renvoie des données typées ou une erreur mise en forme, offrant les avantages des deux méthodes.

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.

Vérification rapide : parse ou safeParse

Vérifiez votre compréhension de la différence entre parse et safeParse.

Récapitulatif : parse ou safeParse

Vous avez appris que parse lève une exception pour les données invalides, tandis que safeParse renvoie un résultat success/error, quand utiliser chacune de ces méthodes et comment lire les problèmes 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);

Questions Fréquemment Posées

La leçon « parse ou safeParse » est-elle gratuite ?

Oui — le texte complet de « parse ou safeParse » est gratuit à lire ici sur le web. Pour la pratiquer de manière interactive (un éditeur de code intégré et un tuteur IA 24/7) et déverrouiller le reste du cours TypeScript Academy, passe à CoddyKit PRO. Le cours TypeScript Academy comprend 4 leçons au total.

Qu'est-ce que j'apprendrai dans « parse ou safeParse » ?

Gérer avec élégance la réussite et l’échec de la validation. Tu pratiques TypeScript Academy avec du code pratique que tu exécutes directement dans le navigateur, et un tuteur IA 24/7 répond à tes questions au fur et à mesure que tu avances dans la leçon.

Dois-je avoir de l'expérience pour commencer TypeScript Academy ?

Aucune expérience préalable n'est requise. TypeScript Academy sur CoddyKit est structuré pour les débutants jusqu'aux apprenants avancés, donc tu peux commencer ici ou depuis le début et avancer à ton rythme. Ceci est la leçon 3 sur 4.

Combien de temps prend la leçon « parse ou safeParse » ?

La plupart des leçons CoddyKit prennent environ 5–10 minutes. Chacune est courte et interactive, tu progresses régulièrement et tu repiques exactement où tu t'es arrêté sur le web et l'app.

Peux-tu écrire et exécuter du code dans cette leçon TypeScript Academy ?

Oui. Chaque leçon TypeScript Academy inclut un éditeur de code intégré, tu écris et exécutes du vrai code directement dans ton navigateur et tu reçois des retours IA instantanés — aucune configuration locale requise.

Toutes les leçons de ce cours

← Retour à TypeScript Academy