Proxy and Reflect

What it is and why it exists

Proxy creates a wrapper object through which you can observe or redefine fundamental operations on a target. Property reads, assignments, in, delete, key enumeration, function calls, and construction each have a corresponding proxy trap . Callers keep using ordinary JavaScript syntax instead of switching to a special interface such as get("name").

Reflect is a collection of static methods, not a constructor. It exposes fundamental operations as functions such as Reflect.get(), Reflect.set(), and Reflect.ownKeys(), and all 13 interceptable operations have a same-named trap. When a handler changes only a small part of the behavior, a Reflect call clearly says that everything else should retain the language’s default semantics.

These APIs fit access observation, write validation, virtual properties, revocable views, and the low-level machinery behind reactive systems or object membranes. They solve the problem of intervening in language operations while preserving ordinary object syntax. They aren’t the default abstraction for every business object.

A proxy isn’t a copy of its target. A successful write through the proxy usually changes the target, and another target alias bypasses the handler, yet proxy and target have different object identities. Hiding underscore-prefixed properties or rejecting one read can enforce an interface convention, but it can’t turn a still-reachable target into a secure vault.

How it works

new Proxy(target, handler) requires both target and handler to be objects. When JavaScript performs an internal object operation on the proxy, the proxy looks up the corresponding trap; if it doesn’t exist, the operation forwards to the target. A non-callable trap or a result that violates a language invariant makes the operation throw TypeError.

A property read with default forwarding follows this sequence:

1. The expression proxy[key] starts the proxy’s internal [[Get]] operation.
2. The proxy looks up the handler’s get trap.
3. get(target, key, receiver) receives the target, property key, and original receiver.
4. The trap calls Reflect.get(target, key, receiver) to perform ordinary read semantics.
5. The engine checks any invariants that constrain the trap result, then returns it to the caller.

Trap arguments are defined by the intercepted language operation; they aren’t arbitrary callback signatures. Here is the full mapping. Operations involving a property descriptor are especially easy to confuse with assignment.

The receiver is the object that originally received the operation. It may be the proxy or an object inheriting from the proxy. Reflect.get(target, key, receiver) makes that receiver the this value inside an accessor; writing target[key] instead fixes the accessor’s this to the target. The receiver passed to Reflect.set() likewise matters for inherited setters and for which object ultimately receives a defined property.

Reflect doesn’t automatically make an operation safe, nor does it bypass other proxies. If the target is itself a proxy, Reflect.get() may still invoke its trap; if the target property is a getter, the read still executes it. A handler should call the corresponding method on target, not repeat the same reflective operation on receiver, which can recurse into the current trap.

Policies usually span several traps. Validation in set doesn’t intercept Object.defineProperty(proxy, key, descriptor), and hiding a name in get doesn’t automatically affect in, key enumeration, or descriptor queries. Inventory every operation callers can perform, then decide which ones forward, reject, or need mutually consistent answers.

Examples

These four examples build from default forwarding to receiver, a consistent virtual property, and revocation. Every output shown below came from running its file locally with Node 24.

Validate writes and preserve ordinary reads

The first handler adds a log to reads and validates writes for fields with declared rules. A property key may be a Symbol, so the log calls String(key) instead of interpolating the key directly into a template literal.

Reflect.set() returns a Boolean, which exactly matches the set trap’s return contract. If it returns false, ordinary assignment in strict mode throws TypeError; a handler shouldn’t hide that failure by always returning true. This example promises validation only for ordinary assignment and doesn’t yet cover the property-definition path.

The rules object also has a prototype, so generic library code shouldn’t assume every arbitrary key is safe to use as an index. Object.hasOwn(rules, key), a null-prototype dictionary, or a Map can make the rule set explicit. Here, both data and rules come from the same trusted code, keeping the example focused on trap forwarding.

Preserve the accessor receiver

The two proxies differ only in whether they forward receiver. A child object inherits the getter through the proxy, so that difference changes which properties its this value sees.

const account = {
  owner: "base",
  currency: "USD",
  get label() {
    return `${this.owner}:${this.currency}`;
  },
};

const badProxy = new Proxy(account, {
  get(target, key) {
    return Reflect.get(target, key, target);
  },
});

const goodProxy = new Proxy(account, {
  get(target, key, receiver) {
    return Reflect.get(target, key, receiver);
  },
});

const badChild = Object.create(badProxy);
badChild.owner = "Mina";
badChild.currency = "EUR";

const goodChild = Object.create(goodProxy);
goodChild.owner = "Mina";
goodChild.currency = "EUR";

console.log(badChild.label);
console.log(goodChild.label);

base:USD
Mina:EUR

badProxy explicitly uses target as the receiver, so the getter reads fields from the base object. goodProxy preserves the original goodChild, and the getter reads that child’s own fields. Tests that only evaluate proxy.label don’t expose this bug; include an inheritance or accessor case.

