swarpc 0.17.2 → 0.18.0

package/README.md

@@ -254,6 +254,50 @@ setTimeout(() => cancel().then(() => console.warn("Took too long!!")), 5_000);
 await request;
 ```
 
+### Call in "once" mode
+
+The "once" mode allows you to automatically cancel any previous ongoing call before running a new one. This is useful for scenarios like search-as-you-type, where you only care about the latest request.
+
+#### Method-scoped once mode
+
+Cancel any previous call of the same method:
+
+```js
+// If any previous call of searchIMDb is ongoing, it gets cancelled beforehand
+const result = await swarpc.searchIMDb.once({ query });
+```
+
+#### Method-scoped once mode with key
+
+Cancel any previous call of the same method with the same key:
+
+```js
+// If any previous call of searchIMDb with "foo" as the key is ongoing,
+// it gets cancelled beforehand
+const result = await swarpc.searchIMDb.onceBy("foo", { query });
+```
+
+This allows multiple concurrent calls with different keys:
+
+```js
+// These two calls can run concurrently
+const result1 = await swarpc.searchIMDb.onceBy("search-bar", {
+  query: "action",
+});
+const result2 = await swarpc.searchIMDb.onceBy("sidebar", { query: "comedy" });
+```
+
+#### Global once mode
+
+Cancel any ongoing call with the same global key, across all methods:
+
+```js
+// Any call from ANY procedure with "global-search" key gets cancelled beforehand
+const result = await swarpc.onceBy("global-search").searchIMDb({ query });
+```
+
+This is useful when you want to ensure only one operation of a certain type is running at a time, regardless of which procedure is being called.
+
 ### Polyfill a `localStorage` for the Server to access
 
 You might call third-party code that accesses on `localStorage` from within your procedures.

package/dist/client.d.ts

@@ -3,7 +3,7 @@
  * @mergeModuleWith <project>
  */
 import { type LogLevel } from "./log.js";
-import { ClientMethod, Hooks, WorkerConstructor, zProcedures, type ProceduresMap } from "./types.js";
+import { ClientMethod, ClientMethodCallable, Hooks, WorkerConstructor, zProcedures, type ProceduresMap } from "./types.js";
 /**
  * The sw&rpc client instance, which provides {@link ClientMethod | 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.
@@ -11,6 +11,13 @@ import { ClientMethod, Hooks, WorkerConstructor, zProcedures, type ProceduresMap
  */
 export type SwarpcClient<Procedures extends ProceduresMap> = {
     [zProcedures]: Procedures;
+    /**
+     * Create a proxy that cancels any ongoing call with the given global key before running new calls.
+     * Usage: `await swarpc.onceBy("global-key").myMethod(...)`
+     */
+    onceBy: (key: string) => {
+        [F in keyof Procedures]: ClientMethodCallable<Procedures[F]>;
+    };
 } & {
     [F in keyof Procedures]: ClientMethod<Procedures[F]>;
 };

package/dist/client.js

@@ -3,6 +3,10 @@ import { makeNodeId, nodeIdOrSW, whoToSendTo } from "./nodes.js";
 import { zProcedures, } from "./types.js";
 import { findTransferables } from "./utils.js";
 const pendingRequests = new Map();
+const onceByMethod = new Map();
+const onceByMethodAndKey = new Map();
+const onceByGlobalKey = new Map();
+const emptyProgressCallback = () => { };
 let _clientListenerStarted = new Set();
 export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug", restartListener = false, hooks = {}, localStorage = {}, } = {}) {
     const l = createLogger("client", loglevel);
@@ -24,6 +28,23 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
         }
         l.info(null, `Started ${nodeCount} node${nodeCount > 1 ? "s" : ""}`, Object.keys(nodes));
     }
+    const cancelRequest = (requestId, reason, functionName) => {
+        const pending = pendingRequests.get(requestId);
+        if (!pending)
+            return;
+        const nodeId = pending.nodeId;
+        const l = createLogger("client", loglevel, nodeIdOrSW(nodeId), requestId);
+        l.debug(requestId, `Cancelling ${functionName} with`, reason);
+        pending.reject(new Error(reason));
+        postMessageSync(l, nodeId ? nodes?.[nodeId] : undefined, {
+            by: "sw&rpc",
+            requestId,
+            functionName,
+            abort: { reason },
+        });
+        pendingRequests.delete(requestId);
+    };
+    const runProcedureFunctions = new Map();
     for (const functionName of Object.keys(procedures)) {
         if (typeof functionName !== "string") {
             throw new Error(`[SWARPC Client] Invalid function name, don't use symbols`);
