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 at https://github.com/Agoric/realms-shim, notice that this library is now deprecated.
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
let g = window; // outer global
let r = new Realm(); // root realm
let f = r.evaluate("(function() { return 17 })");
f() === 17 // true
Reflect.getPrototypeOf(f) === g.Function.prototype // false
Reflect.getPrototypeOf(f) === r.global.Function.prototype // true
Example: simple subclass
class EmptyRealm extends Realm {
constructor(...args) {
super(...args);
let global = this.global;
// delete global descriptors:
delete global.Math;
...
}
}
Example: DOM mocking
class FakeWindow extends Realm {
constructor(...args) {
super(...args);
let global = this.global;
global.document = new FakeDocument(...);
global.alert = new Proxy(fakeAlert, { ... });
...
}
}
API (TypeScript Format)
interface RealmInit {
thisValue?: object;
}
interface Realm {
readonly global: typeof globalThis;
readonly thisValue: typeof globalThis, object;
evaluate(sourceText: string): any;
intrinsics(): Record<string, any>;
}
declare var Realm: {
prototype: Realm;
new(options?: RealmInit): Realm;
};
Presentations
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:
npm install
npm run build
open index.html
Alternative, you can use npm run watch.