Dekoratory w TypeScript: metody, klasy, pola i akcesory

Dekorator to funkcja, którą dołączasz do klasy albo składowej klasy za pomocą @name. Dostaje oryginalną metodę (albo klasę, albo pole) oraz opisujący ją obiekt kontekstu i może zwrócić zamiennik. TypeScript obsługuje standardowe dekoratory bez żadnej flagi kompilatora.

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 wykonuje się raz, gdy klasa zostaje zdefiniowana, i zastępuje add zwracanym opakowaniem. Każde wywołanie przechodzi przez to opakowanie. Parametry generyczne zachowują typy this, argumentów i wartości zwracanej metody, więc add nadal przyjmuje dwie liczby i zwraca liczbę.

Jak kompilują się dekoratory

Standardowe dekoratory pochodzą z propozycji TC39 dla JavaScriptu, a TypeScript implementuje je od wersji 5.0. Propozycja nie jest jeszcze częścią standardu JavaScript, a Node 24 nie parsuje składni @, więc przy targecie ES2022 (jak na tych stronach) kompilator przepisuje każdą dekorowaną klasę na zwykły JavaScript, który wywołuje funkcje pomocnicze (__esDecorate i __runInitializers, emitowane na początku pliku). Wynik działa wszędzie tam, gdzie działa ES2022.

Jedna konsekwencja: pliku z dekoratorami nie da się uruchomić przy wbudowanym w Node usuwaniu typów (node file.ts), które usuwa tylko typy i zostawia @ na miejscu. Node zatrzymuje się z SyntaxError: Invalid or unexpected token. Najpierw skompiluj plik przez tsc albo bundler.

Rodzaje dekoratorów i ich sygnatury

Każdy standardowy dekorator ma kształt (value, context) => replacement | void. To, czym jest value i co możesz zwrócić, zależy od tego, co jest dekorowane:

Każdy obiekt kontekstu ma kind, name i addInitializer. Kontekst składowej klasy ma też static, private i obiekt access do odczytu składowej z instancji. Dekoratory działają także na składowych statycznych i #private.

Fabryki dekoratorów

Żeby przekazać opcje, napisz funkcję, która zwraca dekorator, i wywołaj ją w miejscu @. To fabryka dekoratorów:

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) najpierw wywołuje retry, a zwracana przez nią funkcja jest właściwym dekoratorem. Wiele dekoratorów można układać jeden na drugim: w @a @b method() najpierw stosowany jest b, a a opakowuje wynik.

Dekoratory klas i addInitializer

Dekorator klasy dostaje samą klasę. Może zwrócić podklasę, która ją zastąpi, albo nic nie zwracać i tylko gdzieś ją zapisać. context.addInitializer rejestruje kod do wykonania w określonym momencie: dla dekoratora klasy zaraz po pełnym zdefiniowaniu klasy; dla dekoratora metody przy tworzeniu każdej instancji.

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

Dekorator klasy stoi nad klasą (albo po export). Bez @bound wywołanie loose() rzuciłoby wyjątek, bo this byłoby undefined.

Dekoratory pól i akcesorów

Dekorator pola nie widzi późniejszych przypisań i nie może ich przechwycić: jego value to undefined, a jedyne, co może zwrócić, to funkcja przekształcająca wartość początkową pola. Żeby przechwytywać odczyty i zapisy, zadeklaruj pole ze słowem kluczowym accessor, które zamienia je w parę getter i setter opartą na prywatnym magazynie, i udekoruj właśnie je:

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 należy do tej samej propozycji. Emituje prawdziwy getter i setter nad polem #private, dlatego p.price = -5 przechodzi przez set dekoratora.

Standardowe dekoratory a starsze experimentalDecorators

Przed TypeScript 5.0 jedynymi dekoratorami w TypeScript była wczesna wersja propozycji, włączana przez experimentalDecorators. Ta flaga nadal istnieje i przełącza kompilator na starszy model, z innymi sygnaturami i semantyką:

Dekorator napisany dla jednego modelu nie przechodzi sprawdzania typów w drugim. Oto dekorator w starym stylu w projekcie bez flagi:

// 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.

Rozwiązanie to albo przepisanie go w standardowej formie (value, context), jak w pierwszym przykładzie na tej stronie, albo włączenie starszego modelu dla całego projektu:

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

Angular, NestJS i TypeORM nadal ustawiają experimentalDecorators w konfiguracjach generowanych przez swoje narzędzia i wymagają go w dokumentacji. NestJS i TypeORM potrzebują też emitDecoratorMetadata, bo odczytują typy w czasie działania: NestJS, żeby wstrzykiwać parametry konstruktora, a TypeORM, żeby mapować właściwości na kolumny:

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

Jeśli używasz jednego z tych frameworków, pisz dekoratory w starym stylu i trzymaj się jego dokumentacji. W nowym kodzie bez takiego frameworka używaj standardowych dekoratorów.

Kiedy używać dekoratorów

Dekoratory pasują do zachowań przekrojowych, które inaczej powtarzałyby się w wielu metodach: logowania, pomiaru czasu, cache, ponawiania prób, sprawdzania uprawnień, walidacji i rejestrowania klas w kontenerze albo routerze. Ukrywają też przepływ sterowania, bo czytelnik musi sprawdzić, co robi @retry, zanim zrozumie, co robi metoda. Przy jednym albo dwóch użyciach prostsza jest zwykła funkcja wyższego rzędu (const fetchData = retry(3, rawFetch)), która działa też poza klasami.