@@ -43,7 +64,7 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                 functionName,
             }, options);
         };
-        const _runProcedure = async (input, onProgress = () => { }, reqid, nodeId) => {
+        const _runProcedure = async (input, onProgress = emptyProgressCallback, reqid, nodeId) => {
             const validation = procedures[functionName].input["~standard"].validate(input);
             if (validation instanceof Promise)
                 throw new Error("Validations must not be async");
@@ -70,6 +91,7 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                     .catch(reject);
             });
         };
+        runProcedureFunctions.set(functionName, _runProcedure);
         instance[functionName] = _runProcedure;
         instance[functionName].broadcast = async (input, onProgresses, nodesCount) => {
             let nodesToUse = [undefined];
@@ -111,7 +133,74 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                 },
             };
         };
+        instance[functionName].once = async (input, onProgress) => {
+            const previousRequestId = onceByMethod.get(functionName);
+            if (previousRequestId) {
+                cancelRequest(previousRequestId, "Cancelled by .once() call", functionName);
+                onceByMethod.delete(functionName);
+            }
+            const requestId = makeRequestId();
+            onceByMethod.set(functionName, requestId);
+            try {
+                return await _runProcedure(input, onProgress, requestId);
+            }
+            finally {
+                if (onceByMethod.get(functionName) === requestId) {
+                    onceByMethod.delete(functionName);
+                }
+            }
+        };
+        instance[functionName].onceBy = async (key, input, onProgress) => {
+            const trackingKey = `${functionName}:${key}`;
+            const previousRequestId = onceByMethodAndKey.get(trackingKey);
+            if (previousRequestId) {
+                cancelRequest(previousRequestId, `Cancelled by .onceBy("${key}") call`, functionName);
+                onceByMethodAndKey.delete(trackingKey);
+            }
+            const requestId = makeRequestId();
+            onceByMethodAndKey.set(trackingKey, requestId);
+            try {
+                return await _runProcedure(input, onProgress, requestId);
+            }
+            finally {
+                if (onceByMethodAndKey.get(trackingKey) === requestId) {
+                    onceByMethodAndKey.delete(trackingKey);
+                }
+            }
+        };
     }
+    instance.onceBy = (globalKey) => {
+        const proxy = {};
+        for (const functionName of Object.keys(procedures)) {
+            if (typeof functionName !== "string")
+                continue;
+            proxy[functionName] = async (input, onProgress) => {
+                const previousRequestId = onceByGlobalKey.get(globalKey);
+                if (previousRequestId) {
+                    const pending = pendingRequests.get(previousRequestId);
+                    if (pending) {
+                        cancelRequest(previousRequestId, `Cancelled by global onceBy("${globalKey}") call`, pending.functionName);
+                    }
+                    onceByGlobalKey.delete(globalKey);
+                }
+                const requestId = makeRequestId();
+                onceByGlobalKey.set(globalKey, requestId);
+                const _runProcedure = runProcedureFunctions.get(functionName);
+                if (!_runProcedure) {
+                    throw new Error(`No procedure found for ${functionName}`);
+                }
+                try {
+                    return await _runProcedure(input, onProgress ?? emptyProgressCallback, requestId);
+                }
+                finally {
+                    if (onceByGlobalKey.get(globalKey) === requestId) {
+                        onceByGlobalKey.delete(globalKey);
+                    }
+                }
+            };
+        }
+        return proxy;
+    };
     return instance;
 }
 async function postMessage(ctx, message, options) {

package/dist/types.d.ts

@@ -122,10 +122,14 @@ export type PayloadCore<PM extends ProceduresMap, Name extends keyof PM = keyof
         message: string;
     };
 };
