@swmansion/popcorn 0.3.2 → 0.4.0-next.0

package/dist/popcorn.d.ts

@@ -1,138 +1,265 @@
-import { PopcornError, PopcornInternalError } from "./errors";
-import type { AnySerializable } from "./types";
-import type { PopcornErrorCode, PopcornInternalErrorCode } from "./errors";
-export { PopcornError, PopcornInternalError };
-export type { PopcornErrorCode, PopcornInternalErrorCode };
-/** Options for Popcorn.init() */
-export type PopcornInitOptions = {
-    /** DOM element to mount an iframe */
-    container?: HTMLElement;
-    /** Paths to compiled Elixir bundles (`.avm` files). */
-    bundlePaths?: string[];
-    /** Handler for stderr messages. */
-    onStderr?: (message: string) => void;
-    /** Handler for stdout messages. */
-    onStdout?: (message: string) => void;
-    /** Handler called when Popcorn reloads due to iframe crash */
-    onReload?: (reason: string) => void;
-    /** Heartbeat timeout in milliseconds. If an iframe doesn't respond within this time, it is reloaded. */
-    heartbeatTimeoutMs?: number;
-    /** Directory containing Wasm and scripts used inside iframe. */
-    wasmDir?: string;
-    /** Enable debug logging. */
-    debug?: boolean;
+import { type Result } from "./errors";
+import { type PopcornEvent } from "./events";
+import type { AnyValue, BeamBootOptions, OtpErrorPayload, Pid, TtySize } from "./types";
+/** Output type for a terminal. */
+type TtyOutput = "text" | "bytes";
+type OutputChunk<Output extends TtyOutput> = Output extends "bytes" ? Uint8Array : string;
+/** Browser VM configuration. */
+export type PopcornOpts<Output extends TtyOutput = "text"> = {
+    beam?: Pick<BeamBootOptions, "emulatorArgs" | "extraArgs" | "env"> & {
+        /**
+         * Asset directory URL.
+         *
+         * Must end with `/`. Defaults to `otp/` next to the worker.
+         */
+        otpAssetsRoot?: string;
+    };
+    tty?: {
+        /** Initial terminal size. Defaults to 80 columns and 24 rows. */
+        size?: TtySize;
+        /** Output callback format. Defaults to `text` with streamed UTF-8 decoding. Use `bytes` for raw chunks. */
+        output?: Output;
+    };
+    timeoutsMs?: {
+        /**
+         * Maximum wait for the VM bridge.
+         *
+         * Defaults to 10 000 ms.
+         */
+        boot?: number;
+        /**
+         * Maximum wait for entrypoint startup after bridge readiness.
+         *
+         * Defaults to 60 000 ms.
+         */
+        appStartup?: number;
+        /**
+         * Maximum wait for a send resolving its process target.
+         *
+         * Defaults to 5 000 ms.
+         */
+        send?: number;
+    };
+    /**
+     * Receives stdout.
+     *
+     * Defaults to `console.log`.
+     * When `tty.output` is "bytes", we pass an `ArrayBuffer` as an argument and `string` otherwise
+     */
+    onStdout?: (chunk: OutputChunk<Output>) => void;
+    /**
+     * Receives stderr.
+     *
+     * Defaults to `console.error`.
+     * When `tty.output` is "bytes", we pass an `ArrayBuffer` as an argument and `string` otherwise
+     */
+    onStderr?: (chunk: OutputChunk<Output>) => void;
+    /**
+     * Receives VM errors and exits before shutdown.
+     *
+     * Defaults to console output.
+     */
+    onError?: (event: OtpErrorPayload) => void;
+    /**
+     * Module worker URL.
+     *
+     * Defaults to the worker included with the package.
+     */
+    workerUrl?: string | URL;
 };
-/** Options for cast method */
-export type CastOptions = {
-    /** Receiver process name. */
-    process?: string;
+type VmExitReason = {
+    reason: "deinit";
+} | {
+    reason: "abort";
+    data: string;
+} | {
+    reason: "error";
+    data: string;
+} | {
+    reason: "exit";
+    data: number;
 };
-/** Options for call method */
-export type CallOptions = {
-    /** Registered Elixir process name. */
-    process?: string;
-    /** Timeout (in milliseconds) for the call */
+type CallOpts = {
     timeoutMs?: number;
+    proxy?: string;
 };
-type CallResult = {
-    ok: true;
-    /** Serialized value returned from Elixir */
-    data: AnySerializable;
-    /** Amount of time it took to process the call */
-    durationMs: number;
-} | {
-    ok: false;
-    /** Error from failed call */
-    error: Error;
-    /** Amount of time it took to process the call */
-    durationMs: number;
+export type GenServer = {
+    /**
+     * Calls a GenServer by registered name or {@link Pid} and waits for its reply.
+     *
+     * Requires a running `Popcorn.Proxy`, registered as `popcorn_proxy` by default.
+     *
+     * @param opts - `timeoutMs` defaults to 5 000 ms. `proxy` allows to select another registered proxy.
+     * @returns A {@link 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.
+     */
+    call(target: string | Pid, request?: AnyValue, opts?: CallOpts): Promise<Result<AnyValue>>;
+    /**
+     * Sends a cast through the proxy.
+     *
+     * Success confirms delivery to the proxy
+     * @see {@link call}
+     * @param opts - `proxy` allows to select another registered proxy.
+     */
+    cast(target: string | Pid, request?: AnyValue, opts?: {
+        proxy?: string;
+    }): Promise<Result<null>>;
 };
-type LogType = "stdout" | "stderr";
-type LogListener = (message: string) => void;
-type MessageHandler = (eventName: string, payload: AnySerializable) => void;
 /**
- * Manages Elixir by setting up iframe, WASM module, and event listeners. Used to sent messages to Elixir processes.
- */
-export declare class Popcorn {
-    heartbeatTimeoutMs: number | null;
-    private onReloadCallback;
-    private bridge;
-    private bridgeConfig;
-    private debug;
-    private bundleURLs;
+ * A BEAM VM in a browser worker.
+ *
+ * Use {@link Popcorn.init} to create and start an instance.
+ **/
+export declare class Popcorn<Output extends TtyOutput = "text"> {
+    private vmWorker;
     private state;
-    private defaultReceiver;
-    private requestId;
-    private calls;
-    private logListeners;
-    private messageHandlers;
-    private mountResolve;
-    private heartbeatTimeout;
-    private reloadN;
-    private constructor();
+    private readonly opts;
+    private readonly ttySize;
+    private output;
+    private requestSeq;
+    private settleBoot;
+    private readonly eventHandlers;
+    private readonly pendingSends;
+    private readonly pendingCalls;
+    private callSeq;
+    private readonly trackedValues;
+    private trackedKeySeq;
+    private io;
+    private vmReady;
+    readonly genserver: GenServer;
+    private readonly TrackedValue;
+    private Pid;
+    private readonly onWorkerMessage;
     /**
-     * Creates an iframe and sets up communication channels.
-     * Returns after the Elixir app calls `Popcorn.Wasm.ready/0,1`.
+     * Creates the worker.
      *
-     * @example
-     * import { Popcorn } from "@swmansion/popcorn";
-     * const popcorn = await Popcorn.init({
-     *   onStdout: console.log,
-     *   onStderr: console.error,
-     *   debug: true,
-     * });
+     * Call {@link boot} to start the VM.
+     **/
+    constructor(opts: PopcornOpts<Output>);
+    private spawnWorker;
+    /**
+     * Creates an instance and waits for {@link boot}.
+     *
+     * For startup messages, use the constructor and register {@link onEvent} before boot.
+     *
+     * @returns Ok tuple or `runtime:eval-unavailable` if the page blocks JavaScript evaluation.
      */
-    static init(options: PopcornInitOptions): Promise<Popcorn>;
-    private mount;
+    static init<Output extends TtyOutput = "text">(opts: PopcornOpts<Output>): Promise<Result<Popcorn<Output>>>;
     /**
-     * Sends a message to an Elixir process and awaits for the response.
+     * Starts the VM and waits for its bridge and entrypoint application.
      *
-     * If Elixir doesn't respond in configured timeout, the returned promise will be rejected with "process timeout" error.
+     * Without an entrypoint, waits only for the bridge.
      *
-     * Unless passed via options, the name passed in `Popcorn.Wasm.set_default_receiver/1` on the Elixir side is used.
-     * Throws "Unspecified target process" if default process is not set and no process is specified.
+     * After shutdown, starts a fresh VM with the original options.
+     *
+     * @returns Ok tuple with `this` if boot completes or error tuple.
      *
      * @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
+     * ```ts
+     * const popcorn = new Popcorn({});
+     * popcorn.onEvent((message) => console.log(message));
+     * const result = await popcorn.boot();
+     * if (!result.ok) throw result.error;
+     * ```
      */
-    call(args: AnySerializable, { process, timeoutMs }?: CallOptions): Promise<CallResult>;
+    boot(): Promise<Result<Popcorn<Output>>>;
     /**
-     * Sends a message to an Elixir process (default or from options) and returns immediately.
+     * Queues terminal input.
+     *
+     * Encodes strings as UTF-8 and copies byte arrays. Does not append a newline.
      *
-     * Unless passed via options, the name passed in `Popcorn.Wasm.set_default_receiver/1` on the Elixir side is used.
-     * Throws "Unspecified target process" if default process is not set and no process is specified.
+     * Returns `stdio:overflow` if the chunk exceeds the remaining 64 KiB queue capacity.
+     * An overflow leaves the queue unchanged.
      */
-    cast(args: AnySerializable, { process }?: CastOptions): void;
+    writeStdin(chunk: string | Uint8Array): Result<null>;
     /**
-     * Destroys an iframe and resets the instance.
+     * Sends new terminal dimensions to a booted VM.
+     *
+     * Each dimension must be between 1 and 65,535.
      */
-    deinit(): void;
-    private teardownBridge;
+    resizeTty(columns: number, rows: number): Result<null>;
     /**
-     * Registers a log listener that will be called when output of the specified type is received.
+     * Sends a payload to a registered process name or a {@link Pid} from this VM boot.
+     *
+     * The process receives `{wasm, Payload}`.
+     * A send timeout does not cancel delivery.
+     * Uses the value conversions in {@link AnyValue}. An omitted, `null`, or `undefined` payload becomes an empty map.
+     *
+     * @returns Ok tuple or `bridge:not-started` before boot and `vm:exited` after shutdown.
+     *
+     * @example
+     * Send an Erlang `{ok, <<"value">>}` tuple to a registered `receiver` process.
+     *
+     * ```ts
+     * const result = await popcorn.send("receiver", tuple(atom("ok"), "value"));
+     * if (!result.ok) throw result.error;
+     * ```
+     *
+     * @see {@link AnyValue}
+     * @see {@link atom}
+     * @see {@link tuple}
      */
-    registerLogListener(listener: LogListener, type: LogType): void;
+    send(rawTarget: string | Pid, payload?: AnyValue): Promise<Result<null>>;
+    private sendBridge;
     /**
-     * Unregisters a previously registered log listener.
+     * Registers a handler for BEAM message payloads.
+     *
+     * Messages with no handlers are lost. Startup messages can arrive before {@link boot} resolves.
+     * VM errors and terminal output use the callbacks in {@link PopcornOpts}.
+     *
+     * @returns a function that removes the handler.
      */
-    unregisterLogListener(listener: LogListener, type: LogType): void;
-    private notifyLogListeners;
+    onEvent(handler: (event: PopcornEvent) => void): () => void;
     /**
-     * Registers a catch-all event handler. Returns an unsubscribe function.
+     * 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.
      */
-    onMessage(handler: MessageHandler): () => void;
-    private onEvent;
-    private iframeHandler;
-    private onCallAck;
-    private onCall;
-    private onHeartbeat;
-    private reloadIframe;
-    trace(...messages: unknown[]): void;
-    private transition;
-    private assertStatus;
+    deinit(reason?: VmExitReason): void;
+    private clearTrackedValues;
+    private emit;
+    private completeCall;
+    private parseCallReply;
+    private call;
+    private callBridge;
+    private cast;
+    private castBridge;
+    private nextCallId;
+    private runJs;
+    private asRef;
+    private sendRunJsReply;
+    private jsWithCurrentEnv;
+    private reviveHandles;
+    /** Maps pids and `TrackedValue`s during encoding, collecting handles into
+     * `tracked` for the caller to register once encoding succeeds. */
+    private handleMapper;
+    private deleteTrackedValue;
+    private completeSend;
+    private nextRequestId;
+    private handleStdout;
+    private handleStderr;
+    private handleOtpError;
 }
+/**
+ * Thread counts for {@link schedulers}.
+ *
+ * Each count must be positive.
+ */
+export type SchedulerOptions = {
+    /** Regular schedulers. */
+    base: number;
+    /** Dirty CPU schedulers. */
+    dirtyCpu: number;
+    /** Dirty I/O schedulers. */
+    dirtyIo: number;
+};
+/**
+ * Builds `beam.emulatorArgs` for scheduler counts.
+ *
+ * Defaults to one scheduler of each type.
+ */
+export declare function schedulers(opts: SchedulerOptions): string[];
+export {};