io-ts pour TypeScript : guide complet avec exemples

Qu'est-ce que io-ts et pourquoi en a-t-on besoin ?

\nio-ts est une bibliothèque pour TypeScript qui résout l'un des problèmes les plus épineux du développement avec ce langage : le décalage entre les types statiques (au moment de la compilation) et les données réelles (au moment de l'exécution). TypeScript est un outil remarquable, mais son système de types ne fonctionne qu'en phase de développement. Lorsque votre application s'exécute, tous les types sont effacés. Si vous recevez des données d'une API externe, d'un formulaire sur un site, du localStorage ou de toute autre source non contrôlée par votre compilateur, vous ne pouvez pas être certain que les données correspondent aux types déclarés.\n

\nC'est là qu'intervient la validation à l'exécution (runtime). io-ts vous permet de définir un schéma de données une seule fois, puis de l'utiliser à deux fins :\n

\n
• Typage statique (compile-time) : TypeScript déduit les types à partir de votre schéma, assurant la sécurité du code lors de l'écriture.
\n
• Validation à l'exécution (runtime) : io-ts vérifie si les données réelles correspondent à votre schéma et retourne soit un résultat réussi, soit une erreur détaillée.
\n

\nLa bibliothèque est basée sur le concept de codecs. Un codec est un objet qui sait comment décoder (vérifier et transformer) des données brutes en un type TypeScript et comment encoder (sérialiser) ce type en retour. Cela fait de io-ts un outil puissant non seulement pour la validation, mais aussi pour la sérialisation/désérialisation sécurisée des données.\n

Installation

\nio-ts est une bibliothèque pour l'écosystème Node.js et les navigateurs, elle s'installe donc via npm (ou yarn). Notez que io-ts nécessite fp-ts comme dépendance peer, car il utilise des concepts fonctionnels tels que Either et Option.\n

npm install io-ts fp-ts

\nOu, si vous utilisez yarn :\n

yarn add io-ts fp-ts

\nAprès l'installation, vous pouvez importer la bibliothèque dans votre projet :\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';

Démarrage rapide : premier exemple

\nCommençons par un exemple simple. Supposons que nous attendions un objet utilisateur avec les champs name (chaîne) et age (nombre). Définissons le schéma avec io-ts et essayons de valider quelques données.\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';\n\n// 1. Définir le schéma (codec)\nconst User = t.type({\n    name: t.string,\n    age: t.number,\n});\n\n// 2. Fonction pour obtenir le type en toute sécurité\ntype User = t.TypeOf<typeof User>;\n\n// 3. Données à vérifier\nconst validData = { name: 'Alice', age: 30 };\nconst invalidData = { name: 'Bob', age: 'vingt' }; // age - chaîne, pas un nombre\n\n// 4. Validation\nconst result1 = User.decode(validData);\nconst result2 = User.decode(invalidData);\n\nconsole.log(isRight(result1)); // true\nconsole.log(isLeft(result2));  // true\n\n// 5. Extraire les données (si la validation a réussi)\nif (isRight(result1)) {\n    const user: User = result1.right;\n    console.log(user.name); // Alice\n}\n\n// 6. Gérer l'erreur\nif (isLeft(result2)) {\n    console.error('Erreur de validation :', result2.left);\n    // Affichera une liste d'erreurs, par exemple :\n    // [ { value: 'vingt', context: [...], message: 'Invalid value "vingt" supplied to : { name: string, age: number }/age: number' } ]\n}\n

\nDans cet exemple, nous voyons le modèle clé : decode retourne Either<Errors, A> de la bibliothèque fp-ts. Either est un conteneur qui peut contenir soit une erreur (type gauche), soit une valeur réussie (type droit). Nous vérifions le résultat à l'aide des fonctions isRight et isLeft.\n

Méthodes et fonctions principales de io-ts

\nio-ts fournit