npm - @swmansion/popcorn - Versions diffs - 0.2.0-rc.1 - Mend

@swmansion/popcorn 0.2.0-rc.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/dist/AtomVM.wasm ADDED Viewed

Binary file

package/dist/bridge.d.ts ADDED Viewed

@@ -0,0 +1,22 @@
+import { type IframeRequest, type IframeResponse, type AnySerializable } from "./types";
+export type IframeBridgeArgs = {
+    container: HTMLElement;
+    config: Record<string, string>;
+    script: {
+        url: string;
+        entrypoint: string;
+    };
+    debug: boolean;
+    onMessage: (data: IframeResponse) => void;
+};
+export declare function sendIframeResponse(type: string, data: AnySerializable): void;
+export declare class IframeBridge {
+    private iframe;
+    private handlerRef;
+    private debug;
+    private onMessage;
+    constructor(args: IframeBridgeArgs);
+    sendIframeRequest(data: IframeRequest): void;
+    deinit(): void;
+    private messageHandler;
+}

package/dist/bridge.mjs ADDED Viewed

@@ -0,0 +1,68 @@
+import { isMessageType } from './types.mjs';
+import { throwError } from './utils.mjs';
+const STYLE_HIDDEN = "visibility: hidden; width: 0px; height: 0px; border: none";
+function sendIframeResponse(type, data) {
+    window.parent.postMessage({ type, value: data });
+}
+class IframeBridge {
+    iframe;
+    handlerRef;
+    // @ts-expect-error TODO: use for tracing
+    debug;
+    onMessage;
+    constructor(args) {
+        const { container, config, script, debug, onMessage } = args;
+        this.debug = debug;
+        this.onMessage = onMessage;
+        this.iframe = document.createElement("iframe");
+        this.iframe.srcdoc = `
+      <html lang="en" dir="ltr">
+          <head>
+          ${metaTagsFrom(config)}
+          </head>
+          <body>
+            <script type="module" defer>
+              import { ${script.entrypoint} } from "${script.url}";
+              ${script.entrypoint}();
+            </script>
+          </body>
+      </html>`;
+        this.iframe.style = STYLE_HIDDEN;
+        this.handlerRef = this.messageHandler.bind(this);
+        window.addEventListener("message", this.handlerRef);
+        // mount
+        container.appendChild(this.iframe);
+    }
+    sendIframeRequest(data) {
+        const w = this.iframe.contentWindow;
+        if (w === null)
+            throwError({ t: "assert" });
+        w.postMessage(data);
+    }
+    deinit() {
+        window.removeEventListener("message", this.handlerRef);
+        this.iframe.remove();
+    }
+    messageHandler({ data }) {
+        if (isIframeResponse(data)) {
+            this.onMessage(data);
+        }
+    }
+}
+function isIframeResponse(payload) {
+    if (typeof payload !== "object" || payload === null)
+        return false;
+    if (!Object.hasOwn(payload, "type") || !Object.hasOwn(payload, "value"))
+        return false;
+    if (typeof payload.type !== "string")
+        return false;
+    return isMessageType(payload.type);
+}
+function metaTagsFrom(config) {
+    return Object.entries(config)
+        .map(([key, value]) => `<meta name="${key}" content="${value}" />`)
+        .join("\n");
+}
+export { IframeBridge, sendIframeResponse };

package/dist/iframe.d.ts ADDED Viewed

	@@ -0,0 +1 @@
1	+ export declare function runIFrame(): Promise<void>;

package/dist/iframe.mjs ADDED Viewed

