JavaScript Decorators: Metadata en Transformatie

JavaScript Decorators, een feature geïnspireerd door talen als Python en Java, bieden een krachtige en expressieve manier om metadata toe te voegen en classes, methodes, eigenschappen en parameters te transformeren. Ze bieden een schone, declaratieve syntaxis om de functionaliteit van code te verbeteren en de scheiding van verantwoordelijkheden te bevorderen. Hoewel decorators nog een relatief nieuwe toevoeging zijn aan het JavaScript-ecosysteem, winnen ze aan populariteit, vooral binnen frameworks zoals Angular en bibliotheken die metadata gebruiken voor dependency injection en andere geavanceerde functies. Dit artikel verkent de fundamenten van JavaScript decorators, hun toepassing en hun potentieel voor het creëren van beter onderhoudbare en uitbreidbare codebases.

Wat zijn JavaScript Decorators?

In de kern zijn decorators speciale soorten declaraties die kunnen worden gekoppeld aan classes, methodes, accessors, eigenschappen of parameters. Ze gebruiken de @expression-syntaxis, waarbij expression moet evalueren naar een functie die tijdens runtime wordt aangeroepen met informatie over de gedecoreerde declaratie. Decorators fungeren in wezen als functies die het gedrag van het gedecoreerde element wijzigen of uitbreiden.

Zie decorators als een manier om bestaande code in te kapselen of te vergroten zonder deze rechtstreeks te wijzigen. Dit principe, bekend als het Decorator-patroon in softwareontwerp, stelt u in staat om functionaliteit dynamisch aan een object toe te voegen.

Decorators inschakelen

Hoewel decorators deel uitmaken van de ECMAScript-standaard, zijn ze in de meeste JavaScript-omgevingen niet standaard ingeschakeld. Om ze te gebruiken, moet u doorgaans uw build-tools configureren. Hier leest u hoe u decorators in enkele veelvoorkomende omgevingen kunt inschakelen:

• TypeScript: Decorators worden native ondersteund in TypeScript. Zorg ervoor dat de compileroptie experimentalDecorators is ingesteld op true in uw tsconfig.json-bestand:

            {
  "compilerOptions": {
    "target": "esnext",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true, // Optioneel, maar vaak nuttig
    "module": "commonjs", // Of een ander modulesysteem zoals "es6" of "esnext"
    "moduleResolution": "node"
  }
}
            

              
                Copy
              
            
          

• Babel: Als u Babel gebruikt, moet u de @babel/plugin-proposal-decorators-plugin installeren en configureren:

            npm install --save-dev @babel/plugin-proposal-decorators

            

              
                Copy
              
            
          

Voeg vervolgens de plugin toe aan uw Babel-configuratie (bijv. .babelrc of babel.config.js):

            {
  "plugins": [["@babel/plugin-proposal-decorators", { "version": "2023-05" }]]
}
            

              
                Copy
              
            
          

De version-optie is belangrijk en moet overeenkomen met de versie van de decorator-proposal die u target. Raadpleeg de documentatie van de Babel-plugin voor de laatste aanbevolen versie.

Soorten Decorators

Er zijn verschillende soorten decorators, elk ontworpen voor specifieke elementen:

• Class Decorators: Toegepast op classes.
• Method Decorators: Toegepast op methodes binnen een class.
• Accessor Decorators: Toegepast op getter- of setter-accessors.
• Property Decorators: Toegepast op eigenschappen van een class.
• Parameter Decorators: Toegepast op parameters van een methode of constructor.

Class Decorators

Class decorators worden toegepast op de constructor van een class en kunnen worden gebruikt om een class-definitie te observeren, wijzigen of vervangen. Ze ontvangen de class constructor als hun enige argument.

Voorbeeld:

            function sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

@sealed
class Greeter {
  greeting: string;
  constructor(message: string) {
    this.greeting = message;
  }
  greet() {
    return "Hello, " + this.greeting;
  }
}

