Un type TypeScript disparaît à la compilation. Le formulaire, la réponse d'API et le fichier de configuration, eux, arrivent à l'exécution, et rien ne garantit qu'ils ressemblent à ce qui était annoncé.
Zod comble ce trou : le même schéma vérifie la donnée pour de vrai et fournit son type.
Définition
Zod est une bibliothèque de validation par schéma. On décrit la forme attendue en assemblant des règles, puis on confronte une valeur inconnue à cette description. Ce qui passe est conforme, ce qui échoue est décrit ligne par ligne.
import { z } from "zod";
const Facture = z.object({
id: z.number().int().positive(),
email: z.email(),
montant: z.number().min(0),
statut: z.enum(["brouillon", "payee"]),
});
const resultat = Facture.safeParse(donneeRecue);
if (!resultat.success) {
console.log(resultat.error.issues);
// [{ path: ["id"], message: "Too small: expected number to be >0" }]
}Chaque règle s'enchaîne à la précédente et restreint un peu plus l'ensemble accepté. La lecture se fait de gauche à droite : un nombre, entier, strictement positif.
Deux façons d'échouer
| Méthode | Ce qu'elle fait en cas d'échec |
|---|---|
| parse | Lève une erreur, à attraper avec un try |
| safeParse | Rend un objet dont la propriété success vaut false |
La première convient là où l'échec est anormal, par exemple une variable d'environnement manquante au démarrage. La seconde convient partout où l'échec est attendu, typiquement un formulaire, puisqu'il faut afficher les messages plutôt qu'interrompre.
Le type vient du schéma
Écrire le schéma puis retaper le type à côté crée deux vérités qui divergeront. Zod déduit le second du premier, ce qui garantit qu'ils ne peuvent plus se contredire.
type Facture = z.infer<typeof Facture>;
// { id: number; email: string;
// montant: number; statut: "brouillon" | "payee" }Après un safeParse réussi, la propriété data porte déjà ce type. La vérification à l'exécution et la connaissance à la compilation viennent donc du même endroit, ce qui est exactement ce qui manquait à TypeScript seul.
Questions fréquentes
Où placer la validation ?
À chaque frontière du programme : réponse d'API, corps de requête reçu, formulaire, variables d'environnement, contenu d'un fichier JSON. À l'intérieur, une fois la donnée validée, les types suffisent. Valider deux fois la même valeur au milieu de la chaîne ne fait que ralentir le programme.
Zod remplace-t-il TypeScript ?
Non, les deux répondent à des questions différentes. TypeScript vérifie la cohérence du code écrit, avant l'exécution, sans coût une fois compilé. Zod vérifie une valeur réelle pendant l'exécution, avec un coût. Ils se complètent d'autant mieux que le second sait produire ce dont le premier a besoin.
Que faire des messages d'erreur ?
Les messages par défaut sont écrits en anglais et pour un développeur : ils conviennent aux journaux, pas à un utilisateur. Chaque règle accepte un message personnalisé, ce qui permet de traduire et de reformuler au cas par cas. Le tableau issues porte le chemin de chaque champ fautif, de quoi placer le message sous le bon champ du formulaire.