tc39/proposal-realms

Name: proposal-realms

Owner: Ecma TC39

Description: ECMAScript Proposal, specs, and reference implementation for Realms

Created: 2016-04-14 15:26:14.0

Updated: 2018-05-24 19:37:59.0

Pushed: 2018-05-24 19:37:57.0

Homepage: null

Size: 374

Language: JavaScript

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

ECMAScript spec proposal for Realms API

Status

Current Stage

This proposal is at stage 2 of the TC39 Process.

Champions

• @dherman
• @caridy
• @erights

Spec Text

You can view the spec rendered as HTML.

Shim/Polyfill

A shim implementation of the Realm API can be found here.

You can play around with the current version of the shim in a Realm here and in a Frozen Realm here.

Realms

History

• worked on this during ES2015 time frame, so never went through stages process
• got punted to later (rightly so!)
• goal of this proposal: resume work on this, reassert committee interest via advancing to stage 2
• original idea from @dherman: What are Realms?

Intuitions

• sandbox
• iframe without DOM
• principled version of Node's 'vm' module
• sync Worker

Use cases

• security isolation (with synchronous but coarse-grained communication channel)
• plugins (e.g., spreadsheet functions)
• in-browser code editors
• server-side rendering
• testing/mocking (e.g., jsdom)
• in-browser transpilation

Examples

Example: simple realm

g = window; // outer global
r = new Realm(); // root realm

f = r.evaluate("(function() { return 17 })");

=== 17 // true

ect.getPrototypeOf(f) === g.Function.prototype // false
ect.getPrototypeOf(f) === r.global.Function.prototype // true

Example: simple compartment

g = window; // outer global
r1 = new Realm(); // root realm
r2 = new r1.global.Realm({ intrinsics: "inherit" }); // realm compartment

f = r1.evaluate("(function() { return 17 })");

=== 17 // true

ect.getPrototypeOf(f) === g.Function.prototype // false
ect.getPrototypeOf(f) === r1.global.Function.prototype // true
ect.getPrototypeOf(f) === r2.global.Function.prototype // true

Example: simple subclass

s EmptyRealm extends Realm {
nstructor(...args) { super(...args); }
it() { /* do nothing */ }

Example: DOM mocking

s FakeWindow extends Realm {
it() {
super.init(); // install the standard primordials
let global = this.global;

global.document = new FakeDocument(...);
global.alert = new Proxy(fakeAlert, { ... });
...

Example: parameterized evaluator

Transform Trap

The transform trap provides a way to preprocess any sourceText value before it is evaluated, and it applies to direct and indirect evaluation alike. E.g.:

t r = new Realm({
ansform(sourceText) {
return remapXToY(sourceText);


obal.y = 1;
t a = r.evaluate(`let x = 2; eval("x")`);      // yields 1 after remapping `x` to the global `y`.
t b = r.evaluate(`let x = 3; (0, eval)("x")`); // yields 1 after remapping `x` to the global `y`.

For mode details about how to implement a JS dialects with Realms, check the following gist:

• https://gist.github.com/dherman/9146568 (outdated API, but the same principle applies).

Example: controlling direct evaluation

The isDirectEval trap provides a way to control when certain invocation to an eval identifier qualifies as direct eval. This is important if you plan to replace the eval intrinsic to provide your own evaluation mechanism:

t r = new Realm({
DirectEval(func) {
return func === r.customEval;


tion customEval(sourceText) {
turn compile(sourceText);

obal.eval = customEval; // providing a custom evaluation mechanism
t source = `
t x = 1;
unction foo() {
let x = 2;
eval('x');      // yields 2 if `compile` doesn't alter the code
(0,eval)('x');  // yields 1 if `compile` doesn't alter the code
();

aluate(source);

Import Trap

The import trap has been removed for stage 2. We might bring it back at some point.

Contributing

Updating the spec text for this proposal

The source for the spec text is located in spec/index.emu and it is written in ecmarkup language.

When modifying the spec text, you should be able to build the HTML version in index.html by using the following command:

install
run build
 index.html

Alternative, you can use npm run watch.