Method Decorator

A method decorator is a higher-order function applied to a class method declaration that intercepts and potentially modifies the method’s definition, behavior, or metadata before the class is fully initialized. Evaluated at class definition time, a method decorator allows developers to wrap, replace, or augment the method’s execution logic.

ECMAScript Stage 3 Proposal Mechanics

In the ECMAScript Stage 3 decorators proposal, a method decorator is a function that receives two arguments: the original method and a context object.

function methodDecorator(value, context) {
  // 'value' is the original method being decorated
  
  // Return a new function to replace the original method
  return function(...args) {
    // Pre-execution logic
    const result = value.apply(this, args);
    // Post-execution logic
    return result;
  };
}

class ExampleClass {
  @methodDecorator
  executeTask(payload) {
    return payload;
  }
}

The value Parameter

For method decorators, the value parameter is strictly the function reference of the method being decorated.

The context Parameter

The context object provides metadata about the method being decorated and utilities for initialization. For a method decorator, the context object contains:

• kind: A string literal strictly set to "method".
• name: The string or symbol representing the method’s name.
• static: A boolean indicating whether the method is a static class method (true) or a prototype method (false).
• private: A boolean indicating whether the method is a private class member (e.g., #myMethod).
• access: An object containing a get(object) method, which retrieves the method from the specified instance, and a has(object) method, which returns a boolean indicating whether the method exists on a given instance.
• addInitializer: A function that accepts a callback. The callback is executed during the class instantiation process (for prototype methods) or class definition process (for static methods), allowing for binding or setup logic.

Return Value Behavior

• Returning a Function: If the decorator returns a function, this new function completely replaces the original method on the class prototype (or constructor, if static).
• Returning undefined: If the decorator returns undefined (or lacks a return statement), the original method remains unmodified.
• Returning other types: Returning any non-callable object (other than undefined) throws a TypeError.

Legacy (TypeScript / Babel) Mechanics

Many existing codebases use the legacy “experimental” decorator implementation (e.g., TypeScript’s experimentalDecorators: true). The mechanics and signature differ significantly from the Stage 3 proposal.

function legacyMethodDecorator(target, propertyKey, descriptor) {
  const originalMethod = descriptor.value;

  // Return a completely new PropertyDescriptor object
  return {
    ...descriptor,
    value: function(...args) {
      return originalMethod.apply(this, args);
    }
  };
}

In the legacy implementation, the decorator receives three arguments:

1. target: The prototype of the class for an instance method, or the constructor function for a static method.
2. propertyKey: The name of the method (string or symbol).
3. descriptor: The PropertyDescriptor object for the method (identical to the object returned by Object.getOwnPropertyDescriptor).

To modify the method in the legacy implementation, the decorator can return a completely new PropertyDescriptor object. Alternatively, it can mutate the provided descriptor object directly; if it does so, it may return undefined, and the transpiler will still utilize the mutated original descriptor.

Because legacy decorators are a transpiler feature rather than a native JavaScript engine feature, the engine does not handle the decorator directly. Instead, the transpiler-emitted code is responsible for taking the resulting descriptor (whether new or mutated) and passing it to Object.defineProperty to configure the method on the target object.

Master JavaScript with Deep Grasping Methodology!

Learn More