swarpc 0.15.0 → 0.16.0

package/README.md

@@ -3,7 +3,7 @@
   <img src="./logo.svg" alt="sw&rpc" />
 </h1>
 
-RPC for Service Workers -- move that heavy computation off of your UI thread!
+RPC for Service (and other types of) Workers -- move that heavy computation off of your UI thread!
 
 </div>
  
@@ -12,11 +12,13 @@ RPC for Service Workers -- move that heavy computation off of your UI thread!
 ## Features
 
 - Fully typesafe
+- Lightweight: no dependencies, less than 5 kB (minified+gzipped)
 - Supports any [Standard Schema](https://standardschema.dev)-compliant validation library (ArkType, Zod, Valibot, etc.)
 - Cancelable requests
 - Parallelization with multiple worker instances
 - Automatic [transfer](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects) of transferable values from- and to- worker code
 - A way to polyfill a pre-filled `localStorage` to be accessed within the worker code
+- First-class support for signaling progress updates (and e.g. display a progress bar)
 - Supports [Service workers](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker), [Shared workers](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker) and [Dedicated workers](https://developer.mozilla.org/en-US/docs/Web/API/Worker)
 
 ## Installation
@@ -83,9 +85,9 @@ export const procedures = {
 } as const satisfies ProceduresMap;
 ```
 
-### 2. Register your procedures in the service worker
+### 2. Register your procedures in worker
 
-In your service worker file:
+In your worker file:
 
 ```javascript
 import fetchProgress from "fetch-progress"
@@ -152,6 +154,30 @@ Here's a Svelte example!
 </ul>
 ```
 
+### 4. Registering your worker
+
+#### Service Workers
+
+If you use SvelteKit, [just name your service worker file `src/service-worker.ts`](https://svelte.dev/docs/kit/service-workers)
+
+_If you use any other (meta) framework, please contribute usage documentation here :)_
+
+#### Dedicated or Shared Workers
+
+Preferred over service workers for heavy computations, since you can run multiple instances of them (see [Configure parallelism](#configure-parallelism))
+
+If you use Vite, you can [import files as Web Worker classes](https://vite.dev/guide/features.html#web-workers):
+
+```ts
+import { Client } from "swarpc";
+import { procedures } from "$lib/off-thread/procedures.ts";
+import OffThreadWorker from "$lib/off-thread/worker.ts?worker";
+
+const client = Client(procedures, {
+  worker: OffThreadWorker, // don't instanciate the class, sw&rpc does it
+});
+```
+
 ### Configure parallelism
 
 By default, when a `worker` is passed to the `Client`'s options, the client will automatically spin up `navigator.hardwareConcurrency` worker instances and distribute requests among them. You can customize this behavior by setting the `Client:options.nodes` option to control the number of _nodes_ (worker instances).
@@ -166,7 +192,7 @@ For example:
 
 ```ts
 const client = Client(procedures, {
-  worker: "./worker.js",
+  worker: MyWorker,
   nodes: 4,
 });
 

package/dist/client.d.ts

@@ -2,8 +2,8 @@
  * @module
  * @mergeModuleWith <project>
  */
-import { RequestBoundLogger, type Logger, type LogLevel } from "./log.js";
-import { ClientMethod, Hooks, Payload, WorkerConstructor, zProcedures, type ProceduresMap } from "./types.js";
+import { type LogLevel } from "./log.js";
+import { ClientMethod, 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.
@@ -14,30 +14,6 @@ export type SwarpcClient<Procedures extends ProceduresMap> = {
 } & {
     [F in keyof Procedures]: ClientMethod<Procedures[F]>;
 };
-/**
- * Context for passing around data useful for requests
- */
-type Context<Procedures extends ProceduresMap> = {
-    /** A logger, bound to the client */
-    logger: Logger;
-    /** The node to use */
-    node: Worker | SharedWorker | undefined;
-    /** The ID of the node to use */
-    nodeId: string | undefined;
-    /** Hooks defined by the client */
-    hooks: Hooks<Procedures>;
-    /** Local storage data defined by the client for the faux local storage */
-    localStorage: Record<string, any>;
-};
-export type PendingRequest = {
-    /** ID of the node the request was sent to. udefined if running on a service worker */
-    nodeId?: string;
-    functionName: string;
-    reject: (err: Error) => void;
-    onProgress: (progress: any) => void;
-    resolve: (result: any) => void;
-};
-export type ClientOptions = Parameters<typeof Client>[1];
 /**
  *
  * @param procedures procedures the client will be able to call, see {@link ProceduresMap}
@@ -64,26 +40,3 @@ export declare function Client<Procedures extends ProceduresMap>(procedures: Pro
     restartListener?: boolean;
     localStorage?: Record<string, any>;
 }): SwarpcClient<Procedures>;
-/**
- * A quicker version of postMessage that does not try to start the client listener, await the service worker, etc.
- * esp. useful for abort logic that needs to not be... put behind everything else on the event loop.
- * @param l
- * @param worker
- * @param message
- * @param options
- */
-export declare function postMessageSync<Procedures extends ProceduresMap>(l: RequestBoundLogger, worker: Worker | SharedWorker | undefined, message: Payload<Procedures>, options?: StructuredSerializeOptions): void;
-/**
- * Starts the client listener, which listens for messages from the sw&rpc server.
- * @param ctx.worker if provided, the client will use this worker to listen for messages, instead of using the service worker
- * @returns
- */
-export declare function startClientListener<Procedures extends ProceduresMap>(ctx: Context<Procedures>): Promise<void>;
-/**
- * Generate a random request ID, used to identify requests between client and server.
- * @source
- * @returns a 6-character hexadecimal string
- */
-export declare function makeRequestId(): string;
-export {};
-//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -1,42 +1,13 @@
-/**
- * @module
- * @mergeModuleWith <project>
- */
 import { createLogger, } from "./log.js";
 import { makeNodeId, nodeIdOrSW, whoToSendTo } from "./nodes.js";
 import { zProcedures, } from "./types.js";
 import { findTransferables } from "./utils.js";
-/**
- * Pending requests are stored in a map, where the key is the request ID.
- * Each request has a set of handlers: resolve, reject, and onProgress.
- * This allows having a single listener for the client, and having multiple in-flight calls to the same procedure.
- */
 const pendingRequests = new Map();
-// Have we started the client listener?
 let _clientListenerStarted = new Set();
-/**
- *
- * @param procedures procedures the client will be able to call, see {@link ProceduresMap}
- * @param options various options
- * @param options.worker The worker class, **not instantiated**, or a path to the source code. If not provided, the client will use the service worker. If a string is provided, it'll instantiate a regular `Worker`, not a `SharedWorker`.
- * Example: `"./worker.js"`
- * See {@link Worker} (used by both dedicated workers and service workers), {@link SharedWorker}, and
- * the different [worker types](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API#worker_types) that exist
- * @param options.hooks Hooks to run on messages received from the server. See {@link Hooks}
- * @param options.loglevel Maximum log level to use, defaults to "debug" (shows everything). "info" will not show debug messages, "warn" will only show warnings and errors, "error" will only show errors.
- * @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}.
- * @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 function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug", restartListener = false, hooks = {}, localStorage = {}, } = {}) {
     const l = createLogger("client", loglevel);
     if (restartListener)
         _clientListenerStarted.clear();
-    // Store procedures on a symbol key, to avoid conflicts with procedure names
     const instance = { [zProcedures]: procedures };
     nodeCount ??= navigator.hardwareConcurrency || 1;
     let nodes;
@@ -72,23 +43,17 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                 functionName,
             }, options);
         };
-        // Set the method on the instance
         const _runProcedure = async (input, onProgress = () => { }, reqid, nodeId) => {
-            // Validate the input against the procedure's input schema
             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();
-            // Choose which node to use
             nodeId ??= whoToSendTo(nodes, pendingRequests);
             const node = nodes && nodeId ? nodes[nodeId] : undefined;
             const l = createLogger("client", loglevel, nodeIdOrSW(nodeId), requestId);
             return new Promise((resolve, reject) => {
-                // Store promise handlers (as well as progress updates handler)
-                // so the client listener can resolve/reject the promise (and react to progress updates)
-                // when the server sends messages back
                 pendingRequests.set(requestId, {
                     nodeId,
                     functionName,
@@ -99,14 +64,12 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
                 const transfer = procedures[functionName].autotransfer === "always"
                     ? findTransferables(input)
                     : [];
-                // Post the message to the server
                 l.debug(`Requesting ${functionName} with`, input);
                 return send(node, nodeId, requestId, { input }, { transfer })
                     .then(() => { })
                     .catch(reject);
             });
         };
-        // @ts-expect-error
         instance[functionName] = _runProcedure;
         instance[functionName].broadcast = async (input, onProgresses, nodesCount) => {
             let nodesToUse = [undefined];
@@ -151,16 +114,11 @@ export function Client(procedures, { worker, nodes: nodeCount, loglevel = "debug
     }
     return instance;
 }
-/**
- * Warms up the client by starting the listener and getting the worker, then posts a message to the worker.
- * @returns the worker to use
- */
 async function postMessage(ctx, message, options) {
     await startClientListener(ctx);
     const { logger: l, node: worker } = ctx;
     if (!worker && !navigator.serviceWorker.controller)
         l.warn("", "Service Worker is not controlling the page");
-    // If no worker is provided, we use the service worker
     const w = worker instanceof SharedWorker
         ? worker.port
         : worker === undefined
@@ -171,18 +129,9 @@ async function postMessage(ctx, message, options) {
     }
     w.postMessage(message, options);
 }
-/**
- * A quicker version of postMessage that does not try to start the client listener, await the service worker, etc.
- * esp. useful for abort logic that needs to not be... put behind everything else on the event loop.
- * @param l
- * @param worker
- * @param message
- * @param options
- */
-export function postMessageSync(l, worker, message, options) {
+function postMessageSync(l, worker, message, options) {
     if (!worker && !navigator.serviceWorker.controller)
         l.warn("Service Worker is not controlling the page");
-    // If no worker is provided, we use the service worker
     const w = worker instanceof SharedWorker
         ? worker.port
         : worker === undefined
@@ -193,16 +142,10 @@ export function postMessageSync(l, worker, message, options) {
     }
     w.postMessage(message, options);
 }
-/**
- * Starts the client listener, which listens for messages from the sw&rpc server.
- * @param ctx.worker if provided, the client will use this worker to listen for messages, instead of using the service worker
- * @returns
- */
-export async function startClientListener(ctx) {
+async function startClientListener(ctx) {
     if (_clientListenerStarted.has(nodeIdOrSW(ctx.nodeId)))
         return;
     const { logger: l, node: worker } = ctx;
-    // Get service worker registration if no worker is provided
     if (!worker) {
         const sw = await navigator.serviceWorker.ready;
         if (!sw?.active) {
@@ -213,33 +156,24 @@ export async function startClientListener(ctx) {
         }
     }
     const w = worker ?? navigator.serviceWorker;
-    // Start listening for messages
     l.debug(null, "Starting client listener", { w, ...ctx });
     const listener = (event) => {
-        // Get the data from the event
         const eventData = event.data || {};
-        // Ignore other messages that aren't for us
         if (eventData?.by !== "sw&rpc")
             return;
-        // We don't use a schema here, we trust the server to send valid data
         const payload = eventData;
-        // Ignore #initialize request, it's client->server only
         if ("isInitializeRequest" in payload) {
             l.warn(null, "Ignoring unexpected #initialize from server", payload);
             return;
         }
         const { requestId, ...data } = payload;
-        // 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, cannot process ${JSON.stringify(data)}`);
         }
-        // React to the data received: call hook, call handler,
-        // and remove the request from pendingRequests (unless it's a progress update)
         if ("error" in data) {
             ctx.hooks.error?.(data.functionName, new Error(data.error.message));
             handlers.reject(new Error(data.error.message));
@@ -263,7 +197,6 @@ export async function startClientListener(ctx) {
         w.addEventListener("message", listener);
     }
     _clientListenerStarted.add(nodeIdOrSW(ctx.nodeId));
-    // Recursive terminal case is ensured by calling this *after* _clientListenerStarted is set to true: startClientListener() will therefore not be called in postMessage() again.
     await postMessage(ctx, {
         by: "sw&rpc",
         functionName: "#initialize",
@@ -272,11 +205,6 @@ export async function startClientListener(ctx) {
         nodeId: nodeIdOrSW(ctx.nodeId),
     });
 }
-/**
- * Generate a random request ID, used to identify requests between client and server.
- * @source
- * @returns a 6-character hexadecimal string
- */
-export function makeRequestId() {
+function makeRequestId() {
     return Math.random().toString(16).substring(2, 8).toUpperCase();
 }

package/dist/index.d.ts

@@ -3,7 +3,8 @@
  * @mergeModuleWith <project>
  */
 import "./polyfills.js";
-export * from "./client.js";
-export * from "./server.js";
 export type { ProceduresMap, CancelablePromise } from "./types.js";
-//# sourceMappingURL=index.d.ts.map
+export { Client } 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,7 +1,3 @@
-/**
- * @module
- * @mergeModuleWith <project>
- */
 import "./polyfills.js";
-export * from "./client.js";
-export * from "./server.js";
+export { Client } from "./client.js";
+export { Server } from "./server.js";

package/dist/localstorage.d.ts

@@ -1,14 +1 @@
-export declare class FauxLocalStorage {
-    data: Record<string, any>;
-    keysOrder: string[];
-    constructor(data: Record<string, any>);
-    setItem(key: string, value: string): void;
-    getItem(key: string): any;
-    hasItem(key: string): boolean;
-    removeItem(key: string): void;
-    clear(): void;
-    key(index: number): string;
-    get length(): number;
-    register(subject: WorkerGlobalScope | SharedWorkerGlobalScope): void;
-}
-//# sourceMappingURL=localstorage.d.ts.map
+export {};

package/dist/localstorage.js

@@ -33,7 +33,6 @@ export class FauxLocalStorage {
         return this.keysOrder.length;
     }
     register(subject) {
-        // @ts-expect-error
         subject.localStorage = this;
     }
 }

package/dist/log.d.ts

@@ -2,33 +2,4 @@
  * @module
  * @mergeModuleWith <project>
  */
-/**
- * @ignore
- */
-export declare function createLogger(side: "server" | "client", level: LogLevel, nid?: string): Logger;
-export declare function createLogger(side: "server" | "client", level: LogLevel, nid: string, rqid: string): RequestBoundLogger;
-/**
- * @ignore
- */
-export type Logger = {
-    debug: (rqid: string | null, message: string, ...args: any[]) => void;
-    info: (rqid: string | null, message: string, ...args: any[]) => void;
-    warn: (rqid: string | null, message: string, ...args: any[]) => void;
-    error: (rqid: string | null, message: string, ...args: any[]) => void;
-};
-export type RequestBoundLogger = {
-    debug: (message: string, ...args: any[]) => void;
-    info: (message: string, ...args: any[]) => void;
-    warn: (message: string, ...args: any[]) => void;
-    error: (message: string, ...args: any[]) => void;
-};
-/** @source */
-declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
-export type LogLevel = (typeof LOG_LEVELS)[number];
-/**
- *
- * @param scope
- */
-export declare function injectIntoConsoleGlobal(scope: WorkerGlobalScope | SharedWorkerGlobalScope, nodeId: string): void;
 export {};
-//# sourceMappingURL=log.d.ts.map

package/dist/log.js

@@ -1,7 +1,3 @@
-/**
- * @module
- * @mergeModuleWith <project>
- */
 export function createLogger(side, level = "debug", nid, rqid) {
     const lvls = LOG_LEVELS.slice(LOG_LEVELS.indexOf(level));
     if (rqid && nid) {
@@ -20,7 +16,6 @@ export function createLogger(side, level = "debug", nid, rqid) {
         error: lvls.includes("error") ? logger("error", side, nid) : () => { },
     };
 }
-/** @source */
 const LOG_LEVELS = ["debug", "info", "warn", "error"];
 const PATCHABLE_LOG_METHODS = [
     "debug",
@@ -40,13 +35,6 @@ const originalConsole = PATCHABLE_LOG_METHODS.reduce((result, method) => {
     result[method] = console[method];
     return result;
 }, {});
-/**
- * Send log messages to the console, with a helpful prefix.
- * @param method
- * @param side
- * @param ids request ID and node ID
- * @param args passed to console methods directly
- */
 function log(method, side, { rqid, nid }, ...args) {
     const prefix = [
         `[SWARPC ${side}]`,
@@ -62,12 +50,8 @@ function log(method, side, { rqid, nid }, ...args) {
         prefixStyles.push("color: hotpink", "color: inherit");
     return originalConsole[method](prefix, ...prefixStyles, ...args);
 }
-/**
- *
- * @param scope
- */
-export function injectIntoConsoleGlobal(scope, nodeId) {
+export function injectIntoConsoleGlobal(scope, nodeId, requestId) {
     for (const method of PATCHABLE_LOG_METHODS) {
-        scope.self.console[method] = logger(method, "server", nodeId);
+        scope.self.console[method] = (...args) => logger(method, "server", nodeId)(requestId, ...args);
     }
 }

package/dist/nodes.d.ts

@@ -1,15 +1 @@
-import { PendingRequest } from "./client.js";
-/**
- * Returns to which node to send the next request, given the state of the currently pending requests
- */
-export declare function whoToSendTo(nodes: undefined | Record<string, unknown>, requests: Map<string, PendingRequest>): undefined | string;
-export declare function nodeIdFromScope(scope: WorkerGlobalScope, _scopeType?: "dedicated" | "shared" | "service"): string;
-/**
- * Generate a random request ID, used to identify nodes in the client
- * @source
- */
-export declare function makeNodeId(): string;
-declare const serviceWorkerNodeId: "(SW)";
-export declare function nodeIdOrSW(id: string | undefined): string | typeof serviceWorkerNodeId;
 export {};
-//# sourceMappingURL=nodes.d.ts.map

package/dist/nodes.js

@@ -1,7 +1,4 @@
 import { scopeIsDedicated, scopeIsShared } from "./scopes.js";
-/**
- * Returns to which node to send the next request, given the state of the currently pending requests
- */
 export function whoToSendTo(nodes, requests) {
     if (!nodes)
         return undefined;
@@ -14,7 +11,6 @@ export function whoToSendTo(nodes, requests) {
     for (const [node, reqs] of requestsPerNode.entries()) {
         if (!node)
             continue;
-        // Send to the least busy node
         if (reqs.length < requestsPerNode.get(chosen).length)
             chosen = node;
     }
@@ -27,14 +23,10 @@ export function nodeIdFromScope(scope, _scopeType) {
     }
     return "(SW)";
 }
-/**
- * Generate a random request ID, used to identify nodes in the client
- * @source
- */
 export function makeNodeId() {
     return "N" + Math.random().toString(16).substring(2, 5).toUpperCase();
 }
-const serviceWorkerNodeId = "(SW)"; // Fixed ID for the service worker, as there's only one
+const serviceWorkerNodeId = "(SW)";
 export function nodeIdOrSW(id) {
     return id ?? serviceWorkerNodeId;
 }

package/dist/polyfills.d.ts

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=polyfills.d.ts.map

package/dist/polyfills.js

@@ -1,13 +1,3 @@
-/**
- * Groups elements from an iterable into a Map based on a callback function.
- *
- * @template K, T
- * @param {Iterable<T>} iterable - The iterable to group.
- * @param {function(T, number): K} callbackfn - The callback function to
- * determine the grouping key.
- * @returns {Map<K, T[]>} A Map where keys are the grouping keys and values are
- * arrays of grouped elements.
- */
 Map.groupBy ??= function groupBy(iterable, callbackfn) {
     const map = new Map();
     let i = 0;

package/dist/scopes.d.ts

@@ -1,4 +1 @@
-export declare function scopeIsShared(scope: WorkerGlobalScope, _scopeType?: "dedicated" | "shared" | "service"): scope is SharedWorkerGlobalScope;
-export declare function scopeIsDedicated(scope: WorkerGlobalScope, _scopeType?: "dedicated" | "shared" | "service"): scope is DedicatedWorkerGlobalScope;
-export declare function scopeIsService(scope: WorkerGlobalScope, _scopeType?: "dedicated" | "shared" | "service"): scope is ServiceWorkerGlobalScope;
-//# sourceMappingURL=scopes.d.ts.map
+export {};

package/dist/server.d.ts

@@ -21,7 +21,7 @@ export type SwarpcServer<Procedures extends ProceduresMap> = {
  * @param options various options
  * @param options.scope The worker scope to use, defaults to the `self` of the file where Server() is called.
  * @param options.loglevel Maximum log level to use, defaults to "debug" (shows everything). "info" will not show debug messages, "warn" will only show warnings and errors, "error" will only show errors.
- * @param options._scopeType @internal Don't touch, this is used in testing environments because the mock is subpar. Manually overrides worker scope type detection.
+ * @param options._scopeType Don't touch, this is used in testing environments because the mock is subpar. Manually overrides worker scope type detection.
  * @returns a SwarpcServer instance. Each property of the procedures map will be a method, that accepts a function implementing the procedure (see {@link ProcedureImplementation}). There is also .start(), to be called after implementing all procedures.
  *
  * An example of defining a server:
@@ -32,4 +32,3 @@ export declare function Server<Procedures extends ProceduresMap>(procedures: Pro
     loglevel?: LogLevel;
     _scopeType?: "dedicated" | "shared" | "service";
 }): SwarpcServer<Procedures>;
-//# sourceMappingURL=server.d.ts.map