Aller au contenu principal

Interopérabilité Kanon ↔ Zod

Données de compatibilité réelles. Pas de suppositions. Analysé contre Zod v4 Classic.

Zod v4 Classic vs Mini

Zod v4 propose deux API :

  • Classic : Chaînage de méthodes (.optional(), .nullable()). Cette page couvre Classic.
  • Mini : Fonctions pures comme l'API native de Kanon (optional(schema), nullable(schema))

Si vous utilisez Zod Mini, envisagez d'utiliser les imports directs de Kanon au lieu du shim z : la syntaxe est quasi identique.

TL;DR​

API principale compatible. Primitives, composites, unions, wrappers, coercition, refinements et transforms fonctionnent avec le shim z.

MétriqueValeur
Primitives15/15 (100%)
Composites6/6 (100%)
Opérateurs3/3 (100%)
Modes objet3/3 (100%)
Effort de migrationChangement d'imports uniquement (pour la plupart des schémas)
En résumé

Si vous utilisez des primitives, objets, tableaux, unions et wrappers basiques, vous êtes couvert. Changez vos imports et c'est fait.

À propos de cette page​

L'API native de Kanon est conçue pour un tree-shaking optimal : fonctions pures, imports directs, pas de surcharge de classes. Nous recommandons d'utiliser les imports directs pour les applications en production.

Cependant, pour une migration fluide depuis Zod, Kanon fournit un shim z avec une API compatible 1:1 avec Zod :

// Changez juste votre import
import { z } from "pithos/kanon/helpers/as-zod.shim";

// Votre code Zod existant fonctionne tel quel
const schema = z.object({
  name: z.string(),
  age: z.number().optional(),
});

Cette page se concentre sur le shim z : toutes les tables de compatibilité ci-dessous utilisent la syntaxe z.. Une fois migré, vous pouvez progressivement refactorer vers les imports directs pour une optimisation maximale du bundle.

Ce que Kanon gère de la même façon​

Cliquez pour développer chaque catégorie et voir les fonctionnalités supportées :

Primitives (100%)15/15

z.string(), z.number(), z.boolean(), z.bigint(), z.date(), z.symbol(), z.undefined(), z.null(), z.void(), z.any(), z.unknown(), z.never(), z.literal(), z.enum(), z.nativeEnum()

Composites (100%)6/6

z.object(), z.array(), z.tuple(), z.record(), z.map(), z.set()

Opérateurs (100%)3/3

z.union(), z.intersection(), z.discriminatedUnion(), .or(), .and()

Wrappers (100%)7/7

.optional(), .nullable(), .nullish(), .default(), .readonly(), z.lazy(), .catch()

Transformations d'objets (100%)5/5

.partial(), .required(), .pick(), .omit(), .keyof()

Modes objet (100%)3/3

z.object() (strip par défaut), .strict(), .passthrough()

Coercition (100%)5/5

z.coerce.string(), z.coerce.number(), z.coerce.boolean(), z.coerce.bigint(), z.coerce.date()

Refinements (100%)2/2

.refine(), .superRefine()

Transforms (100%)2/2

.transform(), .array()

Contraintes de chaînes (100%)10/10

.min(), .max(), .length(), .email(), .url(), .uuid(), .regex(), .includes(), .startsWith(), .endsWith()

Contraintes numériques (100%)10/10

.min(), .max(), .int(), .positive(), .negative(), .gt(), .gte(), .lt(), .lte(), .multipleOf()

Exemples de code​

Avec le shim z, votre code Zod fonctionne tel quel. Changez juste l'import.

Schéma basique​

// Zod
import { z } from "zod";

// Kanon (changez juste l'import !)
import { z } from "pithos/kanon/helpers/as-zod.shim";

// Le même code fonctionne dans les deux
const userSchema = z.object({
  id: z.number(),
  name: z.string(),
  active: z.boolean(),
});

Avec contraintes​

