swarpc 0.10.0 → 0.11.0

package/README.md

@@ -15,6 +15,24 @@ RPC for Service Workers -- move that heavy computation off of your UI thread!
 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

package/dist/client.d.ts

@@ -14,6 +14,19 @@ 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 worker instance to use */
+    worker: Worker | SharedWorker | 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>;
+};
 /**
  *
  * @param procedures procedures the client will be able to call, see {@link ProceduresMap}
@@ -25,16 +38,18 @@ export type SwarpcClient<Procedures extends ProceduresMap> = {
  * @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)
  * @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, }?: {
+export declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, loglevel, restartListener, hooks, localStorage, }?: {
     worker?: Worker | SharedWorker;
     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.
@@ -47,15 +62,15 @@ export declare function Client<Procedures extends ProceduresMap>(procedures: Pro
 export declare function postMessageSync<Procedures extends ProceduresMap>(l: Logger, 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,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;AAED;;GAEG;AACH,KAAK,OAAO,CAAC,UAAU,SAAS,aAAa,IAAI;IAC/C,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAA;IACzC,kCAAkC;IAClC,KAAK,EAAE,KAAK,CAAC,UAAU,CAAC,CAAA;IACxB,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAClC,CAAA;AAkBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EACE,MAAM,EACN,QAAkB,EAClB,eAAuB,EACvB,KAAU,EACV,YAAiB,GAClB,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;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC9B,GACL,YAAY,CAAC,UAAU,CAAC,CA2G1B;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;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,SAAS,aAAa,EACxE,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,iBAoFzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/client.js

@@ -24,12 +24,13 @@ let _clientListenerStarted = false;
  * @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)
  * @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, loglevel = "debug", restartListener = false, hooks = {}, } = {}) {
+export function Client(procedures, { worker, loglevel = "debug", restartListener = false, hooks = {}, localStorage = {}, } = {}) {
     const l = createLogger("client", loglevel);
     if (restartListener)
         _clientListenerStarted = false;
@@ -40,7 +41,13 @@ export function Client(procedures, { worker, loglevel = "debug", restartListener
             throw new Error(`[SWARPC Client] Invalid function name, don't use symbols`);
         }
         const send = async (requestId, msg, options) => {
-            return postMessage(l, worker, hooks, {
+            const ctx = {
+                logger: l,
+                worker,
+                hooks,
+                localStorage,
+            };
+            return postMessage(ctx, {
                 ...msg,
                 by: "sw&rpc",
                 requestId,
@@ -101,8 +108,9 @@ export function Client(procedures, { worker, loglevel = "debug", restartListener
  * 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(l, worker, hooks, message, options) {
-    await startClientListener(l, worker, hooks);
+async function postMessage(ctx, message, options) {
+    await startClientListener(ctx);
+    const { logger: l, 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
@@ -140,13 +148,13 @@ export function postMessageSync(l, worker, message, options) {
 }
 /**
  * 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 async function startClientListener(l, worker, hooks = {}) {
+export async function startClientListener(ctx) {
     if (_clientListenerStarted)
         return;
+    const { logger: l, worker } = ctx;
     // Get service worker registration if no worker is provided
     if (!worker) {
         const sw = await navigator.serviceWorker.ready;
@@ -159,7 +167,7 @@ export async function startClientListener(l, worker, hooks = {}) {
     }
     const w = worker ?? navigator.serviceWorker;
     // Start listening for messages
-    l.debug(null, "Starting client listener", { worker, w, hooks });
+    l.debug(null, "Starting client listener", { w, ...ctx });
     const listener = (event) => {
         // Get the data from the event
         const eventData = event.data || {};
@@ -167,7 +175,13 @@ export async function startClientListener(l, worker, hooks = {}) {
         if (eventData?.by !== "sw&rpc")
             return;
         // We don't use a arktype schema here, we trust the server to send valid data
-        const { requestId, ...data } = eventData;
+        const payload = eventData;
+        // Ignore #initialize request, it's client->server only
+        if ("localStorageData" 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");
@@ -180,16 +194,16 @@ export async function startClientListener(l, worker, hooks = {}) {
         // 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) {
-            hooks.error?.(data.functionName, new Error(data.error.message));
+            ctx.hooks.error?.(data.functionName, new Error(data.error.message));
             handlers.reject(new Error(data.error.message));
             pendingRequests.delete(requestId);
         }
         else if ("progress" in data) {
-            hooks.progress?.(data.functionName, data.progress);
+            ctx.hooks.progress?.(data.functionName, data.progress);
             handlers.onProgress(data.progress);
         }
         else if ("result" in data) {
-            hooks.success?.(data.functionName, data.result);
+            ctx.hooks.success?.(data.functionName, data.result);
             handlers.resolve(data.result);
             pendingRequests.delete(requestId);
         }
@@ -202,6 +216,12 @@ export async function startClientListener(l, worker, hooks = {}) {
         w.addEventListener("message", listener);
     }
     _clientListenerStarted = true;
+    // 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",
+        localStorageData: ctx.localStorage,
+    });
 }
 /**
  * Generate a random request ID, used to identify requests between client and server.

package/dist/localstorage.d.ts

@@ -0,0 +1,14 @@
+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

package/dist/localstorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localstorage.d.ts","sourceRoot":"","sources":["../src/localstorage.ts"],"names":[],"mappings":"AAAA,qBAAa,gBAAgB;IAC3B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACzB,SAAS,EAAE,MAAM,EAAE,CAAA;gBAEP,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAKrC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAKlC,OAAO,CAAC,GAAG,EAAE,MAAM;IAInB,OAAO,CAAC,GAAG,EAAE,MAAM;IAInB,UAAU,CAAC,GAAG,EAAE,MAAM;IAMtB,KAAK;IAKL,GAAG,CAAC,KAAK,EAAE,MAAM;IAIjB,IAAI,MAAM,WAET;IAED,QAAQ,CAAC,OAAO,EAAE,iBAAiB,GAAG,uBAAuB;CAI9D"}

package/dist/localstorage.js

@@ -0,0 +1,39 @@
+export class FauxLocalStorage {
+    data;
+    keysOrder;
+    constructor(data) {
+        this.data = data;
+        this.keysOrder = Object.keys(data);
+    }
+    setItem(key, value) {
+        if (!this.hasItem(key))
+            this.keysOrder.push(key);
+        this.data[key] = value;
+    }
+    getItem(key) {
+        return this.data[key];
+    }
+    hasItem(key) {
+        return Object.hasOwn(this.data, key);
+    }
+    removeItem(key) {
+        if (!this.hasItem(key))
+            return;
+        delete this.data[key];
+        this.keysOrder = this.keysOrder.filter((k) => k !== key);
+    }
+    clear() {
+        this.data = {};
+        this.keysOrder = [];
+    }
+    key(index) {
+        return this.keysOrder[index];
+    }
+    get length() {
+        return this.keysOrder.length;
+    }
+    register(subject) {
+        // @ts-expect-error
+        subject.localStorage = this;
+    }
+}

package/dist/server.d.ts

@@ -19,7 +19,7 @@ export type SwarpcServer<Procedures extends ProceduresMap> = {
  * Creates a sw&rpc server instance.
  * @param procedures procedures the server will implement, see {@link ProceduresMap}
  * @param options various options
- * @param options.worker The worker scope to use, defaults to the `self` of the file where Server() is called.
+ * @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.
  * @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.

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EACL,kBAAkB,EAKlB,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAA;AAgBnB;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,aAAa,IAAI;IAC3D,CAAC,WAAW,CAAC,EAAE,UAAU,CAAA;IACzB,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAA;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,GAAG;KACD,CAAC,IAAI,MAAM,UAAU,GAAG,CACvB,IAAI,EAAE,uBAAuB,CAC3B,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EACtB,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EACzB,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CACzB,KACE,IAAI;CACV,CAAA;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EACE,QAAkB,EAClB,KAAK,EACL,UAAU,GACX,GAAE;IACD,KAAK,CAAC,EAAE,iBAAiB,CAAA;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,UAAU,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;CAC3C,GACL,YAAY,CAAC,UAAU,CAAC,CAgN1B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EACL,kBAAkB,EAMlB,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,KAAK,aAAa,EACnB,MAAM,YAAY,CAAA;AAiBnB;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,UAAU,SAAS,aAAa,IAAI;IAC3D,CAAC,WAAW,CAAC,EAAE,UAAU,CAAA;IACzB,CAAC,gBAAgB,CAAC,EAAE,kBAAkB,CAAC,UAAU,CAAC,CAAA;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB,GAAG;KACD,CAAC,IAAI,MAAM,UAAU,GAAG,CACvB,IAAI,EAAE,uBAAuB,CAC3B,UAAU,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EACtB,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,EACzB,UAAU,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CACzB,KACE,IAAI;CACV,CAAA;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EACE,QAAkB,EAClB,KAAK,EACL,UAAU,GACX,GAAE;IACD,KAAK,CAAC,EAAE,iBAAiB,CAAA;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,UAAU,CAAC,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAA;CAC3C,GACL,YAAY,CAAC,UAAU,CAAC,CA0N1B"}

package/dist/server.js

@@ -5,8 +5,9 @@
 /// <reference lib="webworker" />
 import { type } from "arktype";
 import { createLogger } from "./log.js";
-import { PayloadHeaderSchema, PayloadSchema, zImplementations, zProcedures, } from "./types.js";
+import { PayloadHeaderSchema, PayloadInitializeSchema, PayloadSchema, zImplementations, zProcedures, } from "./types.js";
 import { findTransferables } from "./utils.js";
+import { FauxLocalStorage } from "./localstorage.js";
 class MockedWorkerGlobalScope {
     constructor() { }
 }
@@ -19,7 +20,7 @@ const abortedRequests = new Set();
  * Creates a sw&rpc server instance.
  * @param procedures procedures the server will implement, see {@link ProceduresMap}
  * @param options various options
- * @param options.worker The worker scope to use, defaults to the `self` of the file where Server() is called.
+ * @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.
  * @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.
@@ -72,9 +73,9 @@ export function Server(procedures, { loglevel = "debug", scope, _scopeType, } =
         const port = await new Promise((resolve) => {
             if (!scopeIsShared(scope))
                 return resolve(undefined);
-            console.log("Awaiting shared worker connection...");
+            l.debug(null, "Awaiting shared worker connection...");
             scope.addEventListener("connect", ({ ports: [port] }) => {
-                console.log("Shared worker connected with port", port);
+                l.debug(null, "Shared worker connected with port", port);
                 resolve(port);
             });
         });
@@ -94,6 +95,12 @@ export function Server(procedures, { loglevel = "debug", scope, _scopeType, } =
             }
         };
         const listener = async (event) => {
+            if (PayloadInitializeSchema.allows(event.data)) {
+                const { localStorageData } = event.data;
+                l.debug(null, "Setting up faux localStorage", localStorageData);
+                new FauxLocalStorage(localStorageData).register(scope);
+                return;
+            }
             // Decode the payload
             const { requestId, functionName } = PayloadHeaderSchema(type.enumerated(...Object.keys(procedures))).assert(event.data);
             l.debug(requestId, `Received request for ${functionName}`, event.data);
@@ -124,6 +131,8 @@ export function Server(procedures, { loglevel = "debug", scope, _scopeType, } =
             }
             // Define payload schema for incoming messages
             const payload = PayloadSchema(type(`"${functionName}"`), schemas.input, schemas.progress, schemas.success).assert(event.data);
+            if ("localStorageData" in payload)
+                throw "Unreachable: #initialize request payload should've been handled already";
             // Handle abortion requests (pro-choice ftw!!)
             if (payload.abort) {
                 const controller = abortControllers.get(requestId);

package/dist/types.d.ts

@@ -105,6 +105,12 @@ export type Hooks<Procedures extends ProceduresMap> = {
      */
     progress?: <Procedure extends keyof ProceduresMap>(procedure: Procedure, data: Procedures[Procedure]["progress"]["inferOut"]) => void;
 };
