High-level entrypoint for running JavaScript through Boa from Elixir.

Boam wraps a dedicated Boa runtime behind a GenServer. Each runtime owns a single Rust worker thread because Boa Context values are not thread-safe.

JavaScript code can call back into Elixir with beam.call(name, ...args). The dispatch itself happens through a separate BEAM process, which keeps the runtime process focused on driving the JavaScript engine.

You can either:

• pass your own dispatcher with :dispatcher
• install JavaScript shims with :js_expose
• register Elixir handlers with :exports when Boam manages the dispatcher
• use legacy combined config with :expose
• run startup JavaScript with :prelude
• generate shim code manually with Boam.JS.export_prelude/1

Quick Start

{:ok, _dispatcher} =
  MyApp.JsDispatcher.start_link(name: MyApp.JsDispatcher)

{:ok, runtime} =
  Boam.start_link(
    dispatcher: MyApp.JsDispatcher,
    js_expose: %{math: %{sum: true}}
  )

Boam.eval(runtime, "1 + 2")
#=> {:ok, 3}

Boam.eval(runtime, "math.sum(2, 3)")
#=> {:ok, 5}

The built-in dispatcher is available for simpler cases:

{:ok, runtime} =
  Boam.start_link(
    exports: %{
      "console.log" => fn [message] -> "logged: #{message}" end
    },
    js_expose: %{
      console: %{
        log: true
      }
    }
  )

Boam.eval(runtime, "console.log('hello')")
#=> {:ok, "logged: hello"}

Value Bridge

Values crossing between JavaScript and Elixir are intentionally restricted to JSON-compatible data:

• null maps to nil
• booleans, numbers, strings, arrays, and objects round-trip normally
• top-level JavaScript undefined is returned as :undefined
• undefined cannot be passed through beam.call/1

Returned JavaScript objects are serialized through Boa's JSON conversion, so object keys come back to Elixir as strings.

Architecture

• Boam.Runtime owns the Rust runtime resource
• Boam.Dispatcher receives beam.call(...) requests
• Boam.JS generates JavaScript shim preludes
• Boam provides the small public entrypoint for the common case