Décorateurs JavaScript : Libérer la puissance de la méta-programmation

Les décorateurs JavaScript, introduits comme fonctionnalité standard dans l'ES2022, offrent un moyen puissant et élégant d'ajouter des métadonnées et de modifier le comportement des classes, méthodes, propriétés et paramètres. Ils proposent une syntaxe déclarative pour appliquer des préoccupations transversales, menant à un code plus maintenable, réutilisable et expressif. Cet article de blog plongera dans le monde des décorateurs JavaScript, explorant leurs concepts fondamentaux, leurs applications pratiques et les mécanismes sous-jacents qui les font fonctionner.

Que sont les décorateurs JavaScript ?

Au fond, les décorateurs sont des fonctions qui modifient ou améliorent l'élément décoré. Ils utilisent le symbole @ suivi du nom de la fonction décorateur. Considérez-les comme des annotations ou des modificateurs qui ajoutent des métadonnées ou changent le comportement sous-jacent sans altérer directement la logique principale de l'entité décorée. Ils enveloppent efficacement l'élément décoré, y injectant une fonctionnalité personnalisée.

Par exemple, un décorateur pourrait automatiquement journaliser les appels de méthode, valider les paramètres d'entrée ou gérer le contrôle d'accès. Les décorateurs favorisent la séparation des préoccupations, gardant la logique métier principale propre et ciblée tout en vous permettant d'ajouter des comportements supplémentaires de manière modulaire.

La syntaxe des décorateurs

Les décorateurs sont appliqués en utilisant le symbole @ avant l'élément qu'ils décorent. Il existe différents types de décorateurs, chacun ciblant un élément spécifique :

• Décorateurs de classe : Appliqués aux classes.
• Décorateurs de méthode : Appliqués aux méthodes.
• Décorateurs de propriété : Appliqués aux propriétés.
• Décorateurs d'accesseur : Appliqués aux méthodes getter et setter.
• Décorateurs de paramètre : Appliqués aux paramètres de méthode.

Voici un exemple de base d'un décorateur de classe :

            @logClass
class MyClass {
  constructor() {
    // ...
  }
}

function logClass(target) {
  console.log(`Class ${target.name} has been created.`);
}

            

              
                Copy
              
            
          

Dans cet exemple, logClass est une fonction décorateur qui prend le constructeur de la classe (target) en argument. Elle journalise ensuite un message dans la console chaque fois qu'une instance de MyClass est créée.

Comprendre la méta-programmation

Les décorateurs sont étroitement liés au concept de méta-programmation. Les métadonnées sont des « données sur les données ». Dans le contexte de la programmation, les métadonnées décrivent les caractéristiques et les propriétés des éléments de code, tels que les classes, les méthodes et les propriétés. Les décorateurs vous permettent d'associer des métadonnées à ces éléments, permettant l'introspection à l'exécution et la modification du comportement en fonction de ces métadonnées.

L'API Reflect Metadata (faisant partie de la spécification ECMAScript) fournit un moyen standard de définir et de récupérer les métadonnées associées aux objets et à leurs propriétés. Bien qu'elle ne soit pas strictement requise pour tous les cas d'utilisation des décorateurs, c'est un outil puissant pour les scénarios avancés où vous devez accéder et manipuler dynamiquement les métadonnées à l'exécution.

Par exemple, vous pourriez utiliser Reflect Metadata pour stocker des informations sur le type de données d'une propriété, des règles de validation ou des exigences d'autorisation. Ces métadonnées peuvent ensuite être utilisées par les décorateurs pour effectuer des actions telles que la validation des entrées, la sérialisation des données ou l'application de politiques de sécurité.

Types de décorateurs avec exemples

1. Décorateurs de classe

Les décorateurs de classe sont appliqués au constructeur de la classe. Ils peuvent être utilisés pour modifier la définition de la classe, ajouter de nouvelles propriétés ou méthodes, ou même remplacer la classe entière par une autre.

Exemple : Implémentation du patron de conception Singleton

Le patron de conception Singleton garantit qu'une seule instance d'une classe est créée. Voici comment vous pouvez l'implémenter en utilisant un décorateur de classe :

            function Singleton(target) {
  let instance = null;

  return function (...args) {
    if (!instance) {
      instance = new target(...args);
    }
    return instance;
  };
}

