Sortie de Zod 4

 (zod.dev)
1 points par GN⁺ 2025-05-20 | 1 commentaires | Partager sur WhatsApp
  • Bibliothèque de déclaration de schémas et de validation : sortie de la version 4 de Zod. Cette version stable inclut des améliorations majeures de performances et des fonctionnalités demandées de longue date
  • De fortes améliorations ont été apportées en vitesse et taille de bundle, et une nouvelle version mini (v4-mini) réduit drastiquement la taille du bundle
  • Ajout d’un nouveau registre de métadonnées, de la conversion vers JSON Schema et de l’inférence des types récursifs
  • L’expérience développeur est renforcée avec la personnalisation des messages d’erreur et un système de locales multilingue
  • L’extensibilité progresse encore avec l’introduction d’un sous-package core réutilisable pour construire des bibliothèques à l’avenir

Présentation de Zod 4

Informations sur cette sortie majeure

  • Après un an de développement intensif, Zod 4 sort en version stable
  • Le développement a été mené avec le soutien de l’OSS Fellowship de Clerk
  • Zod 4 est actuellement distribué en parallèle de Zod 3, ce qui facilite une migration progressive
  • Les détails sur certains changements incompatibles sont disponibles dans le Migration guide

Contexte de la croissance

  • Par rapport à Zod 3, lancé en 2021, Zod 4 a connu une croissance exponentielle du nombre d’étoiles GitHub et des téléchargements hebdomadaires
  • Zod 4 est bien plus rapide, plus léger et améliore l’efficacité du compilateur TypeScript
  • Neuf problèmes majeurs réclamés de longue date ont été résolus

Benchmarks et performances

  • Gain de vitesse :
    • Parsing de chaînes : 14,71 fois plus rapide
    • Parsing de tableaux : 7,43 fois plus rapide
    • Parsing d’objets (safeParse) : 6,5 fois plus rapide
  • Des scripts sont fournis pour exécuter directement les benchmarks depuis le dépôt
  • Grâce à une structure générique améliorée, les chaînages de méthodes comme .extend() et .omit() offrent des performances de compilation multipliées par 10
  • La vitesse de compilation TypeScript s’améliore fortement sur les schémas volumineux et les grandes bases de code

Taille de bundle et Zod Mini

  • La taille du bundle de base a diminué de 57 %, ce qui rend v4 2,3 fois plus petit que v3
  • zod/v4-mini propose une API orientée fonctions, compatible tree-shaking, qui peut réduire la taille du bundle jusqu’à 85 %
  • Les différences d’API entre core et v4-mini sont détaillées dans la documentation officielle
  • La structure a été pensée pour permettre aux bundlers d’éliminer facilement les méthodes inutilisées

Registre de métadonnées et prise en charge de JSON Schema

  • Il est possible d’enregistrer et de gérer des typed metadata de manière fortement typée sur les schémas
  • Le registre global (z.globalRegistry) gère les métadonnées compatibles JSON Schema et permet leur inclusion automatique
  • .meta() et .describe() facilitent la documentation des schémas
  • .toJSONSchema() permet de convertir les schémas au format JSON Schema, avec prise en compte automatique des métadonnées

Inférence automatique des types récursifs

  • Les types d’objets récursifs et mutuellement récursifs peuvent être définis et inférés naturellement sans cast de type séparé
  • L’ergonomie progresse nettement par rapport aux patterns de Zod 3
  • Même avec des types récursifs et mutuellement récursifs, toutes les méthodes de schéma restent utilisables

Types de fichiers et fonctionnalités de validation

  • Le nouveau type file() permet de valider des instances de File
  • Des validations de contraintes variées sont proposées, notamment sur la taille des fichiers (min, max) et les types MIME

Messages d’erreur et système de locales

  • L’API de locales globale (z.locales) permet la prise en charge multilingue des messages d’erreur
  • La fonction officielle z.prettifyError fournit un formatage d’erreurs plus convivial

