TypeScript decorators

[jamesadarich]

Outcomes

• [x] what is a decorator? A way to modify classes and class members. Provides annotations / meta-programming syntax for classes and class members (accessor, property, or parameter). It is used to observe, modify, or replace an original definition. It cannot be used in a decoration file, on an overload or in any other ambient context.
• [x] how do you make a decorator? usage @example or a class or class member. Define example function which takes in target or a factory to pass in additional details.
• [x] when do they execute? They execute functions at run-time
• [x] when should you use one? When you wish to observe, modify, or replace original behavior

[gruckion]

Basics: Decorators are evaluated in this order parameter, method, accessor or property decorators, for instance and static members. For constructors parameter decorators are applied and class decorators for class's. Used as @expression where expression evaluates to a function that is called at run-time.

@example
function example(target) {
    // act with target
}

Decorator factories are used to customize how they are applied.

//decorator factory
function color(value: string) {
    return function (target) {
        // act with target and value
    }
}

Decorators are first evaluated then called (f o g)(x) = f(g(x)).

@f @g method() { }

f(): evaluated g(): evaluated

g(): called f(): called

Useful links: https://www.typescriptlang.org/docs/handbook/decorators.html

[gruckion]

Class Decorators: are applied to the constructor and are used to observe, modify, or replace a class definition. Can not be used in a declaration file or declare class. The class's constructor is used at the parameter of the decorator and is called at run-time.

The return type of a class decorator is a new constructor. Care must be taken to manage the original prototype if this is used.

@sealed
class Greeter {
    greeting: string;
    constructor(message: string) {
        this.greeting = message;
    }
    greet() {
        return "Hello, " + this.greeting;
    }
}

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

function classDecorator<T extends {new(...args:any[]):{}}>(constructor:T) {
    return class extends constructor {
        newProperty = "new property";
        hello = "override";
    }
}

@classDecorator
class Greeter {
    property = "property";
    hello: string;
    constructor(m: string) {
        this.hello = m;
    }
}

console.log(new Greeter("world"));

[gruckion]

Method Decorators:

The decorator is applied to the property descriptor for the method. It is used to observe, modify, or replace a method definition. It cannot be used in a decoration file, on an overload or in any other ambient context.

The method decorator is called with three arguments.

1. The constructor of the class for a static member, or the prototype of a class for an instance member.
2. The name of the member.
3. The property descriptor for the member.

The return type of the method descriptor will be used as the property descriptor for the method.

class Greeter {
    greeting: string;
    constructor(message: string) {
        this.greeting = message;
    }

    @enumerable(false)
    greet() {
        return "Hello, " + this.greeting;
    }
}

//decorator factory
function enumerable(value: boolean) {
    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
        descriptor.enumerable = value;
    };
}

[gruckion]

Accessor Decorators

[gruckion]

Property Decorators

[gruckion]

Parameter Decorators