Portals.JavaScript (portals_javascript v0.1.0)

Copy Markdown View Source

Run JavaScript workers under Portals, on Node.js, Bun, Deno or QuickJS.

This package bundles one dependency-free JavaScript worker SDK (the portals-worker module) and makes require('portals-worker') resolve to it on every runtime, so the same CommonJS worker script runs on all four. Nothing is installed with npm.

children = [
  {Portals.Pool,
   Portals.JavaScript.worker_opts(
     script: Application.app_dir(:my_app, "priv/js/worker.js"),
     runtime: :bun,
     name: MyApp.JS,
     size: 4
   )}
]
:runtimeExecutableHow the SDK is foundTransport
:node (default)nodeNODE_PATHUnix socket
:bunbunNODE_PATHUnix socket
:denodeno runa preloaded resolve hook (--require), with --unstable-detect-cjsUnix socket
:quickjsqjsthe bundled QuickJS host, which provides the Node APIs the SDK needsframed stdio

See the JavaScript guide for a full walkthrough and each runtime's trade-offs.

Summary

Functions

runtimes()

The supported runtimes.

sdk_path()

Absolute path to the bundled portals-worker SDK.

worker_opts(opts)

Build Portals.start_worker/1 / Portals.start_pool/1 options for a JavaScript worker script.

Functions

runtimes()

@spec runtimes() :: [atom()]

The supported runtimes.

sdk_path()

Absolute path to the bundled portals-worker SDK.

worker_opts(opts)

Build Portals.start_worker/1 / Portals.start_pool/1 options for a JavaScript worker script.

Options

  • :script (required) — path to the worker entry script, which calls new Worker({...}).run().
  • :runtime — :node (default), :bun, :deno or :quickjs.
  • :executable — the runtime's binary, as a name looked up on PATH or a path. Defaults to node, bun, deno or qjs.
  • :runtime_args — runtime flags placed before the script, e.g. ["--max-old-space-size=512"] for Node.js.
  • :deno_permissions — Deno permission flags. Defaults to ["--allow-all"]; the SDK itself needs --allow-read, --allow-write, --allow-env and --allow-net (Deno counts connecting to the Unix socket as network access).
  • :args — arguments passed to the script. Portals appends the socket path after these, as the last argument.
  • :env — extra {name, value} environment entries; these win over the ones set here.

Every other option is passed through unchanged. For :quickjs the worker always uses the framed stdio transport (transport: :stdio), because QuickJS has no socket API.