Add :define option, quickbeam-types npm package, fix script init deadlock

:define option — inject globals into JS runtime before script runs,
using the native beam_to_js converter (no JSON roundtrip). Values are
set via a new define_global NIF that calls JS_SetPropertyStr on the
QuickJS global object.

Script loading moved to handle_continue — scripts that use Beam.callSync
(fs, path, process.env, etc.) no longer deadlock during GenServer init.
The start_link caller waits for a :script_loaded message, preserving
synchronous error reporting for script failures.

Bundler fix: pass import specifiers (not absolute paths) as filenames
to OXC so its topo-sort correctly orders dependencies before entry code.

npm/quickbeam-types — types package for the Beam API globals, with
@types/node as peer dependency for Node API coverage. Example updated
to use `/// <reference types="quickbeam-types" />` and real imports.

Author: dannote

examples/static-site/README.md

@@ -34,15 +34,18 @@ Open `_site/index.html` in a browser.
 
 ## How it works
 
-**`priv/ts/build.ts`** — TypeScript with a real npm import:
+**`priv/ts/build.ts`** — TypeScript with real npm imports and Node APIs:
 
 ```typescript
 import { marked } from "marked"
+import fs from "node:fs"
+import path from "node:path"
 
 const files = fs.readdirSync(contentDir).filter(f => f.endsWith(".md"))
 for (const file of files) {
   const html = marked.parse(body)
   fs.writeFileSync(path.join(outputDir, `${slug}.html`), page)
+  console.log(`  ${slug}.html → ${meta.title}`)
 }
 ```
 
@@ -52,13 +55,8 @@ for (const file of files) {
 {:ok, rt} = QuickBEAM.start(
   script: "priv/ts/build.ts",
   apis: [:browser, :node],
-  handlers: %{
-    "log" => fn [%{"slug" => slug, "title" => title}] ->
-      IO.puts("  #{slug}.html → #{title}")
-    end
-  }
+  define: %{"contentDir" => "priv/content", "outputDir" => "_site"}
 )
-QuickBEAM.send_message(rt, %{contentDir: "priv/content", outputDir: "_site"})
 ```
 
 ## What replaces what

examples/static-site/build.exs

@@ -1,16 +1,13 @@
 content_dir = Path.join(__DIR__, "priv/content")
 output_dir = Path.join(__DIR__, "_site")
 
+script = Path.join(__DIR__, "priv/ts/build.ts") |> Path.expand()
+{:ok, code} = QuickBEAM.JS.Bundler.bundle_file(script)
+
 {:ok, rt} =
   QuickBEAM.start(
-    script: Path.join(__DIR__, "priv/ts/build.ts"),
     apis: [:browser, :node],
-    handlers: %{
-      "log" => fn [%{"slug" => slug, "title" => title}] ->
-        IO.puts("  #{slug}.html → #{title}")
-      end
-    }
+    define: %{"contentDir" => content_dir, "outputDir" => output_dir}
   )
 
-QuickBEAM.send_message(rt, %{contentDir: content_dir, outputDir: output_dir})
-Process.sleep(1000)
+{:ok, _} = QuickBEAM.eval(rt, code)

examples/static-site/package-lock.json

@@ -2,5 +2,9 @@
   "private": true,
   "dependencies": {
     "marked": "^15.0.0"
+  },
+  "devDependencies": {
+    "quickbeam-types": "file:../../npm/quickbeam-types",
+    "@types/node": "^22.0.0"
   }
 }

examples/static-site/package.json

@@ -1,12 +1,10 @@
+/// <reference types="quickbeam-types" />
 import { marked } from "marked"
+import fs from "node:fs"
+import path from "node:path"
 
-const { fs, path } = globalThis as any
-
-declare const Beam: {
-  call(name: string, data?: unknown): void
-  callSync(name: string, data?: unknown): any
-  onMessage(handler: (msg: any) => void): void
-}
+declare const contentDir: string
+declare const outputDir: string
 
 interface FrontMatter {
   title: string
@@ -84,30 +82,26 @@ function renderIndex(posts: { slug: string; title: string; date: string }[]): st
 </html>`
 }
 