@Singleton
class DatabaseConnection {
  constructor(connectionString) {
    this.connectionString = connectionString;
    console.log(`Connecting to ${connectionString}`);
  }

  query(sql) {
    console.log(`Executing query: ${sql}`);
  }
}

const db1 = new DatabaseConnection('mongodb://localhost:27017');
const db2 = new DatabaseConnection('mongodb://localhost:27017');

console.log(db1 === db2); // Sortie : true

            

              
                Copy
              
            
          

Dans cet exemple, le décorateur Singleton enveloppe la classe DatabaseConnection. Il garantit qu'une seule instance de la classe est créée, peu importe le nombre de fois que le constructeur est appelé.

2. Décorateurs de méthode

Les décorateurs de méthode sont appliqués aux méthodes au sein d'une classe. Ils peuvent être utilisés pour modifier le comportement de la méthode, ajouter de la journalisation, implémenter la mise en cache ou appliquer le contrôle d'accès.

Exemple : Journalisation des appels de méthode

Ce décorateur journalise le nom de la méthode et ses arguments chaque fois que la méthode est appelée.

            function logMethod(target, propertyKey, descriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args) {
    console.log(`Appel de la méthode : ${propertyKey} avec les arguments : ${JSON.stringify(args)}`);
    const result = originalMethod.apply(this, args);
    console.log(`Méthode ${propertyKey} a retourné : ${result}`);
    return result;
  };
  return descriptor;
}

class Calculator {
  @logMethod
  add(x, y) {
    return x + y;
  }

  @logMethod
  subtract(x, y) {
    return x - y;
  }
}

const calc = new Calculator();
calc.add(5, 3); // Journalise : Appel de la méthode : add avec les arguments : [5,3]
                //       Méthode add a retourné : 8
calc.subtract(10, 4); // Journalise : Appel de la méthode : subtract avec les arguments : [10,4]
                  //       Méthode subtract a retourné : 6

            

              
                Copy
              
            
          

Ici, le décorateur logMethod enveloppe la méthode originale. Avant d'exécuter la méthode originale, il journalise le nom de la méthode et ses arguments. Après l'exécution, il journalise la valeur de retour.

3. Décorateurs de propriété

Les décorateurs de propriété sont appliqués aux propriétés au sein d'une classe. Ils peuvent être utilisés pour modifier le comportement de la propriété, implémenter la validation ou ajouter des métadonnées.

Exemple : Validation des valeurs de propriété

            function validate(target, propertyKey) {
  let value;

  const getter = function () {
    return value;
  };

  const setter = function (newValue) {
    if (typeof newValue !== 'string' || newValue.length < 3) {
      throw new Error(`La propriété ${propertyKey} doit être une chaîne de caractères avec au moins 3 caractères.`);
    }
    value = newValue;
  };

  Object.defineProperty(target, propertyKey, {
    get: getter,
    set: setter,
    enumerable: true,
    configurable: true,
  });
}

class User {
  @validate
  name;
}

const user = new User();

try {
  user.name = 'Jo'; // Lance une erreur
} catch (error) {
  console.error(error.message);
}

user.name = 'John Doe'; // Fonctionne correctement
console.log(user.name);

            

              
                Copy
              
            
          

Dans cet exemple, le décorateur validate intercepte l'accès à la propriété name. Lorsqu'une nouvelle valeur est assignée, il vérifie si la valeur est une chaîne de caractères et si sa longueur est d'au moins 3 caractères. Si ce n'est pas le cas, il lance une erreur.

4. Décorateurs d'accesseur

Les décorateurs d'accesseur sont appliqués aux méthodes getter et setter. Ils sont similaires aux décorateurs de méthode, mais ils ciblent spécifiquement les accesseurs (getters et setters).

Exemple : Mise en cache des résultats du getter

            function cached(target, propertyKey, descriptor) {
  const originalGetter = descriptor.get;
  let cacheValue;
  let cacheSet = false;

  descriptor.get = function () {
    if (cacheSet) {
      console.log(`Retour de la valeur en cache pour ${propertyKey}`);
      return cacheValue;
    } else {
      console.log(`Calcul et mise en cache de la valeur pour ${propertyKey}`);
      cacheValue = originalGetter.call(this);
      cacheSet = true;
      return cacheValue;
    }
  };
  return descriptor;
}

