Decorators

Decorators are class finishing tools

A decorator is a function that receives part of a class while the class is being defined. It can look at the part, wrap it, replace it, register setup work, or attach metadata for other code to read later.

The current proposal-style shape is (value, context). value is the method, field, auto-accessor, or class piece being decorated. context is a label and toolbox: it tells the decorator the kind, name, whether the member is static or private, and exposes tools such as addInitializer and metadata.

This lesson keeps the runnable demos in plain JavaScript. The code blocks show decorator syntax, and the tests compile that syntax with TypeScript, but the live labs run a desugared model made from ordinary function calls. That keeps the page honest in browsers that cannot parse decorator syntax yet.

A method decorator receives the original function. If it returns a new function, that new function becomes the method. That is perfect for logging, timing, memoizing, retrying, or checking permissions.

The lab below shows two common decorators. logged wraps a method so it prints before and after the real call. bound registers an initializer so each instance binds its method once, which matters when a method is detached from its 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 turning bound off while the detached call is on. The method is called without its object, so this is lost. Turn bound back on and the initializer fixes the instance before the detached call happens.

Decorators are not called each time you call a method. They run while the class is being defined. The replacement method they return, or the initializer they register, affects what happens later.

1function logged(value, context) {Run2  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));

In the method version, the decorator returns a wrapper function. In the field version, the decorator returns an initializer transform. The transform receives the field’s starting value every time a new instance is created.

A field decorator is great when you only need to transform the initial value. A number can be clamped as an instance is created, or a missing string can be replaced with a default.

An auto-accessor creates a hidden storage slot with a public getter and setter door. A decorator can wrap the door: transform the starting value with init, change reads with get, and guard writes with set.

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);

Sometimes a decorator does not need to wrap anything. It just records facts: “this method saves data,” “this field is required,” or “this class handles this route.” That is metadata.

The metadata proposal gives every decorator on the same class a shared context.metadata object. After the class is defined, code can read that object from the class through Symbol.metadata. Because metadata is a separate proposal, compiled examples may need a small Symbol.metadata fallback.

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);

At the time of writing, treat decorators as syntax you compile, not syntax every JavaScript engine will parse directly. I checked the TC39 proposal materials, the decorator-metadata README, and Node 22. Node 22 rejected a normal script containing decorator syntax.

TypeScript can compile the proposal-style syntax used in the examples in this lesson. That is different from TypeScript’s older experimentalDecorators mode, which used the legacy (target, key, descriptor) shape. Babel can also compile decorators, but you must choose a plugin/version that matches your codebase.

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

Ask what you need to change. Do you need the whole class, a callable method, a starting field value, or a property door that sees future reads and writes?

Where you will use decorators

Decorators shine when a cross-cutting behavior appears in many places: logging every command method, binding event handlers, validating values, annotating routes, or describing fields for serialization. They keep the core method small while the reusable wrapper handles the repeated concern.

• UI classes can bind methods once so callbacks do not lose this.
• Models can clamp or normalize incoming data before storing it.
• Frameworks can collect route or validation metadata at class definition time.
• Libraries can memoize expensive methods without rewriting the method body.

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

Common misconceptions

• “Decorators are just comments.” They are functions that can change behavior.
• “Every engine runs them today.” Compile or feature-detect; do not assume native parsing.
• “Old TypeScript decorators are the same thing.” Legacy decorators use a different call shape.
• “A field decorator sees the field’s value immediately.” It returns an initializer that sees each instance’s value later.
• “Binding can happen before instances exist.” Binding needs addInitializer because each instance has its own method value.
• “Metadata is automatic reflection.” Decorators must choose what to write, and metadata support may need a fallback.

Key takeaways

• Decorators are functions called while a class is being defined.
• Proposal-style decorators receive (value, context), not the older legacy TypeScript descriptor shape.
• Methods may return replacement functions; fields may return initializer transforms.
• Auto-accessors let decorators wrap initial value setup, reads, and writes.
• Metadata is separate and may require Symbol.metadata support.
• Compile or feature-detect before shipping decorator syntax.

A decorator is a class-definition-time function that can wrap, initialize, or annotate a class or class element.

Up next: eval & new Function.