Décorateurs TypeScript : méthode, classe, champ et accessor

Un décorateur est une fonction que vous attachez à une classe ou à un membre de classe avec @name. Il reçoit la méthode d'origine (ou la classe, ou le champ) plus un objet de contexte qui la décrit, et il peut renvoyer un remplaçant. TypeScript prend en charge les décorateurs standard sans aucune option du compilateur.

function logged<This, Args extends unknown[], Return>(
    method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    const name = String(context.name);
    return function (this: This, ...args: Args): Return {
        console.log(`-> ${name}(${args.join(", ")})`);
        const result = method.call(this, ...args);
        console.log(`<- ${name} = ${result}`);
        return result;
    };
}

class Calculator {
    @logged
    add(a: number, b: number): number {
        return a + b;
    }
}

new Calculator().add(2, 3);
// -> add(2, 3)
// <- add = 5

@logged s'exécute une fois, quand la classe est définie, et remplace add par l'enveloppe qu'il renvoie. Chaque appel passe par cette enveloppe. Les paramètres génériques préservent les types de this, des arguments et du retour de la méthode : add prend donc toujours deux nombres et renvoie un nombre.

Comment les décorateurs sont compilés

Les décorateurs standard viennent d'une proposition TC39 pour JavaScript, que TypeScript implémente depuis TypeScript 5.0. La proposition ne fait pas encore partie du standard JavaScript, et Node 24 ne sait pas analyser la syntaxe @ : quand la cible est ES2022 (comme sur ces pages), le compilateur réécrit donc chaque classe décorée en JavaScript ordinaire qui appelle des fonctions auxiliaires (__esDecorate et __runInitializers, émises en haut du fichier). La sortie tourne partout où tourne ES2022.

Une conséquence : un fichier contenant des décorateurs ne peut pas s'exécuter avec le type stripping intégré de Node (node file.ts), qui se contente de retirer les types et laisse le @ en place. Node s'arrête avec SyntaxError: Invalid or unexpected token. Compilez d'abord avec tsc ou un bundler.

Sortes de décorateurs et leurs signatures

Chaque décorateur standard a la forme (value, context) => replacement | void. Ce qu'est value, et ce que vous pouvez renvoyer, dépend de ce qui est décoré :

Chaque objet de contexte possède kind, name et addInitializer. Le contexte d'un membre de classe possède aussi static, private et un objet access pour lire le membre sur une instance. Les décorateurs fonctionnent aussi sur les membres statiques et #private.

Fabriques de décorateurs

Pour passer des options, écrivez une fonction qui renvoie un décorateur et appelez-la à l'endroit du @. C'est une fabrique de décorateurs :

function retry(times: number) {
    return function <This, Args extends unknown[], Return>(
        method: (this: This, ...args: Args) => Return,
        _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
    ) {
        return function (this: This, ...args: Args): Return {
            for (let attempt = 1; ; attempt++) {
                try {
                    return method.call(this, ...args);
                } catch (e) {
                    if (attempt >= times) throw e;
                    console.log(`attempt ${attempt} failed, retrying`);
                }
            }
        };
    };
}

class Client {
    calls = 0;

    @retry(3)
    fetchData(): string {
        this.calls++;
        if (this.calls < 3) throw new Error("flaky");
        return `ok after ${this.calls} calls`;
    }
}

console.log(new Client().fetchData());

@retry(3) appelle d'abord retry, et la fonction qu'il renvoie est le véritable décorateur. Plusieurs décorateurs s'empilent : dans @a @b method(), b est appliqué en premier et a enveloppe le résultat.

Décorateurs de classe et addInitializer

Un décorateur de classe reçoit la classe elle-même. Il peut renvoyer une sous-classe pour la remplacer, ou ne rien renvoyer et simplement l'enregistrer quelque part. context.addInitializer enregistre du code à exécuter à un moment précis : pour un décorateur de classe, juste après la définition complète de la classe ; pour un décorateur de méthode, à la construction de chaque instance.

const registry = new Map<string, new () => object>();

function register(id: string) {
    return function <T extends new () => object>(target: T, context: ClassDecoratorContext<T>) {
        context.addInitializer(() => {
            registry.set(id, target);
        });
    };
}

// Binds a method to its instance, so it survives being passed as a callback.
function bound<This, Args extends unknown[], Return>(
    _method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    context.addInitializer(function (this: This) {
        const self = this as Record<string | symbol, unknown>;
        const fn = self[context.name] as (...a: unknown[]) => unknown;
        self[context.name] = fn.bind(this);
    });
}

