swarpc 0.4.0 → 0.5.0

package/dist/swarpc.d.ts

@@ -1,8 +1,22 @@
 import { 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.
+ * @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 }?: {
     worker?: Worker;
 }): SwarpcClient<Procedures>;

package/dist/swarpc.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"swarpc.d.ts","sourceRoot":"","sources":["../src/swarpc.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAEnB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3E,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,CA+E1B;AA4DD,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,CAyC1B"}
+{"version":3,"file":"swarpc.d.ts","sourceRoot":"","sources":["../src/swarpc.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,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,CA0G1B;AAoFD;;;;;;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,CA0D1B"}

package/dist/swarpc.js

@@ -1,11 +1,23 @@
 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]) {
@@ -14,61 +26,89 @@ export function Server(procedures, { worker } = {}) {
             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);
+                self.postMessage(data, { transfer });
             }
             else {
                 await self.clients.matchAll().then((clients) => {
-                    clients.forEach((client) => client.postMessage(data));
+                    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);
-            const postError = async (error) => postMessage({
-                functionName,
-                requestId,
+            // 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({ 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 postMessage({ functionName, requestId, 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 postMessage({ functionName, requestId, 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) {
     if (_clientListenerStarted)
         return;
+    // Get service worker registration if no worker is provided
     if (!worker) {
         const sw = await navigator.serviceWorker.ready;
         if (!sw?.active) {
@@ -79,16 +119,23 @@ async function startClientListener(worker) {
         }
     }
     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
+        // We don't use a arktype schema here, we trust the server to send valid data
         const { functionName, requestId, ...data } = event.data || {};
+        // 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
+        // Unless it's a progress update, the request is finished, thus we can remove it from the pending requests
         if ("error" in data) {
             handlers.reject(new Error(data.error.message));
             pendingRequests.delete(requestId);
@@ -103,16 +150,28 @@ async function startClientListener(worker) {
     });
     _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.
+ * @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 } = {}) {
+    // 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);
+            // 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");
@@ -121,28 +180,56 @@ export function Client(procedures, { worker } = {}) {
                 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 });
+                w.postMessage({ functionName, input, requestId }, {
+                    transfer: procedures[functionName].autotransfer === "always"
+                        ? findTransferables(input)
+                        : [],
+                });
             });
         });
     }
     return instance;
 }