@@ -0,0 +1,200 @@
+import Module$1 from './AtomVM.mjs';
+import { sendIframeResponse } from './bridge.mjs';
+import { MESSAGES, HEARTBEAT_INTERVAL_MS } from './types.mjs';
+// @ts-expect-error atomvm doesn't have types yet
+let Module = null;
+class TrackedValue {
+    key;
+    value;
+    constructor({ key, value }) {
+        if (typeof key !== "number") {
+            throw new Error("key property in TrackedValue must be a number");
+        }
+        this.key = key;
+        this.value = value;
+    }
+}
+globalThis.TrackedValue = TrackedValue;
+async function runIFrame() {
+    const metaElement = document.querySelector('meta[name="bundle-path"]');
+    if (!metaElement) {
+        throw new Error("Missing meta[name='bundle-path'] element");
+    }
+    const bundlePath = metaElement.content;
+    const bundleBuffer = await fetch(bundlePath).then((resp) => resp.arrayBuffer());
+    const bundle = new Int8Array(bundleBuffer);
+    sendIframeResponse(MESSAGES.INIT, null);
+    const initProcess = await startVm(bundle);
+    window.addEventListener("message", async ({ data }) => {
+        const type = data.type;
+        if (type === MESSAGES.CALL) {
+            await handleCall(data.value);
+        }
+        else if (type === MESSAGES.CAST) {
+            handleCast(data.value);
+        }
+    });
+    sendIframeResponse(MESSAGES.START_VM, initProcess);
+    setInterval(() => sendIframeResponse(MESSAGES.HEARTBEAT, null), HEARTBEAT_INTERVAL_MS);
+}
+async function startVm(avmBundle) {
+    let resolveResultPromise = null;
+    const resultPromise = new Promise((resolve) => {
+        resolveResultPromise = resolve;
+    });
+    const moduleInstance = await Module$1({
+        preRun: [
+            function ({ FS }) {
+                FS.mkdir("/data");
+                FS.writeFile("/data/bundle.avm", avmBundle);
+            },
+        ],
+        arguments: ["/data/bundle.avm"],
+        print(text) {
+            sendIframeResponse(MESSAGES.STDOUT, text);
+        },
+        printErr(text) {
+            sendIframeResponse(MESSAGES.STDERR, text);
+        },
+        onAbort() {
+            // Timeout so that error logs are (hopefully) printed
+            // before we terminate
+            setTimeout(() => sendIframeResponse(MESSAGES.RELOAD, null), 100);
+        },
+    });
+    Module = moduleInstance;
+    moduleInstance["serialize"] = JSON.stringify;
+    moduleInstance["deserialize"] = deserialize;
+    moduleInstance["cleanupFunctions"] = new Map();
+    moduleInstance["onTrackedObjectDelete"] = (key) => {
+        const fns = moduleInstance["cleanupFunctions"];
+        const fn = fns.get(key);
+        fns.delete(key);
+        try {
+            fn?.();
+        }
+        catch (e) {
+            console.error(e);
+        }
+        finally {
+            moduleInstance["trackedObjectsMap"].delete(key);
+        }
+    };
+    const origCast = moduleInstance["cast"];
+    const origCall = moduleInstance["call"];
+    moduleInstance["cast"] = (process, args) => {
+        const serialized = moduleInstance.serialize(args);
+        origCast(process, serialized);
+    };
+    moduleInstance["call"] = (process, args) => {
+        const serialized = moduleInstance.serialize(args);
+        return origCall(process, serialized);
+    };
+    moduleInstance["onRunTrackedJs"] = (scriptString, isDebug) => {
+        const trackValue = (tracked) => {
+            const getKey = moduleInstance["nextTrackedObjectKey"];
+            const map = moduleInstance["trackedObjectsMap"];
+            if (tracked instanceof TrackedValue) {
+                map.set(tracked.key, tracked.value);
+                return tracked.key;
+            }
+            const key = getKey();
+            map.set(key, tracked);
+            return key;
+        };
+        let fn;
+        try {
+            const indirectEval = eval;
+            fn = indirectEval(scriptString);
+        }
+        catch (e) {
+            // TODO: send onEvalError for Popcorn object
+            console.error(e);
+            return null;
+        }
+        if (isDebug)
+            ensureFunctionEval(fn);
+        let result;
+        try {
+            result = fn?.(moduleInstance);
+        }
+        catch (e) {
+            // TODO: send onEvalError for Popcorn object
+            console.error(e);
+            return null;
+        }
+        if (isDebug)
+            ensureResultKeyList(result);
+        return result?.map(trackValue) ?? [];
+    };
+    moduleInstance["onGetTrackedObjects"] = (keys) => {
+        const getTrackedObject = (key) => {
+            const serialize = moduleInstance["serialize"];
+            const map = moduleInstance["trackedObjectsMap"];
+            return serialize(map.get(key));
+        };
+        return keys.map(getTrackedObject);
+    };
+    moduleInstance["onElixirReady"] = (initProcess) => {
+        moduleInstance["onElixirReady"] = null;
+        resolveResultPromise?.(initProcess);
+    };
+    return resultPromise;
+}
+async function handleCall(request) {
+    if (!Module) {
+        throw new Error("Module not initialized");
+    }
+    const { requestId, process, args } = request;
+    sendIframeResponse(MESSAGES.CALL_ACK, { requestId });
+    try {
+        const result = await Module.call(process, args);
+        sendIframeResponse(MESSAGES.CALL, {
+            requestId,
+            data: Module.deserialize(result),
+        });
+    }
+    catch (error) {
+        if (error == "noproc") {
+            sendIframeResponse(MESSAGES.RELOAD, null);
+            console.error("Runtime VM crashed, popcorn iframe reloaded.");
+            return;
+        }
+        sendIframeResponse(MESSAGES.CALL, {
+            requestId,
+            error: Module.deserialize(error),
+        });
+    }
+}
+function handleCast(request) {
+    if (!Module) {
+        throw new Error("Module not initialized");
+    }
+    const { process, args } = request;
+    Module.cast(process, args);
+}
+function ensureFunctionEval(maybeFunction) {
+    if (typeof maybeFunction !== "function") {
+        throw new Error("Script passed to onRunTrackedJs() is not wrapped in a function");
+    }
+}
+function ensureResultKeyList(result) {
+    if (!Array.isArray(result) && result !== undefined) {
+        throw new Error("Script passed to onRunTrackedJs() returned invalid value, accepted values are arrays and undefined");
+    }
+}
+function deserialize(message) {
+    return JSON.parse(message, (_key, value) => {
+        const isRef = typeof value === "object" &&
+            value !== null &&
+            Object.hasOwn(value, "popcorn_ref") &&
+            Object.getOwnPropertyNames(value).length == 1;
+        if (!isRef) {
+            return value;
+        }
+        return Module?.trackedObjectsMap.get(value.popcorn_ref);
+    });
+}
+export { runIFrame };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+export { Popcorn, PopcornDeinitializedError } from "./popcorn";
+export type { CastOptions, CallOptions } from "./popcorn";
+export type { AnySerializable } from "./types";