// Pogingen om eigenschappen toe te voegen aan de verzegelde class of haar prototype zullen mislukken

            

              
                Copy
              
            
          

In dit voorbeeld voorkomt de @sealed-decorator verdere wijzigingen aan de Greeter-class en haar prototype. Dit kan handig zijn om onveranderlijkheid te garanderen of onbedoelde wijzigingen te voorkomen.

Method Decorators

Method decorators worden toegepast op methodes binnen een class. Ze ontvangen drie argumenten:

• target: Het prototype van de class (voor instance-methodes) of de class constructor (voor statische methodes).
• propertyKey: De naam van de methode die wordt gedecoreerd.
• descriptor: De property descriptor voor de methode.

Voorbeeld:

            function log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`Calling ${propertyKey} with arguments: ${JSON.stringify(args)}`);
    const result = originalMethod.apply(this, args);
    console.log(`Method ${propertyKey} returned: ${result}`);
    return result;
  };

  return descriptor;
}

class Calculator {
  @log
  add(x: number, y: number) {
    return x + y;
  }
}

const calculator = new Calculator();
calculator.add(2, 3); // Output: Calling add with arguments: [2,3]
                      //         Method add returned: 5

            

              
                Copy
              
            
          

De @log-decorator logt de argumenten en de returnwaarde van de add-methode. Dit is een eenvoudig voorbeeld van hoe method decorators kunnen worden gebruikt voor logging, profiling of andere cross-cutting concerns.

Accessor Decorators

Accessor decorators zijn vergelijkbaar met method decorators, maar worden toegepast op getter- of setter-accessors. Ze ontvangen ook dezelfde drie argumenten: target, propertyKey en descriptor.

Voorbeeld:

            function configurable(value: boolean) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    descriptor.configurable = value;
  };
}

class Point {
  private _x: number;
  private _y: number;

  constructor(x: number, y: number) {
    this._x = x;
    this._y = y;
  }

  @configurable(false)
  get x() {
    return this._x;
  }

  set x(value: number) {
      this._x = value;
  }
}

const point = new Point(1, 2);
// Object.defineProperty(point, 'x', { configurable: true }); // Zou een fout veroorzaken omdat 'x' niet configureerbaar is

            

              
                Copy
              
            
          

De @configurable(false)-decorator voorkomt dat de x-getter opnieuw wordt geconfigureerd, waardoor deze niet-configureerbaar wordt.

Property Decorators

Property decorators worden toegepast op eigenschappen van een class. Ze ontvangen twee argumenten:

• target: Het prototype van de class (voor instance-eigenschappen) of de class constructor (voor statische eigenschappen).
• propertyKey: De naam van de eigenschap die wordt gedecoreerd.

Voorbeeld:

            function readonly(target: any, propertyKey: string) {
  Object.defineProperty(target, propertyKey, {
    writable: false,
  });
}

class Person {
  @readonly
  name: string;

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

const person = new Person("Alice");
// person.name = "Bob"; // Dit veroorzaakt een fout in strict mode omdat 'name' readonly is

            

              
                Copy
              
            
          

De @readonly-decorator maakt de name-eigenschap alleen-lezen, waardoor deze na initialisatie niet meer kan worden gewijzigd.

Parameter Decorators

Parameter decorators worden toegepast op parameters van een methode of constructor. Ze ontvangen drie argumenten:

• target: Het prototype van de class (voor instance-methodes) of de class constructor (voor statische methodes of constructors).
• propertyKey: De naam van de methode of constructor.
• parameterIndex: De index van de parameter in de parameterlijst.

Parameter decorators worden vaak gebruikt met reflectie om metadata over de parameters van een functie op te slaan. Deze metadata kan vervolgens tijdens runtime worden gebruikt voor dependency injection of andere doeleinden. Om dit correct te laten werken, moet u de emitDecoratorMetadata-compileroptie inschakelen in uw tsconfig.json-bestand.

Voorbeeld (met reflect-metadata):

