Your Search Results

    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

    Contributors to this page: -TNO-, velvel53, kscarfone, Sheppy, dbruant
    Last updated by: kscarfone,