class Circle {
  constructor(radius) {
    this.radius = radius;
  }

  @cached
  get area() {
    console.log('Calcul de la surface...');
    return Math.PI * this.radius * this.radius;
  }
}

const circle = new Circle(5);
console.log(circle.area); // Calcule et met en cache la surface
console.log(circle.area); // Retourne la surface mise en cache

            

              
                Copy
              
            
          

Le décorateur cached enveloppe le getter de la propriété area. La première fois que l'area est accédée, le getter est exécuté et le résultat est mis en cache. Les accès suivants retournent la valeur mise en cache sans la recalculer.

5. Décorateurs de paramètre

Les décorateurs de paramètre sont appliqués aux paramètres de méthode. Ils peuvent être utilisés pour ajouter des métadonnées sur les paramètres, valider les entrées ou modifier les valeurs des paramètres.

Exemple : Validation d'un paramètre d'e-mail

            const requiredMetadataKey = Symbol("required");

function required(target: Object, propertyKey: string | symbol, parameterIndex: number) {
    let existingRequiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];
    existingRequiredParameters.push(parameterIndex);
    Reflect.defineMetadata(requiredMetadataKey, existingRequiredParameters, target, propertyKey);
}

function validateEmail(email: string) {
  const emailRegex = /^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$/g;
  return emailRegex.test(email);
}

function validate(target: any, propertyName: string, descriptor: TypedPropertyDescriptor) {
  let method = descriptor.value!;

  descriptor.value = function () {
    let requiredParameters: number[] = Reflect.getOwnMetadata(requiredMetadataKey, target, propertyName);
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
          if(arguments.length <= parameterIndex){
             throw new Error("Argument requis manquant.");
          }

          const email = arguments[parameterIndex];
          if (!validateEmail(email)) {
              throw new Error(`Format d'email invalide pour l'argument #${parameterIndex + 1}.`);
          }
      }
    }

    return method.apply(this, arguments);
  }
}

class EmailService {
  @validate
  sendEmail(@required to: string, subject: string, body: string) {
    console.log(`Envoi d'un e-mail à ${to} avec le sujet : ${subject}`);
  }
}

const emailService = new EmailService();

try {
  emailService.sendEmail('invalid-email', 'Bonjour', 'Ceci est un e-mail de test.'); // Lance une erreur
} catch (error) {
  console.error(error.message);
}

emailService.sendEmail('valid@email.com', 'Bonjour', 'Ceci est un e-mail de test.'); // Fonctionne correctement

            

              
                Copy
              
            
          

Dans cet exemple, le décorateur @required marque le paramètre to comme requis et indique qu'il doit être un format d'e-mail valide. Le décorateur validate utilise ensuite Reflect Metadata pour récupérer ces informations et valider le paramètre à l'exécution.

Avantages de l'utilisation des décorateurs

• Amélioration de la lisibilité et de la maintenabilité du code : Les décorateurs fournissent une syntaxe déclarative qui rend le code plus facile à comprendre et à maintenir.
• Réutilisabilité accrue du code : Les décorateurs peuvent être réutilisés sur plusieurs classes et méthodes, réduisant ainsi la duplication de code.
• Séparation des préoccupations : Les décorateurs favorisent la séparation des préoccupations en vous permettant d'ajouter des comportements supplémentaires sans modifier la logique principale.
• Flexibilité accrue : Les décorateurs offrent un moyen flexible de modifier le comportement des éléments de code à l'exécution.
• POA (Programmation Orientée Aspect) : Les décorateurs permettent d'appliquer les principes de la POA, vous permettant de modulariser les préoccupations transversales.

Cas d'utilisation des décorateurs

Les décorateurs peuvent être utilisés dans un large éventail de scénarios, notamment :

• Journalisation : Journaliser les appels de méthode, les métriques de performance ou les messages d'erreur.
• Validation : Valider les paramètres d'entrée ou les valeurs de propriété.
• Mise en cache : Mettre en cache les résultats des méthodes pour améliorer les performances.
• Autorisation : Appliquer des politiques de contrôle d'accès.
• Injection de dépendances : Gérer les dépendances entre les objets.
• Sérialisation/Désérialisation : Convertir des objets depuis et vers différents formats.
• Liaison de données : Mettre à jour automatiquement les éléments de l'interface utilisateur lorsque les données changent.
• Gestion de l'état : Implémenter des patrons de gestion d'état dans des applications comme React ou Angular.
• Versionnement d'API : Marquer des méthodes ou des classes comme appartenant à une version spécifique de l'API.
• Drapeaux de fonctionnalités : Activer ou désactiver des fonctionnalités en fonction des paramètres de configuration.

