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 server to receive beam.call(...) messages; accepts any GenServer.server/0. This is the primary way to integrate Boam into a supervised application.
• :exports - map or keyword list of dispatch handlers when Boam starts its own convenience dispatcher
• :js_expose - nested tree of JavaScript shims to install on globalThis during startup
• :expose - legacy combined tree that configures both :exports and :js_expose
• :prelude - JavaScript source string or list of strings to evaluate during startup, after any generated exposure 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

In most applications you will manage your own dispatch process and pass it in through :dispatcher:

children = [
  {MyApp.JsDispatcher, name: MyApp.JsDispatcher},
  {Boam.Runtime,
   dispatcher: MyApp.JsDispatcher,
   js_expose: %{console: %{log: true}}}
]

The built-in dispatcher exists as convenience sugar. Register Elixir handlers with :exports and install JavaScript shims with :js_expose:

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

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

Dispatch handlers can also queue JS exposure at runtime by sending:

send(runtime, {:boam_expose_js, %{console: %{debug: true}}})

The message is applied after the current runtime operation completes, which avoids deadlocking a beam.call(...) handler.

Notes

• Avoid synchronously calling back into the same runtime from a dispatch handler before replying, or the call will deadlock. Use notify_expose_js/2 or send(runtime, {:boam_expose_js, tree}) from dispatch handlers instead.
• If you pass a named sibling dispatcher, use a supervisor strategy that restarts the runtime after the dispatcher restarts, because the runtime resolves the dispatcher to a pid during startup.
• Top-level JavaScript undefined is surfaced as {:ok, :undefined}.