package/dist/index.mjs ADDED Viewed

	@@ -0,0 +1 @@
1	+ export { Popcorn, PopcornDeinitializedError } from './popcorn.mjs';

package/dist/plugins/esbuild.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import type { Plugin } from "esbuild";
+import { type PopcornPluginOptions } from "./shared";
+export declare function popcorn(options: PopcornPluginOptions): Plugin;

package/dist/plugins/esbuild.mjs ADDED Viewed

@@ -0,0 +1,53 @@
+import { mkdir, copyFile } from 'fs/promises';
+import { dirname, resolve, basename, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname$1 = dirname(fileURLToPath(import.meta.url));
+// Plugin is at dist/plugins/esbuild.mjs, dist/ is one level up
+const popcornDistDir = resolve(__dirname$1, "..");
+function popcorn(options) {
+    const bundlePath = options.bundlePath;
+    const bundleName = basename(bundlePath);
+    const bundleDir = dirname(bundlePath);
+    let outputDir;
+    return {
+        name: "popcorn",
+        setup(build) {
+            build.onStart(() => {
+                const opts = build.initialOptions;
+                const isEsm = opts.format === "esm";
+                const outdirFallback = opts.outfile !== undefined ? dirname(opts.outfile) : undefined;
+                const outdir = opts.outdir ?? outdirFallback;
+                if (!isEsm) {
+                    throw new Error("[popcorn] Popcorn works only with esm type builds.");
+                }
+                if (outdir === undefined) {
+                    throw new Error("[popcorn] outdir is not specified, cannot copy files");
+                }
+                outputDir = outdir;
+            });
+            build.onEnd(async () => {
+                await mkdir(outputDir, { recursive: true });
+                try {
+                    await Promise.all([
+                        // Copy bundle to wasm directory
+                        copy(bundleName, { inDir: bundleDir, outDir: outputDir }),
+                        // Copy popcorn runtime files to output directory
+                        // These need to be alongside the bundled code for import.meta.url to work
+                        copy("iframe.mjs", { inDir: popcornDistDir, outDir: outputDir }),
+                        copy("AtomVM.mjs", { inDir: popcornDistDir, outDir: outputDir }),
+                        copy("AtomVM.wasm", { inDir: popcornDistDir, outDir: outputDir }),
+                    ]);
+                }
+                catch (err) {
+                    throw new Error("[popcorn] Failed to copy files", { cause: err });
+                }
+            });
+        },
+    };
+}
+async function copy(name, { inDir, outDir }) {
+    return copyFile(join(inDir, name), join(outDir, name));
+}
+export { popcorn };

package/dist/plugins/rollup.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import type { Plugin } from "rollup";
+import { type PopcornPluginOptions } from "./shared";
+export declare function popcorn(options: PopcornPluginOptions): Plugin<unknown>;

package/dist/plugins/rollup.mjs ADDED Viewed

@@ -0,0 +1,31 @@
+import { readFile } from 'fs/promises';
+import { dirname, resolve, basename } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname$1 = dirname(fileURLToPath(import.meta.url));
+// Plugin is at dist/plugins/rollup.mjs, dist/ is one level up
+const popcornDistDir = resolve(__dirname$1, "..");
+function popcorn(options) {
+    const bundlePath = options.bundlePath;
+    const bundleName = basename(bundlePath);
+    return {
+        name: "popcorn",
+        async generateBundle() {
+            // Emit bundle to wasm directory
+            this.emitFile({
+                type: "asset",
+                fileName: resolve(popcornDistDir, bundleName),
+                source: await readFile(bundlePath),
+            });
+            // Emit popcorn runtime files to output directory
+            // These need to be alongside the bundled code for import.meta.url to work
+            for (const name of ["iframe.mjs", "AtomVM.mjs", "AtomVM.wasm"]) {
+                const sourcePath = resolve(popcornDistDir, name);
+                const source = await readFile(sourcePath);
+                this.emitFile({ type: "asset", fileName: name, source });
+            }
+        },
+    };
+}
+export { popcorn };

package/dist/plugins/shared.d.ts ADDED Viewed

@@ -0,0 +1,7 @@
+export declare const DIST_DIR = "node_modules/@swmansion/popcorn/dist";
+export type PopcornPluginOptions = {
+    /**
+     * Path to the .avm bundle file
+     */
+    bundlePath: string;
+};

package/dist/plugins/vite.d.ts ADDED Viewed

@@ -0,0 +1,3 @@
+import { type PopcornPluginOptions } from "./shared";
+import type { Plugin } from "vite";
+export declare function popcorn(options: PopcornPluginOptions): Plugin;

package/dist/plugins/vite.mjs ADDED Viewed

@@ -0,0 +1,92 @@
+import { readFile, stat } from 'fs/promises';
+import { dirname, resolve, basename } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname$1 = dirname(fileURLToPath(import.meta.url));
+// Plugin is at dist/plugins/vite.mjs, dist/ is one level up
+const popcornDistDir = resolve(__dirname$1, "..");
+function popcorn(options) {
+    const bundlePath = options.bundlePath;
+    const bundleName = basename(bundlePath);
+    const bundleUrl = `/${bundleName}`;
+    let assetsDir;
+    return {
+        name: "popcorn",
+        config() {
+            return {
+                // Exclude popcorn from prebundling so import.meta.url resolves correctly
+                optimizeDeps: {
+                    exclude: ["@swmansion/popcorn"],
+                },
+            };
+        },
+        async configResolved(config) {
+            try {
+                await stat(bundlePath);
+            }
+            catch {
+                this.error(`[popcorn] Bundle doesn't exist at '${bundlePath}'`);
+            }
+            config.server.fs.allow.push(popcornDistDir);
+            assetsDir = config.build.assetsDir;
+        },
+        configureServer(server) {
+            server.middlewares.use(async (req, res, next) => {
+                setSharedArrayBufferHeaders(res);
+                const opts = { bundleUrl, bundlePath };
+                const served = await serveAvmBundle(req, res, opts);
+                if (served)
+                    return;
+                next();
+            });
+        },
+        configurePreviewServer(server) {
+            server.middlewares.use(async (req, res, next) => {
+                setSharedArrayBufferHeaders(res);
+                const opts = { bundleUrl, bundlePath };
+                const served = await serveAvmBundle(req, res, opts);
+                if (served)
+                    return;
+                next();
+            });
+        },
+        async generateBundle() {
+            // Emit bundle to wasm directory
+            this.emitFile({
+                type: "asset",
+                fileName: `${assetsDir}/${bundleName}`,
+                source: await readFile(bundlePath),
+            });
+            // Emit AtomVM files to assets directory (same location as iframe.mjs)
+            // Vite treats iframe.mjs as a static asset and doesn't analyze its imports
+            for (const name of ["AtomVM.mjs", "AtomVM.wasm"]) {
+                this.emitFile({
+                    type: "asset",
+                    fileName: `${assetsDir}/${name}`,
+                    source: await readFile(resolve(popcornDistDir, name)),
+                });
+            }
+        },
+    };
+}
+async function serveAvmBundle(req, res, { bundleUrl, bundlePath }) {
+    try {
+        if (req.url === bundleUrl) {
+            const content = await readFile(bundlePath);
+            res.setHeader("Content-Type", "application/octet-stream");
+            res.end(content);
+            return true;
+        }
+        return false;
+    }
+    catch (err) {
+        console.error(`[popcorn] Failed to serve bundle:`, err);
+        throw err;
+    }
+}
+function setSharedArrayBufferHeaders(res) {
+    res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+    res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
+}
+export { popcorn };

package/dist/popcorn.d.ts ADDED Viewed

@@ -0,0 +1,130 @@
+import { type AnySerializable } from "./types";
+/** Options for Popcorn.init() */
+export type PopcornInitOptions = {
+    /** DOM element to mount an iframe */
+    container?: HTMLElement;
+    /** Path to compiled Elixir bundle (`.avm` file). */
+    bundlePath?: 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;
+};
+/** Options for cast method */
+export type CastOptions = {
+    /** Receiver process name. */
+    process?: string;
+};
+/** Options for call method */
+export type CallOptions = {
+    /** Registered Elixir process name. */
+    process?: string;
+    /** Timeout (in milliseconds) for the call */
+    timeoutMs?: number;
+};
+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?: AnySerializable;
+    /** Amount of time it took to process the call */
+    durationMs: number;
+};
+type LogType = "stdout" | "stderr";
+type LogListener = (message: string) => void;
+export declare class PopcornDeinitializedError extends Error {
+}
+/**
+ * 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 bundleURL;
+    private state;
+    private initProcess;
+    private requestId;
+    private calls;
+    private logListeners;
+    private awaitedMessage;
+    private heartbeatTimeout;
+    private reloadN;
+    private constructor();
+    /**
+     * 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 init(options: PopcornInitOptions): Promise<Popcorn>;
+    private mount;
+    /**
+     * 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
+     */
+    call(args: AnySerializable, { process, timeoutMs }?: CallOptions): Promise<CallResult>;
+    /**
+     * 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: AnySerializable, { process }?: CastOptions): void;
+    /**
+     * Destroys an iframe and resets the instance.
+     */
+    deinit(): void;
+    /**
+     * Registers a log listener that will be called when output of the specified type is received.
+     */
+    registerLogListener(listener: LogListener, type: LogType): void;
+    /**
+     * Unregisters a previously registered log listener.
+     */
+    unregisterLogListener(listener: LogListener, type: LogType): void;
+    private notifyLogListeners;
+    private iframeHandler;
+    private onCallAck;
+    private onCall;
+    private onHeartbeat;
+    private reloadIframe;
+    private awaitMessage;
+    trace(...messages: unknown[]): void;
+    private transition;
+    private assertStatus;
+}
+export {};