Fonctions de format et template literals

  • Les formats de chaîne existants (email, etc.) sont remontés au niveau supérieur, ce qui améliore la lisibilité et le tree-shaking
  • Plusieurs options de regex d’email sont proposées pour répondre à différents besoins de validation
  • Prise en charge des types template literal : mise en œuvre facilitée de motifs de chaînes et de combinaisons complexes exprimables dans le système de types

Nouveaux formats numériques et bigint

  • Prise en charge de types entiers et à virgule flottante à largeur fixe (int32, uint64, etc.)
  • Possibilité de générer des schémas avec contraintes min/max ajoutées automatiquement dans des plages sûres

Présentation de z.stringbool

  • Permet le parsing de booléens à partir de chaînes (yes, no, etc.), avec prise en charge du parsing façon variables d’environnement
  • Les valeurs truthy/falsy sont personnalisables

Unification de l’API de personnalisation des erreurs

  • Un paramètre error unifié rationalise la structure des messages d’erreur et de la logique de traitement
  • Les anciennes API liées aux erreurs (message, invalid_type_error, errorMap) sont désormais dépréciées

Autres améliorations clés

  • Les discriminated unions prennent en charge divers schémas, l’imbrication et les combinaisons
  • .literal() peut désormais accepter plusieurs valeurs à la fois
  • Les validations personnalisées comme .refine() sont intégrées de façon plus intuitive
  • Avec .overwrite() lié aux transformations, un post-traitement est possible sans changer le type transformé

Extensibilité de la bibliothèque et nouveau core

  • Avec zod/v4/core, les fonctionnalités essentielles sont isolées dans un sous-package distinct, ce qui facilite les intégrations et extensions sur diverses bibliothèques et plateformes
  • Une documentation guide ainsi que des exemples d’extension sont fournis pour les auteurs de bibliothèques

Conclusion

  • Zod 4 s’impose comme une bibliothèque de validation de données qui améliore fortement la sûreté de typage, les performances, l’extensibilité et l’expérience développeur
  • D’autres billets de conception et mises à jour sont annoncés pour la suite
  • Un large éventail de support est prévu, aussi bien pour les utilisateurs existants que pour les auteurs de bibliothèques

Bon parsing à tous
— Colin McDonnell @colinhacks

À lire aussi

