TypeBox pour TypeScript : guide complet avec exemples

Qu'est-ce que TypeBox et pourquoi l'utiliser ?

TypeBox est une bibliothèque puissante pour TypeScript qui permet de définir des schémas de données compatibles avec la norme JSON Schema, tout en déduisant automatiquement des types statiques TypeScript corrects. En termes simples, c'est un pont entre la validation des données à l'exécution (quand votre application vérifie les données à la volée) et les types au moment de la compilation (quand TypeScript vérifie la correction du code avant son exécution).

Pourquoi en avez-vous besoin ? Dans le développement web moderne, les données proviennent souvent de sources non fiables : requêtes API, formulaires, fichiers de configuration. Sans validation, vous risquez des erreurs d'exécution difficiles à détecter. TypeBox résout ce problème avec élégance : vous décrivez le schéma une seule fois, et vous obtenez :

• Un validateur à l'exécution — vérifie si un objet correspond au schéma pendant l'exécution du programme.
• Un type statique — TypeScript déduit automatiquement le type, que vous pouvez utiliser pour les annotations.
• Un JSON Schema — le schéma peut être sérialisé en JSON et utilisé dans d'autres outils (par exemple, pour générer des formulaires UI ou de la documentation).

TypeBox est idéal pour : créer des endpoints API avec validation du corps de la requête, travailler avec des fichiers de configuration, construire des formulaires complexes avec validation de champs, et tout scénario où la sécurité des types à toutes les étapes est cruciale.

Installation de TypeBox

TypeBox est une bibliothèque pour Node.js/TypeScript, elle s'installe donc via npm (ou yarn/pnpm).

npm install @sinclair/typebox

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

import { Type } from '@sinclair/typebox';

Pour la validation, vous aurez également besoin d'un validateur. TypeBox ne l'inclut pas par défaut pour laisser le choix au développeur. Nous recommandons d'utiliser @sinclair/typebox/compiler (le compilateur intégré) ou ajv (un validateur JSON Schema populaire). Installons le compilateur :

npm install @sinclair/typebox-compiler

Ou, si vous préférez AJV :

npm install ajv ajv-formats

Notez que la bibliothèque s'appelle @sinclair/typebox, et non simplement typebox. Ceci est important pour une installation correcte.

Démarrage rapide avec un exemple de code

Créons un schéma simple pour un utilisateur et testons-le.

import { Type } from '@sinclair/typebox';
import { TypeCompiler } from '@sinclair/typebox/compiler';

// 1. Définir le schéma utilisateur
const UserSchema = Type.Object({
    id: Type.Number(),
    name: Type.String({ minLength: 2 }),
    email: Type.String({ format: 'email' }),
    age: Type.Optional(Type.Number({ minimum: 0, maximum: 120 })),
});

// 2. Créer le compilateur pour la validation
const validator = TypeCompiler.Compile(UserSchema);

// 3. Données de test
const validUser = {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
};

const invalidUser = {
    id: 'pas-un-nombre',
    name: 'A',
    email: 'email-invalide',
};

// 4. Validation
console.log(validator.Check(validUser));   // true
console.log(validator.Check(invalidUser)); // false

// 5. Obtenir le type statique
type UserType = Static<typeof UserSchema>;
// UserType est maintenant { id: number; name: string; email: string; age?: number; }

Dans cet exemple, nous avons défini un schéma, l'avons compilé en un validateur et vérifié deux objets. Notez l'utilisation de Type.Optional pour le champ age — il peut être absent. Nous avons également utilisé format: 'email' pour valider le format de l'email.

Méthodes et fonctions principales de TypeBox

TypeBox offre un ensemble riche de fonctions pour créer des schémas. Voici les plus importantes.

1. Type.String()

Ce qu'elle fait : Crée un schéma pour le type chaîne de caractères. Permet