swarpc 0.18.0 → 0.20.0

package/README.md

@@ -210,6 +210,39 @@ for (const result of await client.initDB.broadcast("localhost:5432")) {
 }
 ```
 
+You also have a very convenient way to aggregate the results of all nodes, if you don't need to handle errors in a fine-grained way:
+
+```ts
+const userbase = await client.tableSize.broadcast
+  .orThrow("users")
+  .then((counts) => sum(counts))
+  .catch((e) => {
+    // e is an AggregateError with every failing node's error
+    console.error("Could not get total user count:", e);
+  });
+```
+
+Otherwise, you have access to a handful of convenience properties on the returned array, to help you narrow down what happened on each node:
+
+```ts
+async function userbase() {
+  const counts = await client.tableSize.broadcast("users");
+
+  if (counts.ko) {
+    throw new Error(
+      `All nodes failed to get table size: ${counts.failureSummary}`,
+    );
+  }
+
+  return {
+    exact: counts.ok,
+    count:
+      sum(counts.successes) +
+      average(counts.successes) * counts.failures.length,
+  };
+}
+```
+
 ### Make cancelable requests
 
 #### Implementation
@@ -217,21 +250,16 @@ for (const result of await client.initDB.broadcast("localhost:5432")) {
 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) => {
+server.searchIMDb(async ({ query }, onProgress, { abortSignal }) => {
   // 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
+  // Use `abortSignal?.throwIfAborted()` within hot loops and at key points
   for (...) {
-    /* here */ if (aborted) return
+    abortSignal?.throwIfAborted();
     ...
   }
 
   // When using fetch:
-  await fetch(..., { signal: abort })
+  await fetch(..., { signal: abortSignal })
 })
 ```
 
@@ -298,6 +326,16 @@ 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.
 
+#### With broadcasting
+
+You can combine "once" mode with broadcasting as well, just use `.broadcast.once` or `.broadcast.onceBy` instead of `.once` or `.onceBy`:
+
+```js
+// Load the inference model on all nodes. If we call this again before the previous model finishes loading,
+// the previous load requests get cancelled.
+await swarpc.loadInferenceModel.broadcast.once({ url });
+```
+
 ### 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

@@ -18,9 +18,20 @@ export type SwarpcClient<Procedures extends ProceduresMap> = {
     onceBy: (key: string) => {
         [F in keyof Procedures]: ClientMethodCallable<Procedures[F]>;
     };
+    /**
+     * Disconnects all event listeners created by the client, and:
+     * - for Shared Workers: closes the port started by the client
+     * - for Dedicated Workers: terminates the worker instance
+     * - for Service Workers: does nothing (there is no connection to close)
+     */
+    destroy(): void;
 } & {
     [F in keyof Procedures]: ClientMethod<Procedures[F]>;
 };
+/**
+ * Names that can't be used as procedure names. Will fail at runtime, when starting the client.
+ */
+export declare const RESERVED_PROCEDURE_NAMES: readonly ["onceBy", "destroy"];
 /**
  *
  * @param procedures procedures the client will be able to call, see {@link ProceduresMap}
@@ -34,16 +45,18 @@ export type SwarpcClient<Procedures extends ProceduresMap> = {
  * @param options.restartListener If true, will force the listener to restart even if it has already been started. You should probably leave this to false, unless you are testing and want to reset the client state.
  * @param options.localStorage Define a in-memory localStorage with the given key-value pairs. Allows code called on the server to access localStorage (even though SharedWorkers don't have access to the browser's real localStorage)
  * @param options.nodes the number of workers to use for the server, defaults to {@link navigator.hardwareConcurrency}.
+ * @param options.nodeIds node IDs to use. If not provided, random IDs will be generated for each node.
  * @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, see {@link ClientMethod}
  *
  * An example of defining and using a client:
  * {@includeCode ../example/src/routes/+page.svelte}
  */
-export declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, nodes: nodeCount, loglevel, restartListener, hooks, localStorage, }?: {
+export declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, nodes: nodeCount, loglevel, restartListener, hooks, localStorage, nodeIds, }?: {
     worker?: WorkerConstructor | string;
     nodes?: number;
     hooks?: Hooks<Procedures>;
     loglevel?: LogLevel;
     restartListener?: boolean;
     localStorage?: Record<string, any>;
+    nodeIds?: string[];
 }): SwarpcClient<Procedures>;