+/**
+ * Convenience shortcuts for logging.
+ */
 const l = {
     server: {
-        debug: (rqid, message, ...args) => log("debug", "server", rqid, message, ...args),
-        info: (rqid, message, ...args) => log("info", "server", rqid, message, ...args),
-        warn: (rqid, message, ...args) => log("warn", "server", rqid, message, ...args),
-        error: (rqid, message, ...args) => log("error", "server", rqid, message, ...args),
+        debug: logger("debug", "server"),
+        info: logger("info", "server"),
+        warn: logger("warn", "server"),
+        error: logger("error", "server"),
     },
     client: {
-        debug: (rqid, message, ...args) => log("debug", "client", rqid, message, ...args),
-        info: (rqid, message, ...args) => log("info", "client", rqid, message, ...args),
-        warn: (rqid, message, ...args) => log("warn", "client", rqid, message, ...args),
-        error: (rqid, message, ...args) => log("error", "client", rqid, message, ...args),
+        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(" ") +

package/dist/types.d.ts

@@ -1,22 +1,71 @@
 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";
 };
-export type ProcedureImplementation<I extends Type, P extends Type, S extends Type> = (input: I["inferOut"], onProgress: (progress: P["inferOut"]) => void) => Promise<S["inferOut"]>;
+/**
+ * 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"]>;
 };
+/**
+ * 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>;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAEnC,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,IAAI;IACtE,KAAK,EAAE,CAAC,CAAA;IACR,QAAQ,EAAE,CAAC,CAAA;IACX,OAAO,EAAE,CAAC,CAAA;CACX,CAAA;AAED,MAAM,MAAM,uBAAuB,CACjC,CAAC,SAAS,IAAI,EACd,CAAC,SAAS,IAAI,EACd,CAAC,SAAS,IAAI,IACZ,CACF,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,EACpB,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI,KAC1C,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;AAE3B,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAEvE,MAAM,MAAM,kBAAkB,CAAC,UAAU,SAAS,aAAa,IAAI;KAChE,CAAC,IAAI,MAAM,UAAU,GAAG,uBAAuB,CAC9C,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EACtB,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EACzB,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CACzB;CACF,CAAA;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAChE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,EAC5B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI,KACvD,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;AAEtC,eAAO,MAAM,gBAAgB,eAAmC,CAAA;AAChE,eAAO,MAAM,WAAW,eAA8B,CAAA;AAEtD,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,aAAa,IAAI;IAC3D,CAAC,WAAW,CAAC,EAAE,UAAU,CAAA;CAC1B,GAAG;KACD,CAAC,IAAI,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CACrD,CAAA;AAED,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,aAAa,IAAI;IAC3D,CAAC,WAAW,CAAC,EAAE,UAAU,CAAA;IACzB,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAA;IAClD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,GAAG;KACD,CAAC,IAAI,MAAM,UAAU,GAAG,CACvB,IAAI,EAAE,uBAAuB,CAC3B,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EACtB,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EACzB,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CACzB,KACE,IAAI;CACV,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAA;AAEnC;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,EAAE,CAAC,SAAS,IAAI,IAAI;IACtE;;OAEG;IACH,KAAK,EAAE,CAAC,CAAA;IACR;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAA;IACX;;OAEG;IACH,OAAO,EAAE,CAAC,CAAA;IACV;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,aAAa,CAAA;CAClD,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,CACjC,CAAC,SAAS,IAAI,EACd,CAAC,SAAS,IAAI,EACd,CAAC,SAAS,IAAI,IACZ,CACF,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,EACpB,UAAU,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,SAAS,CAAC,KAAK,IAAI,KACzC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAA;AAE1B;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAEvE;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,UAAU,SAAS,aAAa,IAAI;KAChE,CAAC,IAAI,MAAM,UAAU,GAAG,uBAAuB,CAC9C,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EACtB,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EACzB,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CACzB;CACF,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAChE,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,EAC5B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,UAAU,CAAC,KAAK,IAAI,KACvD,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,CAAC,CAAC,CAAA;AAEtC;;GAEG;AACH,eAAO,MAAM,gBAAgB,eAAmC,CAAA;AAChE;;GAEG;AACH,eAAO,MAAM,WAAW,eAA8B,CAAA;AAEtD;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,aAAa,IAAI;IAC3D,CAAC,WAAW,CAAC,EAAE,UAAU,CAAA;CAC1B,GAAG;KACD,CAAC,IAAI,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CACrD,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,aAAa,IAAI;IAC3D,CAAC,WAAW,CAAC,EAAE,UAAU,CAAA;IACzB,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAA;IAClD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAC1B,GAAG;KACD,CAAC,IAAI,MAAM,UAAU,GAAG,CACvB,IAAI,EAAE,uBAAuB,CAC3B,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EACtB,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EACzB,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CACzB,KACE,IAAI;CACV,CAAA"}

package/dist/types.js

@@ -1,2 +1,8 @@
+/**
+ * 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

@@ -0,0 +1,2 @@
+export declare function findTransferables(value: any): Transferable[];
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

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

package/dist/utils.js

@@ -0,0 +1,32 @@
+// TODO: keep it in sync with web standards, how?
+const transferableClasses = [
+    OffscreenCanvas,
+    ImageBitmap,
+    MessagePort,
+    MediaSourceHandle,
+    ReadableStream,
+    WritableStream,
+    TransformStream,
+    AudioData,
+    VideoFrame,
+    RTCDataChannel,
+    ArrayBuffer,
+];
+export function findTransferables(value) {
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (typeof value === "object") {
+        if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+            return [value];
+        }
+        if (transferableClasses.some((cls) => value instanceof cls)) {
+            return [value];
+        }
+        if (Array.isArray(value)) {
+            return value.flatMap(findTransferables);
+        }
+        return Object.values(value).flatMap(findTransferables);
+    }
+    return [];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarpc",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Full type-safe RPC library for service worker -- move things off of the UI thread with ease!",
   "keywords": [
     "service-workers",
@@ -28,6 +28,7 @@
   "types": "dist/swarpc.d.ts",
   "scripts": {
     "build": "tsc",
+    "dev": "tsc --watch",
     "test": "echo \"Error: no test specified\" && exit 1",
     "typedoc": "typedoc src/swarpc.ts src/types.ts --readme README.md"
   },

package/src/swarpc.ts

@@ -1,25 +1,38 @@
-import { type } from "arktype"
+import { type, type Type } from "arktype"
 import {
   ImplementationsMap,
+  Procedure,
   zImplementations,
   zProcedures,
   type ProceduresMap,
   type SwarpcClient,
   type SwarpcServer,
 } from "./types.js"
+import { findTransferables } from "./utils.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 function Server<Procedures extends ProceduresMap>(
   procedures: Procedures,
   { worker }: { worker?: Worker } = {}
 ): SwarpcServer<Procedures> {
+  // 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]) {
@@ -29,6 +42,7 @@ export function Server<Procedures extends ProceduresMap>(
     }) as SwarpcServer<Procedures>[typeof functionName]
   }
 
+  // Define payload schema for incoming messages
   const PayloadSchema = type.or(
     ...Object.entries(procedures).map(([functionName, { input }]) => ({
       functionName: type(`"${functionName}"`),
@@ -38,55 +52,77 @@ export function Server<Procedures extends ProceduresMap>(
   )
 
   instance.start = (self: Window) => {
+    // Used to post messages back to the client
     const postMessage = async (
-      data: { functionName: string; requestId: string } & Partial<{
+      data: {
+        functionName: string
+        requestId: string
+        autotransfer: Procedure<Type, Type, Type>["autotransfer"]
+      } & Partial<{
         result: any
         error: any
         progress: any
       }>
     ) => {
+      const transfer =
+        data.autotransfer === "never" ? [] : findTransferables(data)
+
       if (worker) {
-        self.postMessage(data)
+        self.postMessage(data, { transfer })
       } else {
         await (self as any).clients.matchAll().then((clients: any[]) => {
-          clients.forEach((client) => client.postMessage(data))
+          clients.forEach((client) => client.postMessage(data, { transfer }))
         })
       }
     }
 
+    // Listen for messages from the client
     self.addEventListener("message", async (event: MessageEvent) => {
+      // 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: { result: any } | { error: any } | { progress: any }
+      ) => postMessage({ functionName, requestId, autotransfer, ...data })
+
+      // Prepare a function to post errors back to the client
       const postError = async (error: any) =>
-        postMessage({
-          functionName,
-          requestId,
+        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: any) => {
         l.server.debug(requestId, `Progress for ${functionName}`, progress)
-        await postMessage({ functionName, requestId, progress })
+        await postMsg({ progress })
       })
+        // Send errors
         .catch(async (error: any) => {
           l.server.error(requestId, `Error in ${functionName}`, error)
           await postError(error)
         })
+        // Send results
         .then(async (result: any) => {
           l.server.debug(requestId, `Result for ${functionName}`, result)
-          await postMessage({ functionName, requestId, result })
+          await postMsg({ result })
         })
     })
   }
@@ -94,22 +130,38 @@ export function Server<Procedures extends ProceduresMap>(
   return instance
 }
 
+/**
+ * Generate a random request ID, used to identify requests between client and server.
+ * @returns a 6-character hexadecimal string
+ */
 function generateRequestId(): string {
   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<string, PendingRequest>()
 type PendingRequest = {
   reject: (err: Error) => void
   onProgress: (progress: any) => void
   resolve: (result: any) => void
 }
 
-const pendingRequests = new Map<string, PendingRequest>()
-
+// 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?: Worker) {
   if (_clientListenerStarted) return
 
+  // Get service worker registration if no worker is provided
   if (!worker) {
     const sw = await navigator.serviceWorker.ready
     if (!sw?.active) {
@@ -122,15 +174,21 @@ async function startClientListener(worker?: Worker) {
   }
 
   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
+    // We don't use a arktype schema here, we trust the server to send valid data
     const { functionName, requestId, ...data } =
       (event as MessageEvent).data || {}
 
+    // 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(
@@ -138,6 +196,8 @@ async function startClientListener(worker?: Worker) {
       )
     }
 
+    // React to the data received
+    // Unless it's a progress update, the request is finished, thus we can remove it from the pending requests
     if ("error" in data) {
       handlers.reject(new Error(data.error.message))
       pendingRequests.delete(requestId)
@@ -152,10 +212,18 @@ async function startClientListener(worker?: Worker) {
   _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.
+ * @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 extends ProceduresMap>(
   procedures: Procedures,
   { worker }: { worker?: Worker } = {}
 ): SwarpcClient<Procedures> {
+  // Store procedures on a symbol key, to avoid conflicts with procedure names
   const instance = { [zProcedures]: procedures } as Partial<
     SwarpcClient<Procedures>
   >
@@ -169,11 +237,15 @@ export function Client<Procedures extends ProceduresMap>(
       )
     }
 
+    // Set the method on the instance
     // @ts-expect-error
     instance[functionName] = (async (input: unknown, 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)
 
+      // If no worker is provided, we use the service worker
       const w =
         worker ?? (await navigator.serviceWorker.ready.then((r) => r.active))
 
@@ -187,10 +259,22 @@ export function Client<Procedures extends ProceduresMap>(
 
         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 })
+        w.postMessage(
+          { functionName, input, requestId },
+          {
+            transfer:
+              procedures[functionName].autotransfer === "always"
+                ? findTransferables(input)
+                : [],
+          }
+        )
       })
     }) as SwarpcClient<Procedures>[typeof functionName]
   }
