revision:
JavaScript decorators are a feature that allows you to annotate and modify classes, methods, properties, or even parameters in a declarative way.
They provide a way to add metadata or alter the behavior of certain elements in your code without directly modifying the original source code.
P. S. Decorators are an experimental feature and have been part of the ECMAScript proposal process for several years. As of now (2023), they are still in Stage 3 of the TC39 process, meaning they are not yet officially part of the JavaScript language standard but are widely used in frameworks like Angular and libraries like MobX.
JavaScript decorators allow to effectively add brand-new behaviors and features to pre-existing functions or classes. This makes scaling the existing features easier. Decorators wrap around the base code, which adds up to the original functionality of it.
A decorator is essentially a function that gets called with specific arguments depending on what it decorates (e.g., class, method, property). The decorator function can then return a new definition or modify the existing one.
A decorator is a way of wrapping one piece of code with another : literally "decorating" it, which is a concept similar to "functional composition" or "higher-order functions".
This concept is possible in JavaScript because of first-class functions — JavaScript functions that are treated as first-class citizens.
The concept of decorators is not new in JavaScript because higher-order functions are a form of function decorators.
The syntax for decorators involves using the @ symbol followed by the decorator name:
@decoratorName
class MyClass {
// ...
}
function doSomething(name) {
console.log('Hello, ' + name);
}
function loggingDecorator(wrapped) {
return function() {
console.log('Starting');
const result = wrapped.apply(this, arguments);
console.log('Finished');
return result;
}
}
const wrapped = loggingDecorator(doSomething);
Class Decorators : applied to classes.
Method Decorators : applied to methods within a class.
Property Decorators : applied to properties within a class.
Parameter Decorators : applied to parameters of methods or constructors.
To use decorators in JavaScript, you need to enable them via Babel or TypeScript since they are not natively supported in all environments yet.
Babel : use the @babel/plugin-proposal-decorators plugin.
TypeScript : enable the experimentalDecorators option in your tsconfig.json.
When a decorator is called, it receives two arguments : "value" and "context".
The value argument refers to the value being decorated but it is undefined if it is a class field.
The context refers to an object that contains metadata about the value being decorated.
Decorators support classes and public, private, and static class members such as methods, accessors, and class fields.
Example
function decorator (value, context) {
console.log("decorated value is:", value);
console.log("context is: ", context);
}
@decorator
class C {
@decorator // decorates a class field
p = 5;
@decorator // decorates a method
m() {}
@decorator // decorates a getter
get x() {}
@decorator // decorates a setter
set x(v) {}
}
class decorators are applied to the whole class, enabling us to decorate the class. The class decorator receives a class as the first argument. And it can optionally return a new class or replace the decorated class, but it throws an error if a nonconstructable value is returned.
Example
function log(value, { kind, name }) {
if (kind === "class") {
const newClass = class extends value {
constructor(...args) {
super(...args);
console.log(`constructing a class with arguments: ${args.join(", ")}`);
}
}
console.log(`An instance of the ${name} ${kind} has been created`)
return newClass;
}
}
@log
class Person {
constructor(name, profession) {
}
}
const stefan = new Person('Stefan Winters', "Developer");
These are binary functions applied to members of a class. The first argument, "value", refers to the member property of the class we are decorating. This makes possible a pattern where we can optionally return a new method or replace the decorated function. If we return a new method, it will replace the original on the prototype. But if it is a static method, it will replace it on the class itself. However, if we return any other type of value, an error will be thrown.
Example
class Person {
constructor(name, age, job) {
this.name = name;
this.age = age;
this.job = job;
}
@log
getBio() {
return `${this.name} is a ${this.age} years old ${this.job}`;
}
}
// creates a new person
let man = new Person("Stefan", 30, "developer");
man.getBio()
Function decorators are functions. They take a function as an argument and return a new function that enhances the function argument without modifying it.
Decorators use a special syntax in JavaScript, whereby they are prefixed with an "@" symbol and placed immediately "before the code" being decorated.
Example
@log
class ExampleClass {
doSomething() {
//
}
}
It's possible to use as many decorators on the same piece of code as you desire, and they'll be applied in the order that you declare them.
Also, class decorators come after "export" and "default", and it is possible to decorate both a "class declaration" and "class expression".