            import 'reflect-metadata';

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

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

  descriptor.value = function (...args: any[]) {
    let requiredParameters: number[] = Reflect.getOwnMetadata("required", target, propertyName);
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
        if (args[parameterIndex] === null || args[parameterIndex] === undefined) {
          throw new Error(`Missing required argument at index ${parameterIndex}`);
        }
      }
    }
    return method.apply(this, args);
  };
}

class User {
  name: string;
  age: number;

  constructor(@required name: string, public surname: string, @required age: number) {
    this.name = name;
    this.age = age;
  }

  @validate
  greet(prefix: string, @required salutation: string): string {
    return `${prefix} ${salutation} ${this.name}`;
  }
}

// Gebruik

try {
  const user1 = new User("John", "Doe", 30);
  console.log(user1.greet("Mr.", "Hello"));

  const user2 = new User(undefined as any, "Doe", null as any);

} catch (error) {
  console.error(error.message);
}

try {
  const user = new User("John", "Doe", 30);
  console.log(user.greet("Mr.", undefined as any));
} catch (error) {
  console.error(error.message);
}


            

              
                Copy
              
            
          

In dit voorbeeld markeert de @required-decorator parameters als verplicht. De @validate-decorator gebruikt vervolgens reflectie (via reflect-metadata) om te controleren of de vereiste parameters aanwezig zijn voordat de methode wordt aangeroepen. Dit voorbeeld toont het basisgebruik, en het wordt aanbevolen om robuuste parametervalidatie te creëren in een productie-scenario.

Om reflect-metadata te installeren:

            npm install reflect-metadata --save

            

              
                Copy
              
            
          

Decorators gebruiken voor Metadata

Een van de belangrijkste toepassingen van decorators is het koppelen van metadata aan classes en hun leden. Deze metadata kan tijdens runtime worden gebruikt voor verschillende doeleinden, zoals dependency injection, serialisatie en validatie. De reflect-metadata-bibliotheek biedt een standaardmanier om metadata op te slaan en op te halen.

Voorbeeld:

            import 'reflect-metadata';

const TYPE_KEY = "design:type";
const PARAMTYPES_KEY = "design:paramtypes";
const RETURNTYPE_KEY = "design:returntype";

function Type(type: any) {
    return Reflect.metadata(TYPE_KEY, type);
}


function LogType(target: any, propertyKey: string) {
  const t = Reflect.getMetadata(TYPE_KEY, target, propertyKey);
  console.log(`${target.constructor.name}.${propertyKey} type: ${t.name}`);
}

class Demo {
    @LogType
    public name: string;
    constructor(name: string){
      this.name = name;
    }
}

            

              
                Copy
              
            
          

Decorator Factories

Decorator factories zijn functies die een decorator retourneren. Ze stellen u in staat om argumenten door te geven aan de decorator, waardoor deze flexibeler en herbruikbaarder wordt.

Voorbeeld:

            function deprecated(deprecationReason: string) {
  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
    const originalMethod = descriptor.value;

    descriptor.value = function (...args: any[]) {
      console.warn(`Method ${propertyKey} is deprecated: ${deprecationReason}`);
      return originalMethod.apply(this, args);
    };

    return descriptor;
  };
}

class LegacyComponent {
  @deprecated("Use the newMethod instead.")
  oldMethod() {
    console.log("Old method called");
  }

  newMethod() {
    console.log("New method called");
  }
}

const component = new LegacyComponent();
component.oldMethod(); // Output: Method oldMethod is deprecated: Use the newMethod instead.
                       //         Old method called

            

              
                Copy
              
            
          

De @deprecated-decorator factory neemt een afkeuringsbericht als argument en logt een waarschuwing wanneer de gedecoreerde methode wordt aangeroepen. Dit stelt u in staat om methodes als verouderd te markeren en ontwikkelaars te begeleiden bij de migratie naar nieuwere alternatieven.

