JavaScript Decorators: Metadata og Transformation

JavaScript Decorators, en feature inspireret af sprog som Python og Java, tilbyder en kraftfuld og udtryksfuld måde at tilføje metadata og transformere klasser, metoder, egenskaber og parametre. De giver en ren, deklarativ syntaks til at forbedre kodens funktionalitet og fremme "separation of concerns" (adskillelse af ansvarsområder). Selvom decorators stadig er en relativt ny tilføjelse til JavaScript-økosystemet, vinder de popularitet, især inden for frameworks som Angular og biblioteker, der bruger metadata til dependency injection og andre avancerede funktioner. Denne artikel udforsker det grundlæggende i JavaScript decorators, deres anvendelse og deres potentiale for at skabe mere vedligeholdelsesvenlige og udvidelige kodebaser.

Hvad er JavaScript Decorators?

I deres kerne er decorators specielle slags deklarationer, der kan tilknyttes klasser, metoder, accessors, egenskaber eller parametre. De bruger @expression-syntaksen, hvor expression skal evaluere til en funktion, der vil blive kaldt ved kørsel med information om den dekorerede deklaration. Decorators fungerer i bund og grund som funktioner, der modificerer eller udvider adfærden for det dekorerede element.

Tænk på decorators som en måde at "wrappe" (indkapsle) eller udvide eksisterende kode uden at ændre den direkte. Dette princip, kendt som Decorator-mønsteret inden for softwareudvikling, giver dig mulighed for at tilføje funktionalitet til et objekt dynamisk.

Aktivering af Decorators

Selvom decorators er en del af ECMAScript-standarden, er de ikke aktiveret som standard i de fleste JavaScript-miljøer. For at bruge dem skal du typisk konfigurere dine build-værktøjer. Her er, hvordan du aktiverer decorators i nogle almindelige miljøer:

• TypeScript: Decorators understøttes native i TypeScript. Sørg for, at compiler-indstillingen experimentalDecorators er sat til true i din tsconfig.json-fil:

            {
  "compilerOptions": {
    "target": "esnext",
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true, // Optional, but often useful
    "module": "commonjs", // Or another module system like "es6" or "esnext"
    "moduleResolution": "node"
  }
}
            

              
                Copy
              
            
          

• Babel: Hvis du bruger Babel, skal du installere og konfigurere @babel/plugin-proposal-decorators-pluginnet:

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

            

              
                Copy
              
            
          

Tilføj derefter pluginnet til din Babel-konfiguration (f.eks. .babelrc eller babel.config.js):

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

              
                Copy
              
            
          

version-indstillingen er vigtig og bør matche den version af decorators-forslaget, du sigter mod. Konsulter Babel-plugin-dokumentationen for den senest anbefalede version.

Typer af Decorators

Der findes flere typer decorators, hver designet til specifikke elementer:

• Klasse-decorators: Anvendes på klasser.
• Metode-decorators: Anvendes på metoder i en klasse.
• Accessor-decorators: Anvendes på getter- eller setter-accessors.
• Egenskabs-decorators (Property): Anvendes på en klasses egenskaber.
• Parameter-decorators: Anvendes på parametre i en metode eller constructor.

Klasse-decorators

Klasse-decorators anvendes på en klasses constructor og kan bruges til at observere, modificere eller erstatte en klassedefinition. De modtager klassens constructor som deres eneste argument.

Eksempel:

            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;
  }
}

// Attempting to add properties to the sealed class or its prototype will fail

            

              
                Copy
              
            
          

I dette eksempel forhindrer @sealed-decoratoren yderligere ændringer i Greeter-klassen og dens prototype. Dette kan være nyttigt for at sikre immutability (uforanderlighed) eller forhindre utilsigtede ændringer.

Metode-decorators

Metode-decorators anvendes på metoder i en klasse. De modtager tre argumenter:

• target: Klassens prototype (for instansmetoder) eller klassens constructor (for statiske metoder).
• propertyKey: Navnet på den metode, der dekoreres.
• descriptor: Egenskabsbeskrivelsen (property descriptor) for metoden.

Eksempel:

            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
              
            
          

@log-decoratoren logger argumenterne og returværdien for add-metoden. Dette er et simpelt eksempel på, hvordan metode-decorators kan bruges til logging, profilering eller andre tværgående anliggender (cross-cutting concerns).

Accessor-decorators

Accessor-decorators ligner metode-decorators, men anvendes på getter- eller setter-accessors. De modtager også de samme tre argumenter: target, propertyKey og descriptor.

Eksempel:

            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 }); // Would throw an error because 'x' is not configurable

            

              
                Copy
              
            
          

@configurable(false)-decoratoren forhindrer x-getteren i at blive rekonfigureret, hvilket gør den ikke-konfigurerbar.

Egenskabs-decorators (Property)

Egenskabs-decorators anvendes på en klasses egenskaber. De modtager to argumenter:

• target: Klassens prototype (for instansegenskaber) eller klassens constructor (for statiske egenskaber).
• propertyKey: Navnet på den egenskab, der dekoreres.

Eksempel:

            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"; // This will cause an error in strict mode because 'name' is readonly

            

              
                Copy
              
            
          

@readonly-decoratoren gør name-egenskaben skrivebeskyttet (read-only), hvilket forhindrer den i at blive ændret efter initialisering.

Parameter-decorators

