Old Proxy API

Non-standard
This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

Warning: The SpiderMonkey Proxy implementation is a prototype and the Proxy API and semantics specifications are unstable. The SpiderMonkey implementation may not reflect the latest specification draft. It is subject to change anytime. It is provided as an experimental feature. Do not rely on it for production code.

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.
handler
The object that intercepts properties.
proxy
The object whose properties are being intercepted.
proxy factory
The object or method that creates intercessive proxies.
traps
The methods that provide property access. This is analogous to the concept of traps in operating systems.

Proxies can be either be trapping or fixed.

Proxy API

Catch-alls can be defined only on distinct proxy objects, controlled by a handler object. There are two kinds of proxies:

object proxies

var proxy = Proxy.create(handler, proto);

and function proxies :

var proxy = Proxy.createFunction(handler, callTrap, constructTrap);

Where:

  • proto is an optional object representing the proxy’s prototype (defaults to null if none is provided).
  • callTrap is a variable-argument function(args) { return any; } that reifies “proxy(args)”. Note: The this-binding of the callTrap function is the this-binding of the call-site.
  • constructTrap is an optional variable-argument function(args) { return any-object; } that reifies “new proxy(args)”. The this-binding of the constructTrap is either undefined (in strict mode) or the global object (in non-strict mode). If no constructTrap is provided, performing new proxy(...args) calls the proxy’s callTrap with this bound to a new object delegating to the proxy's prototype.
  • handler is an object that implements the handler API.

Handler API

There are two kinds of traps: fundamental and derived traps. If one of the fundamental traps isn't implemented and the proxy is used in a way that expects the fundamental trap to be defined, then an error is thrown. If a derived trap is implemented, then that trap's code is called whenever the corresponding behavior happens on the proxy. If the derived trap is undefined, a default implementation using the fundamental traps is used. In other words: fundamental traps are required, derived traps are optional.

Fundamental traps

