reflect-metadata pour TypeScript : guide complet avec exemples

Bienvenue dans ce guide détaillé sur la bibliothèque reflect-metadata pour TypeScript. Cette bibliothèque est le socle de nombreux frameworks modernes comme Angular, NestJS et TypeORM. Elle permet d'ajouter et de lire des métadonnées (des données sur les données) pour les classes, méthodes, propriétés et paramètres lors de l'exécution du programme. Si vous voulez comprendre le fonctionnement des décorateurs et de l'injection de dépendances (Dependency Injection ou DI) en TypeScript, maîtriser reflect-metadata est indispensable.

1. Qu'est-ce que c'est et pourquoi l'utiliser ?

reflect-metadata est un polyfill (une implémentation) pour l'objet natif Reflect, qui fait partie de la spécification ES2016 (ES7). L'objectif principal de cette bibliothèque est de fournir une API pour manipuler les métadonnées associées à divers éléments du code (classes, méthodes, propriétés). En JavaScript standard, cette fonctionnalité n'existe pas, c'est pourquoi TypeScript nécessite l'installation d'un package dédié.

Pourquoi est-ce utile ? Imaginez que vous développez un framework. Vous devez savoir de quelles dépendances une classe a besoin, quelles routes sont liées aux méthodes d'un contrôleur, ou quels champs d'une entité doivent être sérialisés en JSON. Sans métadonnées, vous seriez obligé de stocker ces informations dans des fichiers de configuration séparés ou d'utiliser des motifs complexes. reflect-metadata vous permet de stocker ces informations directement dans le code, le rendant ainsi plus auto-documenté et plus facile à analyser.

Cette bibliothèque est étroitement liée aux décorateurs. Un décorateur est une fonction qui s'applique à une classe, une méthode ou une propriété. À l'intérieur d'un décorateur, vous pouvez appeler Reflect.defineMetadata pour enregistrer une information, puis, ailleurs dans le programme, utiliser Reflect.getMetadata pour la récupérer. C'est la base pour implémenter l'injection de dépendances, les ORM (Object-Relational Mapping), la validation et bien d'autres motifs.

2. Installation

L'installation de la bibliothèque se fait via npm (Node Package Manager). Assurez-vous d'avoir Node.js (version 12 ou supérieure) installé.

npm install reflect-metadata --save

Après l'installation, vous devez importer la bibliothèque au tout début de votre fichier d'entrée (généralement main.ts ou index.ts) pour la rendre disponible globalement.

import "reflect-metadata";

Important : L'import doit être effectué avant tout autre code qui utilise Reflect. Si vous utilisez un framework (par exemple, Angular), il le fera automatiquement pour vous. Sinon, ajoutez cette ligne au début de votre fichier.

Vous devez également activer le support des décorateurs et des métadonnées dans le fichier tsconfig.json :

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

Le flag emitDecoratorMetadata force le compilateur TypeScript à générer des métadonnées de type pour les éléments décorés. Ceci est nécessaire pour le bon fonctionnement de nombreux frameworks.

3. Démarrage rapide — un exemple minimal fonctionnel

Créons un exemple simple qui montre comment ajouter des métadonnées à une classe et les lire.

import "reflect-metadata";

// 1. Définir une clé pour les métadonnées
const METADATA_KEY = "ma_cle_personnalisee";

// 2. Créer un décorateur qui ajoute des métadonnées
function MonDecorateur(valeur: string) {
    return function (cible: any) {
        // cible est le constructeur de la classe
        Reflect.defineMetadata(METADATA_KEY, valeur, cible);
    };
}

// 3. Appliquer le décorateur à une classe
@MonDecorateur("Ceci est ma classe")
class MaClasse {
    saluer() {
        console.l