Praktijkvoorbeelden

Decorators hebben een breed scala aan toepassingen in de moderne JavaScript-ontwikkeling:

• Dependency Injection: Frameworks zoals Angular leunen zwaar op decorators voor dependency injection.
• Routing: In webapplicaties kunnen decorators worden gebruikt om routes voor controllers en methodes te definiëren.
• Validatie: Decorators kunnen worden gebruikt om invoergegevens te valideren en ervoor te zorgen dat deze aan bepaalde criteria voldoen.
• Autorisatie: Decorators kunnen worden gebruikt om beveiligingsbeleid af te dwingen en de toegang tot bepaalde methodes of bronnen te beperken.
• Logging en Profiling: Zoals in de bovenstaande voorbeelden getoond, kunnen decorators worden gebruikt voor het loggen en profilen van code-uitvoering.
• State Management: Decorators kunnen integreren met state management-bibliotheken om componenten automatisch bij te werken wanneer de state verandert.

Voordelen van het gebruik van Decorators

• Verbeterde leesbaarheid van code: Decorators bieden een declaratieve syntaxis voor het toevoegen van functionaliteit, waardoor code gemakkelijker te begrijpen en te onderhouden is.
• Scheiding van verantwoordelijkheden: Decorators stellen u in staat om cross-cutting concerns (bijv. logging, validatie, autorisatie) te scheiden van de kernbedrijfslogica.
• Herbruikbaarheid: Decorators kunnen worden hergebruikt in meerdere classes en methodes, wat code-duplicatie vermindert.
• Uitbreidbaarheid: Decorators maken het gemakkelijk om de functionaliteit van bestaande code uit te breiden zonder deze rechtstreeks te wijzigen.

Uitdagingen en Overwegingen

• Leercurve: Decorators zijn een relatief nieuwe functie, en het kan enige tijd duren om te leren hoe ze effectief te gebruiken.
• Compatibiliteit: Zorg ervoor dat uw doelomgeving decorators ondersteunt en dat u uw build-tools correct hebt geconfigureerd.
• Debugging: Het debuggen van code die decorators gebruikt kan uitdagender zijn dan het debuggen van reguliere code, vooral als de decorators complex zijn.
• Overmatig gebruik: Vermijd overmatig gebruik van decorators, omdat dit uw code moeilijker te begrijpen en te onderhouden kan maken. Gebruik ze strategisch voor specifieke doeleinden.
• Runtime Overhead: Decorators kunnen enige runtime overhead introduceren, vooral als ze complexe bewerkingen uitvoeren. Overweeg de prestatie-implicaties bij het gebruik van decorators in prestatiekritieke applicaties.

Conclusie

JavaScript Decorators zijn een krachtig hulpmiddel om de functionaliteit van code te verbeteren en de scheiding van verantwoordelijkheden te bevorderen. Door een schone, declaratieve syntaxis te bieden voor het toevoegen van metadata en het transformeren van classes, methodes, eigenschappen en parameters, kunnen decorators u helpen om beter onderhoudbare, herbruikbare en uitbreidbare codebases te creëren. Hoewel ze een leercurve en enkele potentiële uitdagingen met zich meebrengen, kunnen de voordelen van het gebruik van decorators in de juiste context aanzienlijk zijn. Naarmate het JavaScript-ecosysteem blijft evolueren, zullen decorators waarschijnlijk een steeds belangrijker onderdeel worden van de moderne JavaScript-ontwikkeling.

Overweeg te onderzoeken hoe decorators uw bestaande code kunnen vereenvoudigen of u in staat kunnen stellen om expressievere en beter onderhoudbare applicaties te schrijven. Met een zorgvuldige planning en een goed begrip van hun mogelijkheden, kunt u decorators benutten om robuustere en schaalbaardere JavaScript-oplossingen te creëren.