Skip to content
Spec-compliant shim for Realms TC39 Proposal
JavaScript Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Fix and automate integration tests Oct 1, 2019
examples Prevent mangling of variables. Oct 1, 2019
scripts Add CircleCI config and npm-audit-fix script (#5) Mar 28, 2019
src Resolve issues with transforms Oct 15, 2019
test-integration Add integration tests Oct 1, 2019
test Resolve issues with transforms Oct 15, 2019
.babelrc move everything in the shim directory to top level Mar 18, 2019
.eslintrc correct paths now that shim files are top level, fix package.json suc… Mar 18, 2019
.esmrc Add code coverage Jul 6, 2018
.gitignore package cleanups Sep 19, 2019
.nycrc correct paths now that shim files are top level, fix package.json suc… Mar 18, 2019
.prettierrc reformat to 80 columns automatically Apr 30, 2019
.travis.yml Fixes Jul 29, 2018
LICENSE move everything in the shim directory to top level Mar 18, 2019
LICENSE-aura move everything in the shim directory to top level Mar 18, 2019
LICENSE-caja move everything in the shim directory to top level Mar 18, 2019
LICENSE-corejs move everything in the shim directory to top level Mar 18, 2019
LICENSE-v8 move everything in the shim directory to top level Mar 18, 2019
NEWS.md release 1.2.1 Oct 16, 2019
NOTICE move everything in the shim directory to top level Mar 18, 2019
README.md release 1.1.0 Sep 24, 2019
SECURITY.md update SECURITY.md for upcoming release Oct 2, 2019
package-lock.json results of running npm audit fix Nov 20, 2019
package.json 1.2.2-dev.0 Oct 16, 2019
rollup.config.js Prevent mangling of variables. Oct 1, 2019

README.md

Realm Shim

Build Status Coverage Status dependency status dev dependency status License

This folder contains a shim implementation of the Realm API Proposal.

Limitations

The current implementation has 3 main limitations:

  • All code evaluated inside a Realm runs in strict mode.
  • Direct eval is not supported.
  • let, global function declarations and any other feature that relies on new bindings in global contour are not preserved between difference invocations of eval, instead we create a new contour everytime.

Building the Shim

git clone https://github.com/Agoric/realms-shim.git
cd realms-shim
npm install
npm run shim:build

This will install the necessary dependencies and build the shim locally.

Playground

To open the playground example in your default browser:

npm run shim:build
open examples/simple.html

Usage

To use the shim in a webpage, build the shim, then:

  <script src="../dist/realm-shim.min.js"></script>
  <script>
    const r = new Realm();
    [...]
  </script>

To use the shim with node:

  const Realm = require('./realm-shim.min.js');
  const r = new Realm();
  [...]

You can also use the ES6 module version of the Realms shim in Node.js via the package esm. To do that, launch node with esm via the "require" option:

npm install esm
node -r esm main.js

And import the realm module in your code:

  import Realm from './src/realm';
  const r = new Realm();
  [...]

Examples

Example 1: Root Realm

To create a root realm with a new global and a fresh set of intrinsics:

const r = new Realm(); // root realm
r.global === this; // false
r.global.JSON === JSON; // false

Example 2: Realm Compartment

To create a realm compartment with a new global and inherit the intrinsics from another realm:

const r1 = new Realm(); // root realm
const r2 = new r1.global.Realm({ intrinsics: 'inherit' }); // realm compartment
r1.global === r2.global; // false
r1.global.JSON === r2.global.JSON; // true

Example 3: Realm Compartment from current Realm

To create a realm compartment with a new global and inherit the intrinsics from the current execution context:

const r = new Realm({ intrinsics: 'inherit' }); // realm compartment
r.global === this; // false
r.global.JSON === JSON; // true

Bug Disclosure

Please help us practice coordinated security bug disclosure, by using the instructions in SECURITY.md to report security-sensitive bugs privately.

For non-security bugs, please use the regular Issues page.

You can’t perform that action at this time.