swarpc 0.6.1 → 0.7.1

package/src/server.ts

@@ -0,0 +1,193 @@
+import { type } from "arktype"
+import { createLogger, type LogLevel } from "./log.js"
+import {
+  ImplementationsMap,
+  Payload,
+  PayloadCore,
+  PayloadHeaderSchema,
+  PayloadSchema,
+  zImplementations,
+  zProcedures,
+  type ProceduresMap,
+  type SwarpcServer,
+} from "./types.js"
+import { findTransferables } from "./utils.js"
+
+export type { SwarpcServer } from "./types.js"
+
+const abortControllers = new Map<string, AbortController>()
+const abortedRequests = new Set<string>()
+
+/**
+ * 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 extends ProceduresMap>(
+  procedures: Procedures,
+  { worker, loglevel = "debug" }: { worker?: Worker; loglevel?: LogLevel } = {}
+): SwarpcServer<Procedures> {
+  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]: {} as ImplementationsMap<Procedures>,
+    start: (self: Window) => {},
+  } as SwarpcServer<Procedures>
+
+  // 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)
+        })
+      }
+    }) as SwarpcServer<Procedures>[typeof functionName]
+  }
+
+  instance.start = (self: Window) => {
+    // Used to post messages back to the client
+    const postMessage = async (
+      autotransfer: boolean,
+      data: Payload<Procedures>
+    ) => {
+      const transfer = autotransfer ? [] : findTransferables(data)
+
+      if (worker) {
+        self.postMessage(data, { transfer })
+      } else {
+        await (self as any).clients.matchAll().then((clients: any[]) => {
+          clients.forEach((client) => client.postMessage(data, { transfer }))
+        })
+      }
+    }
+
+    // Listen for messages from the client
+    self.addEventListener("message", async (event: MessageEvent) => {
+      // 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: PayloadCore<Procedures, typeof functionName>
+      ) => {
+        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: any) =>
+        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: any) => {
+          l.debug(requestId, `Progress for ${functionName}`, progress)
+          await postMsg({ progress })
+        },
+        abortControllers.get(requestId)?.signal
+      )
+        // Send errors
+        .catch(async (error: any) => {
+          // 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: any) => {
+          l.debug(requestId, `Result for ${functionName}`, result)
+          await postMsg({ result })
+        })
+        .finally(() => {
+          abortedRequests.delete(requestId)
+        })
+    })
+  }
+
+  return instance
+}

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { Type } from "arktype"
+import { type, type Type } from "arktype"
 
 /**
  * A procedure declaration
@@ -30,16 +30,35 @@ export type Procedure<I extends Type, P extends Type, S extends Type> = {
   autotransfer?: "always" | "never" | "output-only"
 }
 
+/**
+ * A promise that you can cancel by calling `.cancel(reason)` on it:
+ *
+ * ```js
+ * const { request, cancel } = client.runProcedure.cancelable(input, onProgress)
+ * setTimeout(() => cancel("Cancelled by user"), 1000)
+ * const result = await request
+ * ```
+ */
+export type CancelablePromise<T> = {
+  request: Promise<T>
+  /**
+   * Abort the request.
+   * @param reason The reason for cancelling the request.
+   */
+  cancel: (reason: string) => Promise<void>
+}
+
 /**
  * An implementation of a procedure
  */
 export type ProcedureImplementation<
   I extends Type,
   P extends Type,
