Notational Conventions

This section describes the conventions used here to describe type signatures.

A [T] is an array-like value (only ever used read-only in this API), i.e., one with an integer length and whose indexed properties from 0 to length - 1 are of type T.

A type T? should be read as T | undefined -- that is, an optional value that may be undefined.

Realms

A realm object abstracts the notion of a distinct global environment, with its own global object, copy of the standard library, and "intrinsics" (standard objects that are not bound to global variables, like the initial value of Object.prototype).

Extensible web: This is the dynamic equivalent of a same-origin <iframe> without DOM.

The constructor arguments are optional and have the same signature as the arguments to new Proxy. If at least one is provided, then the global object of the realm is created as if via new Proxy within the new realm. Otherwise, the global object of the realm is an ordinary object with the new realm's intrinsic %ObjectPrototype% as its [[Prototype]].

The indirectEval method allows custom evaluation behavior for indirect calls to the eval function. By default, it simply returns the source unmodified.

The directEval method allows custom evaluation behavior for direct calls to the eval function. By default, it simply returns the source unmodified.

The nonEval method allows custom evaluation behavior for direct function calls that appear to be direct calls to eval but whose callee turns out not to be the eval function. By default, it simply calls the callee on the arguments, using the self parameter as the this binding.

The init method allows custom initialization of the global state of the realm at construction time. By default, the init method defines the standard library on the global object with standard values and attributes.

Realm Properties

stdlib

A property descriptor map containing this realm's standard global bindings, with their standard attributes, of the ECMAScript standard library. These can be easily copied to a global object via

Object.defineProperties(global, realm.stdlib)

intrinsics

A dictionary object containing the initial values of this realm's intrinsics. For each intrinsic %Foo% there is an entry Foo in the dictionary. For example, the %ObjectPrototype% and %GeneratorFunction% intrinsics are mapped as ObjectPrototype and GeneratorFunction, respectively.

global

The global object associated with the realm.

Realm Methods

eval

Synchronously execute a top-level script. The source is interpreted as a Script and evaluated with this bound to the realm's global object.

Extensible web: This is the dynamic equivalent of a <script> in HTML.

// eval : (string) -> any
v =r.eval(src)

Meta-object protocol

A realm object can hook into the semantics of code evaluation using the three overrideable eval methods.

Indirect eval

The standard builtin eval function, when called indirectly as a first-class function, delegates to the indirectEval method to translate its source. For example:

A note on Function

The Function constructor doesn't need any special meta-object protocol, since it can be configured simply by replacing the global binding of Function and the value of Function.prototype.constructor to point to a new function. Similarly, the constructor for generator functions can be replaced by modifying Object.getPrototypeOf(function*(){}).constructor.