Decorator in TypeScript: metodi, classi, campi e accessor

Un decorator è una funzione che applichi a una classe o a un membro di una classe con @name. Riceve il metodo originale (o la classe, o il campo) più un oggetto di contesto che lo descrive, e può restituire un sostituto. TypeScript supporta i decorator standard senza alcun flag del compilatore.

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 viene eseguito una volta, quando la classe viene definita, e sostituisce add con il wrapper che restituisce. Ogni chiamata passa dal wrapper. I parametri generici mantengono intatti i tipi di this, degli argomenti e del ritorno del metodo, quindi add accetta ancora due numeri e restituisce un numero.

Come vengono compilati i decorator

I decorator standard vengono da una proposta TC39 per JavaScript, e TypeScript li implementa da TypeScript 5.0. La proposta non fa ancora parte dello standard JavaScript, e Node 24 non riconosce la sintassi @, quindi quando il target è ES2022 (come in queste pagine) il compilatore riscrive ogni classe decorata in JavaScript semplice che chiama funzioni helper (__esDecorate e __runInitializers, emesse in cima al file). L'output funziona ovunque funzioni ES2022.

Una conseguenza: un file con decorator non può essere eseguito con il type stripping integrato di Node (node file.ts), che rimuove solo i tipi e lascia la @ al suo posto. Node si ferma con SyntaxError: Invalid or unexpected token. Compilalo prima con tsc o con un bundler.

Tipi di decorator e le loro firme

Ogni decorator standard ha la forma (value, context) => replacement | void. Cosa sia value, e cosa puoi restituire, dipende da ciò che viene decorato:

Ogni oggetto di contesto ha kind, name e addInitializer. Il contesto di un membro di classe ha anche static, private e un oggetto access per leggere il membro da un'istanza. I decorator funzionano anche sui membri statici e #private.

Decorator factory

Per passare delle opzioni, scrivi una funzione che restituisce un decorator e chiamala nel punto della @. Questa è una decorator factory:

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) chiama prima retry, e la funzione che restituisce è il decorator vero e proprio. Più decorator si impilano: in @a @b method(), b viene applicato per primo e a avvolge il risultato.

Decorator di classe e addInitializer

Un decorator di classe riceve la classe stessa. Può restituire una sottoclasse per sostituirla, oppure non restituire nulla e limitarsi a registrarla da qualche parte. context.addInitializer registra del codice da eseguire in un momento preciso: per un decorator di classe, subito dopo che la classe è stata definita del tutto; per un decorator di metodo, quando ogni istanza viene costruita.

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

Il decorator di classe va sopra la classe (o dopo export). Senza @bound, chiamare loose() lancerebbe un errore, perché this sarebbe undefined.

Decorator di campo e di accessor

Un decorator di campo non può vedere né intercettare le assegnazioni successive: il suo value è undefined, e tutto ciò che può restituire è una funzione che trasforma il valore iniziale del campo. Per intercettare letture e scritture, dichiara il campo con la parola chiave accessor, che lo trasforma in una coppia getter e setter basata su uno spazio privato, e decora quello:

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 fa parte della stessa proposta. Emette un vero getter e setter sopra un campo #private, ed è per questo che p.price = -5 passa dal set del decorator.

Standard vs experimentalDecorators legacy

Prima di TypeScript 5.0, gli unici decorator di TypeScript erano una versione iniziale della proposta, attivata con experimentalDecorators. Quel flag esiste ancora, e fa passare il compilatore al modello legacy, con firme e semantica diverse:

Un decorator scritto per un modello non supera il controllo dei tipi nell'altro. Ecco un decorator in stile legacy in un progetto senza il flag:

// 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 soluzione è riscriverlo nella forma standard (value, context), come nel primo esempio di questa pagina, oppure attivare il modello legacy per tutto il progetto:

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

Angular, NestJS e TypeORM impostano ancora experimentalDecorators nelle configurazioni generate dai loro strumenti e richieste dalla loro documentazione. NestJS e TypeORM hanno bisogno anche di emitDecoratorMetadata, perché leggono i tipi a runtime: NestJS per iniettare i parametri del costruttore, TypeORM per mappare le proprietà sulle colonne:

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

Se usi uno di questi framework, scrivi i decorator alla maniera legacy e segui la sua documentazione. Per il codice nuovo senza un framework del genere, usa i decorator standard.

Quando usare i decorator

I decorator sono adatti a comportamenti trasversali che altrimenti si ripeterebbero in molti metodi: logging, misurazione dei tempi, cache, tentativi ripetuti, controlli di accesso, validazione e registrazione di classi in un container o in un router. Però nascondono anche il flusso di controllo, perché chi legge deve andare a vedere cosa fa @retry prima di sapere cosa fa il metodo. Per uno o due usi, una semplice funzione di ordine superiore (const fetchData = retry(3, rawFetch)) è più semplice e funziona anche fuori dalle classi.