ES5 shim for ES6 Reflect and Proxy objects
This is a shim for the ECMAScript 6 Reflect and Proxy objects.
This library does two things:
Reflectglobal object that exports the ECMAScript 6 reflection API.
Proxysupport is available, it patches
Proxyto be up-to-date with the ES6 spec.
July 2016 update: the most recent version of all major browsers and node.js now support fully ES6-compliant
Reflectand
Proxyobjects. This shim is primarily useful if you want ES6
Reflectsupport on older browsers or versions of node.js < v6.0.0, or if you want ES6
Proxysupport on versions of node.js < v6.0.0.
May 2016 update: the recently released V8 v4.9 includes native support for ES2015 Proxies and Reflect, making this library obsolete for environments that embed V8 4.9 or newer (like Chrome 49 and Node v6.0). Node v5.10.x or lower still requires this polyfill for proper ES6 Proxy support.
Read Why should I use this library?
For node.js, install via npm:
npm install harmony-reflect
Then:
node --harmony-proxies > var Reflect = require('harmony-reflect');
See release notes for changes to the npm releases.
To use in a browser, just download the single reflect.js file. After loading
a global object
Reflectis defined that contains reflection methods as defined in the ES6 spec.
This library also updates the "harmony-era"
Proxyobject in the V8 engine (also used in node.js) to follow the latest ECMAScript 2015 spec. To create such a proxy, call:
var proxy = new Proxy(target, handler);
See below for a list of spec incompatibilities and other gotcha's.
This module exports an object named
Reflectand updates the global
Proxyobject (if it exists) to be compatible with the latest ECMAScript 6 spec.
The ECMAScript 6 Proxy API allows one to intercept various operations on Javascript objects.
The
ReflectAPI, with support for proxies, was tested on:
node --harmony_proxies(>= v0.7.8)
iojs --harmony_proxies(>= 2.3.0)
v8 --harmony_proxies(>= v3.6)
jsspidermonkey shell
If you need only
Reflectand not an up-to-date
Proxyobject, this library should work on any modern ES5 engine (including all browsers).
Compatibility notes:
chrome://flags/#enable-javascript-harmony) but Chrome v38 removed the
Proxyconstructor. As a result, this library cannot patch the harmony-era
Proxyobject on Chrome v38 or above. If you're working with Chromium directly, it's still possible to enable proxies using
chromium-browser --js-flags="--harmony_proxies".
Proxyconstructor was enabled by default when starting V8 with
--harmony. For recent versions of V8,
Proxymust be explicitly enabled with
--harmony_proxies.
After loading
reflect.jsinto your page or other JS environment, be aware that the following globals are patched to be able to recognize emulated direct proxies:
Object.getOwnPropertyDescriptor Object.defineProperty Object.defineProperties Object.getOwnPropertyNames Object.getOwnPropertySymbols Object.keys Object.{get,set}PrototypeOf Object.assign Object.{freeze,seal,preventExtensions} Object.{isFrozen,isSealed,isExtensible} Object.prototype.valueOf Object.prototype.isPrototypeOf Object.prototype.toString Object.prototype.hasOwnProperty Function.prototype.toString Date.prototype.toString Array.isArray Array.prototype.concat Proxy Reflect
:warning: In node.js, when you
require('harmony-reflect'), only the current module's globals are patched. If you pass an emulated direct proxy to an external module, and that module uses the unpatched globals, the module may not interact with the proxy according to the latest ES6 Proxy API, instead falling back on the old pre-ES6 Proxy API. This can cause bugs, e.g. the built-in
Array.isArraywill return
falsewhen passed a proxy-for-array, while the patched
Array.isArraywill return true. I know of no good fix to reliably patch the globals for all node modules. If you do, let me know.
The examples directory contains a number of examples demonstrating the use of proxies:
Object.observenotification mechanism.
Other example uses of proxies (not done by me, but using this library):
For more examples of proxies, and a good overview of their design rationale, I recommend reading Axel Rauschmayer's blog post on proxies.
The sister project proxy-handlers defines a number of predefined Proxy handlers as "abstract classes" that your code can "subclass" The goal is to minimize the number of traps that your proxy handlers must implement.
This library differs from the ECMAScript 2016 spec as follows:
enumerate()trap, and the corresponding
Reflect.enumerate()method, have been removed. This shim still supports the trap.
This library differs from the ECMAScript 2015 spec as follows:
In ES6,
Proxyis a constructor function that requires the use of
new. That is, you must write
new Proxy(target, handler). This library exports
Proxyas an ordinary function which may be called with or without using the
newoperator.
In ES6,
Function.prototype.toStringand
Date.prototype.toStringdo not operate transparently on Proxies. This shim patches those functions so that stringifying a Proxy-for-a-function or a Proxy-for-a-date "unwraps" the proxy and instead stringifies the target of the Proxy. This behavior may change in the future to be more spec-compatible.
This library does not shim Symbol objects. On modern V8 or io.js which supports Symbol objects natively, due to a bug in V8, Symbols and Proxies don't play well together. Read more.
Proxies-for-arrays are serialized as JSON objects rather than as JSON arrays. That is,
JSON.stringify(new Proxy([], {}))returns "{}" rather than "[]". Read more.