@spec async boot(): Promise<Popcorn<Output>>

Starts the VM and waits for its bridge and entrypoint application.

Without an entrypoint, waits only for the bridge.

After shutdown, starts a fresh VM with the original options.

Returns

This instance. Rejects on failure.

Example

const popcorn = new Popcorn({});
popcorn.onEvent((message) => console.log(message));
await popcorn.boot();

@spec async call(target: string | Pid, request?: unknown, opts?: CallOpts): Promise<unknown>

Calls a GenServer and returns its reply. See tryCall for a result instead of throwing.

@spec async cast(target: string | Pid, request?: unknown, opts?: {
  proxy?: string;
}): Promise<void>

Sends a cast through the proxy. See tryCast for a result instead of throwing.

@spec deinit(reason: VmExitReason = ...): void

Stops the worker and completes pending sends and calls with vm:exited.

Releases tracked values and runs their cleanup callbacks. Keeps event handlers for the next boot. Repeated calls have no effect.

@spec async init<Output extends TtyOutput = "text">(opts: PopcornOpts<Output> = {}): Promise<Popcorn<Output>>

Creates an instance and waits for boot.

Use opts.onEvent to receive messages sent during startup.

Returns

The instance. Rejects on failure.

See

PopcornOpts

@spec onEvent(handler: (event: unknown) => void): () => void

Registers a handler for BEAM message payloads.

Messages with no handlers are lost. Startup messages can arrive before boot resolves. VM errors and terminal output use the callbacks in PopcornOpts.

Returns

a function that removes the handler.

@spec Popcorn<Output extends TtyOutput = "text">(opts: PopcornOpts<Output> = {}): Popcorn<Output>

Creates the worker.

Call boot to start the VM.

@spec resizeTty(columns: number, rows: number): void

Sends new terminal dimensions to a booted VM.

Each dimension must be between 1 and 65,535.

Throws on failure.

@spec async send(rawTarget: string | Pid, payload?: unknown): Promise<void>

Sends a payload to a registered process name or a Pid from this VM boot.

The process receives {wasm, Payload}. A send timeout does not cancel delivery. Uses the value conversions in AnyValue. An omitted, null, or undefined payload becomes an empty map.

Returns

Rejects on failure.

Example

Send an Erlang {ok, <<"value">>} tuple to a registered receiver process.

await popcorn.send("receiver", tuple(atom("ok"), "value"));

See

• AnyValue
• atom
• tuple
• trySend for a result instead of throwing on expected failures.

@spec async tryCall(rawTarget: string | Pid, request?: unknown, opts?: CallOpts): Promise<Result<unknown>>

Calls a GenServer by registered name or Pid and waits for its reply.

Parameters

• opts - timeoutMs defaults to 5 000 ms. proxy allows to select another registered proxy (see Popcorn.Proxy).

Returns

A Result with the reply or a bridge, VM, timeout, or GenServer error.

GenServer failures use genserver:noproc, genserver:exit, or genserver:unserializable. A call timeout does not cancel server work.

@spec async tryCast(rawTarget: string | Pid, request?: unknown, opts?: {
  proxy?: string;
}): Promise<Result<null>>

Sends a cast through the proxy.

Success confirms delivery to the proxy

Parameters

• opts - proxy allows to select another registered proxy.

See

tryCall

@spec async trySend(rawTarget: string | Pid, payload?: unknown): Promise<Result<null>>

See send.

@spec writeStdin(chunk: string | Uint8Array<ArrayBufferLike>): void

Queues terminal input.

Encodes strings as UTF-8 and copies byte arrays. Does not append a newline.

Throws stdio:overflow if the chunk exceeds the remaining 64 KiB queue capacity. An overflow leaves the queue unchanged.