TypeScript Decorators: Methode, Klasse, Feld und Accessor

Ein Decorator ist eine Funktion, die du mit @name an eine Klasse oder einen Klassenmember hängst. Sie bekommt die ursprüngliche Methode (oder Klasse, oder das Feld) plus ein Kontextobjekt, das sie beschreibt, und kann einen Ersatz zurückgeben. TypeScript unterstützt die Standard-Decorators ohne Compiler-Flag.

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 läuft einmal, wenn die Klasse definiert wird, und ersetzt add durch den zurückgegebenen Wrapper. Jeder Aufruf geht durch den Wrapper. Die generischen Parameter erhalten this, Argument und Rückgabetypen der Methode, also nimmt add weiterhin zwei Zahlen und gibt eine Zahl zurück.

Wie Decorators kompiliert werden

Standard-Decorators stammen aus einem TC39-Vorschlag für JavaScript, und TypeScript implementiert sie seit TypeScript 5.0. Der Vorschlag ist noch nicht Teil des JavaScript-Standards, und Node 24 parst die @-Syntax nicht. Ist das Target ES2022 (wie auf diesen Seiten), schreibt der Compiler daher jede dekorierte Klasse in reines JavaScript um, das Hilfsfunktionen aufruft (__esDecorate und __runInitializers, oben in der Datei ausgegeben). Die Ausgabe läuft überall, wo ES2022 läuft.

Eine Folge: Eine Datei mit Decorators läuft nicht mit dem eingebauten Type Stripping von Node (node file.ts), das nur Typen entfernt und das @ stehen lässt. Node bricht mit SyntaxError: Invalid or unexpected token ab. Kompiliere sie vorher mit tsc oder einem Bundler.

Arten von Decorators und ihre Signaturen

Jeder Standard-Decorator hat die Form (value, context) => replacement | void. Was value ist und was du zurückgeben darfst, hängt davon ab, was dekoriert wird:

Jedes Kontextobjekt hat kind, name und addInitializer. Der Kontext eines Klassenmembers hat außerdem static, private und ein Objekt access, um den Member von einer Instanz zu lesen. Decorators funktionieren auch bei statischen und #private Membern.

Decorator Factories

Um Optionen zu übergeben, schreibst du eine Funktion, die einen Decorator zurückgibt, und rufst sie an der @-Stelle auf. Das ist eine 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) ruft zuerst retry auf, und die zurückgegebene Funktion ist der eigentliche Decorator. Mehrere Decorators stapeln sich: Bei @a @b method() wird b zuerst angewendet, und a umhüllt das Ergebnis.

Klassen-Decorators und addInitializer

Ein Klassen-Decorator bekommt die Klasse selbst. Er kann eine Unterklasse als Ersatz zurückgeben oder nichts zurückgeben und sie nur irgendwo registrieren. context.addInitializer registriert Code, der zu einem bestimmten Zeitpunkt läuft: bei einem Klassen-Decorator direkt nachdem die Klasse vollständig definiert ist, bei einem Methoden-Decorator beim Erzeugen jeder Instanz.

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

Der Klassen-Decorator steht über der Klasse (oder nach export). Ohne @bound würde der Aufruf von loose() werfen, weil this undefined wäre.

Feld und Accessor-Decorators

Ein Feld-Decorator kann spätere Zuweisungen weder sehen noch abfangen: Sein value ist undefined, und er kann nur eine Funktion zurückgeben, die den Startwert des Felds umwandelt. Um Lese und Schreibzugriffe abzufangen, deklarierst du das Feld mit dem Schlüsselwort accessor, das es in ein Getter-Setter-Paar mit privatem Speicher verwandelt, und dekorierst das:

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 gehört zum selben Vorschlag. Es erzeugt einen echten Getter und Setter über einem #private Feld, und deshalb geht p.price = -5 durch das set des Decorators.

Standard vs Legacy experimentalDecorators

Vor TypeScript 5.0 hatte TypeScript nur eine frühe Version des Vorschlags, aktiviert mit experimentalDecorators. Dieses Flag gibt es weiterhin, und es schaltet den Compiler auf das Legacy-Modell mit anderen Signaturen und anderer Semantik um:

Ein für ein Modell geschriebener Decorator besteht die Typprüfung im anderen nicht. Hier ein Decorator im Legacy-Stil in einem Projekt ohne das 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.

Die Lösung ist, ihn entweder in die Standardform (value, context) umzuschreiben, wie im ersten Beispiel dieser Seite, oder das Legacy-Modell für das ganze Projekt einzuschalten:

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

Angular, NestJS und TypeORM setzen experimentalDecorators weiterhin in den Konfigurationen, die ihre Tools erzeugen und die ihre Dokumentation verlangt. NestJS und TypeORM brauchen außerdem emitDecoratorMetadata, weil sie Typen zur Laufzeit lesen: NestJS, um Konstruktorparameter zu injizieren, TypeORM, um Eigenschaften auf Spalten abzubilden:

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

Wenn du eines dieser Frameworks nutzt, schreibe Decorators im Legacy-Stil und folge seiner Dokumentation. Für neuen Code ohne ein solches Framework nimm die Standard-Decorators.

Wann Decorators sinnvoll sind

Decorators passen zu Querschnittsverhalten, das sonst in vielen Methoden wiederholt würde: Logging, Zeitmessung, Caching, Wiederholungen, Zugriffsprüfungen, Validierung und das Registrieren von Klassen bei einem Container oder Router. Sie verbergen aber auch den Kontrollfluss, denn wer den Code liest, muss erst nachschlagen, was @retry tut, bevor er weiß, was die Methode tut. Für ein oder zwei Einsätze ist eine einfache Higher-Order Function (const fetchData = retry(3, rawFetch)) einfacher und funktioniert auch außerhalb von Klassen.