Decorators

A decorator changes part of a class

A decorator is a function that you put on part of a class with an @ sign, like @logged. JavaScript calls it once, while it builds the class. It does not wait until you use the class.

A decorator can do these jobs:

• Look at the part it sits on.
• Swap that part for a new version, such as a method that also prints a message.
• Ask for setup work to run each time a new object is made.
• Write notes, called metadata, that other code reads later.

Every decorator gets two inputs, (value, context):

• value is the part being decorated. It can be a method, a field, an auto-accessor, or the whole class. A field is a property written in the class body, like count = 0. You'll meet auto-accessors later in this lesson.
• context is an object that describes that part. It says the kind (such as "method"), the name, and whether the part is static or private. It also holds tools, such as addInitializer and metadata.

Many browsers can't read the @ syntax yet. So this lesson does two things:

• The code blocks show real decorator syntax. The lesson's tests compile that code with TypeScript and check what it prints.
• The live labs run a model: the same steps written as ordinary function calls. The model works in every browser.

A method decorator gets the original method as value. If it returns a new function, that new function takes the method's place. This helps with jobs that many methods share:

• printing a line on every call (this is called logging),
• measuring how long a call takes,
• remembering earlier results,
• trying again after a failure,
• checking that the user is allowed to do something.

The lab below uses two decorators:

• logged wraps the method. The wrapper prints a line, runs the real method, then prints the result.
• bound fixes a common problem. Say you save a method in a variable, like const click = counter.increment, and then call click(2). That call has no object in front of it, so this is lost. bound uses addInitializer to ask for setup work for each new object. The setup work calls .bind(), which makes a copy of the method whose this is always that object.

1function logged(value, context) {2  return function (...args) {3    console.log("call " + String(context.name));4    const result = value.apply(this, args);5    console.log("return " + result);6    return result;7  };8}9 10function bound(value, context) {11  context.addInitializer(function () {12    this[context.name] = this[context.name].bind(this);13  });14}15 16class Counter {17  count = 0;18 19  @logged20  @bound21  increment(step = 1) {22    this.count += step;23    return this.count;24  }25}26 27const counter = new Counter();28const click = counter.increment;29console.log(click(2));

1function logged(value, context) {2  return function (...args) {3    console.log("call " + String(context.name));4    const result = value.apply(this, args);5    console.log("return " + result);6    return result;7  };8}9 10function bound(value, context) {11  context.addInitializer(function () {12    this[context.name] = this[context.name].bind(this);13  });14}15 16const context = {17  kind: "method",18  name: "increment",19  static: false,20  private: false,21  access: {},22  metadata: {},23  addInitializer(initializer) {24    initializers.push(initializer);25  }26};27const initializers = [];28 29let increment = function (step = 1) {30  this.count += step;31  return this.count;32};33increment = bound(increment, context) ?? increment;34increment = logged(increment, context) ?? increment;35 36const counter = { count: 0, increment };37for (const initializer of initializers) initializer.call(counter);38const click = counter.increment;39console.log(click(2));

Try this. Leave saved copy on and turn bound off. The method runs without its object, so this is lost and you see an error. Turn bound back on. The setup work ties the method to the object before the saved copy is called, so it works again.

A decorator does not run each time you call the method. It runs once, while JavaScript builds the class. What it leaves behind is used later:

• A new method it returned runs on every call.
• Setup work it asked for runs each time new makes an object.

1function logged(value, context) {2  return function (...args) {3    console.log("call " + String(context.name));4    const result = value.apply(this, args);5    console.log("return " + result);6    return result;7  };8}9 10function bound(value, context) {11  context.addInitializer(function () {12    this[context.name] = this[context.name].bind(this);13  });14}15 16class Counter {17  count = 0;18 19  @loggedRun20  @bound21  increment(step = 1) {22    this.count += step;23    return this.count;24  }25}26 27const counter = new Counter();28const click = counter.increment;29console.log(click(2));

