Packages

Boa-powered JavaScript runtimes for Elixir with BEAM dispatch hooks.

Current section

Files

Jump to
boam doc readme.html
Raw

doc/readme.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="ie=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="ExDoc v0.40.1">
    <meta name="project" content="boam v0.1.2">


    <title>Boam — boam v0.1.2</title>

    <link rel="stylesheet" href="dist/html-elixir-YJO4MOOW.css" />

    <script defer src="dist/sidebar_items-4C4FEE2F.js"></script>
    <script defer src="docs_config.js"></script>
    <script defer src="dist/html-YU4BZFVS.js"></script>

  </head>
  <body>
    <script>(()=>{var t="ex_doc:settings",e="dark";var o="dark",s="light";var E="sidebar_state",n="closed";var r="sidebar_width";var a="sidebar-open";var i=new URLSearchParams(window.location.search),S=i.get("theme")||JSON.parse(localStorage.getItem(t)||"{}").theme;(S===o||S!==s&&window.matchMedia("(prefers-color-scheme: dark)").matches)&&document.body.classList.add(e);var d=sessionStorage.getItem(E),A=d!==n&&!window.matchMedia(`screen and (max-width: ${768}px)`).matches;document.body.classList.toggle(a,A);var c=sessionStorage.getItem(r);c&&document.body.style.setProperty("--sidebarWidth",`${c}px`);var p=/(Macintosh|iPhone|iPad|iPod)/.test(window.navigator.userAgent);document.documentElement.classList.toggle("apple-os",p);})();
</script>

<div class="body-wrapper">

<button id="sidebar-menu" class="sidebar-button sidebar-toggle" aria-label="toggle sidebar" aria-controls="sidebar">
  <i class="ri-menu-line ri-lg" title="Collapse/expand sidebar"></i>
</button>

<nav id="sidebar" class="sidebar">

  <div class="sidebar-header">
    <div class="sidebar-projectInfo">

      <div>
        <a href="readme.html" class="sidebar-projectName" translate="no">
boam
        </a>
        <div class="sidebar-projectVersion" translate="no">
          v0.1.2
        </div>
      </div>
    </div>
    <ul id="sidebar-list-nav" class="sidebar-list-nav" role="tablist" data-extras="Pages"></ul>
  </div>
</nav>

<output role="status" id="toast"></output>

<main class="content page-extra" id="main" data-type="extras">
  <div id="content" class="content-inner">
    <div class="top-search">
      <div class="search-settings">
        <form class="search-bar" action="search.html">
          <label class="search-label">
            <span class="sr-only">Search documentation of boam</span>
            <div class="search-input-wrapper">
              <input name="q" type="text" class="search-input" placeholder="Press / to search" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" />
              <button type="button" tabindex="-1" class="search-close-button" aria-hidden="true">
                <i class="ri-close-line ri-lg" title="Cancel search"></i>
              </button>
            </div>
          </label>
        </form>
        <div class="autocomplete">
        </div>
        <div class="engine-selector" data-multiple="false">
          <button type="button" class="engine-button" aria-label="Select search engine" aria-haspopup="true" aria-expanded="false">
            <i class="ri-search-2-line" aria-hidden="true"></i>
            <span class="engine-name">Default</span>
            <i class="ri-arrow-down-s-line" aria-hidden="true"></i>
          </button>
          <div class="engine-dropdown" hidden role="menu">

              <button type="button"
                      class="engine-option"
                      data-engine-url="search.html?q="
                      role="menuitemradio"
                      aria-checked="true">
                <span class="name">Default</span>
                <span class="help">In-browser search</span>
              </button>

          </div>
        </div>
        <button class="icon-settings display-settings">
          <i class="ri-settings-3-line"></i>
          <span class="sr-only">Settings</span>
        </button>
      </div>
    </div>

<div id="top-content">
  <div class="heading-with-actions top-heading">
    <h1>Boam</h1>

<a href="readme.md" title="Copy Markdown (hold Ctrl/Cmd and click it to open as Markdown)" class="copy-markdown icon-action" rel="help">
  <i class="ri-markdown-line" aria-hidden="true"></i>
  <span class="sr-only">Copy Markdown</span>
</a>


  </div>


