@swmansion/popcorn 0.2.0-rc.1

package/dist/popcorn.mjs

@@ -0,0 +1,340 @@
+import { IframeBridge } from './bridge.mjs';
+import { HEARTBEAT_TIMEOUT_MS, MESSAGES, MAX_RELOAD_N, CALL_TIMEOUT_MS, INIT_VM_TIMEOUT_MS } from './types.mjs';
+import { throwError } from './utils.mjs';
+
+class PopcornDeinitializedError extends Error {
+}
+const INIT_TOKEN = Symbol();
+const IFRAME_URL = new URL("./iframe.mjs", import.meta.url).href;
+/**
+ * Manages Elixir by setting up iframe, WASM module, and event listeners. Used to sent messages to Elixir processes.
+ */
+class Popcorn {
+    heartbeatTimeoutMs = null;
+    onReloadCallback;
+    bridge = null;
+    bridgeConfig;
+    debug = false;
+    bundleURL;
+    state = { status: "uninitialized" };
+    initProcess = null;
+    requestId = 0;
+    calls = new Map();
+    logListeners = {
+        stdout: new Set(),
+        stderr: new Set(),
+    };
+    awaitedMessage = null;
+    heartbeatTimeout = null;
+    reloadN = 0;
+    constructor(params, token) {
+        if (token !== INIT_TOKEN)
+            throwError({ t: "private_constructor" });
+        const bundlePath = params.bundlePath ?? "/bundle.avm";
+        const bundleURL = new URL(bundlePath, import.meta.url);
+        this.onReloadCallback = params.onReload ?? noop;
+        this.debug = params.debug ?? false;
+        this.bundleURL = bundleURL.href;
+        this.bridgeConfig = {
+            container: params.container,
+            script: { url: IFRAME_URL, entrypoint: "runIFrame" },
+            config: { "bundle-path": this.bundleURL },
+            debug: true,
+            onMessage: this.iframeHandler.bind(this),
+        };
+        this.logListeners.stdout.add(params.onStdout ?? console.log);
+        this.logListeners.stderr.add(params.onStderr ?? console.warn);
+        this.heartbeatTimeoutMs = params.heartbeatTimeoutMs ?? HEARTBEAT_TIMEOUT_MS;
+    }
+    /**
+     * Creates an iframe and sets up communication channels.
+     * Returns after Elixir code calls `Popcorn.Wasm.register/1`.
+     *
+     * @example
+     * import { Popcorn } from "@swmansion/popcorn";
+     * const popcorn = await Popcorn.init({
+     *   onStdout: console.log,
+     *   onStderr: console.error,
+     *   debug: true,
+     * });
+     */
+    static async init(options) {
+        const { container, ...constructorParams } = options;
+        const containerWithDefault = container ?? document.documentElement;
+        const popcorn = new Popcorn({ ...constructorParams, container: containerWithDefault }, INIT_TOKEN);
+        popcorn.trace("Main: init, params: ", { container, ...constructorParams });
+        await popcorn.mount();
+        return popcorn;
+    }
+    async mount() {
+        if (this.bridge !== null)
+            throwError({ t: "already_mounted" });
+        this.assertStatus(["uninitialized", "reload"]);
+        this.transition({ status: "mount" });
+        this.trace("Main: mount, container: ", this.bridgeConfig.container);
+        this.bridge = new IframeBridge(this.bridgeConfig);
+        await this.awaitMessage(MESSAGES.INIT);
+        this.transition({ status: "await_vm" });
+        this.trace("Main: iframe loaded");
+        this.initProcess = await withTimeout(this.awaitMessage(MESSAGES.START_VM), INIT_VM_TIMEOUT_MS);
+        this.transition({ status: "ready" });
+        this.trace("Main: mounted, main process: ", this.initProcess);
+        this.onHeartbeat();
+    }
+    /**
+     * Sends a message to an Elixir process and awaits for the response.
+     *
+     * If Elixir doesn't respond in configured timeout, the returned promise will be rejected with "process timeout" error.
+     *
+     * Unless passed via options, the name passed in `Popcorn.Wasm.register/1` on the Elixir side is used.
+     * Throws "Unspecified target process" if default process is not set and no process is specified.
+     *
+     * @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
+     */
+    async call(args, { process, timeoutMs } = {}) {
+        this.assertStatus(["ready"]);
+        const targetProcess = process ?? this.initProcess;
+        if (this.bridge === null)
+            throwError({ t: "unmounted" });
+        if (targetProcess === null)
+            throwError({ t: "bad_target" });
+        const requestId = this.requestId++;
+        const callPromise = new Promise((resolve, reject) => {
+            if (this.bridge === null)
+                throwError({ t: "unmounted" });
+            this.trace("Main: call: ", { requestId, process, args });
+            this.bridge.sendIframeRequest({
+                type: MESSAGES.CALL,
+                value: { requestId, process: targetProcess, args },
+            });
+            this.calls.set(requestId, {
+                acknowledged: false,
+                startTimeMs: performance.now(),
+                resolve,
+                reject,
+            });
+        });
+        const result = await withTimeout(callPromise, timeoutMs ?? CALL_TIMEOUT_MS);
+        this.calls.delete(requestId);
+        return result;
+    }
+    /**
+     * Sends a message to an Elixir process (default or from options) and returns immediately.
+     *
+     * Unless passed via options, the name passed in `Popcorn.Wasm.register/1` on the Elixir side is used.
+     * Throws "Unspecified target process" if default process is not set and no process is specified.
+     */
+    cast(args, { process } = {}) {
+        this.assertStatus(["ready"]);
+        const targetProcess = process ?? this.initProcess;
+        if (this.bridge === null)
+            throwError({ t: "unmounted" });
+        if (targetProcess === null)
+            throwError({ t: "bad_target" });
+        const requestId = this.requestId++;
+        this.trace("Main: cast: ", { requestId, process, args });
+        this.bridge.sendIframeRequest({
+            type: MESSAGES.CAST,
+            value: { requestId, process: targetProcess, args },
+        });
+    }
+    /**
+     * Destroys an iframe and resets the instance.
+     */
+    deinit() {
+        if (this.bridge === null)
+            throwError({ t: "unmounted" });
+        this.trace("Main: deinit");
+        this.transition({ status: "deinit" });
+        this.bridge.deinit();
+        this.bridge = null;
+        this.awaitedMessage = null;
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = null;
+        }
+        this.logListeners.stdout.clear();
+        this.logListeners.stderr.clear();
+        for (const callData of this.calls.values()) {
+            const durationMs = performance.now() - callData.startTimeMs;
+            callData.reject({
+                error: new PopcornDeinitializedError("Call cancelled due to instance deinit"),
+                durationMs,
+            });
+        }
+        this.calls.clear();
+    }
+    /**
+     * Registers a log listener that will be called when output of the specified type is received.
+     */
+    registerLogListener(listener, type) {
+        this.logListeners[type].add(listener);
+    }
+    /**
+     * Unregisters a previously registered log listener.
+     */
+    unregisterLogListener(listener, type) {
+        this.logListeners[type].delete(listener);
+    }
+    notifyLogListeners(type, message) {
+        this.logListeners[type].forEach((listener) => {
+            listener(message);
+        });
+    }
+    iframeHandler(data) {
+        const awaitedMessage = this.awaitedMessage;
+        if (awaitedMessage && data.type == awaitedMessage.type) {
+            this.awaitedMessage = null;
+            awaitedMessage.resolve?.(data.value);
+            return;
+        }
+        if (data.type === MESSAGES.STDOUT) {
+            this.notifyLogListeners("stdout", data.value);
+        }
+        else if (data.type === MESSAGES.STDERR) {
+            this.notifyLogListeners("stderr", data.value);
+        }
+        else if (data.type === MESSAGES.CALL) {
+            this.onCall(data.value);
+        }
+        else if (data.type === MESSAGES.CALL_ACK) {
+            this.onCallAck(data.value);
+        }
+        else if (data.type === MESSAGES.HEARTBEAT) {
+            this.onHeartbeat();
+        }
+        else if (data.type === MESSAGES.RELOAD) {
+            this.reloadIframe();
+        }
+        else {
+            throwError({ t: "assert" });
+        }
+    }
+    onCallAck({ requestId }) {
+        this.assertStatus(["ready"]);
+        this.trace("Main: onCallAck: ", { requestId });
+        const callData = this.calls.get(requestId);
+        if (callData === undefined)
+            throwError({ t: "bad_ack" });
+        this.calls.set(requestId, { ...callData, acknowledged: true });
+    }
+    onCall({ requestId, error, data, }) {
+        this.assertStatus(["ready"]);
+        this.trace("Main: onCall: ", { requestId, error, data });
+        const callData = this.calls.get(requestId);
+        if (callData === undefined)
+            throwError({ t: "bad_call" });
+        if (!callData.acknowledged)
+            throwError({ t: "no_acked_call" });
+        this.calls.delete(requestId);
+        const durationMs = performance.now() - callData.startTimeMs;
+        if (error !== undefined) {
+            callData.resolve({ ok: false, error, durationMs });
+        }
+        else {
+            callData.resolve({ ok: true, data, durationMs });
+        }
+    }
+    onHeartbeat() {
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+        }
+        this.heartbeatTimeout = setTimeout(() => {
+            this.trace("Main: heartbeat lost");
+            this.reloadIframe("heartbeat_lost");
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        }, this.heartbeatTimeoutMs);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    reloadIframe(reason = "other") {
+        if (this.bridge === null) {
+            throw new Error("WASM iframe not mounted for reload");
+        }
+        if (document.hidden) {
+            this.trace("Main: reloading iframe skipped, window not visible");
+            return;
+        }
+        this.reloadN++;
+        if (this.reloadN > MAX_RELOAD_N) {
+            this.trace("Main: exceeded max reload number");
+            return;
+        }
+        this.trace("Main: reloading iframe");
+        this.transition({ status: "reload" });
+        this.bridge.deinit();
+        this.bridge = null;
+        this.awaitedMessage = null;
+        if (this.heartbeatTimeout) {
+            clearTimeout(this.heartbeatTimeout);
+            this.heartbeatTimeout = null;
+        }
+        for (const callData of this.calls.values()) {
+            const durationMs = performance.now() - callData.startTimeMs;
+            callData.reject({
+                error: new Error("Call cancelled due to iframe reload"),
+                durationMs,
+            });
+        }
+        this.calls.clear();
+        this.onReloadCallback(reason);
+        this.mount();
+    }
+    awaitMessage(type) {
+        if (this.awaitedMessage) {
+            throwError({
+                t: "already_awaited",
+                messageType: this.awaitedMessage.type,
+                awaitedMessageType: type,
+            });
+        }
+        this.awaitedMessage = { type };
+        return new Promise((resolve) => {
+            if (!this.awaitedMessage)
+                throwError({ t: "assert" });
+            this.awaitedMessage.resolve = resolve;
+        });
+    }
+    trace(...messages) {
+        if (this.debug) {
+            console.debug(...messages);
+        }
+    }
+    transition(to) {
+        this.trace(`State: ${this.state.status} -> ${to.status}`);
+        this.state = to;
+    }
+    assertStatus(validStatuses) {
+        const currentStatus = this.state.status;
+        if (!validStatuses.includes(currentStatus)) {
+            throwError({
+                t: "bad_status",
+                status: currentStatus,
+                expectedStatus: validStatuses.join(" | "),
+            });
+        }
+    }
+}
+async function withTimeout(promise, ms) {
+    let timeout = null;
+    const timeoutPromise = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            reject("Promise timeout");
+        }, ms);
+    });
+    const result = await Promise.race([promise, timeoutPromise]);
+    if (!timeout)
+        throwError({ t: "assert" });
+    clearTimeout(timeout);
+    return result;
+}
+function noop() {
+    /* noop */
+}
+
+export { Popcorn, PopcornDeinitializedError };

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+export declare const INIT_VM_TIMEOUT_MS = 30000;
+export declare const CALL_TIMEOUT_MS = 60000;
+export declare const HEARTBEAT_TIMEOUT_MS = 60000;
+export declare const HEARTBEAT_INTERVAL_MS = 500;
+export declare const MAX_RELOAD_N = 3;
+export type AnySerializable = any;
+export type CallRequest = {
+    requestId: number;
+    process: string;
+    args: AnySerializable;
+};
+export type CastRequest = {
+    requestId: number;
+    process: string;
+    args: AnySerializable;
+};
+/** Messages sent from parent window to iframe */
+export type IframeRequest = {
+    type: "popcorn-call";
+    value: CallRequest;
+} | {
+    type: "popcorn-cast";
+    value: CastRequest;
+};
+export type CallResponse = {
+    requestId: number;
+    error?: AnySerializable;
+    data?: AnySerializable;
+};
+export type CallAck = {
+    requestId: number;
+};
+/** Messages sent from iframe to parent window */
+export type IframeResponse = {
+    type: "popcorn-init";
+    value: null;
+} | {
+    type: "popcorn-startVm";
+    value: string;
+} | {
+    type: "popcorn-call";
+    value: CallResponse;
+} | {
+    type: "popcorn-callAck";
+    value: CallAck;
+} | {
+    type: "popcorn-stdout";
+    value: string;
+} | {
+    type: "popcorn-stderr";
+    value: string;
+} | {
+    type: "popcorn-heartbeat";
+    value: null;
+} | {
+    type: "popcorn-reload";
+    value: string | null;
+};
+/** Union of all messages (requests and responses) */
+export type Message = IframeRequest | IframeResponse;
+export declare const MESSAGES: {
+    readonly INIT: "popcorn-init";
+    readonly START_VM: "popcorn-startVm";
+    readonly CALL: "popcorn-call";
+    readonly CAST: "popcorn-cast";
+    readonly CALL_ACK: "popcorn-callAck";
+    readonly STDOUT: "popcorn-stdout";
+    readonly STDERR: "popcorn-stderr";
+    readonly HEARTBEAT: "popcorn-heartbeat";
+    readonly RELOAD: "popcorn-reload";
+};
+export declare function isMessageType(type: string): type is Message["type"];