@@ -198,29 +282,46 @@ export function Client<Procedures extends ProceduresMap>(
   return instance as SwarpcClient<Procedures>
 }
 
+/**
+ * Convenience shortcuts for logging.
+ */
 const l = {
   server: {
-    debug: (rqid: string | null, message: string, ...args: any[]) =>
-      log("debug", "server", rqid, message, ...args),
-    info: (rqid: string | null, message: string, ...args: any[]) =>
-      log("info", "server", rqid, message, ...args),
-    warn: (rqid: string | null, message: string, ...args: any[]) =>
-      log("warn", "server", rqid, message, ...args),
-    error: (rqid: string | null, message: string, ...args: any[]) =>
-      log("error", "server", rqid, message, ...args),
+    debug: logger("debug", "server"),
+    info: logger("info", "server"),
+    warn: logger("warn", "server"),
+    error: logger("error", "server"),
   },
   client: {
-    debug: (rqid: string | null, message: string, ...args: any[]) =>
-      log("debug", "client", rqid, message, ...args),
-    info: (rqid: string | null, message: string, ...args: any[]) =>
-      log("info", "client", rqid, message, ...args),
-    warn: (rqid: string | null, message: string, ...args: any[]) =>
-      log("warn", "client", rqid, message, ...args),
-    error: (rqid: string | null, message: string, ...args: any[]) =>
-      log("error", "client", rqid, message, ...args),
+    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: "debug" | "info" | "warn" | "error",
+  side: "server" | "client"
+) {
+  return (rqid: string | null, message: string, ...args: any[]) =>
+    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: "debug" | "info" | "warn" | "error",
   side: "server" | "client",

package/src/types.ts

@@ -1,22 +1,55 @@
 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["inferOut"]) => void
-) => Promise<S["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"],
@@ -25,20 +58,36 @@ export type ImplementationsMap<Procedures extends ProceduresMap> = {
   >
 }
 
