swarpc 0.10.0 → 0.12.0

package/README.md

@@ -1,153 +1,240 @@
-<div align=center>
-<h1>
-  <img src="./logo.svg" alt="sw&rpc" />
-</h1>
-
-RPC for Service Workers -- move that heavy computation off of your UI thread!
-
-</div>
- 
-* * *
-
-## Installation
-
-```bash
-npm add swarpc arktype
-```
-
-## Usage
-
-### 1. Declare your procedures in a shared file
-
-```typescript
-import type { ProceduresMap } from "swarpc"
-import { type } from "arktype"
-
-export const procedures = {
-  searchIMDb: {
-    // Input for the procedure
-    input: type({ query: "string", "pageSize?": "number" }),
-    // Function to be called whenever you can update progress while the procedure is running -- long computations are a first-class concern here. Examples include using the fetch-progress NPM package.
-    progress: type({ transferred: "number", total: "number" }),
-    // Output of a successful procedure call
-    success: type({
-      id: "string",
-      primary_title: "string",
-      genres: "string[]",
-    }).array(),
-  },
-} as const satisfies ProceduresMap
-```
-
-### 2. Register your procedures in the service worker
-
-In your service worker file:
-
-```javascript
-import fetchProgress from "fetch-progress"
-import { Server } from "swarpc"
-import { procedures } from "./procedures.js"
-
-// 1. Give yourself a server instance
-const swarpc = Server(procedures)
-
-// 2. Implement your procedures
-swarpc.searchIMDb(async ({ query, pageSize = 10 }, onProgress) => {
-  const queryParams = new URLSearchParams({
-    page_size: pageSize.toString(),
-    query,
-  })
-
-  return fetch(`https://rest.imdbapi.dev/v2/search/titles?${queryParams}`)
-    .then(fetchProgress({ onProgress }))
-    .then((response) => response.json())
-    .then(({ titles } => titles)
-})
-
-// ...
-
-// 3. Start the event listener
-swarpc.start(self)
-```
-
-### 3. Call your procedures from the client
-
-Here's a Svelte example!
-
-```svelte
-<script>
-    import { Client } from "swarpc"
-    import { procedures } from "./procedures.js"
-
-    const swarpc = Client(procedures)
-
-    let query = $state("")
-    let results = $state([])
-    let progress = $state(0)
-</script>
-
-<search>
-    <input type="text" bind:value={query} placeholder="Search IMDb" />
-    <button onclick={async () => {
-        results = await swarpc.searchIMDb({ query }, (p) => {
-            progress = p.transferred / p.total
-        })
-    }}>
-        Search
-    </button>
-</search>
-
-{#if progress > 0 && progress < 1}
-    <progress value={progress} max="1" />
-{/if}
-
-<ul>
-    {#each results as { id, primary_title, genres } (id)}
-        <li>{primary_title} - {genres.join(", ")}</li>
-    {/each}
-</ul>
-```
-
-### Make cancelable requests
-
-#### Implementation
-
-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) => {
-  // 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
-  for (...) {
-    /* here */ if (aborted) return
-    ...
-  }
-
-  // When using fetch:
-  await fetch(..., { signal: abort })
-})
-```
-
-#### Call sites
-
-Instead of calling `await client.myProcedure()` directly, call `client.myProcedure.cancelable()`. You'll get back an object with
-
-- `async cancel(reason)`: a function to cancel the request
-- `request`: a Promise that resolves to the result of the procedure call. `await` it to wait for the request to finish.
-
-Example:
-
-```js
-// Normal call:
-const result = await swarpc.searchIMDb({ query })
-
-// Cancelable call:
-const { request, cancel } = swarpc.searchIMDb.cancelable({ query })
-setTimeout(() => cancel().then(() => console.warn("Took too long!!")), 5_000)
-await request
-```
+<div align=center>
+<h1>
+  <img src="./logo.svg" alt="sw&rpc" />
+</h1>
+
+RPC for Service Workers -- move that heavy computation off of your UI thread!
+
+</div>
+ 
+* * *
+
+## Features
+
+- Fully typesafe
+- 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
+- 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
+
+```bash
+npm add swarpc arktype
+```
+
+### Bleeding edge
+
+If you want to use the latest commit instead of a published version, you can, either by using the Git URL:
+
+```bash
+npm add git+https://github.com/gwennlbh/swarpc.git
+```
+
+Or by straight up cloning the repository and pointing to the local directory (very useful to hack on sw&rpc while testing out your changes on a more substantial project):
+
+```bash
+mkdir -p vendored
+git clone https://github.com/gwennlbh/swarpc.git vendored/swarpc
+npm add file:vendored/swarpc
+```
+
+This works thanks to the fact that `dist/` is published on the repository (and kept up to date with a CI workflow).
+
+## Usage
+
+### 1. Declare your procedures in a shared file
+
+```typescript
+import type { ProceduresMap } from "swarpc";
+import { type } from "arktype";
+
+export const procedures = {
+  searchIMDb: {
+    // Input for the procedure
+    input: type({ query: "string", "pageSize?": "number" }),
+    // Function to be called whenever you can update progress while the procedure is running -- long computations are a first-class concern here. Examples include using the fetch-progress NPM package.
+    progress: type({ transferred: "number", total: "number" }),
+    // Output of a successful procedure call
+    success: type({
+      id: "string",
+      primary_title: "string",
+      genres: "string[]",
+    }).array(),
+  },
+} as const satisfies ProceduresMap;
+```
+
+### 2. Register your procedures in the service worker
+
+In your service worker file:
+
+```javascript
+import fetchProgress from "fetch-progress"
+import { Server } from "swarpc"
+import { procedures } from "./procedures.js"
+
+// 1. Give yourself a server instance
+const swarpc = Server(procedures)
+
+// 2. Implement your procedures
+swarpc.searchIMDb(async ({ query, pageSize = 10 }, onProgress) => {
+  const queryParams = new URLSearchParams({
+    page_size: pageSize.toString(),
+    query,
+  })
+
+  return fetch(`https://rest.imdbapi.dev/v2/search/titles?${queryParams}`)
+    .then(fetchProgress({ onProgress }))
+    .then((response) => response.json())
+    .then(({ titles } => titles)
+})
+
+// ...
+
+// 3. Start the event listener
+swarpc.start(self)
+```
+
+### 3. Call your procedures from the client
+
+Here's a Svelte example!
+
+```svelte
+<script>
+    import { Client } from "swarpc"
+    import { procedures } from "./procedures.js"
+
+    const swarpc = Client(procedures)
+
+    let query = $state("")
+    let results = $state([])
+    let progress = $state(0)
+</script>
+
+<search>
+    <input type="text" bind:value={query} placeholder="Search IMDb" />
+    <button onclick={async () => {
+        results = await swarpc.searchIMDb({ query }, (p) => {
+            progress = p.transferred / p.total
+        })
+    }}>
+        Search
+    </button>
+</search>
+
+{#if progress > 0 && progress < 1}
+    <progress value={progress} max="1" />
+{/if}
+
+<ul>
+    {#each results as { id, primary_title, genres } (id)}
+        <li>{primary_title} - {genres.join(", ")}</li>
+    {/each}
+</ul>
+```
+
+### 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).
+
+When `Client:options.worker` is not set, the client will use the Service worker (and thus only a single instance).
+
+#### Send to multiple nodes
+
+Use `Client#(method name).broadcast` to send the same request to all nodes at once. This method returns a Promise that resolves to an array of `PromiseSettledResult` (with an additional property, `node`, the ID of the node the request was sent to), one per node the request was sent to.
+
+For example:
+
+```ts
+const client = Client(procedures, {
+  worker: "./worker.js",
+  nodes: 4,
+});
+
+for (const result of await client.initDB.broadcast("localhost:5432")) {
+  if (result.status === "rejected") {
+    console.error(
+      `Could not initialize database on node ${result.node}`,
+      result.reason,
+    );
+  }
+}
+```
+
+### Make cancelable requests
+
+#### Implementation
+
+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) => {
+  // 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
+  for (...) {
+    /* here */ if (aborted) return
+    ...
+  }
+
+  // When using fetch:
+  await fetch(..., { signal: abort })
+})
+```
+
+#### Call sites
+
+Instead of calling `await client.myProcedure()` directly, call `client.myProcedure.cancelable()`. You'll get back an object with
+
+- `async cancel(reason)`: a function to cancel the request
+- `request`: a Promise that resolves to the result of the procedure call. `await` it to wait for the request to finish.
+
+Example:
+
+```js
+// Normal call:
+const result = await swarpc.searchIMDb({ query });
+
+// Cancelable call:
+const { request, cancel } = swarpc.searchIMDb.cancelable({ query });
+setTimeout(() => cancel().then(() => console.warn("Took too long!!")), 5_000);
+await request;
+```
+
+### Polyfill a `localStorage` for the Server to access
+
+You might call third-party code that accesses on `localStorage` from within your procedures.
+
+Some workers don't have access to the browser's `localStorage`, so you'll get an error.
+
+You can work around this by specifying to swarpc localStorage items to define on the Server, and it'll create a polyfilled `localStorage` with your data.
+
+An example use case is using Paraglide, a i18n library, with [the `localStorage` strategy](https://inlang.com/m/gerre34r/library-inlang-paraglideJs/strategy#localstorage):
+
+```js
+// In the client
+import { getLocale } from "./paraglide/runtime.js";
+
+const swarpc = Client(procedures, {
+  localStorage: {
+    PARAGLIDE_LOCALE: getLocale(),
+  },
+});
+
+await swarpc.myProcedure(1, 0);
+
+// In the server
+import { m } from "./paraglide/runtime.js";
+const swarpc = Server(procedures);
+
+swarpc.myProcedure(async (a, b) => {
+  if (b === 0) throw new Error(m.cannot_divide_by_zero());
+  return a / b;
+});
+```

package/dist/client.d.ts

@@ -2,8 +2,8 @@
  * @module
  * @mergeModuleWith <project>
  */
-import { type Logger, type LogLevel } from "./log.js";
-import { ClientMethod, Hooks, Payload, zProcedures, type ProceduresMap } from "./types.js";
+import { RequestBoundLogger, type Logger, type LogLevel } from "./log.js";
+import { ClientMethod, Hooks, Payload, 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,27 +14,55 @@ 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}
  * @param options various options
- * @param options.worker The instantiated worker object. If not provided, the client will use the service worker.
- * Example: `new Worker("./worker.js")`
+ * @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 declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, loglevel, restartListener, hooks, }?: {
-    worker?: Worker | SharedWorker;
+export declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, nodes: nodeCount, loglevel, restartListener, hooks, localStorage, }?: {
+    worker?: WorkerConstructor | string;
+    nodes?: number;
     hooks?: Hooks<Procedures>;
     loglevel?: LogLevel;
     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.
@@ -44,18 +72,18 @@ export declare function Client<Procedures extends ProceduresMap>(procedures: Pro
  * @param message
  * @param options
  */
-export declare function postMessageSync<Procedures extends ProceduresMap>(l: Logger, worker: Worker | SharedWorker | undefined, message: Payload<Procedures>, options?: StructuredSerializeOptions): void;
+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 worker if provided, the client will use this worker to listen for messages, instead of using the service worker
- * @param force if true, will force the listener to restart even if it has already been started
+ * @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>(l: Logger, worker?: Worker | SharedWorker, hooks?: Hooks<Procedures>): Promise<void>;
+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.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAgB,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnE,OAAO,EACL,YAAY,EACZ,KAAK,EACL,OAAO,EAEP,WAAW,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAA;AAGnB;;;;GAIG;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;AAkBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EACE,MAAM,EACN,QAAkB,EAClB,eAAuB,EACvB,KAAU,GACX,GAAE;IACD,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;IAC9B,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,eAAe,CAAC,EAAE,OAAO,CAAA;CACrB,GACL,YAAY,CAAC,UAAU,CAAC,CAsG1B;AAiCD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,SAAS,aAAa,EAC9D,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,EACzC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,EAC5B,OAAO,CAAC,EAAE,0BAA0B,GACnC,IAAI,CAiBN;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,SAAS,aAAa,EACxE,CAAC,EAAE,MAAM,EACT,MAAM,CAAC,EAAE,MAAM,GAAG,YAAY,EAC9B,KAAK,GAAE,KAAK,CAAC,UAAU,CAAM,iBAmE9B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAEL,kBAAkB,EAClB,KAAK,MAAM,EACX,KAAK,QAAQ,EACd,MAAM,UAAU,CAAC;AAElB,OAAO,EACL,YAAY,EACZ,KAAK,EACL,OAAO,EAEP,iBAAiB,EACjB,WAAW,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAC;AAGpB;;;;GAIG;AACH,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,aAAa,IAAI;IAC3D,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;CAC3B,GAAG;KACD,CAAC,IAAI,MAAM,UAAU,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;CACrD,CAAC;AAEF;;GAEG;AACH,KAAK,OAAO,CAAC,UAAU,SAAS,aAAa,IAAI;IAC/C,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IACxC,gCAAgC;IAChC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,kCAAkC;IAClC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IACzB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACnC,CAAC;AAQF,MAAM,MAAM,cAAc,GAAG;IAC3B,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;IAC7B,UAAU,EAAE,CAAC,QAAQ,EAAE,GAAG,KAAK,IAAI,CAAC;IACpC,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAChC,CAAC;AAKF,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EACE,MAAM,EACN,KAAK,EAAE,SAAS,EAChB,QAAkB,EAClB,eAAuB,EACvB,KAAU,EACV,YAAiB,GAClB,GAAE;IACD,MAAM,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1B,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B,GACL,YAAY,CAAC,UAAU,CAAC,CAgK1B;AAiCD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,UAAU,SAAS,aAAa,EAC9D,CAAC,EAAE,kBAAkB,EACrB,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,EACzC,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC,EAC5B,OAAO,CAAC,EAAE,0BAA0B,GACnC,IAAI,CAiBN;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,SAAS,aAAa,EACxE,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,iBAoFzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}