realms-shim
v1.2.1Realm Shim
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.
Metadata
- Apache-2.0
- Whatever
- TC39 Open Source Contributors
- released 10/16/2019