> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# JavaScript 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.
```javascript theme={"dark"}
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.
```javascript theme={"dark"}
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.
Tired of Poor JavaScript Skills? Fix That With Deep Grasping!
Learn More
