Les Utility Types en TypeScript – Guide complet du débutant à l'avancé (avec Zod)

Les utility types de TypeScript sont des types génériques pré-définis qui facilitent les transformations de types. Ils permettent de créer de nouveaux types à partir de types existants, par exemple en rendant certaines propriétés optionnelles ou en extrayant le type de retour d'une fonction. Ce guide pédagogique, en trois niveaux (débutant, intermédiaire, avancé), présente tous les utility types standards de TypeScript (tels que Partial, Required, Readonly, Pick, Omit, Record, Exclude, Extract, NonNullable, Parameters, ReturnType, InstanceType, ThisType, etc.), avec pour chacun : une explication de son utilité, un exemple d'utilisation en TypeScript, puis une comparaison avec une approche équivalente sous Zod, une bibliothèque de schémas de validation runtime. Nous discuterons également des différences de philosophie entre les types utilitaires de TypeScript (système de types statique) et les schémas Zod (validation à l'exécution).

Mise en place du projet avec Bun

Pour essayer les extraits de code, vous pouvez initialiser un projet TypeScript minimal en utilisant Bun (un exécuteur JavaScript ultra-rapide qui fait aussi office de gestionnaire de paquets). Assurez-vous d'avoir Bun installé, puis dans un dossier vide exécutez :

shell

Bun créera un package.json et un tsconfig.json par défaut. Vous pouvez ensuite exécuter un fichier TypeScript avec bun run fichier.ts (Bun transpile TypeScript à la volée).

Nous sommes prêts à explorer les utility types !

Niveau débutant : utilitaires de base du système de types

Partial<T> – Propriétés optionnelles

TypeScript : L'utility type Partial<T> construit un type à partir d'un type existant T en rendant toutes ses propriétés optionnelles . Autrement dit, chaque propriété de T devient facultative (ajout d'un ?). Cela permet de représenter des objets partiels de ce type. Par exemple, si l'on a un type User avec des champs obligatoires, Partial<User> permettra d'en créer une version où ces champs peuvent être omis :

typescript

Ici, Partial<User> a le type { name?: string; age?: number }. On peut ainsi, par exemple, implémenter une fonction de mise à jour partielle sans exiger tous les champs :

typescript

On appelle updateUser(existingUser, { age: 26 }) avec un objet partiel – TypeScript garantit statiquement que fieldsToUpdate ne contient que des clés valides de User.

Equivalent avec Zod : Zod offre une méthode équivalente pour rendre un schéma d'objet partiel. La méthode .partial() appliquée à un schéma z.object rend toutes les clés optionnelles, à l'instar de Partial en TypeScript . Par exemple :

typescript

Ici PartialUserSchema est un schéma qui valide les objets ne contenant éventuellement qu'un sous-ensemble des clés (name et age deviennent facultatifs). On peut vérifier son fonctionnement :

typescript

Zod permet aussi de rendre seulement certaines propriétés optionnelles en passant un objet en paramètre (UserSchema.partial({ age: true }) ne rend optionnel que age ). À noter, .partial() n'agit que sur le premier niveau ; Zod fournit aussi .deepPartial() pour rendre optionnels récursivement les champs imbriqués .

Required<T> – Propriétés requises

TypeScript : L'utility type Required<T> est l'inverse de Partial : il crée un type à partir de T en rendant toutes ses propriétés obligatoires (non-optionnelles) . Il est utile pour « solidifier » un type dont certaines propriétés étaient optionnelles. Par exemple :

typescript

Dans cet exemple, Required<Settings> est équivalent à { theme: string; fontSize: number } – toute omission de propriété devient une erreur de compilation.

Equivalent avec Zod : Pour un schéma Zod, l'équivalent est la méthode .required(), qui transforme un schéma d'objet en rendant toutes ses propriétés requises (contrairement à .partial() qui les rend optionnelles) . Cette méthode est surtout utile si l'on a d'abord défini un schéma partiel et qu'on souhaite en obtenir la version stricte. Par exemple :

typescript

Ici StrictUserSchema exige que name et age soient présents. On peut aussi cibler certaines propriétés : BaseUserSchema.required({ age: true }) rend seulement age requis (et laisse name optionnel) .

Notez que Required<T> agit au temps de compilation (il n'existe plus dans le code JavaScript émis), alors que schema.required() de Zod agit à l'exécution en validant la présence des clés lors du parse.

Readonly<T> – Immutabilité des propriétés

TypeScript : L'utility Readonly<T> transforme un type T en rendant ses propriétés en lecture seule (immutables) . Toute tentative de réassigner ces propriétés sera signalée comme erreur à la compilation. Par exemple :

typescript

Ici, todo est de type Readonly<Todo> donc ses champs ne peuvent être modifiés après l'initialisation. Cela correspond souvent à l'utilisation de Object.freeze en JavaScript, mais TypeScript ne gère cela qu'au niveau du type (il n'empêche pas réellement la mutation à l'exécution, il avertit seulement au moment de la compilation).

Equivalent avec Zod : Zod propose une fonctionnalité intéressante pour l'immuabilité. La méthode .readonly() appliquée à un schéma retourne un nouveau schéma qui, lors du parsing, appelle Object.freeze() sur le résultat, et dont le type statique est marqué Readonly<...> . Autrement dit, Zod peut figer l'objet validé et garantir qu'il correspond à un type readonly. Par exemple :

typescript

Ici, FrozenUserSchema fige l'objet en sortie de parse. Si vous essayez de modifier frozenUser, une exception sera levée à l'exécution car l'objet est immuable. Ainsi, Zod va plus loin que TypeScript : là où Readonly<T> est purement statique (les propriétés pourraient être modifiées en JS si on contournait le typage), le schéma Zod .readonly() assure l'immuabilité réelle à l'exécution en plus de fournir le type Readonly<...> correspondant.

Pick<T, Keys> – Sélection d'un sous-ensemble de propriétés

TypeScript : Pick<T, Keys> construit un nouveau type à partir de T en ne conservant que certaines propriétés spécifiées par Keys (généralement une union de littéraux de strings représentant les noms de propriétés) . C'est utile pour créer un type plus restreint à partir d'un type existant. Par exemple :

typescript

Ici, TodoPreview ne conserve que title et completed de FullTodo. Toute propriété non listée (description par ex.) est exclue du type résultant.

Equivalent avec Zod : Les schémas Zod d'objets possèdent aussi une méthode .pick() qui crée un nouveau schéma ne contenant que les clés indiquées , de manière semblable :

typescript

On passe un objet avec les clés à conserver mises à true. TodoPreviewSchema ne validera que des objets comportant title et completed (les autres propriétés de FullTodo seront ignorées par le parseur par défaut). Par exemple, TodoPreviewSchema.parse({ title: "Nettoyer", completed: false, description: "..." }) retournera { title: "...", completed: false } en ayant retiré description (car par défaut Zod ignore les clés non spécifiées, comportement qu'on peut ajuster avec .strict() ou .passthrough() selon le besoin).

De manière équivalente, Zod fournit .omit() pour l'effet inverse.

Omit<T, Keys> – Exclusion de propriétés

TypeScript : Omit<T, Keys> crée un nouveau type en partant de T et en supprimant certaines propriétés (Keys) . C'est le complément de Pick (d'ailleurs Omit<T, K> est souvent implémenté comme Pick<T, Exclude<keyof T, K>>). Exemple :

typescript

Ici TaskMeta ne contient plus que id et title. Les propriétés done et dueDate ont été exclues.

Equivalent avec Zod : La méthode .omit() de Zod produit un schéma d'objet sans les clés indiquées . Exemple :

typescript

TaskMetaSchema validera des objets ne comportant que id et title. Toute clé omise (done, dueDate) sera ignorée si présente en entrée. Ainsi, Pick et Omit permettent de projeter un schéma Zod sur un sous-ensemble de champs tout comme leurs équivalents TypeScript le font au niveau des types.

Record<Keys, Type> – Dictionnaire de clés typées

TypeScript : Record<Keys, Type> construit un type d'objet dont les clés sont de type Keys (généralement une union de littéraux de string ou un type string/number plus général) et les valeurs sont de type Type . Cela permet de décrire, par exemple, un objet indexé par des identifiants. Un exemple classique :

typescript

Ici, Record<CatName, CatInfo> garantit que l'objet cats a exactement les clés "miffy", "boris", "mordred", chacune associée à un CatInfo. Record est très utile pour typer des objets utilisés comme dictionnaires ou maps.

Equivalent avec Zod : Zod offre le schéma z.record(keySchema, valueSchema) pour valider des objets de ce genre . On peut l'utiliser avec un schéma de clé (par exemple z.string() ou un schéma de littéraux) et un schéma de valeur. Exemple :

typescript

Ici, AgeMapSchema valide n'importe quelle clé tant que c'est une string (par défaut, Zod z.record sans premier argument suppose string). Si vous avez un ensemble fini de clés, il est souvent préférable d'utiliser z.object({ ... }) avec des clés explicitement nommées ou z.enum([...]) pour contraindre les clés. D'ailleurs, Zod autorise un schéma de clés plus strict : on pourrait définir const CatNameSchema = z.enum(["miffy","boris","mordred"]) puis faire z.record(CatNameSchema, CatInfoSchema) – cependant, sachez qu'à l'exécution les clés d'objets JavaScript sont toujours des chaînes de caractères. Même une clé numérique sera convertie en string au runtime (par ex., une clé 1 devient "1" dans un objet JS) . Zod prend cela en compte et ne permet pas de définir un schéma de clé numérique pur sans le transformer en string.

En résumé, Record<Keys, Type> (TypeScript) et z.record(keySchema, valueSchema) (Zod) permettent tous deux de typer des dictionnaires. Le premier agit au niveau du système de types, le second à l'exécution pour valider la structure de l'objet.

Niveau intermédiaire : manipuler les unions et les types optionnels

Exclude<UnionType, ExcludedMembers> – Retrait de membres d'une union

TypeScript : Exclude<U, E> crée un type en enlevant de l'union U tous les membres qui sont assignables au type E . En d'autres termes, on exclut certains types d'une union. Par exemple :

typescript

Ici, Exclude<Role, "admin"> retire le littéral "admin" de l'union, ne laissant que "user" | "guest". Un autre exemple : Exclude<string | number | boolean, string> donnerait number | boolean (on retire tout ce qui est assignable à string). C'est utile pour affiner un type union en éliminant des cas indésirables.

Equivalent avec Zod : Pour restreindre les possibilités d'une union au runtime, on définit généralement un schéma n'incluant pas les cas à exclure. Par exemple, si l'on a un schéma RoleSchema = z.enum(["admin","user","guest"]), on peut créer un sous-ensemble en n'incluant pas "admin". Zod fournit justement pour les énumérations la méthode `.exclude([…]) qui génère un nouveau schéma d'énumération sans les valeurs spécifiées . Par exemple :

typescript

Ce schéma NonAdminSchema correspond exactement au type Exclude<Role, "admin"> mais assure en plus la validation à l'exécution. Sous le capot, RoleSchema.exclude(["admin"]) retire simplement "admin" de la liste des littéraux autorisés. De même, Zod propose .extract([...]) pour effectuer l'opération complémentaire.

Extract<Type, Union> – Extraction de membres d'une union

TypeScript : Extract<T, U> crée un type en conservant de T uniquement les membres assignables à U . C'est grosso modo l'inverse d'Exclude. Par exemple :

typescript

Autre exemple : Extract<"a" | "b" | "c", "a" | "f"> donnera "a" (car seul "a" est commun aux deux). Ce utility type sert donc à filtrer une union pour n'en extraire qu'un certain sous-type.

Equivalent avec Zod : Comme pour Exclude, Zod permet d'obtenir au runtime un schéma correspondant à un sous-ensemble d'une énumération via .extract([...]) . Reprenons l'exemple des rôles : pour extraire uniquement, disons, les rôles limités "user" et "guest" d'un RoleSchema complet :

typescript

Ici LimitedRolesSchema correspond au type Extract<Role, "user" | "guest">. En pratique, on pourrait obtenir le même résultat en définissant directement z.enum(["user","guest"]), mais .extract est pratique pour dériver un schéma d'un enum existant. Notons que .exclude et .extract de Zod s'appliquent aux schémas énumérations (z.enum ou z.nativeEnum), et non aux unions arbitraires de types complexes. Pour ces derniers, on construit généralement manuellement le nouveau schéma union désiré.

NonNullable<T> – Exclusion de null et undefined

TypeScript : NonNullable<T> construit un type en excluant null et undefined de T . Il est fréquent en TypeScript d'avoir des types union incluant ces valeurs « nullish » et de vouloir un type qui en soit purgé. Par exemple :

typescript

Ici, DefinitelyString ne contient plus que string (ni null ni undefined). Ce utility type est souvent utilisé en combinaison avec des conditions de présence (if (value != null) { ... }) pour aider le compilateur à affiner les types.

Equivalent avec Zod : Avec Zod, par défaut les schémas n'acceptent pas undefined ou null à moins qu'on ne le spécifie. Autrement dit, un schéma z.string() n'acceptera qu'une string, pas undefined. Pour autoriser ces valeurs, on utilise explicitement z.string().optional() (qui permet undefined) ou z.string().nullable() (qui permet null) ou encore .nullish() (qui permet l'un ou l'autre). Ainsi, obtenir l'équivalent d'un type NonNullable revient simplement à ne pas inclure de null/undefined dans le schéma. Si toutefois vous partez d'un schéma plus permissif et voulez le rendre plus strict, vous pouvez utiliser une combinaison de techniques : par exemple, la méthode .unwrap() permet d'extraire le schéma sous-jacent d'un schéma optionnel ou nullable .

typescript

Ici, OptionalName.unwrap() renvoie le schéma original z.string(). On peut ainsi « enlever » le caractère optionnel ou nullable introduit précédemment. Une autre approche consisterait à utiliser une refinement custom pour refuser null/undefined, mais ce serait redondant étant donné le comportement par défaut de Zod. En résumé, TypeScript offre NonNullable<T> pour purifier un type au niveau statique, tandis qu'avec Zod il suffit de définir un schéma n'autorisant pas ces valeurs (ce qui est le cas par défaut, sauf usage explicite de .optional()/.nullable()).

Niveau avancé : introspection de fonctions, classes et contexte

Parameters<T> – Tuple des paramètres d'une fonction

TypeScript : Parameters<Fn> extrait le type sous forme de tuple des paramètres de la fonction Fn . Ce utility type est utile pour réutiliser les types des paramètres d'une fonction (par exemple pour typer une fonction wrapper). Exemples :

typescript

Dans ces exemples, Parameters nous donne un tuple correspondant à la liste des types des arguments de la fonction fournie. Si le type n'est pas une fonction, Parameters retourne never. Pour les fonctions surchargées, il extrait les paramètres de la dernière signature. C'est un moyen d'obtenir un type tuple [Arg0Type, Arg1Type, ...] à partir d'un type fonction.

Equivalent avec Zod : Zod permet de définir des schémas de fonctions via z.function(argsSchema, returnSchema). En plus de valider les entrées/sorties, cela offre des méthodes d'introspection telles que .parameters() qui renvoie le schéma des paramètres (sous forme de tuple) et .returnType() pour le type de retour . On peut ainsi retrouver l'information équivalente à Parameters. Par exemple :

typescript

Ici, Params est exactement le tuple des types d'arguments, équivalent à ce qu'aurait donné Parameters<(arg0: string, arg1: number) => boolean>. Certes, ce tuple pourrait être obtenu directement en TypeScript, mais Zod nous donne un moyen de l'obtenir dynamiquement si besoin, et surtout de valider que des arguments correspondent à ces types à l'exécution. Notons que dans la pratique, on utilise rarement .parameters() seul ; on pourrait directement faire type Params2 = z.infer<typeof myFunctionSchema>, qui donnerait le type de fonction complet. Cependant, .parameters() et .returnType() sont utiles si l'on veut extraire séparément le schéma des inputs ou de la sortie d'une fonction.

ReturnType<T> – Type de retour d'une fonction

TypeScript : ReturnType<Fn> donne le type du résultat de la fonction Fn . C'est utile pour capturer le type qu'une fonction retourne sans le redéfinir manuellement. Par exemple :

typescript

Ici, ReturnType<typeof compute> infère { result: number; error?: string }. Comme pour Parameters, si le type fourni n'est pas une fonction, on obtient never.

Equivalent avec Zod : Poursuivant l'exemple précédent du schéma de fonction, Zod fournit .returnType() qui renvoie le schéma de sortie . Reprenons myFunctionSchema :

typescript

Ce ReturnT correspondrait au ReturnType du type de fonction décrit par myFunctionSchema. Encore une fois, dans un scénario réel, on pourrait directement utiliser z.infer<typeof myFunctionSchema> pour obtenir le type de la fonction (string, number) => boolean, puis en extraire le retour, mais .returnType() nous fournit explicitement le schéma (et donc le type) de retour. L'intérêt concret de ReturnType en TypeScript est souvent de typer une variable qui va recevoir le retour d'une fonction (sans avoir à dupliquer ce type). Dans Zod, l'analogie serait de réutiliser returnSchema pour valider qu'une valeur correspond bien à ce que la fonction devrait retourner, ou de composer ce schéma de retour avec d'autres.

InstanceType<T> – Type d'instance d'une classe

TypeScript : InstanceType<C> obtient le type de l'instance créée par le constructeur C . Habituellement on l'utilise en passant une classe (via typeof MaClasse). Par exemple :

typescript

Ici, InstanceType<typeof Person> est tout simplement Person. Cela peut paraître trivial, mais devient utile si on manipule des types de classes de manière générique (par exemple, une fonction générique qui prend un constructeur en paramètre et qui veut connaître le type des instances de ce constructeur).

Equivalent avec Zod : Zod propose un schéma z.instanceof(SomeClass) pour valider qu'une valeur est bien une instance de la classe donnée . Le schéma résultant, une fois inféré, correspond au type de l'instance. Par exemple :

typescript

CarSchema vérifiera à l'exécution que la valeur est un instanceof Car. Cela va au-delà de TypeScript qui, statiquement, ne fait que lier le type de l'instance au constructeur. Avec Zod, on a une validation runtime sur la provenance de l'objet (même si celui-ci a les propriétés requises, il doit hériter de Car pour passer le test). Ainsi, on obtient une garantie plus forte sur la nature de l'objet.

Il convient de noter que InstanceType (TypeScript) et z.instanceof (Zod) répondent à des besoins différents : le premier dérive un type statique de classe, le second vérifie dynamiquement une instance. Lorsqu'on infère le type de z.instanceof(X), on retrouve bien le type X attendu.

ThisType<T> – Contexte this pour les objets littéraux

TypeScript : ThisType<T> est un utility un peu particulier car il ne produit pas un nouveau type en soi, mais sert de marqueur contextuel pour indiquer le type de this à l'intérieur d'un objet littéral . Il s'utilise surtout dans des scénarios avancés (par exemple pour typer le this dans une usine d'objets contenant données + méthodes). Par exemple, dans le code suivant :

typescript

Dans cet exemple (inspiré de la documentation TypeScript ), ThisType<D & M> indique au compilateur que à l'intérieur de methods, le mot-clé this doit être du type intersection D & M (ici {x: number, y: number} & { moveBy(dx: number, dy: number): void }). Ainsi, this.x et this.y sont correctement reconnus comme number. ThisType n'a d'effet que si le flag --noImplicitThis est activé et uniquement dans le contexte des objets littéraux. En dehors, c'est une interface vide sans impact .

Equivalent avec Zod : Étant donné que ThisType est purement un outil du système de types pour aider à la cohérence du this à la compilation, il n'a pas d'équivalent dans Zod. Zod ne traite que de la validation de valeurs à l'exécution. Le concept de contexte this est lié à la façon dont les fonctions sont appelées en JavaScript, ce qui sort du domaine de la validation de données. Si vous avez un objet dont les méthodes utilisent this, TypeScript peut vous aider avec ThisType pour le typer, mais Zod ne peut pas valider ou influencer cela au runtime (ce serait plutôt le rôle de tests unitaires ou simplement de bien utiliser le this). En résumé, pas d'équivalent direct dans Zod pour ThisType et les utilitaires associés comme ThisParameterType ou OmitThisParameter – ces derniers servent à manipuler statiquement les signatures de fonctions qui utilisent this.

ConstructorParameters<T> – Paramètres d'un constructeur

TypeScript : ConstructorParameters<C> est à new ce que Parameters est à call : il extrait sous forme de tuple les types des paramètres du constructeur C (qui doit être du type abstract new (...args) => any) . Par exemple :

typescript

Ici CircleParams est un tuple correspondant aux arguments du constructeur de Circle. Cet utility est surtout utile dans les fabriques ou lorsqu'on veut créer un type représentant les arguments requis pour instancier une classe.

Equivalent avec Zod : Zod n'a pas de méthode spécifique pour introspecter directement le constructeur d'une classe, mais on peut parvenir à un résultat similaire en combinant d'autres fonctionnalités. Par exemple, pour valider les arguments qu'on compte passer à new Circle(...), on pourrait définir un tuple schéma z.tuple([z.number(), z.string().optional()]) et l'utiliser pour vérifier un array de paramètres. Cependant, Zod n'a pas une méthode constructorParameters() dédiée. Dans la pratique, on utilisera plutôt InstanceType et Parameters avec Zod : par exemple, z.instanceof(Circle) pour valider une instance, et possiblement un schéma de tuple pour valider des arguments avant de les passer au constructeur. L'analogie directe de ConstructorParameters est donc limitée côté Zod – on pourrait dire qu'il n'y en a pas spécifiquement, puisque Zod ne modélise pas la signature des constructeurs.

En résumé, pour toutes les utilités autour de this et des signatures de fonctions (paramètre this, suppression de this, paramètres de constructeurs, etc.), TypeScript propose des solutions statiques, alors que Zod ne couvre pas ces préoccupations (sauf via des constructions manuelles) car elles relèvent plus du langage que de la validation de données externes.

Différences de philosophie entre types utilitaires TypeScript et schémas Zod

Les utility types de TypeScript et les schémas Zod servent tous deux à garantir la fiabilité des données, mais à des niveaux différents : l'un au moment de la compilation, l'autre à l'exécution.

• TypeScript : sécurité statique (compile-time) – Les utility types (et le système de types en général) opèrent lors du développement. TypeScript analyse le code et prévient les incohérences de types avant même que le code ne tourne . Par exemple, Partial<T> assure qu'une fonction n'oubliera pas de gérer le cas où des propriétés sont absentes, ReturnType<Fn> donne la forme attendue des retours de fonctions, etc. Toutefois, ces vérifications n'existent plus une fois l'application lancée : TypeScript efface les types lors de la transpilation en JavaScript. Rien n'empêche donc qu'à l'exécution de mauvaises données circulent (provenant d'un JSON, d'un formulaire utilisateur, d'une API externe…). Le système de types ne peut pas, à lui seul, protéger contre des valeurs imprévues à runtime .
• Zod : validation dynamique (runtime) – Les schémas Zod interviennent au moment de l'exécution pour combler ce manque. En définissant un schéma pour vos données, vous créez un gardien runtime qui vérifie que les données reçues correspondent au format attendu . Par exemple, un schéma PartialUserSchema va vérifier effectivement que l'objet reçu ne contient que des clés valides et que leurs valeurs sont du bon type, là où Partial<User> n'est qu'une assurance compile-time. Ainsi, Zod et TypeScript sont complémentaires : TypeScript garantit la cohérence interne de votre code (ce que vous manipulez correspond aux types annoncés), tandis que Zod garantit la conformité des données externes à vos types .

On peut résumer ainsi :

• TypeScript est un vigile à la compilation, qui attrape les erreurs tôt dans le cycle de développement et vous évite de nombreuses erreurs courantes avant même d'exécuter le code.
• Zod est un gardien à l'exécution, qui s'assure qu'aucune donnée non conforme ne « passe la porte » de votre application (entrée utilisateur, réponse d'API, contenu de config, etc.).

En termes de philosophie, les utility types expriment des transformations ou contraintes au niveau du système de types (ils aident le développeur, n'ayant aucun impact direct sur le code émis), alors que Zod fournit des contrats au niveau du runtime (ils permettent d'implémenter concrètement des validations et transformations de données à l'exécution). Les deux approches répondent à des besoins différents mais liés : maintenir la robustesse du code. D'ailleurs, Zod est conçu pour s'intégrer harmonieusement avec TypeScript : il infère automatiquement des types statiques de vos schémas, évitant la duplication de définitions . Cela veut dire que vous pouvez souvent définir un schéma Zod (pour la validation) et utiliser z.infer pour en tirer le type TypeScript statique correspondant, au lieu de définir une interface TypeScript et un schéma séparément – on a ainsi une source de vérité unique pour vos types de données .

En conclusion, connaître les utility types de TypeScript vous permet de tirer profit du système de types pour écrire un code sûr et expressif, tandis que maîtriser Zod vous donne les outils pour faire respecter ces contrats de types à l'exécution. Utilisés ensemble, ils renforcent considérablement la fiabilité de vos applications TypeScript : TypeScript vous protège des erreurs de programmation, et Zod protège votre application des données imprévues du monde extérieur. Créez vos types, validez vos données, et codez sereinement 🎉!

1bun init
2bun add zod             # ajoute Zod en dépendance

1interface User {
2  name: string;
3  age: number;
4}
5
6const partialUser: Partial<User> = { name: "Alice" };
7// 'partialUser' peut ne contenir que le nom, la propriété 'age' est optionnelle
8partialUser.age = 30;  // OK d'ajouter plus tard car age: number | undefined

1function updateUser(user: User, fieldsToUpdate: Partial<User>): User {
2  return { ...user, ...fieldsToUpdate };
3}

1import { z } from "zod";
2
3const UserSchema = z.object({
4  name: z.string(),
5  age: z.number()
6});
7const PartialUserSchema = UserSchema.partial();
8type PartialUser = z.infer<typeof PartialUserSchema>; 
9// PartialUser est de type { name?: string; age?: number }

1PartialUserSchema.parse({ name: "Alice" });      // OK (age manquant autorisé)
2PartialUserSchema.parse({ });                    // OK (peut être vide)
3PartialUserSchema.parse({ age: " trente " });    // Erreur : age n'est pas un number

1interface Settings {
2  theme?: string;
3  fontSize?: number;
4}
5const s1: Settings = { theme: "dark" };              // OK, fontSize manquant
6const s2: Required<Settings> = { theme: "dark" };    // Erreur – fontSize est requis
7// TypeScript: Property 'fontSize' is missing in type ... but required in type 'Required<Settings>'

1const BaseUserSchema = z.object({
2  name: z.string().optional(),
3  age: z.number().optional()
4});
5// BaseUserSchema : { name?: string; age?: number }
6const StrictUserSchema = BaseUserSchema.required();
7// StrictUserSchema : { name: string; age: number }

1interface Todo { title: string; done: boolean; }
2const todo: Readonly<Todo> = { title: "Init project", done: false };
3todo.done = true;  
4// Erreur TS : Cannot assign to 'done' because it is a read-only property.

1const FrozenUserSchema = z.object({ name: z.string() }).readonly();
2type FrozenUser = z.infer<typeof FrozenUserSchema>; 
3// FrozenUser : Readonly<{ name: string }>
4const frozenUser = FrozenUserSchema.parse({ name: "Bob" });
5frozenUser.name;        // "Bob"
6frozenUser.name = "Eve"; // Erreur en runtime : l'objet est gelé (TypeError en mode strict)

1interface FullTodo {
2  title: string;
3  description: string;
4  completed: boolean;
5}
6type TodoPreview = Pick<FullTodo, "title" | "completed">;
7// TodoPreview : { title: string; completed: boolean }
8const t: TodoPreview = { title: "Nettoyer", completed: false }; // OK

1const FullTodoSchema = z.object({
2  title: z.string(),
3  description: z.string(),
4  completed: z.boolean()
5});
6const TodoPreviewSchema = FullTodoSchema.pick({ title: true, completed: true });
7type TodoPreview = z.infer<typeof TodoPreviewSchema>; 
8// { title: string; completed: boolean }

1interface Task {
2  id: string;
3  title: string;
4  done: boolean;
5  dueDate: string;
6}
7type TaskMeta = Omit<Task, "done" | "dueDate">;
8// TaskMeta : { id: string; title: string }

1const TaskSchema = z.object({
2  id: z.string(),
3  title: z.string(),
4  done: z.boolean(),
5  dueDate: z.string()
6});
7const TaskMetaSchema = TaskSchema.omit({ done: true, dueDate: true });
8type TaskMeta = z.infer<typeof TaskMetaSchema>; 
9// { id: string; title: string }

1type CatName = "miffy" | "boris" | "mordred";
2interface CatInfo { age: number; breed: string; }
3type Cats = Record<CatName, CatInfo>;
4/* Equivalent à :
5type Cats = {
6  miffy: CatInfo;
7  boris: CatInfo;
8  mordred: CatInfo;
9}
10*/
11const cats: Cats = {
12  miffy: { age: 10, breed: "Persan" },
13  boris: { age: 5, breed: "Maine Coon" },
14  mordred: { age: 16, breed: "British Shorthair" }
15};

1// On veut un objet dont les clés sont des prénoms (string) et les valeurs des âges (number)
2const AgeMapSchema = z.record(z.string(), z.number());
3type AgeMap = z.infer<typeof AgeMapSchema>; 
4// AgeMap : Record<string, number>
5AgeMapSchema.parse({ "Alice": 30, "Bob": 25});    // OK
6AgeMapSchema.parse({ "Alice": 30, "Bob": "25" });  // Erreur : "25" n'est pas un number

1type Role = "admin" | "user" | "guest";
2type NonAdmin = Exclude<Role, "admin">;  
3// NonAdmin : "user" | "guest"

1const RoleSchema = z.enum(["admin", "user", "guest"]);
2const NonAdminSchema = RoleSchema.exclude(["admin"]);
3type NonAdmin = z.infer<typeof NonAdminSchema>; 
4// NonAdmin : "user" | "guest"
5NonAdminSchema.parse("user");   // OK
6NonAdminSchema.parse("admin");  // Erreur : "admin" est exclu

1type Mixed = string | number | boolean;
2type NumbersOnly = Extract<Mixed, number | boolean>; 
3// NumbersOnly : number | boolean (on ne garde que ce qui est assignable à number | boolean)

1const LimitedRolesSchema = RoleSchema.extract(["user", "guest"]);
2type LimitedRoles = z.infer<typeof LimitedRolesSchema>; 
3// LimitedRoles : "user" | "guest"
4LimitedRolesSchema.parse("guest");  // OK
5LimitedRolesSchema.parse("admin");  // Erreur, "admin" n'est pas extrait

1type MaybeString = string | null | undefined;
2type DefinitelyString = NonNullable<MaybeString>;  
3// DefinitelyString : string

1const OptionalName = z.string().optional();          // type: string | undefined
2const Name = OptionalName.unwrap();                 // récupère z.string() sous-jacent (type: string)
3Name.parse("Alice");   // "Alice"
4Name.parse(undefined); // Erreur : undefined non accepté

1declare function f1(arg: { a: number; b: string }): void;
2type P0 = Parameters<() => string>;        // P0 : []
3type P1 = Parameters<(s: string) => void>; // P1 : [string]
4type P2 = Parameters<typeof f1>;           // P2 : [{ a: number; b: string }]

1const myFunctionSchema = z.function()
2  .args(z.string(), z.number())
3  .returns(z.boolean());
4// myFunctionSchema correspond à un type (arg0: string, arg1: number) => boolean
5
6const paramsSchema = myFunctionSchema.parameters();  
7// paramsSchema est ZodTuple([ZodString, ZodNumber])
8type Params = z.infer<typeof paramsSchema>;         
9// Params : [ string, number ]

1function compute(x: number): { result: number; error?: string } {
2  return { result: x * 2 };
3}
4type ResultType = ReturnType<typeof compute>; 
5// ResultType : { result: number; error?: string }

1const returnSchema = myFunctionSchema.returnType(); 
2// returnSchema est ZodBoolean
3type ReturnT = z.infer<typeof returnSchema>; 
4// ReturnT : boolean

1class Person {
2  name: string;
3  constructor(name: string) { this.name = name; }
4}
5type PersonInstance = InstanceType<typeof Person>; 
6// PersonInstance : Person

1class Car { wheels = 4; }
2const CarSchema = z.instanceof(Car);
3type CarType = z.infer<typeof CarSchema>; 
4// CarType : Car
5CarSchema.parse(new Car());    // OK
6CarSchema.parse({ wheels: 4 }); // Erreur : n'est pas une instance de Car

1type ObjectDescriptor<D, M> = {
2  data?: D;
3  methods?: M & ThisType<D & M>;
4};
5function makeObject<D, M>(desc: ObjectDescriptor<D, M>): D & M {
6  const data: object = desc.data || {};
7  const methods: object = desc.methods || {};
8  return { ...data, ...methods } as D & M;
9}
10 
11let obj = makeObject({
12  data: { x: 0, y: 0 },
13  methods: {
14    moveBy(dx: number, dy: number) {
15      this.x += dx;   // `this` est de type {x: number, y: number} grâce à ThisType
16      this.y += dy;
17    }
18  }
19});

1class Circle {
2  constructor(radius: number, color?: string) { /* ... */ }
3}
4type CircleParams = ConstructorParameters<typeof Circle>;
5// CircleParams : [radius: number, color?: string]