namespace-proxy

The namespace-proxy is a utility for creating namespaces in objects (similar to those provided by Mozilla's SDK).

A namespace can be used to prevent symbol collisions in object's properties, or to create private APIs and properties.

The main difference between the namespace-proxy and Mozilla's namespace is the use of ES2015 Proxy which allows the namespace-proxy to store the namespaced properties directly on the target object, instead of having a separate storage of these properties.

Furthermore, the namespace-proxy stores all properties via ES2015 symbols, which are unique to each created namespace and thus prevent name collisions.

Setup

You can install the namespace-proxy utility using npm:

npm install --save namespace-proxy

Usage example

The createNamespaceProxy function creates a function that accepts an object and returns a proxy object which is used to access the namespace within the passed-in object.

The created function also is a Proxy, which provides automatically generated symbols by accessing them, and can be used for static properties.

import createNamespaceProxy from "namespace-proxy"

const PRIVATE = createNamespaceProxy()
const PROTECTED = createNamespaceProxy(true) // properties are enumerable

export default class Point {
  constructor(x, y) {
    PROTECTED(this).x = x // stores x in this instance using a symbol named "x"
    PROTECTED(this).y = y
  }

  static get PROTECTED() {
    return PROTECTED // allow other code (subclases) to access this namespace
  }

  get x() {
    return PROTECTED(this).x
  }

  get y() {
    return PROTECTED(this).x
  }

  get distanceFromOrigin() {
    let d1 = PRIVATE.getDistance(this.x, 0)
    let d2 = PRIVATE.getDistance(this.y, 0)
    return Math.sqrt(Math.pow(d1, 2) + Math.pow(d2, 2))
  }

  // method named using a symbol named "getDistance"
  [PRIVATE.getDistance](d1, d2) {
    return Math.abs(d2 - d1)
  }

  // static method named using a symbol named "create"
  static [PROTECTED.create](x, y) {
    return new Point(x, y)
  }
}

Browser and Node.js support

Since the namespace-proxy requires the Proxy API which cannot be polyfilled, only Node.js 6+ and modern browsers are supported. You can check the current list of supported browsers at caniuse.com or the MDN.

At the moment of writing this, the following browsers were supported:

• Chrome/Chromium 49+
• Firefox 18+
• Edge 12+
• Opera & Opera Mobile 36+
• Chrome & Firefox for Android
• Android System WebView / Android Browser 49+

It appears the Safari and iOS browsers will be supported from the version 10.

The current state of this project

There are no current plans for additional features (unless a good case for adding them is made), but the project accepts bug fixes if new bugs are discovered.

Contributing

Time is precious, so, if you would like to contribute (bug fixing, test writing or feature addition), follow these steps:

• fork
• implement (follow the code style)
• pull request
• wait for approval/rejection of the pull request

Filing a bug issue might get me to fix the bug, but filing a feature request will not as I don't have the time to work on this project full-time. You may still propose new features through pull requests. Thank you for understanding.