TypeScript Decorators: Method, Class, Field and Accessor

A decorator is a function you attach to a class or a class member with @name. It receives the original method (or class, or field) plus a context object describing it, and it can return a replacement. TypeScript supports the standard decorators with no compiler flag.

function logged<This, Args extends unknown[], Return>(
    method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    const name = String(context.name);
    return function (this: This, ...args: Args): Return {
        console.log(`-> ${name}(${args.join(", ")})`);
        const result = method.call(this, ...args);
        console.log(`<- ${name} = ${result}`);
        return result;
    };
}

class Calculator {
    @logged
    add(a: number, b: number): number {
        return a + b;
    }
}

new Calculator().add(2, 3);
// -> add(2, 3)
// <- add = 5

@logged runs once, when the class is defined, and replaces add with the wrapper it returns. Every call goes through the wrapper. The generic parameters keep the method's this, argument and return types intact, so add still takes two numbers and returns a number.

How Decorators Compile

Standard decorators come from a TC39 proposal for JavaScript, and TypeScript has implemented them since TypeScript 5.0. The proposal is not part of the JavaScript standard yet, and Node 24 does not parse the @ syntax, so when the target is ES2022 (as on these pages) the compiler rewrites each decorated class into plain JavaScript that calls helper functions (__esDecorate and __runInitializers, emitted at the top of the file). The output runs anywhere ES2022 runs.

One consequence: a file with decorators cannot run under Node's built-in type stripping (node file.ts), which only removes types and leaves the @ in place. Node stops with SyntaxError: Invalid or unexpected token. Compile it with tsc or a bundler first.

Decorator Kinds and Their Signatures

Every standard decorator has the shape (value, context) => replacement | void. What value is, and what you may return, depends on what is decorated:

Every context object has kind, name and addInitializer. A class member's context also has static, private and an access object for reading the member from an instance. Decorators work on static and #private members too.

Decorator Factories

To pass options, write a function that returns a decorator and call it at the @ site. This is a decorator factory:

function retry(times: number) {
    return function <This, Args extends unknown[], Return>(
        method: (this: This, ...args: Args) => Return,
        _context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
    ) {
        return function (this: This, ...args: Args): Return {
            for (let attempt = 1; ; attempt++) {
                try {
                    return method.call(this, ...args);
                } catch (e) {
                    if (attempt >= times) throw e;
                    console.log(`attempt ${attempt} failed, retrying`);
                }
            }
        };
    };
}

class Client {
    calls = 0;

    @retry(3)
    fetchData(): string {
        this.calls++;
        if (this.calls < 3) throw new Error("flaky");
        return `ok after ${this.calls} calls`;
    }
}

console.log(new Client().fetchData());

@retry(3) calls retry first, and the function it returns is the actual decorator. Multiple decorators stack: in @a @b method(), b is applied first and a wraps the result.

Class Decorators and addInitializer

A class decorator receives the class itself. It can return a subclass to replace it, or return nothing and just record it somewhere. context.addInitializer registers code to run at a specific moment: for a class decorator, right after the class is fully defined; for a method decorator, when each instance is constructed.

const registry = new Map<string, new () => object>();

function register(id: string) {
    return function <T extends new () => object>(target: T, context: ClassDecoratorContext<T>) {
        context.addInitializer(() => {
            registry.set(id, target);
        });
    };
}

// Binds a method to its instance, so it survives being passed as a callback.
function bound<This, Args extends unknown[], Return>(
    _method: (this: This, ...args: Args) => Return,
    context: ClassMethodDecoratorContext<This, (this: This, ...args: Args) => Return>,
) {
    context.addInitializer(function (this: This) {
        const self = this as Record<string | symbol, unknown>;
        const fn = self[context.name] as (...a: unknown[]) => unknown;
        self[context.name] = fn.bind(this);
    });
}

@register("greeter")
class Greeter {
    name = "Ada";

    @bound
    greet(): string {
        return `Hello, ${this.name}`;
    }
}

const g = new Greeter();
const loose = g.greet; // detached from g
console.log(loose());  // Hello, Ada
console.log([...registry.keys()], registry.get("greeter") === Greeter); // [ 'greeter' ] true

The class decorator goes above the class (or after export). Without @bound, calling loose() would throw, because this would be undefined.

Field and Accessor Decorators

A field decorator cannot see or intercept later assignments: its value is undefined, and all it can return is a function that transforms the field's initial value. To intercept reads and writes, declare the field with the accessor keyword, which turns it into a getter and setter pair backed by private storage, and decorate that:

function trimmed(_value: undefined, _context: ClassFieldDecoratorContext<unknown, string>) {
    return (initial: string) => initial.trim();
}

function positive<This>(
    target: ClassAccessorDecoratorTarget<This, number>,
    context: ClassAccessorDecoratorContext<This, number>,
): ClassAccessorDecoratorResult<This, number> {
    const check = (v: number) => {
        if (v <= 0) throw new RangeError(`${String(context.name)} must be positive, got ${v}`);
        return v;
    };
    return {
        init: check, // runs on the initial value
        set(v) {
            target.set.call(this, check(v));
        },
    };
}

class Product {
    @trimmed title = "  Lamp  ";
    @positive accessor price = 30;
}

const p = new Product();
console.log(`[${p.title}]`, p.price); // [Lamp] 30
p.price = 45;
console.log(p.price); // 45
try {
    p.price = -5;
} catch (e) {
    if (e instanceof Error) console.log(e.message); // price must be positive, got -5
}

accessor is part of the same proposal. It emits a real getter and setter over a #private field, which is why p.price = -5 goes through the decorator's set.

Standard vs Legacy experimentalDecorators

Before TypeScript 5.0, the only decorators TypeScript had were an early version of the proposal, enabled with experimentalDecorators. That flag still exists, and it switches the compiler to the legacy model, with different signatures and semantics:

A decorator written for one model does not type-check in the other. Here is a legacy-style decorator in a project without the flag:

// This does not compile: a legacy decorator used as a standard one.
function log(target: object, key: string, descriptor: PropertyDescriptor) {
    const original = descriptor.value;
    descriptor.value = function (this: unknown, ...args: unknown[]) {
        console.log("calling", key);
        return original.apply(this, args);
    };
}

class Service {
    @log
    run(): string {
        return "done";
    }
}

console.log(new Service().run());

index.ts(11,5): error TS1241: Unable to resolve signature of method decorator when called as an expression.
  The runtime will invoke the decorator with 2 arguments, but the decorator expects 3.

The fix is either to rewrite it in the standard (value, context) form, as in the first example on this page, or to turn on the legacy model for the whole project:

{
    "compilerOptions": {
        "experimentalDecorators": true,
        "emitDecoratorMetadata": true
    }
}

Angular, NestJS and TypeORM still set experimentalDecorators in the configs their tools generate and their docs ask for. NestJS and TypeORM also need emitDecoratorMetadata, because they read types at runtime: NestJS to inject constructor parameters, TypeORM to map properties to columns:

// Legacy model: needs experimentalDecorators (and emitDecoratorMetadata for DI).
@Injectable()
class UsersService {
    constructor(@Inject(DB) private db: Database) {}
}

If you use one of those frameworks, write decorators the legacy way and follow its docs. For new code with no such framework, use the standard decorators.

When to Use Decorators

Decorators fit cross-cutting behavior that would otherwise be repeated in many methods: logging, timing, caching, retries, access checks, validation, and registering classes with a container or router. They also hide control flow, since a reader has to look up what @retry does before knowing what the method does. For one or two uses, a plain higher-order function (const fetchData = retry(3, rawFetch)) is simpler and works outside classes too.