Skip to content
Tutorials Center
My learning

Topics

JavaScript Reference ยท JSON, Errors and Reflection

The Proxy object

Reference for the JavaScript Proxy object: wrap a target with a handler to intercept reads, writes and more, with validation, defaults, revocable proxies and pitfalls.

A Proxy wraps another object (the target) and lets you intercept the operations performed on it: reading a property, assigning one, checking in, deleting, enumerating keys, calling a function and more. You describe the interceptions in a handler object whose methods are called traps. Any operation without a trap passes straight through to the target.

Proxies power validation layers, default values, logging, change tracking and reactive frameworks. They are a tool for building abstractions, not for everyday code: a proxy adds indirection and makes behavior harder to follow.

JavaScript
const proxy = new Proxy({}, {
  get(target, key) {
    return key in target ? target[key] : "none";
  },
});

Try it

JS Defaults and validation

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Logging, revoking and identity

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
new Proxy(target, handler)
Proxy.revocable(target, handler)
Name Description
target The object to wrap: any object, including arrays, functions and other proxies.
handler An object whose methods are the traps. An empty object {} makes a transparent proxy. See Proxy handler traps.

Return value: new Proxy() returns the proxy. Proxy.revocable() returns { proxy, revoke }; calling revoke() makes every later operation on the proxy throw a TypeError.

Exceptions: TypeError if target or handler is not an object, or if Proxy is called without new. A trap that breaks an invariant (see below) also throws a TypeError.

Usage notes

  • A proxy is a different object from its target. proxy === target is false; writing through the proxy changes the target, but code that holds the target directly bypasses all traps.
  • Return true from a set trap. Returning a falsy value makes the assignment throw a TypeError in strict mode (modules and classes) and fail silently otherwise.
  • Invariants are enforced. For example, a get trap cannot report a different value for a non-writable, non-configurable target property. This protects frozen objects.
  • Use Reflect inside traps to forward the default behavior correctly, including the receiver. See Reflect.
  • Built-ins with internal slots break. Methods of Map, Set, Date and objects with private fields (#x) require the real object as this, so calling them through a proxy throws a TypeError. Bind the method to the target in a get trap.
  • Type checks look through the proxy: Array.isArray(new Proxy([], {})) is true, and typeof is that of the target.
  • Performance. Every intercepted operation runs your JavaScript, so avoid proxies on hot paths.
  • Not polyfillable. A proxy cannot be emulated in older engines.
  • Nested objects are not wrapped automatically. To track deep changes, return another proxy from the get trap.

Browser support

Proxy is supported in every current browser and in Node.js. It cannot be polyfilled for older browsers.