+export declare const PayloadInitializeSchema: import("arktype/internal/methods/object.ts").ObjectType<{
+    by: "sw&rpc";
+    functionName: "#initialize";
+    localStorageData: Record<string, unknown>;
+}, {}>;
+export type PayloadInitialize = typeof PayloadInitializeSchema.infer;
 /**
  * @source
  */
@@ -150,7 +156,7 @@ export type PayloadCore<PM extends ProceduresMap, Name extends keyof PM = keyof
 /**
  * @source
  */
-export declare const PayloadSchema: import("arktype").Generic<[["Name", string], ["I", unknown], ["P", unknown], ["S", unknown]], readonly ["PayloadHeaderSchema<Name>", "&", "PayloadCoreSchema<I, P, S>"], {
+export declare const PayloadSchema: import("arktype").Generic<[["Name", string], ["I", unknown], ["P", unknown], ["S", unknown]], readonly [readonly ["PayloadHeaderSchema<Name>", "&", "PayloadCoreSchema<I, P, S>"], "|", "PayloadInitializeSchema"], {
     PayloadCoreSchema: import("arktype/internal/scope.ts").bindGenericToScope<import("@ark/schema").GenericAst<[["I", unknown], ["P", unknown], ["S", unknown]], {
         readonly "input?": "I";
         readonly "progress?": "P";
@@ -178,6 +184,17 @@ export declare const PayloadSchema: import("arktype").Generic<[["Name", string],
             readonly functionName: "Name";
             readonly requestId: "string >= 1";
         }, {}, {}>;
+        PayloadInitializeSchema: import("arktype/internal/methods/object.ts").ObjectType<{
+            by: "sw&rpc";
+            functionName: "#initialize";
+            localStorageData: Record<string, unknown>;
+        }, {}> & {
+            readonly " brand": [import("arktype/internal/methods/object.ts").ObjectType<{
+                by: "sw&rpc";
+                functionName: "#initialize";
+                localStorageData: Record<string, unknown>;
+            }, {}>, "unparsed"];
+        };
     } & {}>;
     PayloadHeaderSchema: import("arktype/internal/scope.ts").bindGenericToScope<import("@ark/schema").GenericAst<[["Name", string]], {
         readonly by: "\"sw&rpc\"";
@@ -200,7 +217,23 @@ export declare const PayloadSchema: import("arktype").Generic<[["Name", string],
             readonly functionName: "Name";
             readonly requestId: "string >= 1";
         }, {}, {}>;
+        PayloadInitializeSchema: import("arktype/internal/methods/object.ts").ObjectType<{
+            by: "sw&rpc";
+            functionName: "#initialize";
+            localStorageData: Record<string, unknown>;
+        }, {}> & {
+            readonly " brand": [import("arktype/internal/methods/object.ts").ObjectType<{
+                by: "sw&rpc";
+                functionName: "#initialize";
+                localStorageData: Record<string, unknown>;
+            }, {}>, "unparsed"];
+        };
     } & {}>;
+    PayloadInitializeSchema: {
+        by: "sw&rpc";
+        functionName: "#initialize";
+        localStorageData: Record<string, unknown>;
+    };
 }, {
     PayloadCoreSchema: import("arktype/internal/scope.ts").bindGenericToScope<import("@ark/schema").GenericAst<[["I", unknown], ["P", unknown], ["S", unknown]], {
         readonly "input?": "I";
@@ -229,6 +262,17 @@ export declare const PayloadSchema: import("arktype").Generic<[["Name", string],
             readonly functionName: "Name";
             readonly requestId: "string >= 1";
         }, {}, {}>;
+        PayloadInitializeSchema: import("arktype/internal/methods/object.ts").ObjectType<{
+            by: "sw&rpc";
+            functionName: "#initialize";
+            localStorageData: Record<string, unknown>;
+        }, {}> & {
+            readonly " brand": [import("arktype/internal/methods/object.ts").ObjectType<{
+                by: "sw&rpc";
+                functionName: "#initialize";
+                localStorageData: Record<string, unknown>;
+            }, {}>, "unparsed"];
+        };
     } & {}>;
     PayloadHeaderSchema: import("arktype/internal/scope.ts").bindGenericToScope<import("@ark/schema").GenericAst<[["Name", string]], {
         readonly by: "\"sw&rpc\"";
@@ -251,12 +295,28 @@ export declare const PayloadSchema: import("arktype").Generic<[["Name", string],
             readonly functionName: "Name";
             readonly requestId: "string >= 1";
         }, {}, {}>;
+        PayloadInitializeSchema: import("arktype/internal/methods/object.ts").ObjectType<{
+            by: "sw&rpc";
+            functionName: "#initialize";
+            localStorageData: Record<string, unknown>;
+        }, {}> & {
+            readonly " brand": [import("arktype/internal/methods/object.ts").ObjectType<{
+                by: "sw&rpc";
+                functionName: "#initialize";
+                localStorageData: Record<string, unknown>;
+            }, {}>, "unparsed"];
+        };
     } & {}>;
+    PayloadInitializeSchema: {
+        by: "sw&rpc";
+        functionName: "#initialize";
+        localStorageData: Record<string, unknown>;
+    };
 }>;
 /**
  * The effective payload as sent by the server to the client
  */
-export type Payload<PM extends ProceduresMap, Name extends keyof PM = keyof PM> = PayloadHeader<PM, Name> & PayloadCore<PM, Name>;
+export type Payload<PM extends ProceduresMap, Name extends keyof PM = keyof PM> = (PayloadHeader<PM, Name> & PayloadCore<PM, Name>) | PayloadInitialize;
 /**
  * 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.
  */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -3,6 +3,11 @@
  * @mergeModuleWith <project>
  */
 import { type } from "arktype";
+export const PayloadInitializeSchema = type({
+    by: '"sw&rpc"',
+    functionName: '"#initialize"',
+    localStorageData: "Record<string, unknown>",
+});
 /**
  * @source
  */
@@ -25,11 +30,11 @@ export const PayloadCoreSchema = type("<I, P, S>", {
  * @source
  */
 export const PayloadSchema = type
-    .scope({ PayloadCoreSchema, PayloadHeaderSchema })
+    .scope({ PayloadCoreSchema, PayloadHeaderSchema, PayloadInitializeSchema })
     .type("<Name extends string, I, P, S>", [
-    "PayloadHeaderSchema<Name>",
-    "&",
-    "PayloadCoreSchema<I, P, S>",
+    ["PayloadHeaderSchema<Name>", "&", "PayloadCoreSchema<I, P, S>"],
+    "|",
+    "PayloadInitializeSchema",
 ]);
 /**
  * Symbol used as the key for the procedures map on the server instance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarpc",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Full type-safe RPC library for service worker -- move things off of the UI thread with ease!",
   "keywords": [
     "service-workers",
@@ -48,15 +48,15 @@
     "nodemon": "^3.1.10",
     "prettier": "^3.6.2",
     "sirv-cli": "^3.0.1",
-    "typedoc": "^0.28.9",
+    "typedoc": "^0.28.11",
     "typedoc-material-theme": "^1.4.0",
-    "typedoc-plugin-dt-links": "^2.0.13",
+    "typedoc-plugin-dt-links": "^2.0.16",
     "typedoc-plugin-extras": "^4.0.1",
     "typedoc-plugin-inline-sources": "^1.3.0",
-    "typedoc-plugin-mdn-links": "^5.0.7",
+    "typedoc-plugin-mdn-links": "^5.0.9",
     "typedoc-plugin-redirect": "^1.2.0",
     "typescript": "^5.9.2",
-    "vite": "^7.0.6",
+    "vite": "^7.1.3",
     "vitest": "^3.2.4"
   },
   "volta": {

package/src/client.ts

@@ -25,6 +25,20 @@ 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 worker instance to use */
+  worker: Worker | SharedWorker | 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>
+}
+
 /**
  * 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.
@@ -52,6 +66,7 @@ let _clientListenerStarted = false
  * @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)
  * @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:
@@ -64,11 +79,13 @@ export function Client<Procedures extends ProceduresMap>(
     loglevel = "debug",
     restartListener = false,
     hooks = {},
+    localStorage = {},
   }: {
     worker?: Worker | SharedWorker
     hooks?: Hooks<Procedures>
     loglevel?: LogLevel
     restartListener?: boolean
+    localStorage?: Record<string, any>
   } = {}
 ): SwarpcClient<Procedures> {
   const l = createLogger("client", loglevel)
@@ -94,10 +111,15 @@ export function Client<Procedures extends ProceduresMap>(
       msg: PayloadCore<Procedures, typeof functionName>,
       options?: StructuredSerializeOptions
     ) => {
-      return postMessage(
-        l,
+      const ctx: Context<Procedures> = {
+        logger: l,
         worker,
         hooks,
+        localStorage,
+      }
+
+      return postMessage(
+        ctx,
         {
           ...msg,
           by: "sw&rpc",
@@ -179,13 +201,13 @@ export function Client<Procedures extends ProceduresMap>(
  * @returns the worker to use
  */
 async function postMessage<Procedures extends ProceduresMap>(
-  l: Logger,
-  worker: Worker | SharedWorker | undefined,
-  hooks: Hooks<Procedures>,
+  ctx: Context<Procedures>,
   message: Payload<Procedures>,
   options?: StructuredSerializeOptions
 ) {
-  await startClientListener(l, worker, hooks)
+  await startClientListener(ctx)
+
+  const { logger: l, worker } = ctx
 
   if (!worker && !navigator.serviceWorker.controller)
     l.warn("", "Service Worker is not controlling the page")
@@ -239,17 +261,16 @@ export function postMessageSync<Procedures extends ProceduresMap>(
 
 /**
  * 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 async function startClientListener<Procedures extends ProceduresMap>(
-  l: Logger,
-  worker?: Worker | SharedWorker,
-  hooks: Hooks<Procedures> = {}
+  ctx: Context<Procedures>
 ) {
   if (_clientListenerStarted) return
 
+  const { logger: l, worker } = ctx
+
   // Get service worker registration if no worker is provided
   if (!worker) {
     const sw = await navigator.serviceWorker.ready
@@ -265,7 +286,7 @@ export async function startClientListener<Procedures extends ProceduresMap>(
   const w = worker ?? navigator.serviceWorker
 
   // Start listening for messages
-  l.debug(null, "Starting client listener", { worker, w, hooks })
+  l.debug(null, "Starting client listener", { w, ...ctx })
   const listener = (event: Event): void => {
     // Get the data from the event
     const eventData = (event as MessageEvent).data || {}
@@ -274,7 +295,15 @@ export async function startClientListener<Procedures extends ProceduresMap>(
     if (eventData?.by !== "sw&rpc") return
 
     // We don't use a arktype schema here, we trust the server to send valid data
-    const { requestId, ...data } = eventData as Payload<Procedures>
+    const payload = eventData as Payload<Procedures>
+
+    // Ignore #initialize request, it's client->server only
+    if ("localStorageData" 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) {
@@ -292,14 +321,14 @@ export async function startClientListener<Procedures extends ProceduresMap>(
     // 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) {
-      hooks.error?.(data.functionName, new Error(data.error.message))
+      ctx.hooks.error?.(data.functionName, new Error(data.error.message))
       handlers.reject(new Error(data.error.message))
       pendingRequests.delete(requestId)
     } else if ("progress" in data) {
-      hooks.progress?.(data.functionName, data.progress)
+      ctx.hooks.progress?.(data.functionName, data.progress)
       handlers.onProgress(data.progress)
     } else if ("result" in data) {
-      hooks.success?.(data.functionName, data.result)
+      ctx.hooks.success?.(data.functionName, data.result)
       handlers.resolve(data.result)
       pendingRequests.delete(requestId)
     }
@@ -313,6 +342,13 @@ export async function startClientListener<Procedures extends ProceduresMap>(
   }
 
   _clientListenerStarted = true
+
+  // 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",
+    localStorageData: ctx.localStorage,
+  })
 }
 
 /**

package/src/localstorage.ts

@@ -0,0 +1,46 @@
+export class FauxLocalStorage {
+  data: Record<string, any>
+  keysOrder: string[]
+
+  constructor(data: Record<string, any>) {
+    this.data = data
+    this.keysOrder = Object.keys(data)
+  }
+
+  setItem(key: string, value: string) {
+    if (!this.hasItem(key)) this.keysOrder.push(key)
+    this.data[key] = value
+  }
+
+  getItem(key: string) {
+    return this.data[key]
+  }
+
+  hasItem(key: string) {
+    return Object.hasOwn(this.data, key)
+  }
+
+  removeItem(key: string) {
+    if (!this.hasItem(key)) return
+    delete this.data[key]
+    this.keysOrder = this.keysOrder.filter((k) => k !== key)
+  }
+
+  clear() {
+    this.data = {}
+    this.keysOrder = []
+  }
+
+  key(index: number) {
+    return this.keysOrder[index]
+  }
+
+  get length() {
+    return this.keysOrder.length
+  }
+
+  register(subject: WorkerGlobalScope | SharedWorkerGlobalScope) {
+    // @ts-expect-error
+    subject.localStorage = this
+  }
+}

package/src/server.ts

@@ -11,6 +11,7 @@ import {
   Payload,
   PayloadCore,
   PayloadHeaderSchema,
+  PayloadInitializeSchema,
   PayloadSchema,
   ProcedureImplementation,
   zImplementations,
@@ -18,6 +19,7 @@ import {
   type ProceduresMap,
 } from "./types.js"
 import { findTransferables } from "./utils.js"
+import { FauxLocalStorage } from "./localstorage.js"
 
 class MockedWorkerGlobalScope {
   constructor() {}
@@ -57,7 +59,7 @@ const abortedRequests = new Set<string>()
  * Creates a sw&rpc server instance.
  * @param procedures procedures the server will implement, see {@link ProceduresMap}
  * @param options various options
- * @param options.worker The worker scope to use, defaults to the `self` of the file where Server() is called.
+ * @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.
  * @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.
@@ -136,9 +138,9 @@ export function Server<Procedures extends ProceduresMap>(
   instance.start = async () => {
     const port = await new Promise<MessagePort | undefined>((resolve) => {
       if (!scopeIsShared(scope)) return resolve(undefined)
-      console.log("Awaiting shared worker connection...")
+      l.debug(null, "Awaiting shared worker connection...")
       scope.addEventListener("connect", ({ ports: [port] }) => {
-        console.log("Shared worker connected with port", port)
+        l.debug(null, "Shared worker connected with port", port)
         resolve(port)
       })
     })
@@ -164,6 +166,13 @@ export function Server<Procedures extends ProceduresMap>(
     const listener = async (
       event: MessageEvent<any> | ExtendableMessageEvent
     ): Promise<void> => {
+      if (PayloadInitializeSchema.allows(event.data)) {
+        const { localStorageData } = event.data
+        l.debug(null, "Setting up faux localStorage", localStorageData)
+        new FauxLocalStorage(localStorageData).register(scope)
+        return
+      }
+
       // Decode the payload
       const { requestId, functionName } = PayloadHeaderSchema(
         type.enumerated(...Object.keys(procedures))
@@ -211,6 +220,9 @@ export function Server<Procedures extends ProceduresMap>(
         schemas.success
       ).assert(event.data)
 
+      if ("localStorageData" in payload)
+        throw "Unreachable: #initialize request payload should've been handled already"
+
       // Handle abortion requests (pro-choice ftw!!)
       if (payload.abort) {
         const controller = abortControllers.get(requestId)

package/src/types.ts

@@ -4,7 +4,7 @@
  */
 
 import { type, type Type } from "arktype"
-import { Logger, RequestBoundLogger } from "./log.js"
+import { RequestBoundLogger } from "./log.js"
 
 /**
  * A procedure declaration
@@ -131,6 +131,14 @@ export type Hooks<Procedures extends ProceduresMap> = {
   ) => void
 }
 
+export const PayloadInitializeSchema = type({
+  by: '"sw&rpc"',
+  functionName: '"#initialize"',
+  localStorageData: "Record<string, unknown>",
+})
+
+export type PayloadInitialize = typeof PayloadInitializeSchema.infer
+
 /**
  * @source
  */
@@ -184,11 +192,11 @@ export type PayloadCore<
  * @source
  */
 export const PayloadSchema = type
-  .scope({ PayloadCoreSchema, PayloadHeaderSchema })
+  .scope({ PayloadCoreSchema, PayloadHeaderSchema, PayloadInitializeSchema })
   .type("<Name extends string, I, P, S>", [
-    "PayloadHeaderSchema<Name>",
-    "&",
-    "PayloadCoreSchema<I, P, S>",
+    ["PayloadHeaderSchema<Name>", "&", "PayloadCoreSchema<I, P, S>"],
+    "|",
+    "PayloadInitializeSchema",
   ])
 
 /**
@@ -197,7 +205,7 @@ export const PayloadSchema = type
 export type Payload<
   PM extends ProceduresMap,
   Name extends keyof PM = keyof PM,
-> = PayloadHeader<PM, Name> & PayloadCore<PM, Name>
+> = (PayloadHeader<PM, Name> & PayloadCore<PM, Name>) | PayloadInitialize
 
 /**
  * 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.