> ## 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 Field Decorator
A field decorator is a higher-order function applied to a class field that intercepts its definition, allowing developers to modify the field's initialization logic or interact with its evaluation context. Under the ECMAScript Stage 3 Decorators specification, field decorators cannot alter the property descriptor of a field and do not return a descriptor object. To alter a descriptor (such as making a property read-only or converting it to a getter/setter), developers must instead apply a decorator to an auto-accessor field defined with the `accessor` keyword. While the only way a field decorator can directly modify the field itself is by returning a new initializer function, it can still execute side effects or register metadata using the provided context object.
```javascript theme={"dark"}
function fieldDecorator(value, context) {
// Returns a new initializer function
return function(initialValue) {
return initialValue * 2;
};
}
class TargetClass {
@fieldDecorator
targetField = 10;
}
```
## Decorator Signature
A field decorator receives two arguments from the JavaScript engine: `value` and `context`.
### 1. `value`
For field decorators, the `value` argument is always `undefined`. This is because class fields do not possess a concrete value at the time of class definition; they only possess an initializer expression that evaluates later during instantiation.
### 2. `context`
The `context` object provides metadata about the decorated field and utilities for modifying class behavior. For a field decorator, the `context` object contains:
* **`kind`**: A string literal strictly set to `"field"`.
* **`name`**: A string or symbol representing the identifier of the field.
* **`static`**: A boolean indicating whether the field is attached to the class constructor (`true`) or directly to the individual object instance (`false`).
* **`private`**: A boolean indicating whether the field uses private syntax (`#`).
* **`access`**: An object containing `get(instance)` and `set(instance, value)` methods. Unlike parameterless getters and setters, these methods require the target class instance to be passed as an argument to read or write the field's value.
* **`addInitializer(fn)`**: A method that accepts a callback function. For instance fields, this callback executes inside the constructor during instantiation. For static fields, it executes during class evaluation.
* **`metadata`**: A plain JavaScript object shared across all decorators applied to the class and its members. This property is not part of the core Decorators specification; it is defined by the separate Stage 3 `proposal-decorator-metadata` specification, which extends the context object to provide a standard mechanism for storing and retrieving decorator-defined metadata.
## Return Value and Initialization Mechanics
A field decorator can optionally return a function. If a function is returned, it completely replaces the field's original initializer.
```javascript theme={"dark"}
function replaceInitializer(value, context) {
return function(originalValue) {
// 'this' refers to the class instance being constructed
// 'originalValue' is the result of the right-hand side of the field assignment
return typeof originalValue === 'string' ? originalValue.trim() : originalValue;
};
}
```
**Execution Flow:**
1. **Class Definition Phase:** The decorator function is invoked. It receives `undefined` and the `context` object. It returns the new initializer function.
2. **Instantiation Phase:** When `new TargetClass()` is called, the engine evaluates the original right-hand expression of the field.
3. **Mutation Phase:** The engine invokes the function returned by the decorator, passing the evaluated original value as the argument. The return value of this function becomes the final value assigned to the field on the instance.
Tired of Poor JavaScript Skills? Fix That With Deep Grasping!
Learn More
