README.md

ECMAScript spec proposal for ShadowRealm API

Status

• Explainer.
• HTML Rendered Spec.
• Currently at Stage 2.
• Code of Conduct

Champions

• @dherman
• @caridy
• @erights
• @leobalter
• @rwaldron
• @legendecas

Index

• What are ShadowRealms?
• API (TypeScript Format)
• Presentations
• History
• Contributing
  • Updating the spec text for this proposal

What are ShadowRealms?

ShadowRealms are a distinct global environment, with its own global object containing its own intrinsics and built-ins (standard objects that are not bound to global variables, like the initial value of Object.prototype).

See more at the explainer document.

API (TypeScript Format)

declare class ShadowRealm {
    constructor();
    importValue(specifier: string, bindingName: string): Promise<PrimitiveValueOrCallable>;
    evaluate(sourceText: string): PrimitiveValueOrCallable;
}

See some examples in the Explainer file.

Presentations

• TC39 Meeting, July 12th 2021 - Stage 3 Request
• TC39 Meeting, May 25th 2021 - Stage 2 Update
• TC39 Meeting, April 2021 - Introduction of Callable Boundary Reealms
• TC39 Meeting, January 2021 - Realms update from Chrome's position on the previous API
• TC39 Meeting, November 2020 - Stage 2 Update
• TC39 Meeting, June 4th 2020 - Stage 2 Update
• TC39 Incubator Call May 26th 2020
• TC39 Feb 2020 - Stage 2 Update
• TC39 May 2018 - Stage 2 Request (archived)

History

• we moved on from the exposed globalThis model to a lean isolated realms API (see #289 and #291)
• we worked on this during ES2015 time frame, so never went through stages process (ES6 Realm Objects proto-spec.pdf)
• 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?

Contributing

Updating the spec text for this proposal

The source for the spec text is located in spec.html and it is written in ecmarkup language.

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

npm install
npm run build
open dist/index.html

Alternatively, you can use npm run watch.