-  S extends Type
+  S extends Type,
 > = (
   input: I["inferOut"],
-  onProgress: (progress: P["inferIn"]) => void
+  onProgress: (progress: P["inferIn"]) => void,
+  abortSignal?: AbortSignal
 ) => Promise<S["inferIn"]>
 
 /**
@@ -85,19 +104,32 @@ export type Hooks<Procedures extends ProceduresMap> = {
   ) => void
 }
 
+export const PayloadHeaderSchema = type("<Name extends string>", {
+  by: '"sw&rpc"',
+  functionName: "Name",
+  requestId: "string >= 1",
+})
+
 export type PayloadHeader<
   PM extends ProceduresMap,
-  Name extends keyof PM = keyof PM
+  Name extends keyof PM = keyof PM,
 > = {
   by: "sw&rpc"
   functionName: Name & string
   requestId: string
-  autotransfer: PM[Name]["autotransfer"]
 }
 
+export const PayloadCoreSchema = type("<I, P, S>", {
+  "input?": "I",
+  "progress?": "P",
+  "result?": "S",
+  "abort?": { reason: "string" },
+  "error?": { message: "string" },
+})
+
 export type PayloadCore<
   PM extends ProceduresMap,
-  Name extends keyof PM = keyof PM
+  Name extends keyof PM = keyof PM,
 > =
   | {
       input: PM[Name]["input"]["inferOut"]
@@ -108,25 +140,45 @@ export type PayloadCore<
   | {
       result: PM[Name]["success"]["inferOut"]
     }
+  | {
+      abort: { reason: string }
+    }
   | {
       error: { message: string }
     }
 
+export const PayloadSchema = type
+  .scope({ PayloadCoreSchema, PayloadHeaderSchema })
+  .type("<Name extends string, I, P, S>", [
+    "PayloadHeaderSchema<Name>",
+    "&",
+    "PayloadCoreSchema<I, P, S>",
+  ])
+
 /**
  * The effective payload as sent by the server to the client
  */
 export type Payload<
   PM extends ProceduresMap,
-  Name extends keyof PM = keyof PM
+  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
+ * A procedure's corresponding method on the client instance -- used to call the procedure. If you want to be able to cancel the request, you can use the `cancelable` method instead of running the procedure directly.
  */
-export type ClientMethod<P extends Procedure<Type, Type, Type>> = (
+export type ClientMethod<P extends Procedure<Type, Type, Type>> = ((
   input: P["input"]["inferIn"],
   onProgress?: (progress: P["progress"]["inferOut"]) => void
-) => Promise<P["success"]["inferOut"]>
+) => Promise<P["success"]["inferOut"]>) & {
+  /**
+   * A method that returns a `CancelablePromise`. Cancel it by calling `.cancel(reason)` on it, and wait for the request to resolve by awaiting the `request` property on the returned object.
+   */
+  cancelable: (
+    input: P["input"]["inferIn"],
+    onProgress?: (progress: P["progress"]["inferOut"]) => void,
+    requestId?: string
+  ) => CancelablePromise<P["success"]["inferOut"]>
+}
 
 /**
  * Symbol used as the key for the procedures map on the server instance
@@ -138,7 +190,9 @@ export const zImplementations = Symbol("SWARPC implementations")
 export const zProcedures = Symbol("SWARPC procedures")
 
 /**
- * The sw&rpc client instance, which provides methods to call procedures
+ * The sw&rpc client instance, which provides methods to call procedures.
+ * Each property of the procedures map will be a method, that accepts an input, an optional onProgress callback and an optional request ID.
+ * If you want to be able to cancel the request, you can set the request's ID yourself, and call `.abort(requestId, reason)` on the client instance to cancel it.
  */
 export type SwarpcClient<Procedures extends ProceduresMap> = {
   [zProcedures]: Procedures
@@ -153,7 +207,7 @@ export type SwarpcClient<Procedures extends ProceduresMap> = {
 export type SwarpcServer<Procedures extends ProceduresMap> = {
   [zProcedures]: Procedures
   [zImplementations]: ImplementationsMap<Procedures>
-  start(self: Window): void
+  start(self: Window | Worker): void
 } & {
   [F in keyof Procedures]: (
     impl: ProcedureImplementation<

package/dist/swarpc.d.ts

@@ -1,25 +0,0 @@
-import { Hooks, type ProceduresMap, type SwarpcClient, type SwarpcServer } from "./types.js";
-export type { ProceduresMap, SwarpcClient, SwarpcServer } from "./types.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 declare function Server<Procedures extends ProceduresMap>(procedures: Procedures, { worker }?: {
-    worker?: Worker;
-}): SwarpcServer<Procedures>;
-/**
- *
- * @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 declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, hooks }?: {
-    worker?: Worker;
-    hooks?: Hooks<Procedures>;
-}): SwarpcClient<Procedures>;
-//# sourceMappingURL=swarpc.d.ts.map

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);
-    }
-}