package/dist/client.js

@@ -1,24 +1,21 @@
 import { createLogger, } from "./log.js";
-import { makeNodeId, nodeIdOrSW, whoToSendTo } from "./nodes.js";
-import { zProcedures, } from "./types.js";
-import { findTransferables } from "./utils.js";
+import { broadcastNodes, makeNodeId, nodeIdOrSW, whoToSendTo, } from "./nodes.js";
+import { RequestCancelledError, zProcedures, } from "./types.js";
+import { findTransferables, extractFulfilleds, extractRejecteds, sizedArray, } from "./utils.js";
+export const RESERVED_PROCEDURE_NAMES = ["onceBy", "destroy"];
 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 = {}, } = {}) {
+let _clientListeners = new Map();
+export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug", restartListener = false, hooks = {}, localStorage = {}, nodeIds = [], } = {}) {
     const l = createLogger("client", loglevel);
     if (restartListener)
-        _clientListenerStarted.clear();
-    const instance = { [zProcedures]: procedures };
+        _clientListeners.clear();
     nodeCount ??= navigator.hardwareConcurrency || 1;
     let nodes;
     if (worker) {
         nodes = {};
-        for (const _ of Array.from({ length: nodeCount })) {
-            const id = makeNodeId();
+        for (const [i] of Array.from({ length: nodeCount }).entries()) {
+            const id = nodeIds[i] ?? makeNodeId();
             if (typeof worker === "string") {
                 nodes[id] = new Worker(worker, { name: id });
             }
@@ -28,14 +25,55 @@ 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 instance = {
+        [zProcedures]: procedures,
+        destroy() {
+            for (const [nodeId, listener] of _clientListeners.entries()) {
+                l.debug(null, `Destroying listener for node ${nodeId}`);
+                listener.disconnect();
+                _clientListeners.delete(nodeId);
+            }
+            for (const [nodeId, node] of Object.entries(nodes ?? {})) {
+                l.debug(null, `Terminating worker for node ${nodeId}`);
+                if (node instanceof SharedWorker) {
+                    node.port.close();
+                }
+                else {
+                    node.terminate();
+                }
+            }
+        },
+    };
+    function cancelRequests(reason, criterias) {
+        const { nodeIds, functionName, concurrencyKey } = criterias;
+        if (!nodeIds && !functionName && !concurrencyKey) {
+            throw new Error("At least one criteria must be provided to cancel requests");
+        }
+        if (nodeIds?.length === 0) {
+            console.warn("[SWARPC Client] cancelRequests called with empty nodeIds array, no requests will be cancelled");
+            return;
+        }
+        const trackingKey = concurrencyKey
+            ? functionName
+                ? `${functionName}:${concurrencyKey}`
+                : concurrencyKey
+            : undefined;
+        const criteria = (param, fn) => param ? fn(param) : true;
+        const toCancel = [...pendingRequests.entries()].filter(([_, p]) => criteria(nodeIds, (ns) => !p.nodeId || ns.includes(p.nodeId)) &&
+            criteria(functionName, (fn) => p.functionName === fn) &&
+            criteria(trackingKey, (key) => p.concurrencyKey === key));
+        for (const [requestId, { functionName }] of toCancel) {
+            cancelRequest(requestId, reason, functionName);
+        }
+    }
+    function 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));
+        pending.reject(new RequestCancelledError(reason));
         postMessageSync(l, nodeId ? nodes?.[nodeId] : undefined, {
             by: "sw&rpc",
             requestId,
@@ -43,17 +81,21 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
             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`);
         }
+        if (RESERVED_PROCEDURE_NAMES.includes(functionName)) {
+            throw new Error(`[SWARPC Client] Invalid function name: "${functionName}" is a reserved word and can't be used as a procedure name. Reserved names: ${RESERVED_PROCEDURE_NAMES}`);
+        }
         const send = async (node, nodeId, requestId, msg, options) => {
             const ctx = {
                 logger: l,
                 node,
                 nodeId,
+                allNodeIDs: new Set(nodes ? Object.keys(nodes) : []),
                 hooks,
                 localStorage,
             };
@@ -64,13 +106,13 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                 functionName,
             }, options);
         };
-        const _runProcedure = async (input, onProgress = emptyProgressCallback, reqid, nodeId) => {
+        const _runProcedure = async ({ input, onProgress, requestId: explicitRequestId, nodeId, concurrencyKey, }) => {
             const validation = procedures[functionName].input["~standard"].validate(input);
             if (validation instanceof Promise)
                 throw new Error("Validations must not be async");
             if (validation.issues)
                 throw new Error(`Invalid input: ${validation.issues}`);
-            const requestId = reqid ?? makeRequestId();
+            const requestId = explicitRequestId ?? makeRequestId();
             nodeId ??= whoToSendTo(nodes, pendingRequests);
             const node = nodes && nodeId ? nodes[nodeId] : undefined;
             const l = createLogger("client", loglevel, nodeIdOrSW(nodeId), requestId);
@@ -78,8 +120,10 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                 pendingRequests.set(requestId, {
                     nodeId,
                     functionName,
+                    startedAt: performance.now(),
+                    concurrencyKey,
                     resolve,
-                    onProgress,
+                    onProgress: onProgress ?? emptyProgressCallback,
                     reject,
                 });
                 const transfer = procedures[functionName].autotransfer === "always"
@@ -91,14 +135,8 @@ 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];
-            if (nodes)
-                nodesToUse = Object.keys(nodes);
-            if (nodesCount)
-                nodesToUse = nodesToUse.slice(0, nodesCount);
+        const _broadcastProcedure = async ({ input, onProgresses, nodesCountOrIDs, concurrencyKey }) => {
+            const nodesToUse = broadcastNodes(nodes ? Object.keys(nodes) : undefined, nodesCountOrIDs);
             const progresses = new Map();
             function onProgress(nodeId) {
                 if (!onProgresses)
@@ -108,65 +146,93 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                     onProgresses(progresses);
                 };
             }
-            const results = await Promise.allSettled(nodesToUse.map(async (id) => _runProcedure(input, onProgress(id), undefined, id)));
-            return results.map((r, i) => ({ ...r, node: nodeIdOrSW(nodesToUse[i]) }));
+            const settleds = await Promise.allSettled(nodesToUse.map(async (id) => _runProcedure({
+                input,
+                onProgress: onProgress(id),
+                nodeId: id,
+                concurrencyKey,
+            }))).then((results) => results.map((result, index) => ({
+                ...result,
+                node: nodeIdOrSW(nodesToUse[index]),
+            })));
+            const _extras = {
+                byNode: new Map(settleds.map(({ node, ...result }) => [node, result])),
+                successes: sizedArray(extractFulfilleds(settleds).map((r) => r.value)),
+                failures: sizedArray(extractRejecteds(settleds)),
+                get failureSummary() {
+                    return this.failures
+                        ?.map(({ node, reason }) => `Node ${node}: ${reason}`)
+                        .join(";\n");
+                },
+                get ok() {
+                    return this.failures.length === 0;
+                },
+                get ko() {
+                    return this.successes.length === 0;
+                },
+                get status() {
+                    if (this.ok)
+                        return "fulfilled";
+                    if (this.ko)
+                        return "rejected";
+                    return "mixed";
+                },
+            };
+            const extras = _extras;
+            return Object.assign(settleds, extras);
+        };
+        runProcedureFunctions.set(functionName, _runProcedure);
+        instance[functionName] = (input, onProgress) => _runProcedure({ input, onProgress });
+        instance[functionName].broadcast = (input, onProgresses, nodes) => _broadcastProcedure({ input, onProgresses, nodesCountOrIDs: nodes });
+        instance[functionName].broadcast.orThrow = async (...args) => handleBroadcastOrThrowResults(await instance[functionName].broadcast(...args));
+        instance[functionName].broadcast.once = async (input, onProgresses, nodesCountOrIDs) => {
+            const nodesToUse = broadcastNodes(nodes ? Object.keys(nodes) : undefined, nodesCountOrIDs);
+            cancelRequests("Cancelled by .broadcast.once() call", {
+                functionName,
+                nodeIds: nodesToUse.filter((x) => x !== undefined),
+            });
+            return _broadcastProcedure({
+                input,
+                onProgresses,
+                nodesCountOrIDs: nodesToUse,
+            });
+        };
+        instance[functionName].broadcast.once.orThrow = async (...args) => handleBroadcastOrThrowResults(await instance[functionName].broadcast.once(...args));
+        instance[functionName].broadcast.onceBy = async (concurrencyKey, input, onProgresses, nodesCountOrIDs) => {
+            const nodesToUse = broadcastNodes(nodes ? Object.keys(nodes) : undefined, nodesCountOrIDs);
+            cancelRequests("Cancelled by .broadcast.once() call", {
+                concurrencyKey,
+                functionName,
+                nodeIds: nodesToUse.filter((x) => x !== undefined),
+            });
+            return _broadcastProcedure({
+                input,
+                onProgresses,
+                nodesCountOrIDs: nodesToUse,
+                concurrencyKey,
+            });
         };
+        instance[functionName].broadcast.onceBy.orThrow = async (...args) => handleBroadcastOrThrowResults(await instance[functionName].broadcast.onceBy(...args));
         instance[functionName].cancelable = (input, onProgress) => {
             const requestId = makeRequestId();
             const nodeId = whoToSendTo(nodes, pendingRequests);
-            const l = createLogger("client", loglevel, nodeIdOrSW(nodeId), requestId);
             return {
-                request: _runProcedure(input, onProgress, requestId, nodeId),
+                request: _runProcedure({ input, onProgress, requestId, nodeId }),
                 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);
-                    postMessageSync(l, nodeId ? nodes?.[nodeId] : undefined, {
-                        by: "sw&rpc",
-                        requestId,
-                        functionName,
-                        abort: { reason },
-                    });
-                    pendingRequests.delete(requestId);
+                    cancelRequest(requestId, reason, functionName);
                 },
             };
         };
         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);