1 commentaires

 
GN⁺ 2025-05-20
Avis Hacker News

  • L’auteur demande des retours d’expérience et fournit une explication détaillée de sa stratégie de gestion des versions, en soulignant que npm n’est pas adapté à la gestion d’un cas comme Zod ; il mentionne que de très nombreuses bibliothèques importent et utilisent directement les interfaces/classes de Zod, et que si Zod change de version majeure, toutes ces bibliothèques devraient s’adapter en même temps, avec un risque d’explosion des versions ; comme en Go, les changements cassants passent par l’ajout d’un nouveau sous-chemin, et dans un environnement TypeScript, un seul zod@^3.25.0 peut prendre en charge simultanément "zod/v3" et "zod/v4", ce qui offre un chemin de mise à niveau progressive aux utilisateurs finaux

    • Remerciements pour la contribution à Zod et enthousiasme particulier pour les améliorations de performances de tsc et des discriminated unions ; la logique de versioning est bien comprise, mais il est suggéré qu’il serait aussi utile, pour des utilisateurs comme lui qui ne craignent pas les conflits de dépendances transitives, de proposer Zod 4 sous la forme d’un paquet unique 4.0.0 ; devoir remplacer les imports par "zod/v4" risque selon lui d’ajouter du bruit dans le code et des frictions supplémentaires, comme des conflits avec les imports automatiques de l’IDE ; malgré cela, la mise à niveau lui paraît globalement très prometteuse et il remercie l’équipe

    • Il s’excuse s’il a raté l’information en lisant l’article sur mobile, puis demande si le principal irritant lié à .optional() fait partie des 9/10 problèmes majeurs corrigés dans cette version ; il précise continuer à utiliser Zod malgré ces désagréments, tant la bibliothèque est excellente, et remercie pour ce très bon travail

    • Remerciements pour le fait de pouvoir supprimer beaucoup de hacks manuels avec cette nouvelle version de Zod ; il explique utiliser zod-key-parser pour réduire les fautes de frappe et se demande pourquoi ce type de fonctionnalité n’est pas inclus nativement dans la bibliothèque, si cela est considéré hors périmètre ou simplement pas encore implémenté ; il partage aussi des discussions ouvertes à ce sujet

    • Il souligne que minimiser la douleur à court terme est souvent la meilleure approche et cite le chaos de la migration Python 2/3 comme exemple marquant

    • Retour d’expérience sur les grandes difficultés rencontrées avec la combinaison de types récursifs et de discriminated unions, par exemple pour inclure du XML dans du JSON ; il espère que cette mise à jour améliore nettement la situation

  • Un avis exprime des doutes sur l’import zod/v4-mini, en supposant que cela pourrait au contraire augmenter la taille du bundle ; comme la documentation officielle indique que zod/v4 est recommandé dans la plupart des cas, les développeurs d’applications utiliseront zod/v4, mais si les auteurs de bibliothèques ajoutent aussi zod/v4-mini pour économiser de la taille, les deux risquent de se retrouver dans le bundle avec duplication ; il demande si ce problème serait réduit si zod/v4 n’était qu’un wrapper de zod/v4-mini

  • Pour faciliter la migration vers Zod 4, v3 et v4 sont proposés simultanément à partir de zod@3.25, ce qui amène une critique disant que cette structure, combinée aux limites de gestion des dépendances de npm, oblige à faire passer v4 pour v3 ; cela pointe aussi l’inefficacité du système de peer dependencies de npm

    • L’auteur réexplique la stratégie de versioning à la Go par ajout de sous-chemins ; il souligne qu’elle est difficile à introduire dans l’écosystème Zod à cause des particularités de npm, mais qu’elle présente l’avantage de supporter simultanément v3 et v4 tout en offrant une migration progressive

    • Un autre intervenant dit ne pas être d’accord avec l’idée selon laquelle v4 se ferait passer pour v3 à cause d’un système de peer dependencies cassé ; selon lui, il s’agit simplement d’un mécanisme de migration progressive, où l’on remplace peu à peu par zod/v4 avant de passer entièrement à v4

    • Beaucoup critiquent cette décision, mais un commentaire insiste sur le fait qu’il s’agit moins d’une limite fondamentale de npm que d’un choix pragmatique pour permettre une transition graduelle d’une bibliothèque comportant de gros changements

    • Quelqu’un dit avoir peut-être un biais lié à sa longue expérience exclusive avec npm, mais se demande quelle meilleure méthode permettrait de prendre en charge progressivement la transition de v3 à v4 plutôt que d’exiger une migration brutale en une seule fois

    • Un utilisateur explique avoir déjà constaté de gros progrès avec la bêta de Zod 4, mais ne pas parvenir à faire la mise à niveau proprement dans une grosse base de code à cause des réglages de résolution de modules ; il aurait préféré une sortie simple sous forme de nouvelle version majeure, sans couche legacy ; il relaie l’explication de l’auteur sur le risque d’explosion des versions, mais pense malgré tout que le maintien simultané du support v3 peut amortir le choc

  • Une question porte sur la manière de modéliser les réponses serveur quand les types varient selon les endpoints, ou quand certains champs peuvent être null, comme pour des utilisateurs anonymes ; la personne explique qu’en multipliant des fonctions du type normalizeUser ou normalizePost, la maintenance devient de plus en plus complexe, et demande comment cela est géré en pratique

    • Une réponse propose les discriminated unions comme solution, avec une partie commune du schéma définie en objet puis étendue selon les cas ; elle note que dans les situations très variées, la complexité restera de toute façon élevée, mais qu’un validateur de schéma permet au moins de garder une structure cohérente

    • Une autre réponse estime qu’idéalement, la structure de type de User devrait être définie à partir d’une source unique, par exemple sous forme de discriminated union ; en supposant un backend Python, elle suggère un ensemble de modèles Pydantic + unions, puis la génération des types client TypeScript via OpenAPI ou GraphQL

    • Une autre intervention explique que, sans exemple concret, il est difficile de répondre précisément, mais qu’ajouter une propriété discriminante dans les unions, par exemple "user_type", facilite l’accès aux champs spécifiques, car le système de types peut alors reconnaître les bons attributs selon le cas

    • Un autre avis affirme que le serveur devrait exposer directement ses types ; réécrire séparément tous les types côté client serait inefficace ; avec un backend Python, il décrit une approche où Pydantic génère automatiquement la spécification OpenAPI, utilisée ensuite pour générer les types du client TypeScript

    • Il est aussi rappelé que GraphQL est conçu précisément pour ce genre de cas ; avec une bibliothèque GraphQL pour TypeScript, on peut inférer automatiquement la forme des résultats de requête, et le type de réponse s’adapte dynamiquement aux champs sélectionnés

  • Malgré les améliorations de Zod 4, un commentaire affirme qu’ArkType reste nettement plus rapide ; selon lui, les bibliothèques existantes sont limitées en performances par les contraintes de rétrocompatibilité et de stabilité syntaxique, et son analyse de projet l’a conduit à choisir ArkType pour ses performances et son ergonomie TypeScript

    • Quelqu’un dit avoir vu les métriques de vitesse d’ArkType et se demande quel impact concret cela a réellement ; dans des cas courants comme la validation de formulaires, l’effet semble limité, d’où sa question sur d’éventuels usages plus sensibles à la performance, comme une validation d’entrée d’API à très haut débit

    • Un autre précise qu’ArkType n’était pas inclus dans sa recherche initiale, mais qu’il l’avait découvert en cherchant une bonne ergonomie TypeScript ; il n’a néanmoins pas l’intention de quitter Zod

    • Un retour d’expérience indique qu’utiliser ArkType a été très difficile, tandis que Zod est jugé bien plus agréable à utiliser

    • Quelqu’un demande pourquoi ArkType a été choisi plutôt que TypeBox

  • Félicitations à l’équipe Zod pour cette nouvelle sortie ; néanmoins, au vu de la quantité de changements cassants listés dans le guide de migration, il y a une inquiétude sur la charge de maintenance pour les gros projets fortement dépendants de Zod ; à partir d’une expérience de maintenance de vieux projets front-end, le commentaire exprime aussi une certaine lassitude face au rythme des grands changements et au manque de documentation dans l’écosystème JS actuel

    • Une personne dit faire tourner plusieurs grosses applications Next.js et avoir vécu, sur la dernière année, des changements lourds et difficiles comme Next.js 14→15, Next.js pages→app router, React 18→19, Eslint 8→9, Tailwind 3→4 ; elle raconte à quel point cela a été éprouvant, au point d’avoir parfois pensé qu’il aurait mieux valu construire le projet avec Django ; elle note surtout que la migration Tailwind 3→4 a été, contre toute attente, la plus douloureuse

    • Il est expliqué que la stratégie de publication simultanée de l’édition mini vise justement à atténuer ce type de problème, à faciliter la transition progressive, et que l’introduction de mini était aussi devenue nécessaire pour rester compétitif face aux alternatives sur le terrain de l’optimisation du tree-shaking

    • Une suggestion indique que des outils comme les LLM peuvent rendre la migration moins difficile

  • Un commentaire rappelle que Zod est largement supérieur à plusieurs alternatives existantes, mais regrette qu’en développement web il faille toujours décrire la même structure de données de plusieurs façons : validation d’entrée en JS, spécification d’API via Swagger, définitions séparées côté serveur et client, etc. ; cela est jugé trop répétitif et fastidieux

    • Une réponse déplore que TypeScript reste cantonné à l’analyse statique ; sans forcément vouloir des vérifications runtime intégrées, elle aimerait au moins que les données de type des classes, fonctions et objets puissent être facilement réutilisées à l’extérieur ; aujourd’hui, chaque outil doit définir ses propres modèles et builders, d’où une duplication inévitable ; le projet de standardisation Standard Schema semble commencer à s’intégrer aux principales bibliothèques de validation, mais l’extension vers les spécifications d’API et les ORM n’en est encore qu’à ses débuts

    • Une autre réponse rappelle que l’intérêt central de ces outils est de pouvoir définir une fois puis propager la type safety dans toute l’application ; les schémas Zod peuvent ainsi servir de source de vérité unique

    • Il est aussi ajouté que beaucoup de personnes qui trouvent cette architecture verbeuse restent pourtant réticentes dès qu’on propose d’unifier tout cela autour de TypeScript seul, Zod compris

    • Un autre commentaire souligne que toutes les API et tous les systèmes sont en évolution et en expérimentation permanentes ; même si cette multiplication des couches est un inconvénient, dans la pratique, quand l’objectif est simplement que « le projet tourne », cela finit souvent par créer encore plus de travail

    • Globalement, on peut aussi recourir à une approche de type safety de bout en bout comme trpc, mais cela impose d’unifier à la fois le front-end et le back-end en TypeScript, ce qui pose des limites pratiques, notamment dès qu’il faut aussi prendre en charge des plateformes hors web comme le mobile

  • Sans être expert, un commentaire estime que JSON-Schema, fondé sur des schémas et implémentable dans d’autres langages que TypeScript, peut être un bon choix ; il cite par exemple ajv.js.org et demande comment cela se compare à Zod

    • Une réponse explique que Zod ne valide pas seulement des données JSON, mais l’ensemble des objets JS, y compris des valeurs non représentables en JSON comme des dates ou des instances de classes ; il peut aussi intervenir lors d’un processus de transformation, avec des schémas écrits sur des chaînes, par exemple pour valider et convertir une chaîne de date ISO en objet Date

    • Il est aussi précisé que Zod 4 prend désormais en charge la conversion des schémas Zod en JSON-Schema, alors qu’il fallait auparavant une bibliothèque externe ; l’un des grands points distinctifs de Zod reste les fonctionnalités preprocess et refine, qui permettent d’ajouter des callbacks avant validation, par exemple pour transformer du MM/DD/YYYY en DD/MM/YYYY avant de valider — chose impossible avec JSON-Schema

    • Une autre réponse considère que JSON-Schema est aussi un très bon choix ; dans ce cas, TypeBox convient bien pour la génération ; on peut utiliser avj ou bien un système de validation maison ; un validateur maison peut être plus rapide, mais il reste synchrone, tandis que avj permet aussi des validations asynchrones, ce qui peut être utile pour des validations plus poussées

    • Pour un usage multi-langage, JSON-Schema est présenté comme l’option la plus universelle, et enveloppé dans OpenAPI, il permet en plus de générer automatiquement la documentation d’API

  • Quelqu’un vient tout juste de commencer à adopter Zod sur un nouveau projet et se réjouit du timing parfait de cette release ; sans cela, il aurait probablement dû faire de nombreux changements pour migrer vers v4, alors que là, le moment tombe idéalement

  • Une réaction dit être surprise par le nombre d’avis négatifs ; lors des premiers tests de v4, la nouvelle API lui plaisait, mais le chemin de migration l’inquiétait, au point de réfléchir à proposer une publication sous un nom de package séparé ; au final, la solution choisie par l’auteur est jugée excellente et particulièrement élégante, car elle permet d’adopter v4 immédiatement sans attendre la mise à jour de toutes les dépendances

    • Un autre avis estime également qu’il est irréaliste, dans un domaine comme la validation, de tout migrer d’un seul coup, et que l’approche retenue est probablement la meilleure possible en pratique