Parameter-decorators anvendes på parametre i en metode eller constructor. De modtager tre argumenter:

• target: Klassens prototype (for instansmetoder) eller klassens constructor (for statiske metoder eller constructors).
• propertyKey: Navnet på metoden eller constructoren.
• parameterIndex: Parameterens indeks i parameterlisten.

Parameter-decorators bruges ofte med reflection til at gemme metadata om en funktions parametre. Disse metadata kan derefter bruges ved kørsel til dependency injection eller andre formål. For at dette kan fungere korrekt, skal du aktivere compiler-indstillingen emitDecoratorMetadata i din tsconfig.json-fil.

Eksempel (med brug af 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}`;
  }
}

// Usage

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
              
            
          

I dette eksempel markerer @required-decoratoren parametre som påkrævede. @validate-decoratoren bruger derefter reflection (via reflect-metadata) til at kontrollere, om de påkrævede parametre er til stede, før metoden kaldes. Dette eksempel viser den grundlæggende brug, og det anbefales at skabe robust parametervalidering i et produktionsscenarie.

For at installere reflect-metadata:

            npm install reflect-metadata --save

            

              
                Copy
              
            
          

Brug af Decorators til Metadata

En af de primære anvendelser af decorators er at tilknytte metadata til klasser og deres medlemmer. Disse metadata kan bruges ved kørsel til forskellige formål, såsom dependency injection, serialisering og validering. Biblioteket reflect-metadata giver en standardiseret måde at gemme og hente metadata på.

Eksempel:

            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 er funktioner, der returnerer en decorator. De giver dig mulighed for at sende argumenter til decoratoren, hvilket gør den mere fleksibel og genanvendelig.

Eksempel:

            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
              
            
          

@deprecated decorator factory'en tager en forældelsesmeddelelse som et argument og logger en advarsel, når den dekorerede metode kaldes. Dette giver dig mulighed for at markere metoder som forældede (deprecated) og give udviklere vejledning i, hvordan de migrerer til nyere alternativer.

Anvendelsesscenarier fra den virkelige verden

Decorators har en bred vifte af anvendelser i moderne JavaScript-udvikling:

• Dependency Injection: Frameworks som Angular er stærkt afhængige af decorators til dependency injection.
• Routing: I webapplikationer kan decorators bruges til at definere routes for controllere og metoder.
• Validering: Decorators kan bruges til at validere inputdata og sikre, at det opfylder bestemte kriterier.
• Autorisation: Decorators kan bruges til at håndhæve sikkerhedspolitikker og begrænse adgangen til bestemte metoder eller ressourcer.
• Logging og Profiling: Som vist i eksemplerne ovenfor kan decorators bruges til logging og profilering af kodekørsel.
• State Management: Decorators kan integreres med state management-biblioteker for automatisk at opdatere komponenter, når state ændres.

Fordele ved at bruge Decorators

• Forbedret kodelæsbarhed: Decorators giver en deklarativ syntaks til at tilføje funktionalitet, hvilket gør koden lettere at forstå og vedligeholde.
• Separation of Concerns: Decorators giver dig mulighed for at adskille tværgående anliggender (f.eks. logging, validering, autorisation) fra den centrale forretningslogik.
• Genanvendelighed: Decorators kan genbruges på tværs af flere klasser og metoder, hvilket reducerer kodeduplikering.
• Udvidelsesmuligheder: Decorators gør det nemt at udvide funktionaliteten af eksisterende kode uden at ændre den direkte.

Udfordringer og Overvejelser

• Læringskurve: Decorators er en relativt ny feature, og det kan tage lidt tid at lære at bruge dem effektivt.
• Kompatibilitet: Sørg for, at dit mål-miljø understøtter decorators, og at du har konfigureret dine build-værktøjer korrekt.
• Debugging: Debugging af kode, der bruger decorators, kan være mere udfordrende end debugging af almindelig kode, især hvis decoratorerne er komplekse.
• Overforbrug: Undgå at overforbruge decorators, da dette kan gøre din kode sværere at forstå og vedligeholde. Brug dem strategisk til specifikke formål.
• Runtime Overhead: Decorators kan introducere en vis runtime overhead, især hvis de udfører komplekse operationer. Overvej performance-konsekvenserne, når du bruger decorators i performance-kritiske applikationer.

Konklusion

JavaScript Decorators er et kraftfuldt værktøj til at forbedre kodens funktionalitet og fremme "separation of concerns" (adskillelse af ansvarsområder). Ved at tilbyde en ren, deklarativ syntaks til at tilføje metadata og transformere klasser, metoder, egenskaber og parametre, kan decorators hjælpe dig med at skabe mere vedligeholdelsesvenlige, genanvendelige og udvidelige kodebaser. Selvom de kommer med en læringskurve og nogle potentielle udfordringer, kan fordelene ved at bruge decorators i den rette kontekst være betydelige. I takt med at JavaScript-økosystemet fortsætter med at udvikle sig, vil decorators sandsynligvis blive en stadig vigtigere del af moderne JavaScript-udvikling.

Overvej at udforske, hvordan decorators kan forenkle din eksisterende kode eller give dig mulighed for at skrive mere udtryksfulde og vedligeholdelsesvenlige applikationer. Med omhyggelig planlægning og en solid forståelse af deres kapabiliteter kan du udnytte decorators til at skabe mere robuste og skalerbare JavaScript-løsninger.