Pick swap a method to see logged return a wrapper. Pick change a field's start value to see a field decorator. It returns a small function. That function gets the field's starting value each time a new object is made, and returns the value to store.

A field decorator can change a field's starting value. For example, it can keep a number inside a range, or fill in a missing name. It runs once for each new object, when the object is made.

An auto-accessor is a field with the word accessor in front, like accessor nickname = "Ada". JavaScript keeps its value in a hidden place. It also adds a getter and a setter: small functions that run when you read or write the property. A decorator on an auto-accessor can return three functions:

• init changes the starting value.
• get runs on every read.
• set runs on every write, so it can check or clean each new value.

The lab below uses two helpers. .trim() removes spaces from the start and end of a string. Math.min and Math.max keep a number between 0 and 100.

1function clamp(value, context) {2  return function (initialValue) {3    return Math.min(100, Math.max(0, initialValue));4  };5}6 7function trimBox(value, context) {8  return {9    init(initialValue) {10      return initialValue.trim();11    },12    get() {13      return value.get.call(this);14    },15    set(nextValue) {16      value.set.call(this, nextValue.trim());17    }18  };19}20 21class Profile {22  @clamp23  percent = 135;24 25  @trimBox26  accessor nickname = "  Ada  ";27}28 29const profile = new Profile();30console.log(profile.percent);31console.log(profile.nickname);32profile.nickname = "  Grace  ";33console.log(profile.nickname);

1const metadata = {};2const percentContext = {3  kind: "field", name: "percent", static: false, private: false,4  access: {}, metadata, addInitializer() {}5};6const nicknameContext = {7  kind: "accessor", name: "nickname", static: false, private: false,8  access: {}, metadata, addInitializer() {}9};10 11const clampInit = clamp(undefined, percentContext);12const wrapped = trimBox({13  get() { return this._nickname; },14  set(value) { this._nickname = value; }15}, nicknameContext);16 17const profile = {};18profile.percent = clampInit(135);19profile._nickname = wrapped.init("  Ada  ");20Object.defineProperty(profile, "nickname", {21  get() { return wrapped.get.call(profile); },22  set(value) { wrapped.set.call(profile, value); }23});24console.log(profile.percent);25console.log(profile.nickname);26profile.nickname = "  Grace  ";27console.log(profile.nickname);

function nonEmpty(value, context) {
  return function (initialValue) {
    if (initialValue.trim() === "") throw new Error("name is required");
    return initialValue.trim();
  };
}

const name = nonEmpty(undefined, { kind: "field", name: "name" })("  Asha  ");
console.log(name);

nonEmpty returns a function for the starting value. That function removes the spaces around the name, so line 9 prints Asha. If the name were empty, it would throw an error instead.

A field decorator only sees the starting value. It can't see later writes to a plain field. If later writes need checking too, use an auto-accessor.

Sometimes a decorator doesn't need to wrap anything. It only writes down a fact. For example: “this method saves data”, “this field is required”, or “this class handles the home page”. Facts like these are called metadata: data about the code.

Every decorator on the same class gets the same notes object, context.metadata. After the class is built, other code reads that object from the class with Task[Symbol.metadata]. Symbol.metadata is a symbol: a special key that can't clash with any other property name.

Metadata comes from its own, separate proposal. So Symbol.metadata may not exist yet. Line 1 of the metadata code below creates it when it is missing.

1if (!Symbol.metadata) Symbol.metadata = Symbol("Symbol.metadata");2 3function label(text) {4  return function (value, context) {5    context.metadata[context.name] = text;6  };7}8 9class Task {10  @label("Saves draft data")11  save() {}12}13 14console.log(Task[Symbol.metadata].save);

