Close

TypeScript - Class Decorators

[Updated: Dec 25, 2018, Created: Dec 23, 2018]

What are decorators?

A Decorator is a special kind of declaration that can be attached to a class declaration, method, accessor, property, or parameter. Decorators use the form @expression, where expression must evaluate to a function that will be called at runtime with information about the decorated declaration.

Decorators are a stage 2 proposal for JavaScript. That means decorators will be part of JavaScript in a future release.
Decorators are available as an experimental feature of TypeScript.

To enable decorators, we must enable the experimentalDecorators compiler option either on the command line or in your tsconfig.json.

Class decorators

This tutorial shows the use of Class decorators.

If a decorator expression has the arguments e.g. @expression("a", 3) then these arguments are passed to the decorator function expression(arg1: string, arg2: number).

If a decorator expression has no arguments e.g. @expression then the constructor function of the class is passed to the decorator function expression(theConstructor: Function)

In both above cases the decorator expression can return a new constructor function to replace or override the original constructor function.

Examples

tsconfig.json

{
    "compilerOptions": {
        "target": "ES6",
        "experimentalDecorators": true
    }
}

Also check out tutorial on tsconfig.json.

Adding new properties

In following example, the decorator SelfDriving adds a new property to the target class.

Ex1ClassDecorator.ts

function SelfDriving(constructorFunction: Function) {
    console.log('-- decorator function invoked --');
    constructorFunction.prototype.selfDrivable = true;
}

@SelfDriving
class Car {
    private _make: string;
    constructor(make: string) {
        console.log('-- this constructor invoked --');
        this._make = make;
    }
}
console.log('-- creating an instance --');
let car: Car = new Car("Nissan");
console.log(car);
console.log(`selfDriving: ${car['selfDrivable']}`);

console.log('-- creating one more instance --');
car = new Car("Toyota");
console.log(car);
console.log(`selfDriving: ${car['selfDrivable']}`);

Output

-- decorator function invoked --
-- creating an instance --
-- this constructor invoked --
Car { _make: 'Nissan' }
selfDriving: true
-- creating one more instance --
-- this constructor invoked --
Car { _make: 'Toyota' }
selfDriving: true

As seen above the decorator function is called only once when the class Car definition is loaded (before any instance is created).

The compiled JavaScript

var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? 
                         desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") 
        r = Reflect.decorate(decorators, target, key, desc);
      else for (var i = decorators.length - 1; i >= 0; i--) 
        if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
      return c > 3 && r && Object.defineProperty(target, key, r), r;
};
function SelfDriving(constructorFunction) {
    console.log('-- decorator function invoked --');
    constructorFunction.prototype.selfDrivable = true;
}
let Car = class Car {
    constructor(make) {
        console.log('-- this constructor invoked --');
        this._make = make;
    }
};
Car = __decorate([
    SelfDriving
], Car);
console.log('-- creating an instance --');
let car = new Car("Nissan");
console.log(car);
console.log(`selfDriving: ${car['selfDrivable']}`);
console.log('-- creating one more instance --');
car = new Car("Toyota");
console.log(car);
console.log(`selfDriving: ${car['selfDrivable']}`);

Decorator with parameter

function Wheels(numOfWheels: number) {
    console.log('-- decorator factory invoked --');
    return function (constructor: Function) {
        console.log('-- decorator invoked --');
        constructor.prototype.wheels = numOfWheels;
    }
}

@Wheels(4)
class Vechical {
    private _make: string;
    constructor(make: string) {
        console.log('-- this constructor invoked --');
        this._make = make;
    }
}

console.log('-- creating an instance --');

let vechical: Vechical = new Vechical("Nissan");
console.log(vechical);

console.log(vechical['wheels']);

console.log('-- creating another instance --');

vechical = new Vechical("Toyota");
console.log(vechical);
console.log(vechical['wheels']);

Output

