GenServer wrapper around a single Boa runtime.

Each Boam.Runtime process owns one Rust resource, and that resource owns one dedicated worker thread where the Boa engine actually runs. This keeps the JavaScript engine isolated from BEAM scheduler threads while still allowing synchronous eval/2 calls from Elixir.

Options

• :name - optional GenServer name for the runtime process
• :dispatcher - existing dispatcher pid to receive beam.call(...) messages; if omitted, a fresh Boam.Dispatcher process is started automatically
• :exports - map or keyword list of dispatch handlers when Boam starts its own dispatcher
• :expose - nested tree of handlers that should also be installed as JavaScript functions during startup
• :prelude - JavaScript source string or list of strings to evaluate during startup, after any generated :expose shims
• :fallback - optional (name, args -> result) function used when a dispatch name is not present in :exports
• :dispatch_timeout - timeout for a single beam.call(...) round-trip; defaults to 30_000, accepts :infinity

Dispatch Contract

JavaScript code may call:

beam.call("name", arg1, arg2)

The dispatcher receives the function name and arguments as JSON-compatible Elixir values and may reply with:

• any JSON-compatible value
• {:ok, value}
• {:error, reason}

Returning {:error, reason} raises a JavaScript error with reason as the message.

Exposing Functions

:expose lets you define nested JavaScript functions from Elixir:

expose: %{
  console: %{
    log: fn [message] -> "logged: #{message}" end,
    warn: {:dispatch, "logger.warn", fn [message] -> "warn: #{message}" end}
  }
}

This creates console.log(...) and console.warn(...) automatically.

If you already manage your own dispatcher process, use :prelude together with Boam.JS.export_prelude/1 instead of :expose.

Notes

• Avoid synchronously calling back into the same runtime from a dispatch handler before replying, or the call will deadlock.
• Top-level JavaScript undefined is surfaced as {:ok, :undefined}.