1const metadataKey = Symbol.metadata ?? Symbol("Symbol.metadata");2const metadata = {};3const context = {4  kind: "method",5  name: "save",6  static: false,7  private: false,8  access: {},9  metadata,10  addInitializer() {}11};12 13label("Saves draft data")(function save() {}, context);14class Task {}15Task[metadataKey] = metadata;16 17console.log(Task[metadataKey].save);

Decorators are a proposal: a planned feature that TC39, the group that designs JavaScript, is still working on. When this lesson was written, you couldn't count on browsers or Node.js to read the @ syntax. For example, Node 22 rejected a normal script that used it.

So most projects compile decorators. A tool rewrites your code into plain JavaScript that every engine can read. Two common tools:

• TypeScript compiles the decorator syntax used in this lesson. Be careful: TypeScript also has an older mode called experimentalDecorators. That mode passes different inputs, (target, key, descriptor), and many older libraries still use it.
• Babel compiles decorators through a plugin. The plugin version must match the one your project and its libraries expect.

The check below hands a tiny decorator script to new Function. new Function turns a string of code into a function without calling it. If the browser can't read the syntax, it throws a SyntaxError.

1const code = "function dec(value, context) {}\n@dec class C {}";2new Function(code); // parse test only

Each row of the next table is one place your code might run. Read across to see what to expect there.

Ask what you need to change:

• The whole class? Use a class decorator. It gets the class itself as value.
• A method you call? Use a method decorator.
• A field's starting value? Use a field decorator.
• Every read and write of a property? Use an auto-accessor decorator.

Where you will use decorators

Decorators help most when the same extra job shows up in many places. You write the job once and put it on each place with @. The method itself stays short. Common uses:

• UI classes bind methods once, so callbacks don't lose this. (A callback is a function you hand to other code to call later.)
• Data classes trim or limit values before they store them.
• Frameworks collect notes about pages or checks while the class is built.
• Libraries remember the results of slow methods, without changing the method's code.

These ideas build on earlier lessons: class basics, private members, getters and setters, closures, and higher-order functions.

function describe(value, context) {
  return function (...args) {
    console.log(context.name + " called");
    return value(...args);
  };
}

const save = describe((order) => "saved " + order, {
  kind: "method",
  name: "save",
});
console.log(save("tea"));
console.log(typeof save.extra);

The wrapper changes how save runs: it prints save called before line 12 prints saved tea. It doesn't add anything new. So on line 13, typeof save.extra is "undefined".

A decorator can only do these things to the part it sits on:

• swap it for a new one of the same kind, such as a new method for a method,
• ask for setup work,
• write metadata.

It can't add new methods to the class or change its other parts.

Common misconceptions

Each row of the table is one kind of decorator, or the metadata tool. Read across to see what the decorator gets, what it may return, and when its work takes effect.

• “Decorators are just comments.” They are functions, and they can change how the class works.
• “Every browser runs them today.” Compile your code first, or test whether the browser can read the syntax.
• “Old TypeScript decorators are the same thing.” The older experimentalDecorators mode passes (target, key, descriptor), a different set of inputs.
• “A field decorator sees the field’s value right away.” It gets undefined. It returns a function, and that function sees each object’s starting value later.
• “A method can be bound before any object exists.” .bind() needs an object. So a binding decorator uses addInitializer, whose work runs when each object is made.
• “Metadata is filled in for you.” Each decorator decides what to write. Some engines also need Symbol.metadata created first.

Key takeaways

• A decorator is a function that JavaScript calls once, while it builds the class.
• Each decorator gets (value, context). TypeScript's older mode passed (target, key, descriptor) instead.
• A method decorator can return a new function to use instead of the method. A field decorator can return a function that changes the starting value.
• An auto-accessor decorator can change the starting value, every read, and every write.
• Metadata comes from a separate proposal. It may need Symbol.metadata to be created first.
• Compile decorator code, or test for support, before you ship it.

A decorator is a function that runs while a class is built. It can wrap, set up, or add notes to the class or one of its parts.

Up next: eval & new Function.