How do decorators work in TypeScript?

A decorator runs when the decorated declaration is evaluated. It receives the declaration and a context object, and can return a replacement. Standard decorators are the ECMAScript proposal supported by TypeScript 5 and later. Legacy decorators, enabled with experimentalDecorators, use different signatures and are common in older frameworks.

function logged<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 {
    console.log("calling " + String(context.name));
    return method.apply(this, args);
  };
}

class Service {
  @logged
  run(task: string) {
    return "done: " + task;
  }
}

Standard versus legacy

• Standard decorators receive a context with kind, name, addInitializer and metadata
• Legacy decorators receive different arguments and often rely on emitDecoratorMetadata
• experimentalDecorators changes the signatures and cannot be combined casually with standard decorators
• Frameworks such as Angular and older NestJS versions rely on legacy decorator behavior
• Decorator metadata is emitted only when the relevant compiler options are enabled

Decorators are useful for cross-cutting concerns such as logging, dependency injection and validation. They are less useful for core business logic because they hide the call flow from a reader and can make debugging harder. Use them where a framework or a clearly repeated concern justifies them.