Emulated JavaScript code Handler method Description
Object.getOwnPropertyDescriptor(proxy, name) getOwnPropertyDescriptor: function(name) -> PropertyDescriptor | undefined Should return a valid property descriptor object, or undefined to indicate that no property with name exists in the emulated object.
Object.getPropertyDescriptor(proxy, name) getPropertyDescriptor: function(name) -> PropertyDescriptor | undefined This function doesn't exist in ECMAScript 5. Like getOwnPropertyDescriptor, but should also search the prototype chain.
Object.getOwnPropertyNames(proxy) getOwnPropertyNames: function() -> Strings Array Return an array of all own (non-inherited) property names of the emulated object.
Object.getPropertyNames(proxy) getPropertyNames: function() -> Strings Array This function doesn't exist in ECMAScript 5. Like getOwnPropertyNames, but should also return non-overridden inherited properties.
Object.defineProperty(proxy,name,pd) defineProperty: function(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 delete: function(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)

Object.seal(proxy)

Object.preventExtensions(proxy)

fix: function() -> PropertyDescriptor map (indexed on property names) | undefined

Should return an object that maps property names to property descriptors. After a call to fix(), the proxy becomes a regular (non-proxy) object with the properties listed in the return value. The handler is no longer used. Moreover, the respective method (freeze(), seal(), or preventExtension()) is immediately called on the fixed object. Note: the fixed object has the same object identity as the proxy object.

If fix() returns undefined, the call throws a TypeError exception.

Derived traps

Default implementation refers to the code that is called for that trap when the trap isn't explicitly defined. In these functions, this refers to the handler object.

Emulated JavaScript code Handler method Default implementation Description
name in proxy has: function(name) -> boolean
function(name) {
  return !!this.getPropertyDescriptor(name);
}
 
Object.prototype.hasOwnProperty.call(proxy, name) hasOwn: function(name) -> boolean
function(name) {
  return !!this.getOwnPropertyDescriptor(name);
}
 

proxy.name (in the context of "getting the value")

receiver.name (if receiver inherits from a proxy and does not override name)

get: function(receiver, name) -> any
function(receiver, name) {
  var desc = this.getPropertyDescriptor(name);
  if (desc === undefined) {
    return undefined;
  }
  if ('value' in desc) {
    return desc.value;
  } else {
    if (desc.get === undefined) {
      return undefined;
    }
    return desc.get.call(receiver);
  }
}
 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(receiver, name, val) -> boolean
function(receiver, name, val) {
  var desc = this.getOwnPropertyDescriptor(name);
  if (desc) {
    if ('writable' in desc) {
      if (desc.writable) {
        desc.value = val;
        this.defineProperty(name, desc);
        return true;
      } else {
        return false;
      }
    } else { // accessor
      if (desc.set) {
        desc.set.call(receiver, val);
        return true;
      } else {
        return false;
      }
    }
  }
  desc = this.getPropertyDescriptor(name);
  if (desc) {
    if ('writable' in desc) {
      if (desc.writable) {
        // fall through
      } else {
        return false;
      }
    } else { // accessor
      if (desc.set) {
        desc.set.call(receiver, val);
        return true;
      } else {
        return false;
      }
    }
  }
  this.defineProperty(name, {
    value: val,
    writable: true,
    enumerable: true,
    configurable: true});
  return true;
}
 receiver is either the proxy or an object that inherits from the proxy.
for(prop in proxy){...} enumerate: function() -> String Array
function() {
  return this.getPropertyNames().filter(
    function (name) {
      return this.getPropertyDescriptor(name).enumerable
    }
  );
}
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.
Object.keys(proxy) keys: function() -> String Array
function() {
  return this.getOwnPropertyNames().filter(
    function (name) {
      return this.getOwnPropertyDescriptor(name).enumerable
    }
  );
}
 

Invariants

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

  • The triple equal (===) operator is not trapped. p1 === p2 if and only if p1 and p2 refer to the same proxy. Fixing a proxy does not alter its object identity (the object “generated” by the handler during fixing does not have its own object identity; it retains the object identity of the proxy, upholding the illusion that the proxy “becomes” the object).
  • Object.getPrototypeOf(proxy) returns the prototype with which proxy was initialized for an object proxy, and returns Function.prototype for a function proxy.
  • typeof
    • typeof anObjectProxy === "object"
    • typeof aFunctionProxy === "function"
  • instanceof
    • anObjectProxy instanceof C === true if and only if the prototype with which anObjectProxy was initialized equals or inherits from C.prototype
    • aFunctionProxy instanceof Function === true

Common mistakes and misunderstanding

When starting using proxies, there are often a few beginners' mistakes and misunderstandings:

  • Not implementing all traps. Proxies are, by default, "semanticless" objects. If a trap isn't implemented, then if it's a derived trap, the default implementation is used. However, if a fundamental trap is unimplemented, then a call to this trap will throw a TypeError. To make sure no error is thrown when your object is used, you have to implement at least all fundamental traps.
  • Unwanted recursion. Be careful of how you use the receiver argument in 'get' and 'set' traps.
var p = Proxy.create({get: function(receiver, name) {
  print(receiver); // looks for receiver's toString method. receiver turns out to be the proxy, so calling print results in calling the get trap.
  return "something";
} });
var q = p.azerty; // infinite loop
  • The receiver argument in 'get' and 'set' traps may not be the proxy itself:
var proxy;
var handler = {
    has: function (name) {
        return name == 'foo';
    },
    get: function (rcvr, name) {
        if (name != 'foo')
            return undefined;
        print(proxy !== rcvr);
        return "bye";
    },
};
proxy = Proxy.create(handler);
var c = Object.create(proxy);
print(c.foo); // prints: 'true' (from "proxy !== rcvr") and 'bye' (from "c.foo").
// In this example, the get trap rcvr argument is the c object while proxy is its prototype

Examples

Very simple example

A trap is called almost each time something happens to your proxy (that is used like an object). Here is an example:

var incompleteHandler = {get:function(myProxy, name){
                               alert('Property ' + name + ' accessed.');
                               return 1;
                             }
                        };
var p = Proxy.create(incompleteHandler);
var q = p.blabla; // alerts 'Property blabla accessed' and 1 is assigned to q
p.azerty = "Trying to set a property"; // throws an error since neither the set trap or the fundamental trap used in the set trap are implemented

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.

function handlerMaker(obj) {
  return {
    // Fundamental traps
    getOwnPropertyDescriptor: function(name) {
      var desc = Object.getOwnPropertyDescriptor(obj, name);
      // a trapping proxy's properties must always be configurable
      if (desc !== undefined) { desc.configurable = true; }
      return desc;
    },
    getPropertyDescriptor:  function(name) {
      var desc = Object.getPropertyDescriptor(obj, name); // not in ES5
      // a trapping proxy's properties must always be configurable
      if (desc !== undefined) { desc.configurable = true; }
      return desc;
    },
    getOwnPropertyNames: function() {
      return Object.getOwnPropertyNames(obj);
    },
    getPropertyNames: function() {
      return Object.getPropertyNames(obj);                // not in ES5
    },
    defineProperty: function(name, desc) {
      Object.defineProperty(obj, name, desc);
    },
    delete:       function(name) { return delete obj[name]; },   
    fix:          function() {
      if (Object.isFrozen(obj)) {
        return Object.getOwnPropertyNames(obj).map(function(name) {
          return Object.getOwnPropertyDescriptor(obj, name);
        });
      }
      // As long as obj is not frozen, the proxy won't allow itself to be fixed
      return undefined; // will cause a TypeError to be thrown
    },
    // derived traps
    has:          function(name) { return name in obj; },
    hasOwn:       function(name) { return Object.prototype.hasOwnProperty.call(obj, name); },
    get:          function(receiver, name) { return obj[name]; },
    set:          function(receiver, name, val) { obj[name] = val; return true; }, // bad behavior when set fails in non-strict mode
    enumerate:    function() {
      var result = [];
      for (name in obj) { result.push(name); };
      return result;
    },
    keys: function() { return Object.keys(obj) }
  };
}
// ...
var o = Object.create({});
var proxy = Proxy.create(handlerMaker(o));
proxy.blabla = 12; // Thanks to the forwarding, o now has a 'blabla' property with a value of 12
o.blabla++; // just incrementing o.blabla
alert(proxy.blabla); // alerts 13: the getting operation is forwarded to o which returns 13.

See also

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

Document Tags and Contributors

Tags: 
 Contributors to this page: arai, jswisher, fscholz, rvighne, kscarfone, velvel53, Sheppy, -TNO-, dbruant
 Last updated by: arai,