Execute ECMAScript code uniformly across any ECMAScript host environment. See also eshost-cli for an easy way to use this library from the command line.
Using eshost, you can create an agent (eg. a web browser or a command-line ECMAScript host) and evaluate scripts within that agent. Code running within the agent has access to the eshost runtime API which enables code to evaluate scripts, create new realms, handle errors, and so forth all without worrying about the host-specific mechanisms for these capabilities are.
eshost consists of a wrapper around the various ways of executing a host and processing its output (called an Agent) and a runtime library for host-agnostic scripts to use.
npm install eshost
|ch||Windows||Built from source||Chakra console host.|
|d8||Any||Built from source||v8 console host. Errors are reported on stdout. Use $.getGlobal and $.setGlobal to get and set properties of global objects in other realms.|
|jsshell||Any||Download||SpiderMonkey console host.|
|jsc||Mac||Built from source¹|
|nashorn||Any||Built from source|
|edge||Windows||Errors reported from Microsoft Edge are all of type Error. Requires Microsoft WebDriver in your path.|
|chrome||Any||Requires ChromeDriver in your path.|
|firefox||Any||Requires GeckoDriver in your path (possibly renamed to
|safari||Mac||Requires (SafariDriver browser extension)[https://github.com/SeleniumHQ/selenium/wiki/SafariDriver].|
1: Also available on your Mac system at
const esh = ;const agent = esh;const result = await agent;console;
An array of supported host types.
Gets an instance of a runner for a particular host type. See the table above for supported host types.
Initializes the host and returns a promise that is resolved once the host is initialized. Command line hosts have no initialization as a new process is started for each execution.
This is called for you if you use the createAgent factory.
code in the host using the Script goal symbol. Returns a promise for a result object.
By default, a script will run in Eshost until the realm is destroyed. For most command-line hosts, this is done automatically when the script execution queues are empty. However, browsers will remain open waiting for more code to become available. Therefore, eshost will automatically append
$.destroy() to the end of your scripts. This behavior is not correct if you are attempting to execute asynchronous code. In such cases, add
async: true to the options.
$.destroy()on the root realm when it's finished. When false, $.destroy() is added for you.
Stops the currently executing script. For a console host, this simply kills the child process. For browser hosts, it will kill the current window and create a new one.
Destroys the agent, closing any of its associated resources (eg. browser windows, child processes, etc.).
An object with the following keys:
The error object is similar to the error object you get in the host itself. Namely, it has the following keys:
Tears down the agent. For browsers, this will close the browser window.
str to stdout.
A reference to the global object.
Creates a new realm, returning that realm's runtime library ($).
For example, creating two nested realms:
$sub = $;$subsub = $sub;
You can also use a destroy callback that gets called when the code inside the realm calls
$.destroy(). For example:
$sub = $;$sub; // prints "destroyed!"
Creates a new script and evals
code in that realm. If an error is thrown, it will be passed to the onError callback.
Scripts are different from eval in that lexical bindings go into the global lexical contour rather than being scoped to the eval.
Destroys the realm. Note that in some hosts, $.destroy may not actually stop executing code in the realm or even destroy the realm.
Gets a global property name.
Sets a global property name to value.