Getting Started with TypeScript Decorators

Decorators in TypeScript provide a way to add both annotations and a meta-programming syntax for class declarations and members. They can annotate or modify classes or class members. Decorators can be chained or composed; that is, multiple decorators can be applied to a single declaration.

Decorators are available in several object-oriented and functional programming languages, including Python, JavaScript ES6, and TypeScript. Decorators are a lightweight alternative to subclasses. In other languages, such as C++, C#, and Java, the decorator design pattern is implemented with wrapper classes.

In TypeScript, decorators are declared using an at sign (@) before the decorator name and have a matching function that implements the behavior. The file below contains an example of a class decorator (@classDecorator) applied to the class Person.

File: class_decorator_example.ts

1 2 3 4 5 6 7 8

const classDecorator = (target: Function) => { this.title = t; } @classDecorator //class decorator class Person { title: string; }

As of writing this guide, decorators are still an experimental feature in TypeScript. To enable this feature, set the experimentalDecorators compiler flag either on the command line or in your tsconfig.json file.

To enable the decorators feature from the command line, use the following command:

tsc --target ES5 --experimentalDecorators

Decorators can be enabled by setting experimentalDecorators option to true in your tsconfig.json file as follows:

File: tsconfig.json

1 2 3 4 5 6

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

Decorators can be attached to a class declaration, method, accessor, property, or parameter. The example of a Class Decorator given in the TypeScript documentation is shown below:

File: class_decorator_example.ts

1 2 3 4 5 6 7 8 9 10 11 12 13

@sealed class BugReport { type = "report"; title: string; constructor(t: string) { this.title = t; } } function sealed(constructor: Function) { Object.seal(constructor); Object.seal(constructor.prototype); }

JavaScript’s Object.seal() method changes the configurable property descriptor the object’s parameter to false. That means you can’t delete any members of the object or extend the object with new members. The Object.seal() method doesn’t affect the writability of the object; for that, you can instead use Object.freeze().

You can find more examples for method, accessor, property, and parameter decorators in the TypeScript documentation. The usage of decorators in TypeScript is fairly advanced and uses the experimental reflect-metadata package. See Metadata for more information about the reflect-metadata library.

A decorator factory is a function that returns a function/expression that is called by the decorator at runtime. A decorator factory can be written as shown below:

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

The function enumerable accepts a parameter and returns another function that makes use of the parameter. In the above example, it modifies the enumerable property descriptor of the method. The @enumerable decorator applies this change to the example below.

File: decorator_factory_example.ts

1 2 3 4 5 6 7 8 9 10 11

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

Enumerating the greet() method in a for loop is not a good option, so this usage prevents users of the Greeter class from a harmless error.

Decorators provide a way to annotate or modify a class or class member in TypeScript. However, Decorators are still an experimental feature of the language. To learn more about Decorators in TypeScript, visit the Decorators proposal page.