How are Stage 3 decorators different from the old experimental ones?

The legacy TypeScript and Babel decorators received a property descriptor and could mutate it directly. The Stage 3 decorators instead receive the value being decorated plus a structured context object, and they wire up behaviour by returning a replacement value or calling context.addInitializer. The shapes are not compatible.

What is on the decorator context object?

Every decorator gets a context with kind ('class', 'method', 'getter', 'setter', 'accessor', or 'field'), name (string or symbol), static (boolean), private (boolean), an addInitializer function, and for class members access objects with get and/or set to reach the value at runtime.

What can a method decorator return?

A method decorator receives the original function and may return a new function to replace it, or return nothing to keep the original. Whatever it returns becomes the method installed on the prototype (or the class for a static method).

How does a field decorator work?

A field decorator receives undefined as its value and may return an initializer function. That function runs when each instance is created, receives the field's initial value as its argument, and its return value becomes the stored field value, letting you transform or wrap the initial value.

What does addInitializer do?

context.addInitializer(fn) registers a callback that runs during construction (for instance members) or during class definition (for the class and static members), with this bound to the instance or class. It is how you run setup logic such as binding a method or registering metadata.

TC39 Decorators Reference

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

What TC39 decorators are

Decorators are a Stage 3 JavaScript proposal for annotating and modifying classes and their members with reusable @decorator syntax. Unlike the older experimental decorators that mutated a property descriptor, the modern proposal hands each decorator the value being decorated plus a structured context object, and you opt into behaviour by returning a replacement value or calling context.addInitializer. This makes decorators predictable and composable.

How it works

A decorator is a function called once, at class-definition time, with two arguments: (value, context). The value depends on the target — a function for methods, the class itself for class decorators, undefined for fields — and the context always carries kind, name, static, private, and an addInitializer hook (plus an access object for members). What you may return also depends on the target:

function logged(value, context) {
  if (context.kind === "method") {
    return function (...args) {
      console.log(`calling ${String(context.name)}`);
      return value.apply(this, args);
    };
  }
}

The reference below lists each target with the value it receives, the relevant context fields, and the legal return values.

Tips and notes

Decorators evaluate outermost-last: in @a @b method(), b is applied before a, and a wraps b’s result. Field decorators return an initializer (value transformer), not a replacement value. The accessor keyword creates an auto-accessor whose decorator returns an object with get, set, and/or init. Use addInitializer for side-effects like method binding or metadata registration — that is the only place this refers to the instance.