@earendil-works/djs

djs is a small JavaScript and TypeScript engine compiled to WebAssembly, made for running untrusted scripts inside a host: agent tool scripts, plugins, user code. Every sandbox is its own wasm instance with its own heap, so sandboxes share nothing. Scripts get only the host functions you give them, run under a fuel budget and a memory cap, and a run that waits on the host can be suspended into a dump, a plain JavaScript file, and continued later in another process.

The module has no imports and the package no dependencies: it runs in node (20 or newer), Bun, Deno, browsers and web workers.

Install

npm install @earendil-works/djs

Use

import { Sandbox } from "@earendil-works/djs";

const sandbox = await Sandbox.create({
  asyncFunctions: { "tools.search": async (q) => search(q) },
  maxFuel: 50_000_000,
  memoryLimit: 64 << 20,
});

// A script is the body of an async function: its parameters are the keys of the second
// argument, and `await` and `return` work at the top level.
const hits = await sandbox.runAsync("return (await tools.search(query)).slice(0, 3)", { query: "djs" });
sandbox.run("return a + b", { a: 40, b: 2 }); // 42
sandbox.dispose();

Options include typescript: true (scripts are TypeScript), console (where console.log goes), globals, deterministic (repeatable runs) and frozenBuiltins. Errors are SandboxErrors with a kind: threw, syntax, fuel, memory, ...

Entry points

| import | module | for | | --- | --- | --- | | @earendil-works/djs | wasm/djs.wasm | every host | | @earendil-works/djs/slim | wasm/djs-slim.wasm | hosts that count kilobytes: no typed arrays, BigInt, iterator helpers and other families scripts rarely use | | @earendil-works/djs/dump | wasm/djs-dump.wasm | hosts that suspend runs into dumps: the main module plus the dumper | | @earendil-works/djs/dump-runtime | | the helpers a dump needs to continue in a JavaScript engine other than djs |

Each entry point exports the same API, with its own module as the default. To dump runs while running them in the smaller main module, give the sandbox the dump module as its dumpModule:

import { Sandbox } from "@earendil-works/djs";
import { loadModule as loadDumpModule } from "@earendil-works/djs/dump";

const sandbox = await Sandbox.create({ frozenBuiltins: true, dumpModule: await loadDumpModule(), asyncFunctions });
const task = sandbox.start(code, params);
const dump = await task.suspend(); // later, anywhere: (await Sandbox.resume(dump, options)).result

Loading the module

Sandbox.create loads its entry point's module once per process and caches it; loadModule(location) loads another one and new Sandbox({ module }) uses it. In node, Bun and Deno the module is read from the package's wasm/ directory ($DJS_WASM names another main module). In a browser it is fetched from the URL new URL("../wasm/djs.wasm", import.meta.url), a pattern that webpack and Vite recognize and copy into the build. In Vite's dev server, exclude the package from dependency pre-bundling, which would move the code away from its modules:

// vite.config.js
export default { optimizeDeps: { exclude: ["@earendil-works/djs"] } };

In Deno, allow reading the package's directory (--allow-read). With a bundler that does not know the pattern, serve the .wasm file yourself and pass its URL: Sandbox.create({ module: await loadModule("/assets/djs.wasm") }).

Documentation

The guide, with the whole API, the language djs runs, limits, determinism and dumps: https://earendil-works.github.io/djs/js-api.html

License

MIT or Apache-2.0, at your option.