ScriptEngine Class

Gets whether a script is running, i.e. whether the JavaScript execution context stack is not empty. The library performs a microtask checkpoint after running a script or a callback only when no script is running (https://html.spec.whatwg.org/multipage/webappapis.html#clean-up-after-running-script).

Gets whether the engine supports the module scripts (<script type="module">, import()). When it is false (the default), the module scripts are not fetched nor run.

Compiles the value of an event handler content attribute (e.g. onclick="..."), the first time the event handler is used (https://html.spec.whatwg.org/multipage/webappapis.html#getting-the-current-value-of-the-event-handler).

Creates the realm whose global object is global (https://html.spec.whatwg.org/multipage/document-sequences.html#creating-a-new-browsing-context). It is called when a new window is created for a browsing context, before its document becomes the active document, and when the script of a worker is fetched (on the thread of the worker, with the engine returned by ScriptEngine.CreateWorkerScriptEngine). An engine may create the realm lazily, when a script first runs in it.

Creates the script engine of a new worker (https://html.spec.whatwg.org/multipage/workers.html#run-a-worker): each dedicated or shared worker is a new agent, whose event loop runs on its own thread, so it needs its own engine. The method is called on the thread of the worker, before ScriptEngine.CreateRealm is called with the WorkerGlobalScope of the worker; the engine is then only used on that thread, and is disposed (when it implements IDisposable) when the worker ends.

Called when the browsing context of a window is discarded (e.g. its iframe is removed from the document, or it navigates to another document), or when a worker ends: the realm no longer runs scripts, and the engine may release it.

Enters a separate microtask queue: until the returned scope is disposed, the jobs of the engine and the microtasks queued with ScriptEngine.QueueMicrotask go to a new queue, which ScriptEngine.PerformMicrotaskCheckpoint runs; the microtasks that were pending are kept, and are not run in the scope. The scopes nest. A script is considered running in the scope (ScriptEngine.IsScriptRunning): the callbacks invoked in it perform no microtask checkpoint.

Runs a classic script (https://html.spec.whatwg.org/multipage/webappapis.html#run-a-classic-script) in the realm of ClassicScript.Global. The library owns the ordering of the scripts and the "clean up after running script" steps: the engine only evaluates the code.

Runs a module script (https://html.spec.whatwg.org/multipage/webappapis.html#run-a-module-script): links and evaluates the module graph, and reports the error to rethrow or the evaluation errors (including the errors of a top-level await) to the global object.

Extracts the information of an exception (https://html.spec.whatwg.org/multipage/webappapis.html#extract-error): its message, the location of the script, and the value of the error attribute of the ErrorEvent.

Fetches the graph of an external module script ("fetch a module script graph", https://html.spec.whatwg.org/multipage/webappapis.html#fetch-a-module-script-tree): the root is fetched ("fetch a single module script"), then its descendants are loaded. onComplete is called with the module script, or with null when a module of the graph cannot be fetched. A parse error is stored in ModuleScript.ErrorToRethrow.

Returns the base URL of the active script (https://html.spec.whatwg.org/multipage/webappapis.html#active-script), or null when no script is running: the base URL of the strings compiled by setTimeout() and setInterval().

Returns the fetch options of the active script (https://html.spec.whatwg.org/multipage/webappapis.html#active-script), or null when no script is running: the options of the modules imported by import() in a classic script.

Returns the global object of the current realm (https://tc39.es/ecma262/#current-realm), or null when no script is running: the realm of the running function (e.g. the realm of a promise job, which has no entry settings object in the library).

Returns the location of the code that is running (the source file, line and column of the innermost running script), or null when no script is running or when the engine cannot extract it: the source location of the violations of the content security policies (https://w3c.github.io/webappsec-csp/#create-violation-for-global, step 2).

Gets whether a promise has a handler (its [[PromiseIsHandled]] internal slot). The promises rejected without handler are given to GlobalScope.TrackPromiseRejection by the engine.

Parses a module script and loads its descendants ("fetch the descendants of and link a module script", https://html.spec.whatwg.org/multipage/webappapis.html#fetch-the-descendants-of-and-link-a-module-script): the engine resolves the module specifiers and fetches the modules with the library. onComplete is called once the graph is loaded, with true, or with false when a module of the graph cannot be fetched (the script element then fires an error event). A parse error is stored in ModuleScript.ErrorToRethrow.

Called when the document-tree child navigables of the document of a window change (an iframe is inserted or removed): the indexed properties of the WindowProxy (window[0]) changed (https://html.spec.whatwg.org/multipage/nav-history-apis.html#windowproxy-getownproperty).

Called when a document becomes the active document of its browsing context, before it is parsed. The window of the document may be a new window (see ScriptEngine.CreateRealm), or the window of the initial about:blank document, which is reused by a same-origin document.

Parses a classic script (https://html.spec.whatwg.org/multipage/webappapis.html#creating-a-classic-script) without running it: returns the error to rethrow of a script that cannot be parsed (e.g. the SyntaxError of a worker script, which fires an error event at the Worker object instead of being reported), or null.

Runs the jobs of the engine and the microtasks queued with ScriptEngine.QueueMicrotask until the queue is empty (https://html.spec.whatwg.org/multipage/webappapis.html#perform-a-microtask-checkpoint). The exceptions of the jobs are reported by the engine.

Fetches a module script without loading its descendants nor running it ("fetch a modulepreload module script graph", https://html.spec.whatwg.org/multipage/webappapis.html#fetch-a-modulepreload-module-script-graph): the module of a <link rel=modulepreload> element. onComplete is called with true when the module is fetched (even when it has a parse error), or with false when it cannot be fetched.

https://html.spec.whatwg.org/multipage/webappapis.html#prepare-to-run-script: the JavaScript execution context stack is not empty until the returned scope is disposed, which cleans up after running script (a microtask checkpoint when the stack becomes empty). The callbacks invoked in the scope do not perform a microtask checkpoint.

Queues a microtask of the library (e.g. a mutation observer notification) in the job queue of the engine, so that the microtasks of the library and the jobs of the engine (promise reactions) run in order (https://html.spec.whatwg.org/multipage/webappapis.html#queue-a-microtask).

Deserializes a value serialized by ScriptEngine.StructuredSerialize in the realm of global (https://html.spec.whatwg.org/multipage/structured-data.html#structureddeserialize): the result is a new value of the realm (e.g. the MessageEvent.Data of the message events).

Serializes a value for another agent (https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializewithtransfer), e.g. a message posted to a worker or to a MessagePort: the result is given to ScriptEngine.StructuredDeserialize of another engine instance, on another thread, so it must not reference the values of this engine. The objects of transferList are transferred: the ArrayBuffer objects of the engine, and the MessagePort objects.

Serializes a value for storage (https://html.spec.whatwg.org/multipage/structured-data.html#structuredserializeforstorage), e.g. the state of History.PushState: a SharedArrayBuffer throws a DataCloneError.

Runs the success steps once all the values are fulfilled promises, or the failure steps with the reason of the first rejected one (https://webidl.spec.whatwg.org/#wait-for-all). The values are values of the engine, resolved as promises of the realm of global, or RejectedPromise for a promise rejected with an exception.