@register("greeter")
class Greeter {
    name = "Ada";

    @bound
    greet(): string {
        return `Hello, ${this.name}`;
    }
}

const g = new Greeter();
const loose = g.greet; // detached from g
console.log(loose());  // Hello, Ada
console.log([...registry.keys()], registry.get("greeter") === Greeter); // [ 'greeter' ] true

Le décorateur de classe se place au-dessus de la classe (ou après export). Sans @bound, appeler loose() lèverait une exception, car this vaudrait undefined.

Décorateurs de champ et d'accessor

Un décorateur de champ ne peut ni voir ni intercepter les assignations ultérieures : sa value vaut undefined, et il ne peut renvoyer qu'une fonction qui transforme la valeur initiale du champ. Pour intercepter les lectures et les écritures, déclarez le champ avec le mot-clé accessor, qui le transforme en une paire getter/setter adossée à un stockage privé, et décorez-le :

function trimmed(_value: undefined, _context: ClassFieldDecoratorContext<unknown, string>) {
    return (initial: string) => initial.trim();
}

function positive<This>(
    target: ClassAccessorDecoratorTarget<This, number>,
    context: ClassAccessorDecoratorContext<This, number>,
): ClassAccessorDecoratorResult<This, number> {
    const check = (v: number) => {
        if (v <= 0) throw new RangeError(`${String(context.name)} must be positive, got ${v}`);
        return v;
    };
    return {
        init: check, // runs on the initial value
        set(v) {
            target.set.call(this, check(v));
        },
    };
}

class Product {
    @trimmed title = "  Lamp  ";
    @positive accessor price = 30;
}

const p = new Product();
console.log(`[${p.title}]`, p.price); // [Lamp] 30
p.price = 45;
console.log(p.price); // 45
try {
    p.price = -5;
} catch (e) {
    if (e instanceof Error) console.log(e.message); // price must be positive, got -5
}

accessor fait partie de la même proposition. Il émet un vrai getter et un vrai setter au-dessus d'un champ #private, c'est pourquoi p.price = -5 passe par le set du décorateur.

Décorateurs standard ou anciens experimentalDecorators

Avant TypeScript 5.0, les seuls décorateurs de TypeScript étaient une version préliminaire de la proposition, activée avec experimentalDecorators. Cette option existe toujours, et elle fait passer le compilateur à l'ancien modèle, avec des signatures et une sémantique différentes :

Un décorateur écrit pour un modèle ne passe pas la vérification des types dans l'autre. Voici un décorateur de l'ancien style dans un projet sans l'option :

// This does not compile: a legacy decorator used as a standard one.
function log(target: object, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = function (this: unknown, ...args: unknown[]) {
        console.log("calling", key);
        return original.apply(this, args);
    };
}

class Service {
    @log
    run(): string {
        return "done";
    }
}

console.log(new Service().run());

index.ts(11,5): error TS1241: Unable to resolve signature of method decorator when called as an expression.
  The runtime will invoke the decorator with 2 arguments, but the decorator expects 3.

La correction consiste soit à le réécrire sous la forme standard (value, context), comme dans le premier exemple de cette page, soit à activer l'ancien modèle pour tout le projet :

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

Angular, NestJS et TypeORM activent toujours experimentalDecorators dans les configurations générées par leurs outils et le demandent dans leur documentation. NestJS et TypeORM ont aussi besoin de emitDecoratorMetadata, car ils lisent les types à l'exécution : NestJS pour injecter les paramètres du constructeur, TypeORM pour faire correspondre les propriétés aux colonnes :

// Legacy model: needs experimentalDecorators (and emitDecoratorMetadata for DI).
@Injectable()
class UsersService {
    constructor(@Inject(DB) private db: Database) {}
}

Si vous utilisez l'un de ces frameworks, écrivez les décorateurs à l'ancienne et suivez sa documentation. Pour du nouveau code sans ce type de framework, utilisez les décorateurs standard.

Quand utiliser les décorateurs

Les décorateurs conviennent aux comportements transversaux qui seraient sinon répétés dans de nombreuses méthodes : journalisation, mesure du temps, mise en cache, nouvelles tentatives, contrôles d'accès, validation, et enregistrement de classes auprès d'un conteneur ou d'un routeur. Ils masquent aussi le flux de contrôle, puisqu'un lecteur doit aller voir ce que fait @retry avant de savoir ce que fait la méthode. Pour un ou deux usages, une simple fonction d'ordre supérieur (const fetchData = retry(3, rawFetch)) est plus simple et fonctionne aussi en dehors des classes.