-- decorator factory invoked --
-- decorator invoked --
-- creating an instance --
-- this constructor invoked --
Vechical { _make: 'Nissan' }
4
-- creating another instance --
-- this constructor invoked --
Vechical { _make: 'Toyota' }
4

In above example the method Wheels() is a decorator factory which returns a decorator function. The decorator function applies the desired logic based on the passed parameters and the constructor function.

Extending Constructor

Ex3OverrideConstructor.ts

function Compact<T extends { new(...args: any[]): {} }>(constructor: T) {
    return class extends constructor {
        gears: number = 5;
        wheels: number = 3;
    }
}

@Compact
class Automobile {
    make: string;
    wheels: number = 4;
    constructor(make: string) {
        this.make = make;
    }
}

console.log(new Automobile("Nissan"));

Output

Automobile { wheels: 3, make: 'Nissan', gears: 5 }

Also check out tutorials on generic constraints with new() and JavaScript class expressions.

Extending constructor with parameters

Ex4OverrideConstructor.ts

function Specs(numGears: number, numWheels: number) {
    return function <T extends { new(...args: any[]): {} }>(constructor: T) {
        return class extends constructor {
            gears = numGears;
            wheels = numWheels;
        }
    }
}

@Specs(3, 4)
class Wagon {
    make: string;
    constructor(make: string) {
        this.make = make;
    }
}

console.log(new Wagon("Nissan"));

Output

Wagon { make: 'Nissan', gears: 3, wheels: 4 }

Wrapping constructor

In following example we are going to wrap the original constructor in a new constructor.

Ex5ConstructorInterceptor.ts

function log<T extends { new(...constructorArgs: any[]) }>(constructorFunction: T) {

    //new constructor function
    let newConstructorFunction: any = function (...args) {
        console.log("before invoking: " + constructorFunction.name);
        let func: any = function () {
            return new constructorFunction(...args);
        }
        func.prototype = constructorFunction.prototype;
        let result: any = new func();
        console.log("after invoking: " + constructorFunction.name);
        console.log('object created: ' + JSON.stringify(result));
        return result;
    }
    newConstructorFunction.prototype = constructorFunction.prototype;
    return newConstructorFunction;
}

@log
class Task {
    taskName: string;
    constructor(taskName: string) {
        console.log('this constructor invoked');
        this.taskName = taskName;
    }
}
console.log("creating an instance");

let task = new Task("test");
console.log('task created: ' + JSON.stringify(task));
console.log("instanceof Task: " + (task instanceof Task));


Output

creating an instance
before invoking: Task
this constructor invoked
after invoking: Task
object created: {"taskName":"test"}
task created: {"taskName":"test"}
instanceof Task: true

Wrapping constructor with parameters

as

Ex6ConstructorInterceptor.ts

function Listener<I extends ObjectListener<any>>(listener: I) {

    return function <T extends { new(...constructorArgs: any[]) }>(constructorFunction: T) {
        //new constructor function
        let newConstructorFunction: any = function (...args) {
            let func: any = function () {
                return new constructorFunction(...args);
            }
            func.prototype = constructorFunction.prototype;
            let result: any = new func();
            listener.onObjectCreation(result);
            return result;
        }
        newConstructorFunction.prototype = constructorFunction.prototype;
        return newConstructorFunction;
    }
}

interface ObjectListener<T> {
    onObjectCreation(t: T): void;

}
class MyObjectListener implements ObjectListener<any>{
    onObjectCreation(obj: any) {
        console.log("Object created: " + JSON.stringify(obj));
    }
}

@Listener(new MyObjectListener())
class TaskRunner {
    taskName: string;
    constructor(taskName: string) {
        this.taskName = taskName;
    }
}
console.log("creating an instance");

let taskRunner = new TaskRunner("test");



Output

creating an instance
Object created: {"taskName":"test"}

Example Project

Dependencies and Technologies Used:

  • TypeScript 3.2.2
TypeScript - Class Decorators Select All Download
  • typescript-class-decorator-examples
    • Ex1ClassDecorator.ts

    See Also