package/dist/types.mjs

@@ -0,0 +1,22 @@
+const INIT_VM_TIMEOUT_MS = 30_000;
+const CALL_TIMEOUT_MS = 60_000;
+const HEARTBEAT_TIMEOUT_MS = 60_000;
+const HEARTBEAT_INTERVAL_MS = 500;
+const MAX_RELOAD_N = 3;
+const MESSAGES = {
+    INIT: "popcorn-init",
+    START_VM: "popcorn-startVm",
+    CALL: "popcorn-call",
+    CAST: "popcorn-cast",
+    CALL_ACK: "popcorn-callAck",
+    STDOUT: "popcorn-stdout",
+    STDERR: "popcorn-stderr",
+    HEARTBEAT: "popcorn-heartbeat",
+    RELOAD: "popcorn-reload",
+};
+const MESSAGES_TYPES = new Set(Object.values(MESSAGES));
+function isMessageType(type) {
+    return MESSAGES_TYPES.has(type);
+}
+
+export { CALL_TIMEOUT_MS, HEARTBEAT_INTERVAL_MS, HEARTBEAT_TIMEOUT_MS, INIT_VM_TIMEOUT_MS, MAX_RELOAD_N, MESSAGES, isMessageType };

package/dist/utils.d.ts

@@ -0,0 +1,27 @@
+type ErrorData = {
+    t: "assert";
+} | {
+    t: "bad_status";
+    status: string;
+    expectedStatus: string;
+} | {
+    t: "private_constructor";
+} | {
+    t: "bad_call";
+} | {
+    t: "no_acked_call";
+} | {
+    t: "bad_ack";
+} | {
+    t: "unmounted";
+} | {
+    t: "bad_target";
+} | {
+    t: "already_awaited";
+    messageType: string;
+    awaitedMessageType: string;
+} | {
+    t: "already_mounted";
+};
+export declare function throwError(error: ErrorData): never;
+export {};

