Old Proxy API

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

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.

function(name) {
  return !!this.getPropertyDescriptor(name);
}

function(name) {
  return !!this.getOwnPropertyDescriptor(name);
}

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);
  }
}

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;
}

function() {
  return this.getPropertyNames().filter(
    function (name) {
      return this.getPropertyDescriptor(name).enumerable
    }
  );
}

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

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

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