This is a shim for the ECMAScript 6 Reflect and Proxy objects.

This library does two things:

• It defines an ES6-compliant

  Reflect

  global object that exports the ECMAScript 6 reflection API.
• If harmony-era (pre-ES6)

  Proxy

  support is available, it patches

  Proxy

  to 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

Reflect

Proxy

Reflect

Proxy

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?

Installation

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

Reflect

This library also updates the "harmony-era"

Proxy

var proxy = new Proxy(target, handler);

See below for a list of spec incompatibilities and other gotcha's.

API Docs

This module exports an object named

Reflect

Proxy

The ECMAScript 6 Proxy API allows one to intercept various operations on Javascript objects.

• Overview of all supported traps on proxies
• The Reflect API
• The Proxy Handler API

Compatibility

The

Reflect

• Firefox (>= v4.0)

• node --harmony_proxies

  (>= v0.7.8)

• iojs --harmony_proxies

  (>= 2.3.0)

• v8 --harmony_proxies

  (>= v3.6)
• Any recent

  js

  spidermonkey shell

If you need only

Reflect

Proxy

Compatibility notes:

• Chrome (>= v19 && <= v37) used to support proxies behind a flag (

  chrome://flags/#enable-javascript-harmony

  ) but Chrome v38 removed the

  Proxy

  constructor. As a result, this library cannot patch the harmony-era

  Proxy

  object 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"

  .
• In older versions of V8, the

  Proxy

  constructor was enabled by default when starting V8 with

  --harmony

  . For recent versions of V8,

  Proxy

  must be explicitly enabled with

  --harmony_proxies

  .

Dependencies

• ECMAScript 5/strict
• To emulate direct proxies:
  • old Harmony Proxies
  • Harmony WeakMaps

After loading

reflect.js

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')

Array.isArray

false

Array.isArray

Examples

The examples directory contains a number of examples demonstrating the use of proxies:

• membranes: wrappers that transitively isolate two object-graphs.
• observer: a self-hosted implementation of the ES7

  Object.observe

  notification mechanism.
• profiler: a simple profiler to collect usage statistics of an object.

Other example uses of proxies (not done by me, but using this library):

• supporting negative array indices a la Python
• tpyo: using proxies to correct typo's in JS property names
• persistent objects: shows how one might go about using proxies to save updates to objects in a database incrementally
• defaultdict: default values for new keys in objects (as known from Python)

For more examples of proxies, and a good overview of their design rationale, I recommend reading Axel Rauschmayer's blog post on proxies.

Proxy Handler API

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.

Spec Incompatibilities and other gotcha's

This library differs from the ECMAScript 2016 spec as follows:

• In ES7, the

  enumerate()

  trap, and the corresponding

  Reflect.enumerate()

  method, have been removed. This shim still supports the trap.
• The ES7 (and ES6) spec contains a bug that leads to missing invariant checks in the getOwnPropertyDescriptor, defineProperty and deleteProperty traps. This library already contains the patch referred to in this issue.

This library differs from the ECMAScript 2015 spec as follows:

• In ES6,

  Proxy

  is a constructor function that requires the use of

  new

  . That is, you must write

  new Proxy(target, handler)

  . This library exports

  Proxy

  as an ordinary function which may be called with or without using the

  new

  operator.

• In ES6,

  Function.prototype.toString

  and

  Date.prototype.toString

  do 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.