swarpc 0.6.1 → 0.7.0

package/README.md

@@ -107,3 +107,47 @@ Here's a Svelte example!
     {/each}
 </ul>
 ```
+
+### Make cancelable requests
+
+#### Implementation
+
+To make your procedures meaningfully cancelable, you have to make use of the [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) API. This is passed as a third argument when implementing your procedures:
+
+```js
+server.searchIMDb(async ({ query }, onProgress, abort) => {
+  // If you're doing heavy computation without fetch:
+  let aborted = false
+  abort?.addEventListener("abort", () => {
+    aborted = true
+  })
+
+  // Use `aborted` to check if the request was canceled within your hot loop
+  for (...) {
+    /* here */ if (aborted) return
+    ...
+  }
+
+  // When using fetch:
+  await fetch(..., { signal: abort })
+})
+```
+
+#### Call sites
+
+Instead of calling `await client.myProcedure()` directly, call `client.myProcedure.cancelable()`. You'll get back an object with
+
+- `async cancel(reason)`: a function to cancel the request
+- `request`: a Promise that resolves to the result of the procedure call. `await` it to wait for the request to finish.
+
+Example:
+
+```js
+// Normal call:
+const result = await swarpc.searchIMDb({ query })
+
+// Cancelable call:
+const { request, cancel } = swarpc.searchIMDb.cancelable({ query })
+setTimeout(() => cancel().then(() => console.warn("Took too long!!")), 5_000)
+await request
+```

package/dist/src/client.d.ts

@@ -0,0 +1,22 @@
+import { type LogLevel } from "./log.js";
+import { Hooks, type ProceduresMap, type SwarpcClient } from "./types.js";
+export type { SwarpcClient } from "./types.js";
+/**
+ *
+ * @param procedures procedures the client will be able to call
+ * @param options various options
+ * @param options.worker if provided, the client will use this worker to post messages.
+ * @param options.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 declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, loglevel, hooks, }?: {
+    worker?: Worker;
+    hooks?: Hooks<Procedures>;
+    loglevel?: LogLevel;
+}): SwarpcClient<Procedures>;
+/**
+ * Generate a random request ID, used to identify requests between client and server.
+ * @returns a 6-character hexadecimal string
+ */
+export declare function makeRequestId(): string;
+//# sourceMappingURL=client.d.ts.map

package/dist/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnE,OAAO,EACL,KAAK,EAIL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAkB9C;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EACE,MAAM,EACN,QAAkB,EAClB,KAAU,GACX,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GAC1E,YAAY,CAAC,UAAU,CAAC,CA+F1B;AAmGD;;;GAGG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/src/client.js

@@ -0,0 +1,159 @@
+import { createLogger } from "./log.js";
+import { zProcedures } from "./types.js";
+import { findTransferables } from "./utils.js";
+/**
+ * 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;
+/**
+ *
+ * @param procedures procedures the client will be able to call
+ * @param options various options
+ * @param options.worker if provided, the client will use this worker to post messages.
+ * @param options.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, loglevel = "debug", hooks = {}, } = {}) {
+    const l = createLogger("client", loglevel);
+    // 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`);
+        }
+        const send = async (requestId, msg, options) => {
+            return postMessage(l, worker, hooks, {
+                ...msg,
+                by: "sw&rpc",
+                requestId,
+                functionName,
+            }, options);
+        };
+        // Set the method on the instance
+        const _runProcedure = async (input, onProgress = () => { }, reqid) => {
+            // Validate the input against the procedure's input schema
+            procedures[functionName].input.assert(input);
+            const requestId = reqid ?? makeRequestId();
+            return new Promise((resolve, reject) => {
+                // 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, {
+                    functionName,
+                    resolve,
+                    onProgress,
+                    reject,
+                });
+                const transfer = procedures[functionName].autotransfer === "always"
+                    ? findTransferables(input)
+                    : [];
+                // Post the message to the server
+                l.debug(requestId, `Requesting ${functionName} with`, input);
+                send(requestId, { input }, { transfer })
+                    .then(() => { })
+                    .catch(reject);
+            });
+        };
+        // @ts-expect-error
+        instance[functionName] = _runProcedure;
+        instance[functionName].cancelable = (input, onProgress) => {
+            const requestId = makeRequestId();
+            return {
+                request: _runProcedure(input, onProgress, requestId),
+                async cancel(reason) {
+                    if (!pendingRequests.has(requestId)) {
+                        l.warn(requestId, `Cannot cancel ${functionName} request, it has already been resolved or rejected`);
+                        return;
+                    }
+                    l.debug(requestId, `Cancelling ${functionName} with`, reason);
+                    await send(requestId, { abort: { reason } });
+                    pendingRequests.delete(requestId);
+                },
+            };
+        };
+    }
+    return instance;
+}
+/**
+ * Warms up the client by starting the listener and getting the worker, then posts a message to the worker.
+ * @returns the worker to use
+ */
+async function postMessage(l, worker, hooks, message, options) {
+    await startClientListener(l, worker, hooks);
+    if (!worker && !navigator.serviceWorker.controller)
+        l.warn("", "Service Worker is not controlling the page");
+    // 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");
+    }
+    w.postMessage(message, options);
+}
+/**
+ * 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(l, 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.warn("", "Service Worker is not controlling the page");
+        }
+    }
+    const w = worker ?? navigator.serviceWorker;
+    // Start listening for messages
+    l.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 { 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?.(data.functionName, new Error(data.error.message));
+            handlers.reject(new Error(data.error.message));
+            pendingRequests.delete(requestId);
+        }
+        else if ("progress" in data) {
+            hooks.progress?.(data.functionName, data.progress);
+            handlers.onProgress(data.progress);
+        }
+        else if ("result" in data) {
+            hooks.success?.(data.functionName, data.result);
+            handlers.resolve(data.result);
+            pendingRequests.delete(requestId);
+        }
+    });
+    _clientListenerStarted = true;
+}
+/**
+ * Generate a random request ID, used to identify requests between client and server.
+ * @returns a 6-character hexadecimal string
+ */
+export function makeRequestId() {
+    return Math.random().toString(16).substring(2, 8).toUpperCase();
+}