Kanon supporte les mêmes méthodes de contraintes que Zod, y compris les longueurs min/max, les nombres positifs et la validation d'email :

import { z } from "pithos/kanon/helpers/as-zod.shim";

const productSchema = z.object({
  sku: z.string().min(3).max(10),
  price: z.number().positive().max(9999),
  email: z.string().email(),
});

Avec Optional/Nullable​

Les modificateurs optional, nullable et nullish fonctionnent de manière identique à Zod, aucun changement de code nécessaire :

import { z } from "pithos/kanon/helpers/as-zod.shim";

const profileSchema = z.object({
  username: z.string(),
  bio: z.string().optional(),
  avatar: z.string().nullable(),
  nickname: z.string().nullish(),
});

Types union​

Kanon supporte les types union via z.union() et les valeurs littérales, comme Zod :

import { z } from "pithos/kanon/helpers/as-zod.shim";

const statusSchema = z.union([
  z.literal("pending"),
  z.literal("approved"),
  z.literal("rejected"),
]);

const responseSchema = z.object({
  data: z.union([z.string(), z.number()]),
});

Ce que Kanon ne supporte pas​

Le shim z se concentre sur la validation principale. Certaines fonctionnalités de Zod ne sont pas disponibles et ne le seront probablement jamais.

Absent du shim z​

FonctionnalitéAlternative
.pipe()Chaînez les schémas manuellement
.brand()Utilisez des assertions de types
z.instanceof()Utilisez .refine(v => v instanceof Class)
z.preprocess()Utilisez .transform() avant la validation
z.custom()Utilisez .refine() ou .superRefine()

Validateurs de format de chaînes (Zod v4)​

FonctionnalitéAlternative
z.email(), z.uuid(), z.url()Utilisez z.string().email(), etc.
z.jwt(), z.ipv4(), z.base64()Utilisez z.string().regex()
Pourquoi Kanon ne couvre pas 100% de Zod

Kanon se concentre délibérément sur les fonctionnalités essentielles : celles que vous utilisez réellement dans 90%+ des projets.

Couvert à 100% :

  • Primitives, objets, tableaux, tuples, unions, intersections
  • Optional, nullable, default, transforms, refinements
  • Contraintes de chaînes (min, max, regex, email, url...)

Non inclus par choix :

  • Formats d'identifiants spécialisés (CUID, ULID, KSUID, XID, NanoID...)
  • Validateurs réseau (plages CIDR, numéros de téléphone E.164...)
  • Validateurs de hash (MD5, SHA256, SHA512 en hex/base64...)
  • Parsing de durées ISO 8601, formats datetime étendus...

Ce sont des cas limites. Zod les embarque par défaut, ce qui ajoute du poids même si vous ne les utilisez jamais. Kanon non. Si vous en avez besoin, z.string().regex() fonctionne parfaitement.

Ce que Kanon ajoute​

Au-delà de la compatibilité Zod, Kanon apporte des fonctionnalités uniques :

FonctionnalitéDescription
Compilation JITCompilation automatique en validateurs optimisés (2-10x plus rapide)
Tree-Shaking parfaitFonctions pures, pas de surcharge de classes, bundle le plus petit possible
strictObject() / looseObject()Modes de validation d'objets explicites
parseBulk()Validation par lots optimisée pour les tableaux
Imports directsImportez uniquement ce que vous utilisez pour un tree-shaking maximal

Prêt à migrer ? Le guide de migration complet étape par étape se trouve dans la documentation du module Kanon: installer, changer les imports, gérer les cas limites et optimiser avec les imports directs. Aller au guide de migration →

Pas sûr de quelle bibliothèque correspond à votre cas d'usage ? Voir l'aperçu des comparaisons.

Après la migration

Une fois migré avec le shim z, vous pouvez progressivement refactorer vers les imports directs pour des bundles encore plus petits. Consultez la documentation API pour l'API native de Kanon.

Related