Skip to main content

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.

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. 
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. 
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.
Master JavaScript with Deep Grasping Methodology!Learn More