package/dist/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./client.js";
+export * from "./server.js";
+export type { ProceduresMap, CancelablePromise } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export * from "./client.js";
+export * from "./server.js";

package/dist/src/log.d.ts

@@ -0,0 +1,20 @@
+export declare function createLogger(side: "server" | "client", level?: LogLevel): {
+    debug: (rqid: string | null, message: string, ...args: any[]) => void;
+    info: (rqid: string | null, message: string, ...args: any[]) => void;
+    warn: (rqid: string | null, message: string, ...args: any[]) => void;
+    error: (rqid: string | null, message: string, ...args: any[]) => void;
+};
+export type Logger = ReturnType<typeof createLogger>;
+declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+/**
+ * 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
+ */
+export declare function log(severity: "debug" | "info" | "warn" | "error", side: "server" | "client", rqid: string | null, message: string, ...args: any[]): void;
+export {};
+//# sourceMappingURL=log.d.ts.map

package/dist/src/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/log.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,KAAK,GAAE,QAAkB;kBAwBX,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;iBAA9C,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;iBAA9C,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;kBAA9C,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;EAd7D;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAA;AAEpD,QAAA,MAAM,UAAU,6CAA8C,CAAA;AAC9D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAalD;;;;;;;GAOG;AACH,wBAAgB,GAAG,CACjB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC7C,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,EAAE,MAAM,EACf,GAAG,IAAI,EAAE,GAAG,EAAE,QAkBf"}

package/dist/src/log.js

@@ -0,0 +1,45 @@
+export function createLogger(side, level = "debug") {
+    const enabledLevels = LOG_LEVELS.slice(LOG_LEVELS.indexOf(level));
+    return {
+        debug: enabledLevels.includes("debug") ? logger("debug", side) : () => { },
+        info: enabledLevels.includes("info") ? logger("info", side) : () => { },
+        warn: enabledLevels.includes("warn") ? logger("warn", side) : () => { },
+        error: enabledLevels.includes("error") ? logger("error", side) : () => { },
+    };
+}
+const LOG_LEVELS = ["debug", "info", "warn", "error"];
+/**
+ * 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
+ */
+export 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/src/server.d.ts