<p>Boam is an Elixir wrapper around the <a href="https://boajs.dev/">Boa</a> JavaScript
engine, implemented as a Rustler NIF.</p><p>The library starts a dedicated JavaScript runtime per Elixir process and lets
JavaScript call back into the BEAM through an explicit dispatch bridge.</p><h2 id="features" class="section-heading"><a href="#features" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Features</span></h2><ul><li>Boa-backed JavaScript evaluation from Elixir</li><li>Dedicated runtime thread per engine, matching Boa's thread-safety model</li><li><code class="inline">beam.call(name, ...args)</code> bridge from JavaScript into Elixir</li><li>JSON-compatible value round-tripping between JS and Elixir</li><li>Configurable dispatcher process for custom routing and supervision setups</li></ul><h2 id="installation" class="section-heading"><a href="#installation" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Installation</span></h2><p>Add <code class="inline">boam</code> to your list of dependencies in <code class="inline">mix.exs</code>:</p><pre><code class="makeup elixir" translate="no"><span class="kd">def</span><span class="w"> </span><span class="nf">deps</span><span class="w"> </span><span class="k" data-group-id="0183191264-1">do</span><span class="w">
  </span><span class="p" data-group-id="0183191264-2">[</span><span class="w">
    </span><span class="p" data-group-id="0183191264-3">{</span><span class="ss">:boam</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;~&gt; 0.1.0&quot;</span><span class="p" data-group-id="0183191264-3">}</span><span class="w">
  </span><span class="p" data-group-id="0183191264-2">]</span><span class="w">
</span><span class="k" data-group-id="0183191264-1">end</span></code></pre><h2 id="quick-start" class="section-heading"><a href="#quick-start" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Quick Start</span></h2><pre><code class="makeup elixir" translate="no"><span class="p" data-group-id="7816579948-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">runtime</span><span class="p" data-group-id="7816579948-1">}</span><span class="w"> </span><span class="o">=</span><span class="w">
  </span><span class="nc">Boam</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="7816579948-2">(</span><span class="w">
    </span><span class="ss">exports</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="7816579948-3">%{</span><span class="w">
      </span><span class="ss">sum</span><span class="p">:</span><span class="w"> </span><span class="k" data-group-id="7816579948-4">fn</span><span class="w"> </span><span class="p" data-group-id="7816579948-5">[</span><span class="n">left</span><span class="p">,</span><span class="w"> </span><span class="n">right</span><span class="p" data-group-id="7816579948-5">]</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">left</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">right</span><span class="w"> </span><span class="k" data-group-id="7816579948-4">end</span><span class="p">,</span><span class="w">
      </span><span class="ss">greet</span><span class="p">:</span><span class="w"> </span><span class="k" data-group-id="7816579948-6">fn</span><span class="w"> </span><span class="p" data-group-id="7816579948-7">[</span><span class="n">name</span><span class="p" data-group-id="7816579948-7">]</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="s">&quot;hello </span><span class="si" data-group-id="7816579948-8">#{</span><span class="n">name</span><span class="si" data-group-id="7816579948-8">}</span><span class="s">&quot;</span><span class="w"> </span><span class="k" data-group-id="7816579948-6">end</span><span class="w">
    </span><span class="p" data-group-id="7816579948-3">}</span><span class="w">
  </span><span class="p" data-group-id="7816579948-2">)</span><span class="w">

</span><span class="nc">Boam</span><span class="o">.</span><span class="n">eval</span><span class="p" data-group-id="7816579948-9">(</span><span class="n">runtime</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;1 + 2&quot;</span><span class="p" data-group-id="7816579948-9">)</span><span class="w">
</span><span class="c1">#=&gt; {:ok, 3}</span><span class="w">

