class-validator pour TypeScript : guide complet avec exemples

Introduction à class-validator

class-validator est une bibliothèque puissante et populaire pour la validation de données en TypeScript et JavaScript, basée sur les décorateurs. Elle permet de décrire de manière déclarative les règles de validation directement à l'intérieur des classes, en utilisant des annotations. Cela rend le code propre, lisible et facile à maintenir.

Cette bibliothèque est particulièrement utile lors du développement d'applications serveur (par exemple, avec NestJS ou Express), où il est nécessaire de valider les requêtes entrantes, les données de formulaires, les configurations et toute autre structure de données. Au lieu d'écrire de longues chaînes de conditions if-else, il suffit d'ajouter des décorateurs aux propriétés de la classe.

Pourquoi utiliser class-validator ?

• Déclaratif : Les règles de validation sont définies à côté des données, ce qui améliore la lisibilité.
• Ensemble de validateurs puissant : Comprend des dizaines de décorateurs intégrés pour valider les chaînes, les nombres, les dates, les tableaux, les objets imbriqués et bien plus encore.
• Validateurs personnalisés : Permet de créer facilement vos propres règles.
• Intégration avec TypeScript : Prise en charge complète des types et des décorateurs.
• Validation asynchrone : Prend en charge les vérifications nécessitant des opérations asynchrones (par exemple, vérification d'unicité en base de données).

Installation

Pour utiliser class-validator, vous aurez besoin de Node.js et de npm/yarn. Installez la bibliothèque et les dépendances nécessaires :

npm install class-validator class-transformer reflect-metadata

Ou via yarn :

yarn add class-validator class-transformer reflect-metadata

Important : La bibliothèque reflect-metadata est obligatoire pour le fonctionnement des décorateurs. Assurez-vous qu'elle est importée dans votre fichier principal (par exemple, index.ts ou main.ts) :

import 'reflect-metadata';

Assurez-vous également que les paramètres suivants sont activés dans votre fichier tsconfig.json :

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

Démarrage rapide

Créons un modèle d'utilisateur simple et validons-le.

import 'reflect-metadata';
import { validate, IsString, IsEmail, MinLength } from 'class-validator';
import { plainToClass } from 'class-transformer';

class User {
    @IsString()
    @MinLength(3, { message: 'Le nom doit contenir au moins 3 caractères' })
    name: string;

    @IsEmail({}, { message: 'Email invalide' })
    email: string;

    constructor(name: string, email: string) {
        this.name = name;
        this.email = email;
    }
}

async function main() {
    // Création d'un objet avec des données invalides
    const userData = { name: 'Jo', email: 'pas-un-email' };
    
    // Transformation de l'objet simple en instance de classe
    const user = plainToClass(User, userData);
    
    // Validation
    const errors = await validate(user);
    
    if (errors.length > 0) {
        console.log('Erreurs de validation :', errors);
        errors.forEach(error => {
            console.log(`Champ : ${error.property}`);
            for (const constraint in error.constraints) {
                console.log(`  - ${error.constraints[constraint]}`);
            }
        });
    } else {
        console.log('Validation réussie !');
    }
}

main();
// Résultat :
// Erreurs de validation : [...]
// Champ : name
//   - Le nom doit contenir au moins 3 caractères
// Champ : email
//   - Email invalide

Méthodes et décorateurs principaux

1. @IsString()

Fonction : Vérifie si la valeur est une chaîne de caractères.

Paramètres : Accepte un objet optionnel avec les options de validation (par exemple, { message: '...' }).

class Product {
    @IsString()
    title: string;
}

2. @IsNumb