.TS File Format – Decorators

Syntax

Decorator:
    @ Identifier {. Identifier}
    @ Identifier {. Identifier} ( Arguments )
    @ ( Expression )

Decorators go on classes and on their methods, accessors and fields. They cannot go on functions, interfaces or other declarations.

A class decorator may go before or after export, but not in both places.

@register export class A {}
export @register class B {}

const util = { logged };
class C {
  @util.logged run() {}
  @(util.logged) stop() {}
}

@register function f() {}    // error: not valid on a function

With several decorators, the expressions are evaluated from top to bottom, and the decorators are applied from bottom to top, like nested function calls.

Standard decorators

A standard decorator receives the thing being decorated and a context object. It may return a replacement.

Decorator(value, context) => replacement | void

These types are declared in the standard library. The context has these fields:

function logged<This, A extends unknown[], R>(
  target: (this: This, ...a: A) => R,
  context: ClassMethodDecoratorContext<This, (this: This, ...a: A) => R>,
) {
  const name = String(context.name);
  return function (this: This, ...a: A): R {
    console.log("calling", name);
    return target.call(this, ...a);
  };
}

function double<V extends number>(_: undefined, context: ClassFieldDecoratorContext<unknown, V>) {
  return (initial: V) => (initial * 2) as V;
}

class Counter {
  @double count = 1;
  @logged increment(by: number) { return this.count + by; }
}

Standard decorators cannot go on parameters, and they do not work with emitDecoratorMetadata.

Legacy decorators

experimentalDecorators turns on the older proposal. The decorator takes different arguments for each target, and the compiler emits calls to a helper after the class.

For a member, target is the class for a static member and the prototype for an instance member. Only one of a pair of accessors may be decorated, and the decorators apply to the combined property.

function sealed(constructor: Function) {
  Object.seal(constructor);
  Object.seal(constructor.prototype);
}

function enumerable(value: boolean) {
  return function (target: any, key: string | symbol, descriptor: PropertyDescriptor) {
    descriptor.enumerable = value;
  };
}

function required(target: object, key: string | symbol | undefined, index: number) {}

@sealed
class Greeter {
  @enumerable(false)
  greet(@required name: string) { return name; }
}

Decorators are applied in this order: parameter, then method, accessor or property decorators for each instance member; the same for each static member; parameter decorators on the constructor; and finally class decorators.

Decorator metadata

With experimentalDecorators and emitDecoratorMetadata, the compiler records type information for decorated declarations, which the reflect-metadata package can read at run time.

Each type is written as a run-time value, such as String or a class. Types with no run-time value become Object.

__decorate([
    enumerable(false),
    __param(0, required),
    __metadata("design:type", Function),
    __metadata("design:paramtypes", [String]),
    __metadata("design:returntype", void 0)
], Greeter.prototype, "greet", null);