+/**
+ * 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 const zImplementations = Symbol("SWARPC implementations")
+/**
+ * Symbol used as the key for the procedures map on instances
+ */
 export const zProcedures = Symbol("SWARPC procedures")
 
+/**
+ * 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>

package/src/utils.ts

@@ -0,0 +1,40 @@
+type Constructor<T> = new (...args: any[]) => T
+
+// TODO: keep it in sync with web standards, how?
+const transferableClasses: Constructor<Transferable>[] = [
+  OffscreenCanvas,
+  ImageBitmap,
+  MessagePort,
+  MediaSourceHandle,
+  ReadableStream,
+  WritableStream,
+  TransformStream,
+  AudioData,
+  VideoFrame,
+  RTCDataChannel,
+  ArrayBuffer,
+]
+
+export function findTransferables(value: any): Transferable[] {
+  if (value === null || value === undefined) {
+    return []
+  }
+
+  if (typeof value === "object") {
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer) {
+      return [value]
+    }
+
+    if (transferableClasses.some((cls) => value instanceof cls)) {
+      return [value as Transferable]
+    }
+
+    if (Array.isArray(value)) {
+      return value.flatMap(findTransferables)
+    }
+
+    return Object.values(value).flatMap(findTransferables)
+  }
+
+  return []
+}