</span><span class="nc">Boam</span><span class="o">.</span><span class="n">eval</span><span class="p" data-group-id="7816579948-10">(</span><span class="n">runtime</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;beam.call(&#39;sum&#39;, 2, 3)&quot;</span><span class="p" data-group-id="7816579948-10">)</span><span class="w">
</span><span class="c1">#=&gt; {:ok, 5}</span><span class="w">

</span><span class="nc">Boam</span><span class="o">.</span><span class="n">eval</span><span class="p" data-group-id="7816579948-11">(</span><span class="n">runtime</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;beam.call(&#39;greet&#39;, &#39;Ada&#39;)&quot;</span><span class="p" data-group-id="7816579948-11">)</span><span class="w">
</span><span class="c1">#=&gt; {:ok, &quot;hello Ada&quot;}</span></code></pre><h2 id="startup-prelude" class="section-heading"><a href="#startup-prelude" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Startup Prelude</span></h2><p>Run JavaScript during runtime startup with <code class="inline">prelude:</code>:</p><pre><code class="makeup elixir" translate="no"><span class="p" data-group-id="1658605572-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">runtime</span><span class="p" data-group-id="1658605572-1">}</span><span class="w"> </span><span class="o">=</span><span class="w">
  </span><span class="nc">Boam</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="1658605572-2">(</span><span class="w">
    </span><span class="ss">prelude</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="1658605572-3">[</span><span class="w">
      </span><span class="s">&quot;globalThis.appName = &#39;boam&#39;;&quot;</span><span class="p">,</span><span class="w">
      </span><span class="s">&quot;globalThis.version = 1;&quot;</span><span class="w">
    </span><span class="p" data-group-id="1658605572-3">]</span><span class="w">
  </span><span class="p" data-group-id="1658605572-2">)</span></code></pre><p>Those snippets run before your first call to <a href="Boam.html#eval/2"><code class="inline">Boam.eval/2</code></a>.</p><h2 id="automatic-function-exposure" class="section-heading"><a href="#automatic-function-exposure" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Automatic Function Exposure</span></h2><p>If you want JavaScript functions like <code class="inline">console.log(...)</code> without writing wrapper
code by hand, use <code class="inline">expose:</code>:</p><pre><code class="makeup elixir" translate="no"><span class="p" data-group-id="8817996065-1">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">runtime</span><span class="p" data-group-id="8817996065-1">}</span><span class="w"> </span><span class="o">=</span><span class="w">
  </span><span class="nc">Boam</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="8817996065-2">(</span><span class="w">
    </span><span class="ss">expose</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="8817996065-3">%{</span><span class="w">
      </span><span class="ss">console</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="8817996065-4">%{</span><span class="w">
        </span><span class="ss">log</span><span class="p">:</span><span class="w"> </span><span class="k" data-group-id="8817996065-5">fn</span><span class="w"> </span><span class="p" data-group-id="8817996065-6">[</span><span class="n">message</span><span class="p" data-group-id="8817996065-6">]</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="s">&quot;logged: </span><span class="si" data-group-id="8817996065-7">#{</span><span class="n">message</span><span class="si" data-group-id="8817996065-7">}</span><span class="s">&quot;</span><span class="w"> </span><span class="k" data-group-id="8817996065-5">end</span><span class="p">,</span><span class="w">
        </span><span class="ss">warn</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="8817996065-8">{</span><span class="ss">:dispatch</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;logger.warn&quot;</span><span class="p">,</span><span class="w"> </span><span class="k" data-group-id="8817996065-9">fn</span><span class="w"> </span><span class="p" data-group-id="8817996065-10">[</span><span class="n">message</span><span class="p" data-group-id="8817996065-10">]</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="s">&quot;warn: </span><span class="si" data-group-id="8817996065-11">#{</span><span class="n">message</span><span class="si" data-group-id="8817996065-11">}</span><span class="s">&quot;</span><span class="w"> </span><span class="k" data-group-id="8817996065-9">end</span><span class="p" data-group-id="8817996065-8">}</span><span class="w">
      </span><span class="p" data-group-id="8817996065-4">}</span><span class="w">
    </span><span class="p" data-group-id="8817996065-3">}</span><span class="w">
  </span><span class="p" data-group-id="8817996065-2">)</span><span class="w">

</span><span class="nc">Boam</span><span class="o">.</span><span class="n">eval</span><span class="p" data-group-id="8817996065-12">(</span><span class="n">runtime</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;console.log(&#39;hello&#39;)&quot;</span><span class="p" data-group-id="8817996065-12">)</span><span class="w">
</span><span class="c1">#=&gt; {:ok, &quot;logged: hello&quot;}</span></code></pre><p>Leaf dispatch names default to the dot-joined path, so <code class="inline">console.log</code> dispatches
to <code class="inline">&quot;console.log&quot;</code> unless you override it with
<code class="inline">{:dispatch, &quot;custom.name&quot;, handler}</code>.</p><h2 id="manual-shim-generation" class="section-heading"><a href="#manual-shim-generation" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Manual Shim Generation</span></h2><p>If you want to keep dispatch setup separate from runtime startup, generate the
shim code yourself:</p><pre><code class="makeup elixir" translate="no"><span class="n">prelude</span><span class="w"> </span><span class="o">=</span><span class="w">
  </span><span class="nc">Boam.JS</span><span class="o">.</span><span class="n">export_prelude</span><span class="p" data-group-id="5960441428-1">(</span><span class="p" data-group-id="5960441428-2">%{</span><span class="w">
    </span><span class="ss">console</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="5960441428-3">%{</span><span class="w">
      </span><span class="ss">log</span><span class="p">:</span><span class="w"> </span><span class="no">true</span><span class="p">,</span><span class="w">
      </span><span class="ss">error</span><span class="p">:</span><span class="w"> </span><span class="p" data-group-id="5960441428-4">{</span><span class="ss">:dispatch</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;logger.error&quot;</span><span class="p" data-group-id="5960441428-4">}</span><span class="w">
    </span><span class="p" data-group-id="5960441428-3">}</span><span class="w">
  </span><span class="p" data-group-id="5960441428-2">}</span><span class="p" data-group-id="5960441428-1">)</span><span class="w">

</span><span class="p" data-group-id="5960441428-5">{</span><span class="ss">:ok</span><span class="p">,</span><span class="w"> </span><span class="n">runtime</span><span class="p" data-group-id="5960441428-5">}</span><span class="w"> </span><span class="o">=</span><span class="w">
  </span><span class="nc">Boam</span><span class="o">.</span><span class="n">start_link</span><span class="p" data-group-id="5960441428-6">(</span><span class="w">
    </span><span class="ss">prelude</span><span class="p">:</span><span class="w"> </span><span class="n">prelude</span><span class="p">,</span><span class="w">
    </span><span class="ss">fallback</span><span class="p">:</span><span class="w"> </span><span class="k" data-group-id="5960441428-7">fn</span><span class="w"> </span><span class="n">name</span><span class="p">,</span><span class="w"> </span><span class="n">args</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="p" data-group-id="5960441428-8">{</span><span class="n">name</span><span class="p">,</span><span class="w"> </span><span class="n">args</span><span class="p" data-group-id="5960441428-8">}</span><span class="w"> </span><span class="k" data-group-id="5960441428-7">end</span><span class="w">
  </span><span class="p" data-group-id="5960441428-6">)</span></code></pre><h2 id="value-model" class="section-heading"><a href="#value-model" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Value Model</span></h2><p>Boam intentionally restricts the bridge to JSON-compatible values:</p><ul><li>JavaScript <code class="inline">null</code> maps to Elixir <code class="inline">nil</code></li><li>booleans, numbers, strings, arrays, and objects round-trip normally</li><li>top-level JavaScript <code class="inline">undefined</code> becomes <code class="inline">{:ok, :undefined}</code></li><li><code class="inline">undefined</code> is rejected when passed through <code class="inline">beam.call(...)</code></li><li>JavaScript object keys come back as strings</li></ul><p>For predictable round-tripping, return Elixir maps with string keys from
dispatch handlers.</p><h2 id="dispatching-into-elixir" class="section-heading"><a href="#dispatching-into-elixir" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Dispatching Into Elixir</span></h2><p>JavaScript code can call:</p><pre><code class="javascript">beam.call(&quot;name&quot;, arg1, arg2)</code></pre><p>That request is delivered to a <a href="Boam.Dispatcher.html"><code class="inline">Boam.Dispatcher</code></a> process on the BEAM side. A
handler can return:</p><ul><li>any JSON-compatible value</li><li><code class="inline">{:ok, value}</code></li><li><code class="inline">{:error, reason}</code></li></ul><p>If a handler crashes, the JavaScript caller receives an error instead of
hanging forever.</p><h2 id="architecture" class="section-heading"><a href="#architecture" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Architecture</span></h2><ul><li><a href="Boam.html"><code class="inline">Boam</code></a> is the small public entrypoint</li><li><a href="Boam.Runtime.html"><code class="inline">Boam.Runtime</code></a> owns the NIF resource and runtime lifecycle</li><li><a href="Boam.Dispatcher.html"><code class="inline">Boam.Dispatcher</code></a> resolves and executes <code class="inline">beam.call(...)</code> handlers</li><li><a href="Boam.JS.html"><code class="inline">Boam.JS</code></a> generates JavaScript shim preludes from nested export trees</li><li>the internal NIF bridge module is intentionally hidden from the generated docs</li></ul><h2 id="generating-docs" class="section-heading"><a href="#generating-docs" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i></a><span class="text">Generating Docs</span></h2><p>Generate the docs locally with:</p><pre><code class="makeup bash" translate="no"><span class="">mix docs
</span></code></pre><p>The generated site will be written to <code class="inline">doc/</code>.</p>

</div>

<div class="bottom-actions" id="bottom-actions">
  <div class="bottom-actions-item">

  </div>
  <div class="bottom-actions-item">

  </div>
</div>
    <footer class="footer">

        <p>

            <span class="line">
              <a href="https://hex.pm/packages/boam/0.1.2">Hex Package</a>

              <a href="https://preview.hex.pm/preview/boam/0.1.2">Hex Preview</a>

                (<a href="https://preview.hex.pm/preview/boam/0.1.2/show/README.md">current file</a>)

            </span>

          <span class="line">
            <button class="a-main footer-button display-quick-switch" title="Go to package docs">
              Go to package docs
            </button>

              <a href="llms.txt" target="_blank">
                View llms.txt
              </a>


              <a href="boam.epub">
                Download ePub version
              </a>

          </span>
        </p>

        <p class="built-using">
          Built using
          <a href="https://github.com/elixir-lang/ex_doc" title="ExDoc" target="_blank" rel="help noopener" translate="no">ExDoc</a> (v0.40.1) for the

            <a href="https://elixir-lang.org" title="Elixir" target="_blank" translate="no">Elixir programming language</a>

        </p>


    </footer>
  </div>
</main>
</div>

  </body>
</html>