This is a polyfill for the Proxy object, part of ES6. See the MDN docs or Introducing ES2015 Proxies for more information on Proxy itself.

The polyfill supports just a limited subset of proxy 'traps', and comes with a caveat: it invokes seal on any proxied object so that no additional properties can be defined. The properties of your objects can still change - you're just unable to define new ones. For example, proxying unrestricted dictionaries is not a good use-case for this polyfill.

Currently, the following traps are supported-

• get
• set
• apply
• construct

This has no external dependencies. Skip down to usage to get started.

Example

The most compelling use case for Proxy is to provide change notifications.

function observe(o, fn) {
  return new Proxy(o, {
    set(target, property, value) {
      fn(property, value);
      target[property] = value;
    },
  })
}

let x = {'name': 'BB-8'};
let p = observe(x, function(property, value) { console.info(property, value) });
p.name = 'BB-9';
// name BB-9

You can extend this to generate change notifications for anywhere in an object tree-

function observe(o, fn) {
  function buildProxy(prefix, o) {
    return new Proxy(o, {
      set(target, property, value) {
        // same as before, but add prefix
        fn(prefix + property, value);
        target[property] = value;
      },
      get(target, property) {
        // return a new proxy if possible, add to prefix
        let out = target[property];
        if (out instanceof Object) {
          return buildProxy(prefix + property + '.', out);
        }
        return out;  // primitive, ignore
      },
    });
  }

  return buildProxy('', o);
}

let x = {'model': {name: 'Falcon'}};
let p = observe(x, function(property, value) { console.info(property, value) });
p.model.name = 'Commodore';
// model.name Commodore

Adding new properties

The following line will fail (with a TypeError in strict mode) with the polyfill, as it's unable to intercept new properties-

p.model.year = 2016;  // error in polyfill

However, you can replace the entire object at once - once you access it again, your code will see the proxied version.

p.model = {name: 'Falcon', year: 2016};
// model Object {name: "Falcon", year: 2016}

Usage

Include the JavaScript at the start of your page, or include it as a dependency to your build steps. The source is in ES6, but the included, minified version is ES5.

Installation

Available via NPM or Bower-

$ npm install proxy-polyfill
$ bower install proxy-polyfill

Supports

The polyfill supports browsers that implement the full ES5 spec, such as IE9+ and Safari 6+. Firefox, Chrome and Edge support Proxy natively.