-Beam.onMessage((config: { contentDir: string; outputDir: string }) => {
-  const { contentDir, outputDir } = config
-
-  fs.mkdirSync(outputDir, { recursive: true })
+fs.mkdirSync(outputDir, { recursive: true })
 
-  const files = fs.readdirSync(contentDir).filter((f: string) => f.endsWith(".md"))
-  const posts: { slug: string; title: string; date: string }[] = []
+const files = fs.readdirSync(contentDir).filter((f: string) => f.endsWith(".md"))
+const posts: { slug: string; title: string; date: string }[] = []
 
-  for (const file of files) {
-    const source = fs.readFileSync(path.join(contentDir, file), "utf-8")
-    const { meta, body } = parseFrontMatter(source)
+for (const file of files) {
+  const source = fs.readFileSync(path.join(contentDir, file), "utf-8")
+  const { meta, body } = parseFrontMatter(source)
 
-    if (meta.draft === "true" || meta.draft === true) continue
+  if (String(meta.draft) === "true") continue
 
-    const slug = path.basename(file, ".md")
-    const html = marked.parse(body) as string
-    const page = renderPage(meta.title, html)
+  const slug = path.basename(file, ".md")
+  const html = marked.parse(body) as string
+  const page = renderPage(meta.title, html)
 
-    fs.writeFileSync(path.join(outputDir, `${slug}.html`), page)
-    posts.push({ slug, title: meta.title, date: meta.date || "undated" })
+  fs.writeFileSync(path.join(outputDir, `${slug}.html`), page)
+  posts.push({ slug, title: meta.title, date: meta.date || "undated" })
 
-    Beam.call("log", { slug, title: meta.title })
-  }
+  console.log(`  ${slug}.html → ${meta.title}`)
+}
 
-  fs.writeFileSync(path.join(outputDir, "index.html"), renderIndex(posts))
-  Beam.call("log", { slug: "index", title: `Index (${posts.length} posts)` })
-})
+fs.writeFileSync(path.join(outputDir, "index.html"), renderIndex(posts))
+console.log(`  index.html → Index (${posts.length} posts)`)

examples/static-site/priv/ts/build.ts

@@ -15,13 +15,10 @@ defmodule StaticSiteTest do
       QuickBEAM.start(
         script: Path.join(__DIR__, "../priv/ts/build.ts") |> Path.expand(),
         apis: [:browser, :node],
-        handlers: %{
-          "log" => fn _ -> :ok end
-        }
+        define: %{"contentDir" => @content_dir, "outputDir" => output_dir}
       )
 
-    QuickBEAM.send_message(rt, %{contentDir: @content_dir, outputDir: output_dir})
-    Process.sleep(2000)
+    Process.sleep(500)
 
     assert File.exists?(Path.join(output_dir, "index.html"))
     assert File.exists?(Path.join(output_dir, "hello-world.html"))
@@ -37,5 +34,7 @@ defmodule StaticSiteTest do
     assert index =~ "hello-world.html"
     assert index =~ "beam-vs-node.html"
     refute index =~ "draft-post"
+
+    QuickBEAM.stop(rt)
   end
 end

examples/static-site/test/static_site_test.exs

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "strict": true,
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "noEmit": true
+  },
+  "include": ["priv/ts/**/*.ts"]
+}

examples/static-site/tsconfig.json

@@ -74,6 +74,11 @@ defmodule QuickBEAM do
       * `:node` — Node.js compat (process, path, fs, os)
       * `[:browser, :node]` — both
       * `false` — bare QuickJS engine, no polyfills
+    * `:define` — `%{String.t() => term()}` of globals to inject before the script runs.
+      Values are JSON-encoded. Useful for passing config without `Beam.callSync`.
+
+          QuickBEAM.start(script: "build.ts", define: %{"outputDir" => "/tmp/site"})
+
     * `:memory_limit` — maximum JS heap in bytes (default: 256 MB)
     * `:max_stack_size` — maximum JS call stack in bytes (default: 1 MB)
   """

lib/quickbeam.ex

@@ -37,20 +37,22 @@ defmodule QuickBEAM.JS.Bundler do
   end
 
   defp collect_modules(entry_path, node_modules) do
-    case do_collect(entry_path, node_modules, [], MapSet.new()) do
+    basename = Path.basename(entry_path)
+
+    case do_collect(entry_path, basename, node_modules, [], MapSet.new()) do
       {:ok, files, _seen} -> {:ok, Enum.reverse(files)}
       {:error, _} = error -> error
     end
   end
 
-  defp do_collect(abs_path, node_modules, files, seen) do
+  defp do_collect(abs_path, label, node_modules, files, seen) do
     if MapSet.member?(seen, abs_path) do
       {:ok, files, seen}
     else
       case File.read(abs_path) do
         {:ok, source} ->
           seen = MapSet.put(seen, abs_path)
-          files = [{abs_path, source} | files]
+          files = [{label, source} | files]
 
           case extract_imports(source, abs_path) do
             {:ok, specifiers} ->
@@ -92,7 +94,9 @@ defmodule QuickBEAM.JS.Bundler do
         collect_imports(rest, importer, node_modules, files, seen)
 
       {:ok, resolved_path} ->
-        case do_collect(resolved_path, node_modules, files, seen) do
+        label = if relative?(specifier), do: Path.basename(resolved_path), else: specifier
+
+        case do_collect(resolved_path, label, node_modules, files, seen) do
           {:ok, files, seen} ->
             collect_imports(rest, importer, node_modules, files, seen)
 

lib/quickbeam/js/bundler.ex

@@ -53,6 +53,7 @@ defmodule QuickBEAM.Native do
       resolve_call_term: [],
       reject_call_term: [],
       send_message: [],
+      define_global: [],
       memory_usage: [],
       dom_find: [],
       dom_find_all: [],