swarpc 0.6.0 → 0.7.0

package/dist/swarpc.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"swarpc.d.ts","sourceRoot":"","sources":["../src/swarpc.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EAML,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3E;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EAAE,MAAM,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,YAAY,CAAC,UAAU,CAAC,CAuG1B;AA+FD;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EAAE,MAAM,EAAE,KAAU,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;CAAO,GAC1E,YAAY,CAAC,UAAU,CAAC,CA0D1B"}

package/dist/swarpc.js

@@ -1,264 +0,0 @@
-import { type } from "arktype";
-import { zImplementations, zProcedures, } from "./types.js";
-import { findTransferables } from "./utils.js";
-/**
- * Creates a sw&rpc server instance.
- * @param procedures procedures the server will implement
- * @param param1 various options
- * @param param1.worker if provided, the server will use this worker to post messages, instead of sending it to all clients
- * @returns a SwarpcServer instance. Each property of the procedures map will be a method, that accepts a function implementing the procedure. There is also .start(), to be called after implementing all procedures.
- */
-export function Server(procedures, { worker } = {}) {
-    // Initialize the instance.
-    // Procedures and implementations are stored on properties with symbol keys,
-    // to avoid any conflicts with procedure names, and also discourage direct access to them.
-    const instance = {
-        [zProcedures]: procedures,
-        [zImplementations]: {},
-        start: (self) => { },
-    };
-    // Set all implementation-setter methods
-    for (const functionName in procedures) {
-        instance[functionName] = ((implementation) => {
-            if (!instance[zProcedures][functionName]) {
-                throw new Error(`No procedure found for function name: ${functionName}`);
-            }
-            instance[zImplementations][functionName] = implementation;
-        });
-    }
-    // Define payload schema for incoming messages
-    const PayloadSchema = type.or(...Object.entries(procedures).map(([functionName, { input }]) => ({
-        functionName: type(`"${functionName}"`),
-        requestId: type("string >= 1"),
-        input,
-    })));
-    instance.start = (self) => {
-        // Used to post messages back to the client
-        const postMessage = async (data) => {
-            const transfer = data.autotransfer === "never" ? [] : findTransferables(data);
-            if (worker) {
-                self.postMessage(data, { transfer });
-            }
-            else {
-                await self.clients.matchAll().then((clients) => {
-                    clients.forEach((client) => client.postMessage(data, { transfer }));
-                });
-            }
-        };
-        // Listen for messages from the client
-        self.addEventListener("message", async (event) => {
-            // Decode the payload
-            const { functionName, requestId, input } = PayloadSchema.assert(event.data);
-            l.server.debug(requestId, `Received request for ${functionName}`, input);
-            // Get autotransfer preference from the procedure definition
-            const { autotransfer = "output-only" } = instance[zProcedures][functionName];
-            // Shorthand function with functionName, requestId, etc. set
-            const postMsg = async (data) => postMessage({
-                by: "sw&rpc",
-                functionName,
-                requestId,
-                autotransfer,
-                ...data,
-            });
-            // Prepare a function to post errors back to the client
-            const postError = async (error) => postMsg({
-                error: {
-                    message: "message" in error ? error.message : String(error),
-                },
-            });
-            // Retrieve the implementation for the requested function
-            const implementation = instance[zImplementations][functionName];
-            if (!implementation) {
-                await postError("No implementation found");
-                return;
-            }
-            // Call the implementation with the input and a progress callback
-            await implementation(input, async (progress) => {
-                l.server.debug(requestId, `Progress for ${functionName}`, progress);
-                await postMsg({ progress });
-            })
-                // Send errors
-                .catch(async (error) => {
-                l.server.error(requestId, `Error in ${functionName}`, error);
-                await postError(error);
-            })
-                // Send results
-                .then(async (result) => {
-                l.server.debug(requestId, `Result for ${functionName}`, result);
-                await postMsg({ result });
-            });
-        });
-    };
-    return instance;
-}
-/**
- * Generate a random request ID, used to identify requests between client and server.
- * @returns a 6-character hexadecimal string
- */
-function generateRequestId() {
-    return Math.random().toString(16).substring(2, 8).toUpperCase();
-}
-/**
- * Pending requests are stored in a map, where the key is the request ID.
- * Each request has a set of handlers: resolve, reject, and onProgress.
- * This allows having a single listener for the client, and having multiple in-flight calls to the same procedure.
- */
-const pendingRequests = new Map();
-// Have we started the client listener?
-let _clientListenerStarted = false;
-/**
- * Starts the client listener, which listens for messages from the sw&rpc server.
- * @param worker if provided, the client will use this worker to listen for messages, instead of using the service worker
- * @returns
- */
-async function startClientListener(worker, hooks = {}) {
-    if (_clientListenerStarted)
-        return;
-    // Get service worker registration if no worker is provided
-    if (!worker) {
-        const sw = await navigator.serviceWorker.ready;
-        if (!sw?.active) {
-            throw new Error("[SWARPC Client] Service Worker is not active");
-        }
-        if (!navigator.serviceWorker.controller) {
-            l.client.warn("", "Service Worker is not controlling the page");
-        }
-    }
-    const w = worker ?? navigator.serviceWorker;
-    // Start listening for messages
-    l.client.debug("", "Starting client listener on", w);
-    w.addEventListener("message", (event) => {
-        // Get the data from the event
-        const eventData = event.data || {};
-        // Ignore other messages that aren't for us
-        if (eventData?.by !== "sw&rpc")
-            return;
-        // We don't use a arktype schema here, we trust the server to send valid data
-        const { functionName, requestId, ...data } = eventData;
-        // Sanity check in case we somehow receive a message without requestId
-        if (!requestId) {
-            throw new Error("[SWARPC Client] Message received without requestId");
-        }
-        // Get the associated pending request handlers
-        const handlers = pendingRequests.get(requestId);
-        if (!handlers) {
-            throw new Error(`[SWARPC Client] ${requestId} has no active request handlers`);
-        }
-        // React to the data received: call hook, call handler,
-        // and remove the request from pendingRequests (unless it's a progress update)
-        if ("error" in data) {
-            hooks.error?.(functionName, new Error(data.error.message));
-            handlers.reject(new Error(data.error.message));
-            pendingRequests.delete(requestId);
-        }
-        else if ("progress" in data) {
-            hooks.progress?.(functionName, data.progress);
-            handlers.onProgress(data.progress);
-        }
-        else if ("result" in data) {
-            hooks.success?.(functionName, data.result);
-            handlers.resolve(data.result);
-            pendingRequests.delete(requestId);
-        }
-    });
-    _clientListenerStarted = true;
-}
-/**
- *
- * @param procedures procedures the client will be able to call
- * @param param1 various options
- * @param param1.worker if provided, the client will use this worker to post messages.
- * @param param1.hooks hooks to run on messages received from the server
- * @returns a sw&rpc client instance. Each property of the procedures map will be a method, that accepts an input and an optional onProgress callback.
- */
-export function Client(procedures, { worker, hooks = {} } = {}) {
-    // Store procedures on a symbol key, to avoid conflicts with procedure names
-    const instance = { [zProcedures]: procedures };
-    for (const functionName of Object.keys(procedures)) {
-        if (typeof functionName !== "string") {
-            throw new Error(`[SWARPC Client] Invalid function name, don't use symbols`);
-        }
-        // Set the method on the instance
-        // @ts-expect-error
-        instance[functionName] = (async (input, onProgress = () => { }) => {
-            // Validate the input against the procedure's input schema
-            procedures[functionName].input.assert(input);
-            // Ensure that we're listening for messages from the server
-            await startClientListener(worker, hooks);
-            // If no worker is provided, we use the service worker
-            const w = worker ?? (await navigator.serviceWorker.ready.then((r) => r.active));
-            if (!w) {
-                throw new Error("[SWARPC Client] No active service worker found");
-            }
-            return new Promise((resolve, reject) => {
-                if (!worker && !navigator.serviceWorker.controller)
-                    l.client.warn("", "Service Worker is not controlling the page");
-                const requestId = generateRequestId();
-                // Store promise handlers (as well as progress updates handler)
-                // so the client listener can resolve/reject the promise (and react to progress updates)
-                // when the server sends messages back
-                pendingRequests.set(requestId, { resolve, onProgress, reject });
-                // Post the message to the server
-                l.client.debug(requestId, `Requesting ${functionName} with`, input);
-                w.postMessage({ functionName, input, requestId }, {
-                    transfer: procedures[functionName].autotransfer === "always"
-                        ? findTransferables(input)
-                        : [],
-                });
-            });
-        });
-    }
-    return instance;
-}
-/**
- * Convenience shortcuts for logging.
- */
-const l = {
-    server: {
-        debug: logger("debug", "server"),
-        info: logger("info", "server"),
-        warn: logger("warn", "server"),
-        error: logger("error", "server"),
-    },
-    client: {
-        debug: logger("debug", "client"),
-        info: logger("info", "client"),
-        warn: logger("warn", "client"),
-        error: logger("error", "client"),
-    },
-};
-/**
- * Creates partially-applied logging functions given the first 2 args
- * @param severity
- * @param side
- * @returns
- */
-function logger(severity, side) {
-    return (rqid, message, ...args) => log(severity, side, rqid, message, ...args);
-}
-/**
- * Send log messages to the console, with a helpful prefix.
- * @param severity
- * @param side
- * @param rqid request ID
- * @param message
- * @param args passed to console methods directly
- */
-function log(severity, side, rqid, message, ...args) {
-    const prefix = "[" +
-        ["SWARPC", side, rqid ? `%c${rqid}%c` : ""].filter(Boolean).join(" ") +
-        "]";
-    const prefixStyles = rqid ? ["color: cyan;", "color: inherit;"] : [];
-    if (severity === "debug") {
-        console.debug(prefix, ...prefixStyles, message, ...args);
-    }
-    else if (severity === "info") {
-        console.info(prefix, ...prefixStyles, message, ...args);
-    }
-    else if (severity === "warn") {
-        console.warn(prefix, ...prefixStyles, message, ...args);
-    }
-    else if (severity === "error") {
-        console.error(prefix, ...prefixStyles, message, ...args);
-    }
-}

