With the introduction of Classes in TypeScript and ES6, there now exist certain scenarios that require additional features to support annotating or modifying classes and class members.\nDecorators provide a way to add both annotations and a meta-programming syntax for class declarations and members.\nDecorators are a stage 2 proposal for JavaScript and are available as an experimental feature of TypeScript.
\n\n\nNOTE Decorators are an experimental feature that may change in future releases.
\n
To enable experimental support for decorators, you must enable the experimentalDecorators compiler option either on the command line or in your tsconfig.json:
Command Line:
\n\nshelltsc --target ES5 --experimentalDecorators
tsconfig.json:
\n\njson{\n \"compilerOptions\": {\n \"target\": \"ES5\",\n \"experimentalDecorators\": true\n }\n}
A Decorator is a special kind of declaration that can be attached to a class declaration, method, accessor, property, or parameter.\nDecorators use the form @expression, where expression must evaluate to a function that will be called at runtime with information about the decorated declaration.
For example, given the decorator @sealed we might write the sealed function as follows:
\ntsfunction sealed(target) {\n // do something with 'target' ...\n}
\n\nNOTE You can see a more detailed example of a decorator in Class Decorators, below.
\n
If we want to customize how a decorator is applied to a declaration, we can write a decorator factory.\nA Decorator Factory is simply a function that returns the expression that will be called by the decorator at runtime.
\nWe can write a decorator factory in the following fashion:
\n\ntsfunction color(value: string) {\n // this is the decorator factory\n return function(target) {\n // this is the decorator\n // do something with 'target' and 'value'...\n };\n}
\n\nNOTE You can see a more detailed example of a decorator factory in Method Decorators, below.
\n
Multiple decorators can be applied to a declaration, as in the following examples:
\nOn a single line:
\n\nts@f @g x
On multiple lines:
\n\nts@f\n@g\nx
When multiple decorators apply to a single declaration, their evaluation is similar to function composition in mathematics. In this model, when composing functions f and g, the resulting composite (f ∘ g)(x) is equivalent to f(g(x)).
\nAs such, the following steps are performed when evaluating multiple decorators on a single declaration in TypeScript:
\nIf we were to use decorator factories, we can observe this evaluation order with the following example:
\n\ntsfunction f() {\n console.log(\"f(): evaluated\");\n return function(target, propertyKey: string, descriptor: PropertyDescriptor) {\n console.log(\"f(): called\");\n };\n}\n\nfunction g() {\n console.log(\"g(): evaluated\");\n return function(target, propertyKey: string, descriptor: PropertyDescriptor) {\n console.log(\"g(): called\");\n };\n}\n\nclass C {\n @f()\n @g()\n method() {}\n}
Which would print this output to the console:
\n\nshellf(): evaluated\ng(): evaluated\ng(): called\nf(): called
There is a well defined order to how decorators applied to various declarations inside of a class are applied:
\nA Class Decorator is declared just before a class declaration.\nThe class decorator is applied to the constructor of the class and can be used to observe, modify, or replace a class definition.\nA class decorator cannot be used in a declaration file, or in any other ambient context (such as on a declare class).
The expression for the class decorator will be called as a function at runtime, with the constructor of the decorated class as its only argument.
\nIf the class decorator returns a value, it will replace the class declaration with the provided constructor function.
\n\n\nNOTE Should you choose to return a new constructor function, you must take care to maintain the original prototype.\nThe logic that applies decorators at runtime will not do this for you.
\n
The following is an example of a class decorator (@sealed) applied to the Greeter class:
\nts@sealed\nclass Greeter {\n greeting: string;\n constructor(message: string) {\n this.greeting = message;\n }\n greet() {\n return \"Hello, \" + this.greeting;\n }\n}
We can define the @sealed decorator using the following function declaration:
\ntsfunction sealed(constructor: Function) {\n Object.seal(constructor);\n Object.seal(constructor.prototype);\n}
When @sealed is executed, it will seal both the constructor and its prototype.
Next we have an example of how to override the constructor.
\n\ntsfunction classDecorator<T extends { new (...args: any[]): {} }>(\n constructor: T\n) {\n return class extends constructor {\n newProperty = \"new property\";\n hello = \"override\";\n };\n}\n\n@classDecorator\nclass Greeter {\n property = \"property\";\n hello: string;\n constructor(m: string) {\n this.hello = m;\n }\n}\n\nconsole.log(new Greeter(\"world\"));
A Method Decorator is declared just before a method declaration.\nThe decorator is applied to the Property Descriptor for the method, and can be used to observe, modify, or replace a method definition.\nA method decorator cannot be used in a declaration file, on an overload, or in any other ambient context (such as in a declare class).
The expression for the method decorator will be called as a function at runtime, with the following three arguments:
\n\n\nNOTE The Property Descriptor will be
\nundefinedif your script target is less thanES5.
If the method decorator returns a value, it will be used as the Property Descriptor for the method.
\n\n\nNOTE The return value is ignored if your script target is less than
\nES5.
The following is an example of a method decorator (@enumerable) applied to a method on the Greeter class:
\ntsclass Greeter {\n greeting: string;\n constructor(message: string) {\n this.greeting = message;\n }\n\n @enumerable(false)\n greet() {\n return \"Hello, \" + this.greeting;\n }\n}
We can define the @enumerable decorator using the following function declaration:
\ntsfunction enumerable(value: boolean) {\n return function(\n target: any,\n propertyKey: string,\n descriptor: PropertyDescriptor\n ) {\n descriptor.enumerable = value;\n };\n}
The @enumerable(false) decorator here is a decorator factory.\nWhen the @enumerable(false) decorator is called, it modifies the enumerable property of the property descriptor.
An Accessor Decorator is declared just before an accessor declaration.\nThe accessor decorator is applied to the Property Descriptor for the accessor and can be used to observe, modify, or replace an accessor’s definitions.\nAn accessor decorator cannot be used in a declaration file, or in any other ambient context (such as in a declare class).
\n\nNOTE TypeScript disallows decorating both the
\ngetandsetaccessor for a single member.\nInstead, all decorators for the member must be applied to the first accessor specified in document order.\nThis is because decorators apply to a Property Descriptor, which combines both thegetandsetaccessor, not each declaration separately.
The expression for the accessor decorator will be called as a function at runtime, with the following three arguments:
\n\n\nNOTE The Property Descriptor will be
\nundefinedif your script target is less thanES5.
If the accessor decorator returns a value, it will be used as the Property Descriptor for the member.
\n\n\nNOTE The return value is ignored if your script target is less than
\nES5.
The following is an example of an accessor decorator (@configurable) applied to a member of the Point class:
\ntsclass Point {\n private _x: number;\n private _y: number;\n constructor(x: number, y: number) {\n this._x = x;\n this._y = y;\n }\n\n @configurable(false)\n get x() {\n return this._x;\n }\n\n @configurable(false)\n get y() {\n return this._y;\n }\n}
We can define the @configurable decorator using the following function declaration:
\ntsfunction configurable(value: boolean) {\n return function(\n target: any,\n propertyKey: string,\n descriptor: PropertyDescriptor\n ) {\n descriptor.configurable = value;\n };\n}
A Property Decorator is declared just before a property declaration.\nA property decorator cannot be used in a declaration file, or in any other ambient context (such as in a declare class).
The expression for the property decorator will be called as a function at runtime, with the following two arguments:
\n\n\nNOTE A Property Descriptor is not provided as an argument to a property decorator due to how property decorators are initialized in TypeScript.\nThis is because there is currently no mechanism to describe an instance property when defining members of a prototype, and no way to observe or modify the initializer for a property. The return value is ignored too.\nAs such, a property decorator can only be used to observe that a property of a specific name has been declared for a class.
\n
We can use this information to record metadata about the property, as in the following example:
\n\ntsclass Greeter {\n @format(\"Hello, %s\")\n greeting: string;\n\n constructor(message: string) {\n this.greeting = message;\n }\n greet() {\n let formatString = getFormat(this, \"greeting\");\n return formatString.replace(\"%s\", this.greeting);\n }\n}
We can then define the @format decorator and getFormat functions using the following function declarations:
\ntsimport \"reflect-metadata\";\n\nconst formatMetadataKey = Symbol(\"format\");\n\nfunction format(formatString: string) {\n return Reflect.metadata(formatMetadataKey, formatString);\n}\n\nfunction getFormat(target: any, propertyKey: string) {\n return Reflect.getMetadata(formatMetadataKey, target, propertyKey);\n}
The @format(\"Hello, %s\") decorator here is a decorator factory.\nWhen @format(\"Hello, %s\") is called, it adds a metadata entry for the property using the Reflect.metadata function from the reflect-metadata library.\nWhen getFormat is called, it reads the metadata value for the format.
\n\nNOTE This example requires the
\nreflect-metadatalibrary.\nSee Metadata for more information about thereflect-metadatalibrary.
A Parameter Decorator is declared just before a parameter declaration.\nThe parameter decorator is applied to the function for a class constructor or method declaration.\nA parameter decorator cannot be used in a declaration file, an overload, or in any other ambient context (such as in a declare class).
The expression for the parameter decorator will be called as a function at runtime, with the following three arguments:
\n\n\nNOTE A parameter decorator can only be used to observe that a parameter has been declared on a method.
\n
The return value of the parameter decorator is ignored.
\nThe following is an example of a parameter decorator (@required) applied to parameter of a member of the Greeter class:
\ntsclass Greeter {\n greeting: string;\n\n constructor(message: string) {\n this.greeting = message;\n }\n\n @validate\n greet(@required name: string) {\n return \"Hello \" + name + \", \" + this.greeting;\n }\n}
We can then define the @required and @validate decorators using the following function declarations:
\ntsimport \"reflect-metadata\";\n\nconst requiredMetadataKey = Symbol(\"required\");\n\nfunction required(\n target: Object,\n propertyKey: string | symbol,\n parameterIndex: number\n) {\n let existingRequiredParameters: number[] =\n Reflect.getOwnMetadata(requiredMetadataKey, target, propertyKey) || [];\n existingRequiredParameters.push(parameterIndex);\n Reflect.defineMetadata(\n requiredMetadataKey,\n existingRequiredParameters,\n target,\n propertyKey\n );\n}\n\nfunction validate(\n target: any,\n propertyName: string,\n descriptor: TypedPropertyDescriptor<Function>\n) {\n let method = descriptor.value;\n descriptor.value = function() {\n let requiredParameters: number[] = Reflect.getOwnMetadata(\n requiredMetadataKey,\n target,\n propertyName\n );\n if (requiredParameters) {\n for (let parameterIndex of requiredParameters) {\n if (\n parameterIndex >= arguments.length ||\n arguments[parameterIndex] === undefined\n ) {\n throw new Error(\"Missing required argument.\");\n }\n }\n }\n\n return method.apply(this, arguments);\n };\n}
The @required decorator adds a metadata entry that marks the parameter as required.\nThe @validate decorator then wraps the existing greet method in a function that validates the arguments before invoking the original method.
\n\nNOTE This example requires the
\nreflect-metadatalibrary.\nSee Metadata for more information about thereflect-metadatalibrary.
Some examples use the reflect-metadata library which adds a polyfill for an experimental metadata API.\nThis library is not yet part of the ECMAScript (JavaScript) standard.\nHowever, once decorators are officially adopted as part of the ECMAScript standard these extensions will be proposed for adoption.
You can install this library via npm:
\n\nshellnpm i reflect-metadata --save
TypeScript includes experimental support for emitting certain types of metadata for declarations that have decorators.\nTo enable this experimental support, you must set the emitDecoratorMetadata compiler option either on the command line or in your tsconfig.json:
Command Line:
\n\nshelltsc --target ES5 --experimentalDecorators --emitDecoratorMetadata
tsconfig.json:
\n\njson{\n \"compilerOptions\": {\n \"target\": \"ES5\",\n \"experimentalDecorators\": true,\n \"emitDecoratorMetadata\": true\n }\n}
When enabled, as long as the reflect-metadata library has been imported, additional design-time type information will be exposed at runtime.
We can see this in action in the following example:
\n\ntsimport \"reflect-metadata\";\n\nclass Point {\n x: number;\n y: number;\n}\n\nclass Line {\n private _p0: Point;\n private _p1: Point;\n\n @validate\n set p0(value: Point) {\n this._p0 = value;\n }\n get p0() {\n return this._p0;\n }\n\n @validate\n set p1(value: Point) {\n this._p1 = value;\n }\n get p1() {\n return this._p1;\n }\n}\n\nfunction validate<T>(\n target: any,\n propertyKey: string,\n descriptor: TypedPropertyDescriptor<T>\n) {\n let set = descriptor.set;\n descriptor.set = function(value: T) {\n let type = Reflect.getMetadata(\"design:type\", target, propertyKey);\n if (!(value instanceof type)) {\n throw new TypeError(\"Invalid type.\");\n }\n set.call(target, value);\n };\n}
The TypeScript compiler will inject design-time type information using the @Reflect.metadata decorator.\nYou could consider it the equivalent of the following TypeScript:
\ntsclass Line {\n private _p0: Point;\n private _p1: Point;\n\n @validate\n @Reflect.metadata(\"design:type\", Point)\n set p0(value: Point) {\n this._p0 = value;\n }\n get p0() {\n return this._p0;\n }\n\n @validate\n @Reflect.metadata(\"design:type\", Point)\n set p1(value: Point) {\n this._p1 = value;\n }\n get p1() {\n return this._p1;\n }\n}
\n","headings":[{"value":"Introduction","depth":2},{"value":"Decorators","depth":2},{"value":"Decorator Factories","depth":2},{"value":"Decorator Composition","depth":2},{"value":"Decorator Evaluation","depth":2},{"value":"Class Decorators","depth":2},{"value":"Method Decorators","depth":2},{"value":"Accessor Decorators","depth":2},{"value":"Property Decorators","depth":2},{"value":"Parameter Decorators","depth":2},{"value":"Metadata","depth":2}],"frontmatter":{"permalink":"/docs/handbook/decorators.html","title":"Decorators","disable_toc":null,"oneline":"TypeScript Decorators overview"}},"prev":null,"next":null},"pageContext":{"id":"decorators","slug":"/docs/handbook/decorators.html","repoPath":"/packages/documentation/copy/en/reference/Decorators.md","lang":"en","modifiedTime":"2020-08-07T17:00:36.339Z"}}}NOTE Decorator metadata is an experimental feature and may introduce breaking changes in future releases.
\n