Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

JavaScript "Sandboxes" for the web browser.

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
Octocat-spinner-32 Sandbox.js
Octocat-spinner-32 Sandbox.min.js
Octocat-spinner-32 build
Octocat-spinner-32 index.html
Octocat-spinner-32 test.js
README.md

SandboxJS

JavaScript "Sandboxes" for the web browser.

This script offers a very simple interface for JavaScript "Sandboxes". Underneath, it uses the magic power of iframes to create new execution scopes for JavaScript to be evaluated inside of.

This could potentially be used as the backbone for browser-side:

  • Isolated scope module loading (CommonJS could implemented on top of this).
  • Client-side HTML templates, with access to certain defined variables.
  • Defining custom JavaScript environments (APIs), then loading external script files that interact with the custom API (abstracting the browser/DOM away).

API

new Sandbox([bare:Boolean]) -> sandbox

Creates and returns new Sandbox instance. The bare parameter defaults to true, and determines whether or not the sandbox environment should attempt to have all it's extraneous browser/DOM objects removed from the scope. Setting this to false will keep functions like alert, and XMLHttpRequest available for use inside the sandbox.

sandbox.global -> Global

The global scope of the sandbox instance. This is a convenient way to share instances of Objects across scopes, or prepare the sandbox environment with properties that scripts can use (like a "require()" function).

sandbox.eval(jsStr:String) -> ?

Calls eval on the given String inside the sandbox. Variables declared inside the sandbox won't be accessible globally, and global variables won't be visible inside the sandbox. The result of the eval is returned.

sandbox.load(filename:String [, callback:function(err) {}])

Loads the JavaScript file filename and executes it into the sandbox. callback is an optional function that gets invoked when the file has finished loading and being evaluated, or an error occurs (like the file was not found).

sandbox.loadSync(filename:String)

Synchronously loads the JavaScript file filename and executes it into the sandbox. If there is an error while loading (like the file was not found), then this function will throw. This function is highly discouraged, since synchronous network activity blocks the browser, making it appear to freeze! Also, underneath this function uses XMLHttpRequests, which are restricted by the Same Origin Policy. In other words, this function will ONLY work with files from the SAME DOMAIN.

What Isn't SandboxJS?

  • Sandboxes are NOT seperate threads. All Sandbox instances share the same event-loop that the current page uses. As such, never block indefinitely; something like this WILL freeze your browser:

    (new Sandbox()).eval('while(1) {}');

  • Sandboxes are NOT prisons. Depending on the browser, there may be no way to eliminate access to the global scope. So follow the words of Isaac Schlueter: Prisons are designed to keep dangerous criminals. Sandboxes are for children to not get lost or hurt while playing. There are several ways to break out of the sandbox... DON'T!

Script Caching

The <iframe>s used internally seem to be stricter than the host page in regards to script caching. It is sometimes necessary to add appropriate no-cache headers to the HTTP response from your web server to mitigate this problem.

Testing from a file:// URI doesn't seems to share the same problem (scripts are always reloaded from disk as expected).

Something went wrong with that request. Please try again.