Fabriques de décorateurs

Une fabrique de décorateurs est une fonction qui retourne un décorateur. Cela vous permet de personnaliser le comportement du décorateur en passant des arguments à la fonction fabrique.

Exemple : Un journaliseur paramétré

            function logMethodWithPrefix(prefix: string) {
  return function (target, propertyKey, descriptor) {
    const originalMethod = descriptor.value;

    descriptor.value = function (...args) {
      console.log(`${prefix}: Appel de la méthode : ${propertyKey} avec les arguments : ${JSON.stringify(args)}`);
      const result = originalMethod.apply(this, args);
      console.log(`${prefix}: Méthode ${propertyKey} a retourné : ${result}`);
      return result;
    };
    return descriptor;
  };
}

class Calculator {
  @logMethodWithPrefix('[CALCULATION]')
  add(x, y) {
    return x + y;
  }

  @logMethodWithPrefix('[CALCULATION]')
  subtract(x, y) {
    return x - y;
  }
}

const calc = new Calculator();
calc.add(5, 3); // Journalise : [CALCULATION]: Appel de la méthode : add avec les arguments : [5,3]
                //       [CALCULATION]: Méthode add a retourné : 8
calc.subtract(10, 4); // Journalise : [CALCULATION]: Appel de la méthode : subtract avec les arguments : [10,4]
                  //       [CALCULATION]: Méthode subtract a retourné : 6

            

              
                Copy
              
            
          

La fonction logMethodWithPrefix est une fabrique de décorateurs. Elle prend un argument prefix et retourne une fonction décorateur. La fonction décorateur journalise ensuite les appels de méthode avec le préfixe spécifié.

Exemples concrets et études de cas

Prenons l'exemple d'une plateforme de commerce électronique mondiale. Ils pourraient utiliser des décorateurs pour :

• Internationalisation (i18n) : Les décorateurs pourraient traduire automatiquement le texte en fonction de la locale de l'utilisateur. Un décorateur @translate pourrait marquer les propriétés ou les méthodes à traduire. Le décorateur irait ensuite chercher la traduction appropriée dans un paquet de ressources en fonction de la langue sélectionnée par l'utilisateur.
• Conversion de devises : Lors de l'affichage des prix, un décorateur @currency pourrait convertir automatiquement le prix dans la devise locale de l'utilisateur. Ce décorateur devrait accéder à une API externe de conversion de devises et stocker les taux de conversion.
• Calcul des taxes : Les règles fiscales varient considérablement entre les pays et les régions. Les décorateurs pourraient être utilisés pour appliquer le taux de taxe correct en fonction de l'emplacement de l'utilisateur et du produit acheté. Un décorateur @tax pourrait utiliser des informations de géolocalisation pour déterminer le taux de taxe approprié.
• Détection de fraude : Un décorateur @fraudCheck sur les opérations sensibles (comme le paiement) pourrait déclencher des algorithmes de détection de fraude.

Un autre exemple est une entreprise de logistique mondiale :

• Suivi par géolocalisation : Les décorateurs peuvent améliorer les méthodes qui traitent les données de localisation, en journalisant la précision des relevés GPS ou en validant les formats de localisation (latitude/longitude) pour différentes régions. Un décorateur @validateLocation peut s'assurer que les coordonnées respectent une norme spécifique (par ex., ISO 6709) avant leur traitement.
• Gestion des fuseaux horaires : Lors de la planification des livraisons, les décorateurs peuvent convertir automatiquement les heures dans le fuseau horaire local de l'utilisateur. Un décorateur @timeZone utiliserait une base de données de fuseaux horaires pour effectuer la conversion, garantissant que les horaires de livraison sont précis quel que soit l'emplacement de l'utilisateur.
• Optimisation des itinéraires : Les décorateurs pourraient être utilisés pour analyser les adresses d'origine et de destination des demandes de livraison. Un décorateur @routeOptimize pourrait appeler une API externe d'optimisation d'itinéraire pour trouver le trajet le plus efficace, en tenant compte de facteurs comme les conditions de trafic et les fermetures de routes dans différents pays.

