JS API

Popcorn is used to load Elixir code bundle and send messages to it.

Popcorn.init(options)

Initializes a new Popcorn instance, running VM and executing Elixir code.

Options:

• container (DOM node, optional) - DOM element to mount iframe. Default: document.body.
• bundlePath (string, optional) - Path to compiled Elixir bundle (.avm file). Default: "wasm/bundle.avm".
• onStdout (function, optional) - Handler for stdout messages. See notes. Default: console.log.
• onStderr (function, optional) - Handler for stderr messages. See notes. Default: console.warn.
• heartbeatTimeoutMs (number, optional) - Heartbeat timeout in milliseconds. See notes. Default: 60_000.
• wasmDir (string, optional) - Directory containing Wasm and scripts used inside iframe. Default: "./wasm/".
• debug (boolean, optional) - Enable debug logging. Default: false.

Returns: Promise<Popcorn> - Initialized Popcorn instance

Example:

import { Popcorn } from "./wasm/popcorn.js";

const popcorn = await Popcorn.init({
  onStdout: console.log,
  onStderr: console.error,
  debug: true,
});

Notes:

1. onStdout and onStderr both have (text: string) => void signature.
2. If iframe hosting Wasm doesn’t respond in heartbeatTimeoutMs ms, it will be reloaded.

call(args, options)

Sends a message to Elixir process and waits for response.

Parameters:

• args (any) - Any serializable data to send to Elixir.
• options (object):
  • process (string, optional) - Registered Elixir process name. Uses default (see notes) if not specified.
  • timeoutMs (number, optional) - If Elixir doesn’t respond in timeoutMs ms, returned promise will be cancelled. Default: 60_000.

Returns: Promise<{data: any, durationMs: number, error?: any}> - Response from Elixir, including total execution time observed from JS.

Example:

const result = await popcorn.call(
  { action: "get_user", id: 123 },
  { process: "user_server", timeoutMs: 5_000 },
);
console.log(result.data); // Deserialized Elixir response
console.log(result.durationMs); // Entire call duration

Notes:

• Default process name is process name passed in Popcorn.Wasm.register/1.
• Throws “Unspecified target process” if default process is not set.
• Call timeouts result in rejected promise with “Promise timeout”.

cast(args, options)

Sends a fire-and-forget message to Elixir process.

Parameters:

• args (any) - Serializable data to send to Elixir
• options (object):
  • process (string, optional) - Registered Elixir process name. Uses default (see notes) if not specified.

Returns: void

Notes:

• Default process name is process name passed in Popcorn.Wasm.register/1.

deinit()

Destroys the iframe and cleans up resources.

Returns: void