JS Metaprogramming: Advanced Architecture Guide

Metaprogramming is writing code that treats other code, or the structure of an object, as data it can inspect and change at runtime. Instead of hardcoding what a property does, metaprogramming lets you define how property access, iteration, or type conversion behaves for an entire class of objects at once.

JavaScript exposes this through four connected tools: Proxy, Reflect, well-known symbols, and property descriptors. Each one intercepts or customizes a different part of how objects normally behave, starting with the class below that controls its own conversion to a string and a number:

javascript

class Temperature {
  #celsius;
  constructor(celsius) {
    this.#celsius = celsius;
  }
 
  [Symbol.toPrimitive](hint) {
    if (hint === "string") return `${this.#celsius}°C`;
    return this.#celsius;
  }
}
 
const temp = new Temperature(22);
console.log(`Current temp: ${temp}`);
console.log(temp + 10);
// Current temp: 22°C
// 32

Symbol.toPrimitive is a well-known symbol that JavaScript checks automatically during string interpolation and arithmetic. Defining it lets a plain class control exactly how it converts to a string or a number, which is one small example of metaprogramming: changing how a built-in language operation behaves for a specific type.

The Four Tools and What Each One Controls

Each branch solves a different problem. Proxy and Reflect work as a pair around intercepting operations. Symbols and property descriptors work independently, changing how a single object behaves without needing a wrapper around it at all.

Proxy: Intercepting Operations

A Proxy wraps a target object and lets you run custom code whenever something reads, writes, deletes, or otherwise interacts with it, such as the logger below that reports every change before applying it:

javascript

const settings = { theme: "dark" };
 
const loggedSettings = new Proxy(settings, {
  set(target, prop, value) {
    console.log(`Changing ${prop} to ${value}`);
    target[prop] = value;
    return true;
  },
});
 
loggedSettings.theme = "light";
// Changing theme to light

This example only scratches the surface. Proxy has thirteen traps covering nearly every operation an object supports, including function calls and construction. For the full trap list with real use cases like validation and access control, see advanced JavaScript proxies.

Reflect: The Default Behavior Behind Every Trap

Reflect is the companion object that performs the exact default action a Proxy trap would otherwise replace, such as reading a property or removing one, as shown in the trap below that logs a deletion before letting it happen:

javascript

const handler = {
  deleteProperty(target, prop) {
    console.log(`Deleting ${prop}`);
    return Reflect.deleteProperty(target, prop);
  },
};

Reflect matters because writing the default behavior by hand misses details that matter once inheritance is involved, such as correctly binding this inside getters and setters. For the full method reference, see the JavaScript Reflect API.

Well-Known Symbols: Customizing Built-In Behavior

A well-known symbol is a special, predefined value that JavaScript itself checks during a built-in operation. Symbol.iterator is the most common one, and defining it on a plain object, as shown below, lets that object work in a for...of loop:

javascript

const range = {
  from: 1,
  to: 3,
  [Symbol.iterator]() {
    let current = this.from;
    return {
      next: () =>
        current <= this.to
          ? { value: current++, done: false }
          : { value: undefined, done: true },
    };
  },
};
 
for (const number of range) console.log(number);
// 1
// 2
// 3

The range object above is a plain object, not an array, but defining that one symbol makes iteration work on it directly. Other well-known symbols include the string and number conversion hook shown earlier, and one that customizes what the instanceof operator checks. For a deeper look at symbols as values, see the JavaScript Symbol type.

Property Descriptors: Controlling Properties Individually

A property descriptor sets metadata on a single property, independent of its value, controlling whether it can be changed, listed, or reconfigured later:

javascript

const product = {};
 
Object.defineProperty(product, "id", {
  value: "SKU-2201",
  writable: false,
  enumerable: false,
});
 
product.id = "SKU-9999";
console.log(product.id);
console.log(Object.keys(product));
// SKU-2201
// []

The assignment silently fails because the property was marked non-writable, and the key listing skips it entirely because it was marked non-enumerable. This is a narrower, per-property form of metaprogramming compared to Proxy, since it changes one property's rules rather than intercepting every operation on the whole object.

Choosing the Right Tool

When to Avoid Metaprogramming

These tools add a layer of indirection between a simple line of code and what actually happens when it runs. That trade-off is worth it inside a validation library, an ORM, or a reactive state system, where the same generic behavior needs to apply across many different objects. For regular application code, like handling a form submission or rendering a list, plain objects, functions, and classes are almost always clearer and easier to debug.