package/dist/utils.mjs

@@ -0,0 +1,26 @@
+function throwError(error) {
+    switch (error.t) {
+        case "assert":
+            throw new Error("Assertion error");
+        case "bad_status":
+            throw new Error(`Unexpected status transition. Instance in ${error.status} status, expected ${error.expectedStatus}`);
+        case "private_constructor":
+            throw new Error("Don't construct the Popcorn object directly, use Popcorn.init() instead");
+        case "bad_call":
+            throw new Error("Response for non-existent call");
+        case "no_acked_call":
+            throw new Error("Response for non-acknowledged call");
+        case "bad_ack":
+            throw new Error("Ack for non-existent call");
+        case "unmounted":
+            throw new Error("WASM iframe not mounted");
+        case "bad_target":
+            throw new Error("Unspecified target process");
+        case "already_awaited":
+            throw new Error(`Cannot await message ${error.messageType} when a message ${error.awaitedMessageType} is already awaited on`);
+        case "already_mounted":
+            throw new Error("Iframe already mounted");
+    }
+}
+
+export { throwError };

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@swmansion/popcorn",
+  "version": "0.2.0-rc.1",
+  "description": "JS bindings for Popcorn",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://popcorn.swmansion.com",
+  "bugs": {
+    "url": "https://github.com/software-mansion/popcorn/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/software-mansion/popcorn.git"
+  },
+  "author": "Software Mansion",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./vite": {
+      "types": "./dist/plugins/vite.d.ts",
+      "import": "./dist/plugins/vite.mjs"
+    },
+    "./rollup": {
+      "types": "./dist/plugins/rollup.d.ts",
+      "import": "./dist/plugins/rollup.mjs"
+    },
+    "./esbuild": {
+      "types": "./dist/plugins/esbuild.d.ts",
+      "import": "./dist/plugins/esbuild.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "setup:dev": "npm run assets:dev",
+    "dev": "rollup -c --watch",
+    "lint": "tsc --noEmit && eslint && prettier . --check --log-level=warn",
+    "test": "vitest",
+    "build:prod": "pnpm run lint && (rm -r assets || true) && (rm -r dist || true) && pnpm run assets:prod && rollup -c",
+    "assets:dev": "./scripts/get_atomvm.sh assets/",
+    "assets:prod": "RUNTIME_SOURCE='https://github.com/software-mansion-labs/FissionVM.git#swm' ./scripts/get_atomvm.sh assets/"
+  },
+  "peerDependencies": {
+    "esbuild": ">=0.17.0",
+    "rollup": ">=4.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0"
+  },
+  "peerDependenciesMeta": {
+    "esbuild": {
+      "optional": true
+    },
+    "rollup": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.0",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/node": "catalog:",
+    "esbuild": "^0.25.0",
+    "eslint": "catalog:",
+    "globals": "^16.2.0",
+    "prettier": "^3.7.4",
+    "rollup": "^4.55.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.53.0",
+    "vite": "catalog:",
+    "vitest": "^4.0.17"
+  }
+}