Proposal to add Decorators to TypeScript.
For the ECMAScript specific proposal, see http://rbuckton.github.io/reflectdecorators/index.html
A decorator is an expression that is evaluated after a class has been defined, that can be used to annotate or modify the class in some fashion. This expression must evaluate to a function, which is executed by the runtime to apply the decoration.
@decoratorExpression
class C {
}
A class decorator function is a function that accepts a constructor function as its argument, and returns either undefined, the provided constructor function, or a new constructor function. Returning undefined is equivalent to returning the provided constructor function.
// A class decorator function
function dec(target) {
// modify, annotate, or replace target...
}
A property decorator function is a function that accepts three arguments: The object that owns the property, the key for the property (a string or a symbol), and optionally the property descriptor of the property. The function must return either undefined, the provided property descriptor, or a new property descriptor. Returning undefined is equivalent to returning the provided property descriptor.
// A property (or method/accessor) decorator function
function dec(target, key, descriptor) {
// annotate the target and key; or modify or replace the descriptor...
}
A parameter decorator function is a function that accepts three arguments: The function that contains the decorated parameter, the property key of the member (or undefined for a parameter of the constructor), and the ordinal index of the parameter. The return value of this decorator is ignored.
// A parameter decorator
function dec(target, paramIndex) {
// annotate the target and index
}
A decorator factory is a function that can accept any number of arguments, and must return one of the above types of decorator function.
// a class decorator factory function
function dec(x, y) {
// the class decorator function
return function (target) {
// modify, annotate, or replace target...
}
}
A decorator can be legally applied to any of the following:
Please note that a decorator currently cannot be legally applied to any of the following:
This list may change in the future.
Decorators are evaluated in the order they appear preceeding their target declaration, to preserve side-effects due to evaluation order. Decorators are applied to their target declaration in reverse order, starting with the decorator closest to the declaration. This behavior is specified to preserve the expected behavior of decorators without a declarative syntax.
@F
@G
class C {
}
For example, the above listing could be approximately written without decorators in the following fashion:
C = F(G(C))
In the above example, the expression F is evaluated first, followed by the expression G. G is then called with the constructor function as its argument, followed by calling F with the result. The actual process of applying decorators is more complex than the above example however, though you may still imperatively apply decorators with a reflection API.
If a class declaration has decorators on both the class and any of its members or parameters, the decorators are applied using the following pseudocode:
for each member M of class C
if M is an accessor then
let accessor = first accessor (get or set, in declaration order) of M
let memberDecorators = decorators of accessor
for each parameter of accessor
let paramDecorators = decorators of parameter
let paramIndex = ordinal index of parameter
Reflect.decorate(paramDecorators, accessor, paramIndex)
next parameter
let accessor = second accessor (get or set, in declaration order) of M
if accessor then
let memberDecorators = memberDecorators + decorators of accessor
for each parameter of accessor
let paramDecorators = decorators of parameter
let paramIndex = ordinal index of parameter
Reflect.decorate(paramDecorators, accessor, paramIndex)
next parameter
end if
else if M is a method
let memberDecorators = decorators of M
for each parameter of M
let paramDecorators = decorators of parameter
let paramIndex = ordinal index of parameter
Reflect.decorate(paramDecorators, M, paramIndex)
next parameter
else
let memberDecorators = decorators of M
end if
let name = name of M
let target = C.prototype if M is on the prototype; otherwise, C if M is static
Reflect.decorate(memberDecorators, C, name)
next member
for each parameter of C
let paramDecorators = decorators of parameter
let paramIndex = ordinal index of parameter
Reflect.decorate(paramDecorators, C, paramIndex)
next parameter
let classDecorators = decorators of C
let C = Reflect.decorate(classDecorators, C)
In addition to a declarative approach to defining decorators, it is necessary to also include an imperative API capable of applying decorators, as well as defining, reflecting over, and removing decorator metadata from an object, property, or parameter.
A shim for this API can be found here: https://github.com/rbuckton/ReflectDecorators
Reflect.decorate(decorators, target, propertyKey?, descriptor?)
The following are examples of how decorators can be desugared to ES6 (through a transpiler such as TypeScript). These examples levarage an imperative reflection API.
@F("color")
@G
class C {
}
let C = class {
}
Object.defineProperty(C, "name", { value: "C", configurable: true });
C = __decorate([F("color"), G], C);
@F("color")
@G
export class C {
}
export let C = class {
}
Object.defineProperty(C, "name", { value: "C", configurable: true });
C = __decorate([F("color"), G], C);
@F("color")
@G
export default class C {
}
let C = class {
}
Object.defineProperty(C, "name", { value: "C", configurable: true });
C = __decorate([F("color"), G], C);
export default C;
class C {
@F("color")
@G
method() { }
}
class C {
method() { }
}
Object.defineProperty(C.prototype, "method",
__decorate([F("color"), G], C.prototype, "method", Object.getOwnPropertyDescriptor(C.prototype, "method")));
class C {
@F("color")
@G
get accessor() { }
set accessor(value) { }
}
class C {
get accessor() { }
set accessor(value) { }
}
Object.defineProperty(C.prototype, "accessor",
__decorate([F("color"), G], C.prototype, "accessor", Object.getOwnPropertyDescriptor(C.prototype, "accessor")));
class C {
@F("color")
@G
property = 1;
}
class C {
constructor() {
this.property = 1;
}
}
__decorate([F("color"), G], C.prototype, "property");
class C {
constructor(@F("color") @G p) { }
}
class C {
constructor(p) { }
}
__decorate([F("color"), G], C, void 0, 0);
class C {
method(@F("color") @G p) { }
}
class C {
method(p) { }
}
__decorate([F("color"), G], C.prototype, "method", 0);
class C {
set accessor(@F("color") @G p) { }
}
class C {
set accessor(p) { }
}
__decorate([F("color"), G], C.prototype, "accessor", 0);
interface TypedPropertyDescriptor<T> {
enumerable?: boolean;
configurable?: boolean;
writable?: boolean;
value?: T;
get?: () => T;
set?: (value: T) => void;
}
type ClassDecorator = <TFunction extends Function>(target: TFunction): TFunction | void;
type MethodDecorator = <T>(target: Object, propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<T>): TypedPropertyDescriptor<T> | void;
type PropertyDecorator = (target: Object, propertyKey: string | symbol): void;
type ParameterDecorator = (target: Object, propertyKey: string | symbol, parameterIndex: number): void;