+/**
+ * The callable function signature for a client method
+ */
+export type ClientMethodCallable<P extends Procedure<Schema, Schema, Schema>> = (input: Schema.InferInput<P["input"]>, onProgress?: (progress: Schema.InferOutput<P["progress"]>) => void) => Promise<Schema.InferOutput<P["success"]>>;
 /**
  * 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<Schema, Schema, Schema>> = ((input: Schema.InferInput<P["input"]>, onProgress?: (progress: Schema.InferOutput<P["progress"]>) => void) => Promise<Schema.InferOutput<P["success"]>>) & {
+export type ClientMethod<P extends Procedure<Schema, Schema, Schema>> = ClientMethodCallable<P> & {
     /**
      * 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.
      */
@@ -142,6 +146,14 @@ export type ClientMethod<P extends Procedure<Schema, Schema, Schema>> = ((input:
     nodes?: number) => Promise<Array<PromiseSettledResult<Schema.InferOutput<P["success"]>> & {
         node: string;
     }>>;
+    /**
+     * Call the procedure, cancelling any previous ongoing call of this procedure beforehand.
+     */
+    once: (input: Schema.InferInput<P["input"]>, onProgress?: (progress: Schema.InferOutput<P["progress"]>) => void) => Promise<Schema.InferOutput<P["success"]>>;
+    /**
+     * Call the procedure with a concurrency key, cancelling any previous ongoing call of this procedure with the same key beforehand.
+     */
+    onceBy: (key: string, input: Schema.InferInput<P["input"]>, onProgress?: (progress: Schema.InferOutput<P["progress"]>) => void) => Promise<Schema.InferOutput<P["success"]>>;
 };
 export type WorkerConstructor<T extends Worker | SharedWorker = Worker | SharedWorker> = {
     new (opts?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarpc",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "Full type-safe RPC library for service worker -- move things off of the UI thread with ease!",
   "keywords": [
     "service-workers",
@@ -50,33 +50,33 @@
     "@playwright/test": "^1.57.0",
     "@size-limit/esbuild-why": "^12.0.0",
     "@size-limit/preset-small-lib": "^12.0.0",
-    "@vitest/web-worker": "^4.0.15",
-    "arktype": "^2.1.28",
+    "@vitest/web-worker": "^4.0.16",
+    "arktype": "^2.1.29",
     "date-fns": "^4.1.0",
     "husky": "^9.1.7",
     "kacl": "^1.1.1",
-    "knip": "^5.72.0",
+    "knip": "^5.80.0",
     "lint-staged": "^16.2.7",
     "nodemon": "^3.1.11",
-    "oxlint": "^1.32.0",
+    "oxlint": "^1.37.0",
     "pkg-pr-new": "^0.0.62",
     "prettier": "^3.7.4",
     "sirv-cli": "^3.0.1",
     "size-limit": "^12.0.0",
     "typedoc": "^0.28.15",
     "typedoc-material-theme": "^1.4.1",
-    "typedoc-plugin-dt-links": "^2.0.32",
+    "typedoc-plugin-dt-links": "^2.0.36",
     "typedoc-plugin-extras": "^4.0.1",
     "typedoc-plugin-inline-sources": "^1.3.0",
     "typedoc-plugin-mdn-links": "^5.0.10",
     "typedoc-plugin-redirect": "^1.2.1",
     "typescript": "^5.9.3",
-    "vite": "^7.2.7",
-    "vitest": "^4.0.15"
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
   },
   "volta": {
-    "node": "24.11.1",
-    "npm": "11.6.4"
+    "node": "24.12.0",
+    "npm": "11.7.0"
   },
   "lint-staged": {
     "*.{ts,js,md,json,yaml,yml}": [