class-transformer TypeScript : méthodes, exemples…

Introduction à class-transformer : qu'est-ce que c'est et pourquoi l'utiliser ?

class-transformer est une bibliothèque puissante pour TypeScript et JavaScript qui permet de transformer des objets JavaScript simples (plain objects) en instances de classes et vice-versa. Elle résout un problème fondamental : lorsque vous travaillez avec des données provenant d'API, de bases de données ou de fichiers JSON, vous obtenez des objets simples sans méthodes ni types. class-transformer « anime » ces données en les transformant en objets de classe complets avec validation, transformation et sérialisation.

Les principaux cas d'utilisation :

Transformer du JSON d'API en objets de classe typés — par exemple, après avoir reçu une réponse d'une API REST, vous pouvez automatiquement convertir le JSON en instances de vos modèles.
Validation et transformation de données — grâce aux décorateurs, vous pouvez spécifier les champs obligatoires, ceux à transformer (par exemple, une chaîne en nombre ou en date).
Sérialisation d'objets en JSON — la transformation inverse d'instances de classe en objets simples pour envoi au client ou sauvegarde.
Gestion des objets imbriqués et des tableaux — la bibliothèque sait transformer récursivement les structures de données imbriquées.

class-transformer est souvent utilisé avec class-validator (pour la validation) et des frameworks populaires comme NestJS, TypeORM et MikroORM.

Installation

L'installation de la bibliothèque se fait via npm ou yarn :

npm install class-transformer --save

Ou, si vous utilisez yarn :

yarn add class-transformer

Pour utiliser les décorateurs dans TypeScript, vous devez activer la prise en charge des décorateurs expérimentaux dans le fichier tsconfig.json :

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

Il est également recommandé d'installer reflect-metadata pour le bon fonctionnement des décorateurs :

npm install reflect-metadata --save

Et de l'importer au tout début de votre application (généralement dans le fichier principal index.ts ou main.ts) :

import 'reflect-metadata';

Démarrage rapide avec un exemple de code

Créons un modèle d'utilisateur simple et transformons des données JSON en instance de classe.

import { plainToClass, Expose, Type } from 'class-transformer';
import 'reflect-metadata';

// Définition de la classe User
class User {
    @Expose()
    id: number;

    @Expose()
    firstName: string;

    @Expose()
    lastName: string;

    @Expose()
    @Type(() => Date)
    createdAt: Date;

    // Méthode de classe — accessible uniquement après transformation
    getFullName(): string {
        return `${this.firstName} ${this.lastName}`;
    }
}

// Exemple de données provenant d'une API (plain object)
const plainUser = {
    id: 1,
    firstName: 'Jean',
    lastName: 'Dupont',
    createdAt: '2024-01-15T10:30:00Z'
};

// Transformation du plain object en instance de la classe User
const userInstance = plainToClass(User, plainUser);

console.log(userInstance instanceof User); // true
console.log(userInstance.getFullName());   // "Jean Dupont"
console.log(userInstance.createdAt);       // Objet Date : Tue Jan 15 2024 11:30:00 GMT+0100

Comme vous pouvez le voir, nous obtenons un objet de classe complet avec des méthodes et des types correctement transformés (la chaîne de date est devenue un objet Date).