-                }
-            }
+            cancelRequests("Cancelled by .once() call", { functionName });
+            return await _runProcedure({ input, onProgress });
         };
-        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[functionName].onceBy = async (concurrencyKey, input, onProgress) => {
+            cancelRequests(`Cancelled by .onceBy("${concurrencyKey}") call`, {
+                functionName,
+                concurrencyKey,
+            });
+            return await _runProcedure({ input, onProgress, concurrencyKey });
         };
     }
     instance.onceBy = (globalKey) => {
@@ -175,28 +241,20 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
             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);
-                }
+                cancelRequests(`Cancelled by global onceBy("${globalKey}") call`, {
+                    concurrencyKey: 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 await _runProcedure({
+                    input,
+                    onProgress,
+                    requestId,
+                    concurrencyKey: globalKey,
+                });
             };
         }
         return proxy;
@@ -232,7 +290,7 @@ function postMessageSync(l, worker, message, options) {
     w.postMessage(message, options);
 }
 async function startClientListener(ctx) {
-    if (_clientListenerStarted.has(nodeIdOrSW(ctx.nodeId)))
+    if (_clientListeners.has(nodeIdOrSW(ctx.nodeId)))
         return;
     const { logger: l, node: worker } = ctx;
     if (!worker) {
@@ -263,10 +321,12 @@ async function startClientListener(ctx) {
         if (!handlers) {
             throw new Error(`[SWARPC Client] ${requestId} has no active request handlers, cannot process ${JSON.stringify(data)}`);
         }
+        const duration = performance.now() - handlers.startedAt;
         if ("error" in data) {
             ctx.hooks.error?.({
                 procedure: data.functionName,
                 error: new Error(data.error.message),
+                duration,
             });
             handlers.reject(new Error(data.error.message));
             pendingRequests.delete(requestId);
@@ -275,6 +335,7 @@ async function startClientListener(ctx) {
             ctx.hooks.progress?.({
                 procedure: data.functionName,
                 data: data.progress,
+                duration,
             });
             handlers.onProgress(data.progress);
         }
@@ -282,6 +343,7 @@ async function startClientListener(ctx) {
             ctx.hooks.success?.({
                 procedure: data.functionName,
                 data: data.result,
+                duration,
             });
             handlers.resolve(data.result);
             pendingRequests.delete(requestId);
@@ -294,15 +356,31 @@ async function startClientListener(ctx) {
     else {
         w.addEventListener("message", listener);
     }
-    _clientListenerStarted.add(nodeIdOrSW(ctx.nodeId));
+    _clientListeners.set(nodeIdOrSW(ctx.nodeId), {
+        disconnect() {
+            if (w instanceof SharedWorker) {
+                w.port.removeEventListener("message", listener);
+            }
+            else {
+                w.removeEventListener("message", listener);
+            }
+        },
+    });
     await postMessage(ctx, {
         by: "sw&rpc",
         functionName: "#initialize",
         isInitializeRequest: true,
         localStorageData: ctx.localStorage,
         nodeId: nodeIdOrSW(ctx.nodeId),
+        allNodeIDs: ctx.allNodeIDs,
     });
 }
 function makeRequestId() {
     return Math.random().toString(16).substring(2, 8).toUpperCase();
 }
+function handleBroadcastOrThrowResults(results) {
+    if (results.ok) {
+        return results.successes;
+    }
+    throw new AggregateError(results.failures.map((f) => f.reason));
+}

package/dist/index.d.ts

@@ -3,8 +3,8 @@
  * @mergeModuleWith <project>
  */
 import "./polyfills.js";
-export type { ProceduresMap, CancelablePromise } from "./types.js";
-export { Client } from "./client.js";
+export { type ProceduresMap, type CancelablePromise, RequestCancelledError, } from "./types.js";
+export { Client, RESERVED_PROCEDURE_NAMES } from "./client.js";
 export type { SwarpcClient } from "./client.js";
 export { Server } from "./server.js";
 export type { SwarpcServer } from "./server.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 import "./polyfills.js";
-export { Client } from "./client.js";
+export { RequestCancelledError, } from "./types.js";
+export { Client, RESERVED_PROCEDURE_NAMES } from "./client.js";
 export { Server } from "./server.js";

package/dist/nodes.js

@@ -30,3 +30,13 @@ const serviceWorkerNodeId = "(SW)";
 export function nodeIdOrSW(id) {
     return id ?? serviceWorkerNodeId;
 }
+export function broadcastNodes(nodes, target) {
+    if (target && Array.isArray(target))
+        return target;
+    let nodesToUse = [undefined];
+    if (nodes)
+        nodesToUse = [...nodes];
+    if (typeof target === "number")
+        nodesToUse = nodesToUse.slice(0, target);
+    return nodesToUse;
+}

package/dist/server.js

@@ -1,5 +1,5 @@
 import { createLogger, injectIntoConsoleGlobal } from "./log.js";
-import { isPayloadHeader, isPayloadInitialize, validatePayloadCore as validatePayloadCore, zImplementations, zProcedures, } from "./types.js";
+import { isPayloadHeader, isPayloadInitialize, RequestCancelledError, validatePayloadCore, zImplementations, zProcedures, } from "./types.js";
 import { findTransferables } from "./utils.js";
 import { FauxLocalStorage } from "./localstorage.js";
 import { scopeIsDedicated, scopeIsShared, scopeIsService } from "./scopes.js";
@@ -9,6 +9,7 @@ const abortedRequests = new Set();
 export function Server(procedures, { loglevel = "debug", scope, _scopeType, } = {}) {
     scope ??= self;
     const nodeId = nodeIdFromScope(scope, _scopeType);
+    let allNodeIDs = new Set();
     const l = createLogger("server", loglevel, nodeId);
     const instance = {
         [zProcedures]: procedures,
@@ -63,6 +64,7 @@ export function Server(procedures, { loglevel = "debug", scope, _scopeType, } =
                 l.debug(null, "Setting up faux localStorage", localStorageData);
                 new FauxLocalStorage(localStorageData).register(scope);
                 injectIntoConsoleGlobal(scope, nodeId, null);
+                event.data.allNodeIDs.forEach((id) => allNodeIDs.add(id));
                 return;
             }
             if (!isPayloadHeader(procedures, event.data)) {
@@ -99,7 +101,7 @@ export function Server(procedures, { loglevel = "debug", scope, _scopeType, } =
                 const controller = abortControllers.get(requestId);
                 if (!controller)
                     await postError("No abort controller found for request");
-                controller?.abort(payload.abort.reason);
+                controller?.abort(new RequestCancelledError(payload.abort.reason));
                 return;
             }
             abortControllers.set(requestId, new AbortController());
@@ -113,6 +115,7 @@ export function Server(procedures, { loglevel = "debug", scope, _scopeType, } =
                     await postMsg({ progress });
                 }, {
                     nodeId,
+                    nodes: allNodeIDs,
                     abortSignal: abortControllers.get(requestId)?.signal,
                 });
                 l.debug(requestId, `Result for ${functionName}`, result);

package/dist/types.d.ts

@@ -3,6 +3,7 @@
  * @mergeModuleWith <project>
  */
 import type { StandardSchemaV1 as Schema } from "./standardschema.js";
+import { ArrayOneOrMore } from "./utils.js";
 /**
  * A procedure declaration
  */
@@ -73,6 +74,10 @@ tools: {
      * ID of the Node the request is being processed on.
      */
     nodeId: string;
+    /**
+     * IDs of all available Nodes.
+     */
+    nodes: Set<string>;
 }) => Promise<Schema.InferInput<S>>;
 /**
  * Declarations of procedures by name.
@@ -85,6 +90,8 @@ type ProcedureNameAndData<Procedures extends ProceduresMap, Key extends "progres
     [K in keyof Procedures]: {
         procedure: K;
         data: Schema.InferOutput<Procedures[K][Key]>;
+        /** Time in milliseconds the procedure call took */
+        duration: number;
     };
 }[keyof Procedures];
 /**
@@ -97,9 +104,12 @@ export type Hooks<Procedures extends ProceduresMap> = {
     success?: (arg: ProcedureNameAndData<Procedures, "success">) => void;
     /**
      * Called when a procedure call has failed.
+     * @param arg
+     * @param arg.duration time in milliseconds the procedure call took
      */
     error?: (arg: {
         procedure: keyof Procedures;
+        duration: number;
         error: Error;
     }) => void;
     /**
@@ -127,9 +137,75 @@ export type PayloadCore<PM extends ProceduresMap, Name extends keyof PM = keyof
  */
 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.
+ * A procedure that broadcasts its request to multiple nodes.
+ * The return value is an array of results, along with extra properties:
+ * see {@link BroadcasterResultExtrasMixed}, {@link BroadcasterResultExtrasSuccess} and {@link BroadcasterResultExtrasFailure}
  */
-export type ClientMethod<P extends Procedure<Schema, Schema, Schema>> = ClientMethodCallable<P> & {
+export type Broadcaster<P extends Procedure<Schema, Schema, Schema>> = {
+    /**
+     * Returns an array of result values for each node.
+     * @throws {AggregateError} with every failing node's error
+     */
+    orThrow: (input: Schema.InferInput<P["input"]>, onProgress?: (
+    /** Map of node IDs to their progress updates */
+    progresses: Map<string, Schema.InferOutput<P["progress"]>>) => void, 
+    /** Node IDs or number of nodes to send the request to. Leave undefined to send to all nodes. When sending a list of node IDs, "undefined" is interpreted as "run on the service worker" */
+    nodes?: number | Array<string | undefined>) => Promise<Array<Schema.InferOutput<P["success"]>>>;
+} & ((input: Schema.InferInput<P["input"]>, onProgress?: (
+/** Map of node IDs to their progress updates */
+progresses: Map<string, Schema.InferOutput<P["progress"]>>) => void, 
+/** Node IDs or number of nodes to send the request to. Leave undefined to send to all nodes. When sending a list of node IDs, "undefined" is interpreted as "run on the service worker" */
+nodes?: number | Array<string | undefined>) => Promise<Array<PromiseSettledResult<Schema.InferOutput<P["success"]>> & {
+    node: string;
+}> & (BroadcasterResultExtrasMixed<P> | BroadcasterResultExtrasSuccess<P> | BroadcasterResultExtrasFailure)>);
+/**
+ * Extra properties on the result of a broadcaster call, when some nodes succeeded and some failed
+ */
+export type BroadcasterResultExtrasMixed<P extends Procedure<Schema, Schema, Schema>> = {
+    /** Undefined if no failures */
+    failures: ArrayOneOrMore<PromiseRejectedResult & {
+        node: string;
+    }>;
+    /** Formatted error string, undefined if no failures */
+    failureSummary: string;
+    /** True if only failures */
+    ko: false;
+    /** True if no failures */
+    ok: false;
+    /** "mixed" if some failed and some succeeded, "fulfilled" if all succeeded and "rejected" if everything failed */
+    status: "mixed";
+    /** All values of successful calls */
+    successes: ArrayOneOrMore<Schema.InferOutput<P["success"]>>;
+    /** Map of node ID to its result or failure */
+    byNode: Map<string, PromiseSettledResult<Schema.InferOutput<P["success"]>>>;
+};
+/**
+ * Extra properties on the result of a broadcaster call, when all nodes succeeded
+ */
+export type BroadcasterResultExtrasSuccess<P extends Procedure<Schema, Schema, Schema>> = {
+    failures: [];
+    failureSummary: undefined;
+    ko: false;
+    ok: true;
+    status: "fulfilled";
+    successes: ArrayOneOrMore<Schema.InferOutput<P["success"]>>;
+    byNode: Map<string, PromiseFulfilledResult<Schema.InferOutput<P["success"]>>>;
+};
+/**
+ * Extra properties on the result of a broadcaster call, when all nodes failed
+ */
+export type BroadcasterResultExtrasFailure = {
+    failures: ArrayOneOrMore<PromiseRejectedResult & {
+        node: string;
+    }>;
+    failureSummary: string;
+    ko: true;
+    ok: false;
+    status: "rejected";
+    successes: [];
+    byNode: Map<string, PromiseRejectedResult>;
+};
+export type ClientMethodExtraCallables<P extends Procedure<Schema, Schema, Schema>> = {
     /**
      * 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.
      */
@@ -138,14 +214,31 @@ export type ClientMethod<P extends Procedure<Schema, Schema, Schema>> = ClientMe
      * Send the request to specific nodes, or all nodes.
      * Returns an array of results, one for each node the request was sent to.
      * Each result is a {@link PromiseSettledResult}, with also an additional property, the node ID of the request
+     * The results array also has extra properties for convenience, see {@link BroadcasterResultExtrasMixed}, {@link BroadcasterResultExtrasSuccess} and {@link BroadcasterResultExtrasFailure}
      */
-    broadcast: (input: Schema.InferInput<P["input"]>, onProgress?: (
-    /** Map of node IDs to their progress updates */
-    progresses: Map<string, Schema.InferOutput<P["progress"]>>) => void, 
-    /** Number of nodes to send the request to. Leave undefined to send to all nodes */
-    nodes?: number) => Promise<Array<PromiseSettledResult<Schema.InferOutput<P["success"]>> & {
-        node: string;
-    }>>;
+    broadcast: Broadcaster<P> & {
+        /**
+         * Send the request to specific nodes, or all nodes.
+         * Cancels any previous ongoing calls of this procedure on the nodes beforehand.
+         * Returns an array of results, one for each node the request was sent to.
+         * Each result is a {@link PromiseSettledResult}, with also an additional property, the node ID of the request. The results array also has extra properties for convenience, see {@link BroadcasterResultExtrasMixed}, {@link BroadcasterResultExtrasSuccess} and {@link BroadcasterResultExtrasFailure}
+         */
+        once: Broadcaster<P>;
+        /**
+         * Send the request to specific nodes, or all nodes.
+         * Cancels any previous ongoing calls of this procedure on the nodes beforehand that were also run with the specified concurrency key (first argument). See .onceBy for more details.
+         * Returns an array of results, one for each node the request was sent to.
+         * Each result is a {@link PromiseSettledResult}, with also an additional property, the node ID of the request. The results array also has extra properties for convenience, see {@link BroadcasterResultExtrasMixed}, {@link BroadcasterResultExtrasSuccess} and {@link BroadcasterResultExtrasFailure}
+         */
+        onceBy: ((key: string, ...args: Parameters<Broadcaster<P>>) => ReturnType<Broadcaster<P>>) & {
+            /**
+             * Returns an array of result values for each node.
+             * Throws if any node failed.
+             * @throws {AggregateError} with every failing node's error
+             */
+            orThrow: (key: string, ...args: Parameters<Broadcaster<P>>) => Promise<Array<Schema.InferOutput<P["success"]>>>;
+        };
+    };
     /**
      * Call the procedure, cancelling any previous ongoing call of this procedure beforehand.
      */
@@ -155,9 +248,20 @@ export type ClientMethod<P extends Procedure<Schema, Schema, Schema>> = ClientMe
      */
     onceBy: (key: string, 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>> = ClientMethodCallable<P> & ClientMethodExtraCallables<P>;
+export declare const zImplementations: unique symbol;
 export type WorkerConstructor<T extends Worker | SharedWorker = Worker | SharedWorker> = {
     new (opts?: {
         name?: string;
     }): T;
 };
+/**
+ * A cancelable request was cancelled (either via .cancelable's .cancel() or via a .once / .onceBy call)
+ */
+export declare class RequestCancelledError extends Error {
+    constructor(reason: string);
+}
 export {};

package/dist/types.js

@@ -13,6 +13,8 @@ export function isPayloadInitialize(payload) {
         return false;
     if (!("isInitializeRequest" in payload))
         return false;
+    if (!("allNodeIDs" in payload))
+        return false;
     if (payload.by !== "sw&rpc")
         return false;
     if (payload.functionName !== "#initialize")
@@ -86,3 +88,9 @@ export function validatePayloadCore(procedure, payload) {
 }
 export const zImplementations = Symbol("SWARPC implementations");
 export const zProcedures = Symbol("SWARPC procedures");
+export class RequestCancelledError extends Error {
+    constructor(reason) {
+        super(`Request was cancelled: ${reason}`);
+        this.name = "RequestCancelledError";
+    }
+}

package/dist/utils.js

@@ -23,3 +23,15 @@ export function findTransferables(value) {
     }
     return [];
 }
+export function sizedArray(array) {
+    if (array.length === 0) {
+        return [];
+    }
+    return array;
+}
+export function extractFulfilleds(settleds) {
+    return settleds.filter((settled) => settled.status === "fulfilled");
+}
+export function extractRejecteds(settleds) {
+    return settleds.filter((settled) => settled.status === "rejected");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarpc",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Full type-safe RPC library for service worker -- move things off of the UI thread with ease!",
   "keywords": [
     "service-workers",
@@ -47,36 +47,36 @@
   },
   "devDependencies": {
     "@8hobbies/typedoc-plugin-plausible": "^2.2.0",
-    "@playwright/test": "^1.57.0",
+    "@playwright/test": "^1.58.2",
     "@size-limit/esbuild-why": "^12.0.0",
     "@size-limit/preset-small-lib": "^12.0.0",
-    "@vitest/web-worker": "^4.0.16",
+    "@vitest/web-worker": "^4.0.18",
     "arktype": "^2.1.29",
     "date-fns": "^4.1.0",
     "husky": "^9.1.7",
     "kacl": "^1.1.1",
-    "knip": "^5.80.0",
+    "knip": "^5.85.0",
     "lint-staged": "^16.2.7",
-    "nodemon": "^3.1.11",
-    "oxlint": "^1.37.0",
-    "pkg-pr-new": "^0.0.62",
-    "prettier": "^3.7.4",
+    "nodemon": "^3.1.14",
+    "oxlint": "^1.50.0",
+    "pkg-pr-new": "^0.0.63",
+    "prettier": "^3.8.1",
     "sirv-cli": "^3.0.1",
     "size-limit": "^12.0.0",
-    "typedoc": "^0.28.15",
+    "typedoc": "^0.28.17",
     "typedoc-material-theme": "^1.4.1",
-    "typedoc-plugin-dt-links": "^2.0.36",
+    "typedoc-plugin-dt-links": "^2.0.43",
     "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",
+    "typedoc-plugin-mdn-links": "^5.1.1",
+    "typedoc-plugin-redirect": "^1.3.0",
     "typescript": "^5.9.3",
-    "vite": "^7.3.0",
-    "vitest": "^4.0.16"
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
   },
   "volta": {
-    "node": "24.12.0",
-    "npm": "11.7.0"
+    "node": "24.13.1",
+    "npm": "11.10.1"
   },
   "lint-staged": {
     "*.{ts,js,md,json,yaml,yml}": [