package/dist/types.d.ts

@@ -1,114 +0,0 @@
-import type { Type } from "arktype";
-/**
- * A procedure declaration
- */
-export type Procedure<I extends Type, P extends Type, S extends Type> = {
-    /**
-     * ArkType type for the input (first argument) of the procedure, when calling it from the client.
-     */
-    input: I;
-    /**
-     * ArkType type for the data as the first argument given to the `onProgress` callback
-     * when calling the procedure from the client.
-     */
-    progress: P;
-    /**
-     * ArkType type for the output (return value) of the procedure, when calling it from the client.
-     */
-    success: S;
-    /**
-     * When should the procedure automatically add ArrayBuffers and other transferable objects
-     * to the [transfer list](https://developer.mozilla.org/en-US/docs/Web/API/DedicatedWorkerGlobalScope/postMessage#transfer)
-     * when sending messages, both from the client to the server and vice versa.
-     *
-     * Transferring objects can improve performance by avoiding copies of large objects,
-     * but _moves_ them to the other context, meaning that they cannot be used in the original context after being sent.
-     *
-     * 'output-only' by default: only transferables sent from the server to the client will be transferred.
-     */
-    autotransfer?: "always" | "never" | "output-only";
-};
-/**
- * An implementation of a procedure
- */
-export type ProcedureImplementation<I extends Type, P extends Type, S extends Type> = (input: I["inferOut"], onProgress: (progress: P["inferIn"]) => void) => Promise<S["inferIn"]>;
-/**
- * Declarations of procedures by name.
- */
-export type ProceduresMap = Record<string, Procedure<Type, Type, Type>>;
-/**
- * Implementations of procedures by name
- */
-export type ImplementationsMap<Procedures extends ProceduresMap> = {
-    [F in keyof Procedures]: ProcedureImplementation<Procedures[F]["input"], Procedures[F]["progress"], Procedures[F]["success"]>;
-};
-/**
- * Declaration of hooks to run on messages received from the server
- */
-export type Hooks<Procedures extends ProceduresMap> = {
-    /**
-     * Called when a procedure call has been successful.
-     */
-    success?: <Procedure extends keyof ProceduresMap>(procedure: Procedure, data: Procedures[Procedure]["success"]["inferOut"]) => void;
-    /**
-     * Called when a procedure call has failed.
-     */
-    error?: <Procedure extends keyof ProceduresMap>(procedure: Procedure, error: Error) => void;
-    /**
-     * Called when a procedure call sends progress updates.
-     */
-    progress?: <Procedure extends keyof ProceduresMap>(procedure: Procedure, data: Procedures[Procedure]["progress"]["inferOut"]) => void;
-};
-export type PayloadHeader<PM extends ProceduresMap, Name extends keyof PM = keyof PM> = {
-    by: "sw&rpc";
-    functionName: Name & string;
-    requestId: string;
-    autotransfer: PM[Name]["autotransfer"];
-};
-export type PayloadCore<PM extends ProceduresMap, Name extends keyof PM = keyof PM> = {
-    input: PM[Name]["input"]["inferOut"];
-} | {
-    progress: PM[Name]["progress"]["inferOut"];
-} | {
-    result: PM[Name]["success"]["inferOut"];
-} | {
-    error: {
-        message: string;
-    };
-};
-/**
- * The effective payload as sent by the server to the client
- */
-export type Payload<PM extends ProceduresMap, Name extends keyof PM = keyof PM> = PayloadHeader<PM, Name> & PayloadCore<PM, Name>;
-/**
- * A procedure's corresponding method on the client instance -- used to call the procedure
- */
-export type ClientMethod<P extends Procedure<Type, Type, Type>> = (input: P["input"]["inferIn"], onProgress?: (progress: P["progress"]["inferOut"]) => void) => Promise<P["success"]["inferOut"]>;
-/**
- * Symbol used as the key for the procedures map on the server instance
- */
-export declare const zImplementations: unique symbol;
-/**
- * Symbol used as the key for the procedures map on instances
- */
-export declare const zProcedures: unique symbol;
-/**
- * The sw&rpc client instance, which provides methods to call procedures
- */
-export type SwarpcClient<Procedures extends ProceduresMap> = {
-    [zProcedures]: Procedures;
-} & {
-    [F in keyof Procedures]: ClientMethod<Procedures[F]>;
-};
-/**
- * The sw&rpc server instance, which provides methods to register procedure implementations,
- * and listens for incoming messages that call those procedures
- */
-export type SwarpcServer<Procedures extends ProceduresMap> = {
-    [zProcedures]: Procedures;
-    [zImplementations]: ImplementationsMap<Procedures>;
-    start(self: Window): void;
-} & {
-    [F in keyof Procedures]: (impl: ProcedureImplementation<Procedures[F]["input"], Procedures[F]["progress"], Procedures[F]["success"]>) => void;
-};
-//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1,8 +0,0 @@
-/**
- * Symbol used as the key for the procedures map on the server instance
- */
-export const zImplementations = Symbol("SWARPC implementations");
-/**
- * Symbol used as the key for the procedures map on instances
- */
-export const zProcedures = Symbol("SWARPC procedures");

package/dist/utils.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAiBA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,GAAG,YAAY,EAAE,CAsB5D"}