Proxy

Introduction

Proxies are objects for which the programmer has to define the semantics in JavaScript. The default object semantics are implemented in the JavaScript engine, often written in lower-level languages like C++. Proxies let the programmer define most of the behavior of an object in JavaScript. They are said to provide a meta-programming API.

Terminology

catch-all mechanism (or "intercession API")

The technical term for this feature.

proxy

The object whose accesses are being intercepted.

handler

Placeholder object which contains traps.

traps

The methods that provide property access. This is analogous to the concept of traps in operating systems.

target

Object which is the proxy virtualizes. It is often used as storage backend for the proxy. Invariants regarding object non-extensibility or non-configurable properties are verified against the target.

Proxy API

Proxies are new objects; it's not possible to "proxyfy" an existing object. Here is how to create a proxy

var p = new Proxy(target, handler);

Where:

• target is an object (can be any sort of objects, including a native array, a function or even another proxy).
• handler is an object which properties are functions which define the behavior of the proxy when an operation is performed on it.

Handler API

All traps are optional. If a trap has not been defined, the default behavior is to forward the operation to the target.

JavaScript code	Handler method	Description
Object.getOwnPropertyDescriptor(proxy, name)	getOwnPropertyDescriptor function(target, name) -> PropertyDescriptor | undefined	Should return a valid property descriptor object, or undefined to indicate that no property named name exists in the emulated object.
Object.getOwnPropertyNames(proxy)	getOwnPropertyNames function(target) -> [String]	Return an array of all own (non-inherited) property names of the emulated object.
Object.defineProperty(proxy,name,pd)	defineProperty function(target, name, propertyDescriptor) -> any	Define a new property whose attributes are determined by the given propertyDescriptor. The return value of this method is ignored.
delete proxy.name	deleteProperty function(target, name) -> boolean	Delete the named property from the proxy. The boolean return value of this method should indicate whether or not the name property was successfully deleted.
Object.freeze(proxy)	freeze function(target) -> boolean	Freezes the object. The boolean indicates whether the operation was successful
Object.seal(proxy)	seal function(target) -> boolean	Seals the object. The boolean indicates whether the operation was successful
Object.preventExtensions(proxy)	preventExtensions function(target) -> boolean	Makes the object non-extensible. The boolean indicates whether the operation was successful
name in proxy	has function(target, name) -> boolean
Object.prototype.hasOwnProperty.call(proxy, name)	hasOwn function(target, name) -> boolean
proxy.name (in the context of "getting the value") receiver.name (if receiver inherits from a proxy and does not override name)	get function(target, name, receiver) -> any	receiver is either the proxy or an object that inherits from the proxy.
proxy.name = val (in the context of "setting the value") receiver.name = val (if receiver inherits from a proxy and does not override name)	set function(target, name, val, receiver) -> boolean	receiver is either the proxy or an object that inherits from the proxy.
for(prop in proxy){...}	enumerate function(target) -> [String]	From the proxy user point of view, properties appear in the for..in loop in the same order as they are in the returned array. Known bug: for for..in loops, the iterate trap is call while it should be the enumerate trap
for(prop of proxy){...}	iterate function(target) -> iterator
Object.keys(proxy)	keys function(target) -> [String]
proxy.apply(thisValue, args)	apply function(target, thisValue, args) -> any
new proxy(...args)	construct function(target, args) -> any

Invariants

Even though proxies provide a lot of power to users, some operations are not trapped in order to keep the language consistent:

• The double and triple equal (==, ===) operator is not trapped. p1 === p2 if and only if p1 and p2 refer to the same proxy.
• Object.getPrototypeOf(proxy) unconditionally returns Object.getPrototypeOf(target)
• typeof proxy unconditionally returns typeof target
• Object.prototype.toString.call(proxy) unconditionally returns Object.prototype.toString.call(target)

Examples

Very simple example

An object with 37 as its default value when the property name is not in the object

var handler = {
    get: function(target, name){
        return name in target?
            target[name] :
            37;
    }
}

var p = new Proxy({}, handler);
p.a = 1;
p.b = undefined;

console.log(p.a, p.b); // 1, undefined
console.log('c' in p, p.c); // false, 37

No-op forwarding proxy

In this example, we are using a native JavaScript object to which our proxy will forward all operations that are applied to it.

var target = {};
var p = new Proxy(target, {});

p.a = 37; // operation forwarded to the proxy

console.log(target.a); // 37. The operation has been properly forwarded

See also

• "Proxies are awesome" Brendan Eich presentation at JSConf (slides)
• ECMAScript Harmony Proxy proposal page and ECMAScript Harmony proxy semantics page
• Tutorial on proxies
• Old Proxy API page

Licensing note

Some content (text, examples) in this page has been copied or adapted from the ECMAScript wiki which content is licensed CC 2.0 BY-NC-SA