• Stars
    star
    1,134
  • Rank 41,064 (Top 0.9 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created over 8 years ago
  • Updated 4 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Proxy object polyfill

Please note that this polyfill is now in maintenance mode, as of Jan, 2023. We are not planning to add more features or enhancements.


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. Unlike other polyfills, this does not require Object.observe, which is no longer supported anywhere.

⚠️ Note that Firefox, Chrome, Safari 10+ and Edge support Proxy natively. You don't need this if you're only targeting these modern browsers.

The polyfill supports just a limited number of proxy 'traps'. It also works by calling seal on the object passed to Proxy. This means that the properties you want to proxy must be known at creation time.

Additionally, your objects' prototypes will be snapshotted at the time a proxy is created. 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

The Proxy.revocable method is also supported, but only for calls to the above traps.

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, callback) {
  return new Proxy(o, {
    set(target, property, value) {
      callback(property, value);
      target[property] = value;
    },
  });
}

const x = {'name': 'BB-8'};
const p = observe(x, (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, callback) {
  function buildProxy(prefix, o) {
    return new Proxy(o, {
      set(target, property, value) {
        // same as above, but add prefix
        callback(prefix + property, value);
        target[property] = value;
      },
      get(target, property) {
        // return a new proxy if possible, add to prefix
        const out = target[property];
        if (out instanceof Object) {
          return buildProxy(prefix + property + '.', out);
        }
        return out;  // primitive, ignore
      },
    });
  }

  return buildProxy('', o);
}

const x = {'model': {name: 'LEAF'}};
const p = observe(x, (property, value) => console.info(property, value));
p.model.name = 'Tesla';
// model.name Tesla

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}

For a similar reason, this polyfill can't proxy Array objects very well - but you can replace them all at once.

Usage

Install via your favourite package manager as proxy-polyfill.

To polyfill Proxy everywhere

You should either:

  • include proxy-polyfill into your build system (just require it directly, it doesn't export anything), or
  • import the proxy.min.js file directly.

This is the recommended approach and works on the web, in Node, or React Native.

Do not import ./src/proxy.js in old browsers directly, as it uses modern JavaScript features. It needs to be compiled, which is why we have the proxy.min.js file.

To consume the polyfill as a function

This is an advanced pattern. Requires ./src/proxy.js, which exports a proxy polyfill builder function in commonJS.

// commonJS require
const proxyPolyfill = require('proxy-polyfill/src/proxy')();

// Your environment may also support transparent rewriting of commonJS to ES6:
import ProxyPolyfillBuilder from 'proxy-polyfill/src/proxy';
const proxyPolyfill = ProxyPolyfillBuilder();

// Then use...
const myProxy = new proxyPolyfill(...);

Support

The polyfill supports browsers that implement the full ES5 spec, such as IE9+ and Safari 6+. It may work in other non-browser environments too.

More Repositories

1

lighthouse

Automated auditing, performance metrics, and best practices for the web.
JavaScript
28,269
star
2

chrome-extensions-samples

Chrome Extensions Samples
JavaScript
14,888
star
3

workbox

📦 Workbox: JavaScript libraries for Progressive Web Apps
JavaScript
12,346
star
4

web-vitals

Essential metrics for a healthy site.
JavaScript
7,571
star
5

lighthouse-ci

Automate running Lighthouse for every commit, viewing the changes, and preventing regressions
JavaScript
6,377
star
6

rendertron

A Headless Chrome rendering solution
TypeScript
5,936
star
7

samples

A repo containing samples tied to new functionality in each release of Google Chrome.
HTML
5,769
star
8

web.dev

The frontend, backend, and content source code for web.dev
Nunjucks
3,563
star
9

dialog-polyfill

Polyfill for the HTML dialog element
JavaScript
2,443
star
10

web-vitals-extension

A Chrome extension to measure essential metrics for a healthy site
CSS
2,360
star
11

accessibility-developer-tools

This is a library of accessibility-related testing and utility code.
JavaScript
2,280
star
12

developer.chrome.com

The frontend, backend, and content source code for developer.chrome.com
HTML
1,665
star
13

custom-tabs-client

Chrome custom tabs examples
Java
1,399
star
14

chrome-launcher

Launch Google Chrome with ease from node.
TypeScript
1,232
star
15

omnitone

Spatial Audio Rendering on the web.
JavaScript
851
star
16

android-browser-helper

The Android Browser Helper library helps developers use Custom Tabs and Trusted Web Activities on top of the AndroidX browser support library.
Java
693
star
17

devtools-docs

The legacy documentation for Chrome DevTools.
HTML
691
star
18

chromium-dashboard

Chrome Status Dashboard
Python
637
star
19

OriginTrials

Enabling safe experimentation with web APIs
Bikeshed
519
star
20

related-website-sets

Python
395
star
21

audion

Audion is a Chrome extension that adds a Web Audio panel to Developer Tools. This panel visualizes the web audio graph in real-time.
TypeScript
368
star
22

chrome-app-codelab

The goal of this tutorial is to get you building Chrome apps fast. Once you've completed the tutorial, you will have a simple Todo app. We've done our best to capture some of the trickier parts to the development process keeping the sample simple and straightforward.
JavaScript
213
star
23

CrUX

The place to share queries, ideas, or issues related to the Chrome UX Report
Jupyter Notebook
206
star
24

lighthouse-stack-packs

Lighthouse Stack Packs
JavaScript
204
star
25

inert-polyfill

Polyfill for the HTML inert attribute
JavaScript
188
star
26

chrome-types

Code to parse Chrome's internal extension type definitions—published on NPM as chrome-types
JavaScript
184
star
27

ip-protection

171
star
28

devtools-samples

Samples for demonstrating DevTools features.
HTML
152
star
29

CertificateTransparency

HTML
148
star
30

browser-bug-search

Search across all major browser vendor issue trackers
JavaScript
114
star
31

multi-device

Chrome multi-device (mobile) docs
HTML
103
star
32

kino

A sample offline streaming video PWA built for web.dev/media
JavaScript
102
star
33

webstatus.dev

A tool to monitor and track the status of all Web Platform features across dimensions that are related to availability and implementation quality across browsers, and adoption by web developers.
Go
97
star
34

webstore-docs

Developer docs for Chrome Web Store:
HTML
65
star
35

jank-busters

Resources for jank busting on the web.
JavaScript
64
star
36

webdev-infra

JavaScript
40
star
37

private-tokens

39
star
38

budget.json

38
star
39

.github

11
star
40

.allstar

7
star
41

CertificateTransparency-todelete

HTML
7
star
42

baseline-status

JavaScript
4
star
43

lighthouse-plugin-example

JavaScript
1
star