@@ -0,0 +1,15 @@
+import { type LogLevel } from "./log.js";
+import { type ProceduresMap, type SwarpcServer } from "./types.js";
+export type { SwarpcServer } from "./types.js";
+/**
+ * Creates a sw&rpc server instance.
+ * @param procedures procedures the server will implement
+ * @param options various options
+ * @param options.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 declare function Server<Procedures extends ProceduresMap>(procedures: Procedures, { worker, loglevel }?: {
+    worker?: Worker;
+    loglevel?: LogLevel;
+}): SwarpcServer<Procedures>;
+//# sourceMappingURL=server.d.ts.map

package/dist/src/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAK9C;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EAAE,MAAM,EAAE,QAAkB,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GAC5E,YAAY,CAAC,UAAU,CAAC,CAkK1B"}

package/dist/src/server.js

@@ -0,0 +1,132 @@
+import { type } from "arktype";
+import { createLogger } from "./log.js";
+import { PayloadHeaderSchema, PayloadSchema, zImplementations, zProcedures, } from "./types.js";
+import { findTransferables } from "./utils.js";
+const abortControllers = new Map();
+const abortedRequests = new Set();
+/**
+ * Creates a sw&rpc server instance.
+ * @param procedures procedures the server will implement
+ * @param options various options
+ * @param options.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, loglevel = "debug" } = {}) {
+    const l = createLogger("server", loglevel);
+    // 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] = (input, onProgress, abortSignal) => {
+                abortSignal?.throwIfAborted();
+                return new Promise((resolve, reject) => {
+                    abortSignal?.addEventListener("abort", () => {
+                        let { requestId, reason } = abortSignal?.reason;
+                        l.debug(requestId, `Aborted ${functionName} request: ${reason}`);
+                        reject({ aborted: reason });
+                    });
+                    implementation(input, onProgress, abortSignal)
+                        .then(resolve)
+                        .catch(reject);
+                });
+            };
+        });
+    }
+    instance.start = (self) => {
+        // Used to post messages back to the client
+        const postMessage = async (autotransfer, data) => {
+            const transfer = autotransfer ? [] : 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 { requestId, functionName } = PayloadHeaderSchema(type.enumerated(...Object.keys(procedures))).assert(event.data);
+            l.debug(requestId, `Received request for ${functionName}`, event.data);
+            // Get autotransfer preference from the procedure definition
+            const { autotransfer = "output-only", ...schemas } = instance[zProcedures][functionName];
+            // Shorthand function with functionName, requestId, etc. set
+            const postMsg = async (data) => {
+                if (abortedRequests.has(requestId))
+                    return;
+                await postMessage(autotransfer !== "never", {
+                    by: "sw&rpc",
+                    functionName,
+                    requestId,
+                    ...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;
+            }
+            // Define payload schema for incoming messages
+            const payload = PayloadSchema(type(`"${functionName}"`), schemas.input, schemas.progress, schemas.success).assert(event.data);
+            // Handle abortion requests (pro-choice ftw!!)
+            if (payload.abort) {
+                const controller = abortControllers.get(requestId);
+                if (!controller)
+                    await postError("No abort controller found for request");
+                controller?.abort(payload.abort.reason);
+                return;
+            }
+            // Set up the abort controller for this request
+            abortControllers.set(requestId, new AbortController());
+            if (!payload.input) {
+                await postError("No input provided");
+                return;
+            }
+            // Call the implementation with the input and a progress callback
+            await implementation(payload.input, async (progress) => {
+                l.debug(requestId, `Progress for ${functionName}`, progress);
+                await postMsg({ progress });
+            }, abortControllers.get(requestId)?.signal)
+                // Send errors
+                .catch(async (error) => {
+                // Handle errors caused by abortions
+                if ("aborted" in error) {
+                    l.debug(requestId, `Received abort error for ${functionName}`, error.aborted);
+                    abortedRequests.add(requestId);
+                    abortControllers.delete(requestId);
+                    return;
+                }
+                l.error(requestId, `Error in ${functionName}`, error);
+                await postError(error);
+            })
+                // Send results
+                .then(async (result) => {
+                l.debug(requestId, `Result for ${functionName}`, result);
+                await postMsg({ result });
+            })
+                .finally(() => {
+                abortedRequests.delete(requestId);
+            });
+        });
+    };
+    return instance;
+}