Décorateurs et TypeScript

TypeScript offre un excellent support pour les décorateurs. Pour utiliser les décorateurs en TypeScript, vous devez activer l'option de compilation experimentalDecorators dans votre fichier tsconfig.json :

            {
  "compilerOptions": {
    "target": "es6",
    "experimentalDecorators": true,
    // ... autres options
  }
}

            

              
                Copy
              
            
          

TypeScript fournit des informations de type pour les décorateurs, ce qui facilite leur écriture et leur maintenance. TypeScript impose également la sécurité des types lors de l'utilisation des décorateurs, vous aidant à éviter les erreurs à l'exécution. Les exemples de code de cet article de blog sont principalement écrits en TypeScript pour une meilleure sécurité des types et une meilleure lisibilité.

L'avenir des décorateurs

Les décorateurs sont une fonctionnalité relativement nouvelle en JavaScript, mais ils ont le potentiel d'avoir un impact significatif sur la façon dont nous écrivons et structurons le code. À mesure que l'écosystème JavaScript continue d'évoluer, nous pouvons nous attendre à voir davantage de bibliothèques et de frameworks qui exploitent les décorateurs pour fournir des fonctionnalités nouvelles et innovantes. La standardisation des décorateurs dans l'ES2022 assure leur viabilité à long terme et leur adoption généralisée.

Défis et considérations

• Complexité : Une utilisation excessive des décorateurs peut conduire à un code complexe et difficile à comprendre. Il est crucial de les utiliser judicieusement et de les documenter minutieusement.
• Performance : Les décorateurs peuvent introduire une surcharge, surtout s'ils effectuent des opérations complexes à l'exécution. Il est important de prendre en compte les implications sur la performance de l'utilisation des décorateurs.
• Débogage : Le débogage du code qui utilise des décorateurs peut être difficile, car le flux d'exécution peut être moins direct. De bonnes pratiques de journalisation et des outils de débogage sont essentiels.
• Courbe d'apprentissage : Les développeurs qui ne sont pas familiers avec les décorateurs devront peut-être investir du temps pour apprendre comment ils fonctionnent.

Bonnes pratiques pour l'utilisation des décorateurs

• Utilisez les décorateurs avec parcimonie : N'utilisez les décorateurs que lorsqu'ils apportent un avantage clair en termes de lisibilité, de réutilisabilité ou de maintenabilité du code.
• Documentez vos décorateurs : Documentez clairement le but et le comportement de chaque décorateur.
• Gardez les décorateurs simples : Évitez la logique complexe au sein des décorateurs. Si nécessaire, déléguez les opérations complexes à des fonctions séparées.
• Testez vos décorateurs : Testez minutieusement vos décorateurs pour vous assurer qu'ils fonctionnent correctement.
• Suivez les conventions de nommage : Utilisez une convention de nommage cohérente pour les décorateurs (par ex., @LogMethod, @ValidateInput).
• Tenez compte de la performance : Soyez conscient des implications sur la performance de l'utilisation des décorateurs, en particulier dans le code critique pour la performance.

Conclusion

Les décorateurs JavaScript offrent un moyen puissant et flexible d'améliorer la réutilisabilité du code, d'accroître la maintenabilité et de mettre en œuvre des préoccupations transversales. En comprenant les concepts fondamentaux des décorateurs et de l'API Reflect Metadata, vous pouvez les exploiter pour créer des applications plus expressives et modulaires. Bien qu'il y ait des défis à considérer, les avantages de l'utilisation des décorateurs l'emportent souvent sur les inconvénients, en particulier dans les projets vastes et complexes. À mesure que l'écosystème JavaScript évolue, les décorateurs joueront probablement un rôle de plus en plus important dans la façon dont nous écrivons et structurons le code. Expérimentez avec les exemples fournis et explorez comment les décorateurs peuvent résoudre des problèmes spécifiques dans vos projets. Adopter cette fonctionnalité puissante peut conduire à des applications JavaScript plus élégantes, maintenables et robustes dans divers contextes internationaux.