There is no set trap here, but assigning to either child still forwards through the proxy prototype’s default [[Set]] and eventually creates an own property on the child. If the handler adds a set trap, its Reflect.set() call should still receive the original receiver.

Make a virtual property reflect consistently

Implementing only get makes invoice.total readable while "total" in invoice and Object.keys(invoice) deny that it exists. This handler defines the read, existence, key-list, and descriptor operations together so common observation paths agree.

function withTotal(invoice) {
  const totalKey = "total";
  if (Reflect.has(invoice, totalKey)) {
    throw new TypeError("total already exists");
  }

  return new Proxy(invoice, {
    get(target, key, receiver) {
      if (key === totalKey) {
        return receiver.quantity * receiver.unitPrice;
      }
      return Reflect.get(target, key, receiver);
    },
    has(target, key) {
      return key === totalKey || Reflect.has(target, key);
    },
    ownKeys(target) {
      return [...Reflect.ownKeys(target), totalKey];
    },
    getOwnPropertyDescriptor(target, key) {
      if (key === totalKey) {
        return { configurable: true, enumerable: true };
      }
      return Reflect.getOwnPropertyDescriptor(target, key);
    },
  });
}

const invoice = withTotal({ quantity: 3, unitPrice: 25 });
console.log(invoice.total);
console.log("total" in invoice);
console.log(Object.keys(invoice).join(", "));
console.log(JSON.stringify(invoice));

75
true
quantity, unitPrice, total
{"quantity":3,"unitPrice":25,"total":75}

Object.keys() first obtains ownKeys, then retains only string keys whose descriptors are enumerable. JSON.stringify() also reads through these observation paths, so it includes total. Different consumers use different reflective operations, which is why a virtual object needs a coherent surface.

The virtual descriptor says configurable: true because the target has no non-configurable total property supporting a stronger claim. If the target is later made non-extensible, continuing to report an extra key violates an invariant. A production implementation must specify and test that state transition.

Revoke a temporary view

Proxy.revocable() returns a proxy and a revocation function. After revocation, fundamental operations on the proxy fail, while the target object and its other aliases remain usable.

function openReadOnlySession(record) {
  const { proxy, revoke } = Proxy.revocable(record, {
    set() {
      throw new TypeError("read-only session");
    },
  });
  return { view: proxy, close: revoke };
}

const record = { id: "job-7", status: "open" };
const { view, close } = openReadOnlySession(record);

console.log(view.status);
try {
  view.status = "closed";
} catch (error) {
  console.log(error.message);
}

close();
try {
  console.log(view.id);
} catch (error) {
  console.log(error.name);
}

record.status = "closed";
console.log(record.status);

open
read-only session
TypeError
closed

Revocation controls the lifetime of the proxy capability; it isn’t a resource-cleanup protocol. It doesn’t close files, cancel timers, erase target data, or invalidate existing target aliases. The resource owner still needs to expose and invoke an explicit cleanup operation.

A set trap alone doesn’t make a complete read-only view either. Callers may still mutate through defineProperty, deleteProperty, a prototype setter, or a target alias. A real read-only contract must enumerate allowed operations, cover the relevant traps, and control how the target is exposed.

Pitfalls

Losing receiver

Fix: preserve the trap’s receiver when forwarding, and test accessors through an object that inherits from the proxy. Change the receiver only when the contract deliberately binds a method or accessor to the target, and document the resulting identity and encapsulation boundary.

Treating one trap as a complete policy

Fix: build an operation matrix from the threat model and caller APIs. Test assignment, Object.defineProperty(), deletion, in, Object.keys(), Reflect.ownKeys(), and descriptor queries separately, and don’t market a proxy as a security boundary when it can’t be one.

Violating invariants

Fix: start from the corresponding Reflect result and make the smallest required transformation. Test a non-writable, non-configurable data property, an accessor without a setter, and a target passed to Object.preventExtensions(). Treat the exception as a handler defect, not a random caller failure.

Reporting every write as successful

Fix: throw a domain-specific error when rejecting a write and return the actual Boolean from Reflect.set() when accepting one. Test non-writable properties and non-extensible targets, and assert the final descriptor or value instead of checking only that no exception occurred.

Proxying branded objects

Fix: don’t assume an empty handler is transparent for every object. Write an explicit adapter for each concrete type you must support. If you bind methods to the target, test method identity, callback passing, fluent return values, and whether the target now escapes the proxy boundary.

Treating revocation as destruction

Fix: design access revocation and resource lifetime as two explicit protocols. A cleanup function closes or cancels resources, while a revoke function rejects later proxy operations. Test both call orders and repeated calls.

Further reading

• ECMAScript language specification: Proxy Objects
• ECMAScript language specification: The Reflect Object
• MDN: Proxy
• MDN: Reflect
• MDN: handler.get()