Experimental
Create JavaScript sandboxes and execute scripts in them.
Usage
Create a sandbox
To create a sandbox:
const { sandbox, evaluate, load } = require("sdk/loader/sandbox");
let scope = sandbox('http://example.com');
The argument passed to the sandbox defines its privileges. The argument may be:
- a URL string, in which case the sandbox will get the same privileges as a script loaded from that URL
- a DOM window object, to inherit privileges from the window being passed.
- omitted or
null: then the sandbox will have chrome privileges giving it access to all the XPCOM components.
Optionally the sandbox function can be passed a second argument (See sandbox documentation on MDN for details).
Evaluate code
Module provides evaluate function that lets you execute code in the given sandbox:
evaluate(scope, 'var a = 5;'); evaluate(scope, 'a + 2;'); //=> 7
More details about evaluated script may be passed via optional arguments that may improve exception reporting:
// Evaluate code as if it was loaded from 'http://foo.com/bar.js' and // start from 2nd line. evaluate(scope, 'a ++', 'http://foo.com/bar.js', 2);
Version of JavaScript can be also specified via an optional argument:
evaluate(scope, 'let b = 2;', 'bar.js', 1, '1.5'); // throws cause `let` is not defined in JS 1.5.
Load scripts
This module provides a limited API for loading scripts from local URLs. data: URLs are supported.
load(scope, 'resource://path/to/my/script.js'); load(scope, 'file:///path/to/script.js'); load(scope, 'data:,var a = 5;');
Globals
Functions
sandbox(source)
Make a new sandbox that inherits principals from source.
Parameters
source : string|window|null
An object that determines the privileges that will be given to the sandbox. This argument can be:
- a URI string, giving the sandbox the same privileges as a script loaded from that URL
- a DOM window object, giving the sandbox the same privileges as the DOM window
null, to give the sandbox chrome privileges.
Returns
sandbox : A sandbox in which you can evaluate and load JavaScript.
evaluate(sandbox, code, uri, line, version)
Evaluate code in sandbox, and return the result.
Parameters
sandbox : sandbox
The sandbox to use.
code : string
The code to execute.
uri : string
Evaluate the code as if it were being loaded from the given URI. Optional.
line : number
Evaluate the code starting at this line. Optional, defaults to 1.
version : string
Evaluate the code using this version of JavaScript. Defaults to 1.8.
Returns
result : Returns whatever the evaluated code returns.
load(sandbox, uri)
Evaluate code from uri in sandbox.
Parameters
sandbox : sandbox
The sandbox to use.
uri : string
The URL pointing to the script to load. It must be a local chrome:, resource:, file: or data: URL.
Returns
result : Returns whatever the evaluated code returns.
