BEAM Usage

View Source

Datastar BEAM is written in portable Erlang so Erlang, Elixir, Gleam, and other BEAM languages can call the same module.

Erlang

Event = datastar_beam:patch_signals(#{<<"message">> => <<"Hello from Erlang">>}),
io:put_chars(iolist_to_binary(Event)).

Cowboy adapters can stream the returned iodata from route handlers:

ping(_Req) ->
    [
        datastar_beam:patch_signals(#{<<"message">> => <<"Hello from Erlang">>})
    ].

Elixir

Elixir can call the Erlang module directly. When working from this repository, the smoke script can run against the compiled datastar_beam beam files:

elixir -pa _build/default/lib/datastar_beam/ebin examples/elixir_smoke.exs

event =
  :datastar_beam.patch_signals(%{
    "message" => "Hello from Elixir"
  })

IO.puts(IO.iodata_to_binary(event))

For a broader example with golden-style output and property-style checks over options and signal parsing, see examples/elixir_usage.exs.

An optional Elixir wrapper with typespecs is available at bindings/elixir/lib/datastar_beam.ex.

Gleam

Gleam can bind the same Erlang module with @external. When working from this repository, the smoke project can run with ERL_FLAGS pointing at the compiled datastar_beam beam files:

cd examples/gleam_smoke
ERL_FLAGS='-pa ../../_build/default/lib/datastar_beam/ebin' gleam run

import gleam/dynamic.{type Dynamic}
import gleam/io

@external(erlang, "datastar_beam", "patch_signals")
fn patch_signals(signals: String) -> Dynamic

@external(erlang, "erlang", "iolist_to_binary")
fn iolist_to_binary(iodata: Dynamic) -> String

pub fn main() {
  patch_signals("{\"message\":\"Hello from Gleam\"}")
  |> iolist_to_binary
  |> io.println
}

For a broader example with golden-style output and property-style checks over signal event generation, see examples/gleam_smoke/src/datastar_beam_usage.gleam.

An optional Gleam wrapper is available at bindings/gleam/src/datastar_beam.gleam.

Shared Contract

For all BEAM languages:

  • SDK functions return iodata.
  • Options can be maps or proplists.
  • Web-server-neutral functions live in datastar_beam.
  • Optional language wrappers can sit in application code or companion packages.
  • Web-server adapters own routing and streaming integration.
  • Template libraries only need to emit complete HTML fragments as iodata, strings, or common wrappers such as {safe, Iodata} / {ok, Iodata}. See docs/templating.md for HEEx, Nakai, and ErlyDTL examples.