Zod pour TypeScript : guide complet avec exemples

Introduction à Zod : qu'est-ce que c'est et pourquoi l'utiliser

Dans le développement web moderne avec TypeScript, l'un des problèmes clés est d'assurer l'intégrité des données. Même avec un typage strict, TypeScript ne peut pas garantir que les données provenant de sources externes (API, formulaires, localStorage, WebSocket) correspondent réellement aux types déclarés. Le compilateur TypeScript fonctionne au stade du développement, mais pendant l'exécution du programme, les types sont effacés. C'est là que Zod vient à la rescousse.

Zod est une bibliothèque de validation et de typage déclaratif de données pour TypeScript et JavaScript. Elle permet de créer des schémas (schemas) qui servent à la fois de validateur de données pendant l'exécution et de source de vérité pour les types statiques de TypeScript. La philosophie principale de Zod est "un schéma, deux usages" : vous écrivez le schéma une fois, et vous obtenez à la fois la validation et le type automatiquement déduit.

Les principaux avantages de Zod :

\n
• Sécurité des types : déduction automatique des types TypeScript à partir des schémas.
\n
• Déclarativité : syntaxe lisible et concise.
\n
• Compositionnalité : les schémas peuvent être combinés et étendus.
\n
• Erreurs détaillées : messages d'erreur de validation clairs.
\n
• Zéro dépendance : la bibliothèque ne nécessite aucun paquet supplémentaire.
\n

Installation de Zod

Zod est un paquet npm, donc l'installation se fait via le gestionnaire de paquets Node.js. La bibliothèque est écrite en TypeScript et est livrée avec des fichiers de déclaration de types prêts à l'emploi, donc l'installation supplémentaire de @types/zod n'est pas nécessaire.

# Installation via npm\nnpm install zod\n\n# Installation via yarn\nyarn add zod\n\n# Installation via pnpm\npnpm add zod

Après l'installation, vous pouvez importer Zod dans votre projet :

import { z } from "zod";

Remarque : Zod ne s'installe pas via pip, car c'est une bibliothèque pour l'écosystème JavaScript/TypeScript, et non Python.

Démarrage rapide avec un exemple de code

Créons un schéma simple pour valider les données d'un utilisateur et voyons immédiatement comment Zod combine validation et typage.

import { z } from "zod";\n\n// 1. Définir le schéma\nconst UserSchema = z.object({\n    id: z.number().positive(),\n    name: z.string().min(2, "Le nom doit contenir au moins 2 caractères"),\n    email: z.string().email("Email invalide"),\n    age: z.number().int().min(18, "L'âge doit être d'au moins 18 ans").optional(),\n});\n\n// 2. Déduire automatiquement le type à partir du schéma\ntype User = z.infer<typeof UserSchema>;\n\n// 3. Valider les données\nconst validData = {\n    id: 1,\n    name: "Anna",\n    email: "anna@example.com",\n    age: 25,\n};\n\nconst result = UserSchema.safeParse(validData);\n\nif (result.success) {\n    // result.data est de type User\n    console.log("Validation réussie :", result.data);\n} else {\n    // result.error contient des informations détaillées sur les erreurs\n    console.log("Erreurs de validation :", result.error.errors);\n}\n\n// Exemple avec des données invalides\nconst invalidData = {\n    id: -1,\n    name: "A",\n    email: "pas-un-email",\n};\n\nconst invalidResult = UserSchema.safeParse(invalidData);\nif (!invalidResult.success) {\n    console.log("Erreurs :", invalidResult.error.errors);\n    // Affichera :\n    // - id : doit être un nombre positif\n    // - name : Le nom doit contenir au moins 2 caractères\n    // - email : Email invalide\n}

Méthodes et fonctions principales de Zod

Dans cette section, nous allons examiner en détail 10 méthodes clés de Zod qui couvriront 90 % de vos besoins en validation.

1. z.string() — Validation des chaînes de caractères

Ce qu'elle fait : Crée un schéma pour valider les valeurs de type chaîne de caractères. Fournit une chaîne de méthodes pour imposer des contraintes supplémentaires.

Paramètres : Ne prend pas de paramètres lors de la création