swarpc 0.7.1 → 0.9.0

package/dist/client.d.ts

@@ -1,21 +1,47 @@
-import { type LogLevel } from "./log.js";
-import { Hooks, type ProceduresMap, type SwarpcClient } from "./types.js";
-export type { SwarpcClient } from "./types.js";
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { type Logger, type LogLevel } from "./log.js";
+import { ClientMethod, Hooks, 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.
+ * If you want to be able to cancel the request, you can set the request's ID yourself, and call `.abort(requestId, reason)` on the client instance to cancel it.
+ */
+export type SwarpcClient<Procedures extends ProceduresMap> = {
+    [zProcedures]: Procedures;
+} & {
+    [F in keyof Procedures]: ClientMethod<Procedures[F]>;
+};
 /**
  *
- * @param procedures procedures the client will be able to call
+ * @param procedures procedures the client will be able to call, see {@link ProceduresMap}
  * @param options various options
  * @param options.worker if provided, the client will use this worker to post messages.
  * @param options.hooks hooks to run on messages received from the server
- * @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.
+ * @param options.restartListener if true, will force the listener to restart even if it has already been started
+ * @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, hooks, }?: {
+export declare function Client<Procedures extends ProceduresMap>(procedures: Procedures, { worker, loglevel, restartListener, hooks, }?: {
     worker?: Worker;
     hooks?: Hooks<Procedures>;
     loglevel?: LogLevel;
+    restartListener?: boolean;
 }): SwarpcClient<Procedures>;
+/**
+ * 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
+ * @returns
+ */
+export declare function startClientListener<Procedures extends ProceduresMap>(l: Logger, worker?: Worker, hooks?: Hooks<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;

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6B,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnE,OAAO,EACL,KAAK,EAIL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAkB9C;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EACE,MAAM,EACN,QAAkB,EAClB,KAAU,GACX,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GAC1E,YAAY,CAAC,UAAU,CAAC,CA+F1B;AAmGD;;;GAGG;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,EAGL,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;;;;;;;;;;;GAWG;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,CAAA;IACf,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,CAiG1B;AA6BD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,UAAU,SAAS,aAAa,EACxE,CAAC,EAAE,MAAM,EACT,MAAM,CAAC,EAAE,MAAM,EACf,KAAK,GAAE,KAAK,CAAC,UAAU,CAAM,iBA4D9B;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/client.js

@@ -1,5 +1,9 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 import { createLogger } from "./log.js";
-import { zProcedures } from "./types.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.
@@ -11,14 +15,20 @@ const pendingRequests = new Map();
 let _clientListenerStarted = false;
 /**
  *
- * @param procedures procedures the client will be able to call
+ * @param procedures procedures the client will be able to call, see {@link ProceduresMap}
  * @param options various options
  * @param options.worker if provided, the client will use this worker to post messages.
  * @param options.hooks hooks to run on messages received from the server
- * @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.
+ * @param options.restartListener if true, will force the listener to restart even if it has already been started
+ * @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", hooks = {}, } = {}) {
+export function Client(procedures, { worker, loglevel = "debug", restartListener = false, hooks = {}, } = {}) {
     const l = createLogger("client", loglevel);
+    if (restartListener)
+        _clientListenerStarted = false;
     // Store procedures on a symbol key, to avoid conflicts with procedure names
     const instance = { [zProcedures]: procedures };
     for (const functionName of Object.keys(procedures)) {
@@ -96,9 +106,10 @@ async function postMessage(l, worker, hooks, 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
  * @returns
  */
-async function startClientListener(l, worker, hooks = {}) {
+export async function startClientListener(l, worker, hooks = {}) {
     if (_clientListenerStarted)
         return;
     // Get service worker registration if no worker is provided
@@ -113,7 +124,7 @@ async function startClientListener(l, worker, hooks = {}) {
     }
     const w = worker ?? navigator.serviceWorker;
     // Start listening for messages
-    l.debug("", "Starting client listener on", w);
+    l.debug(null, "Starting client listener", { worker, w, hooks });
     w.addEventListener("message", (event) => {
         // Get the data from the event
         const eventData = event.data || {};
@@ -129,7 +140,7 @@ async function startClientListener(l, worker, hooks = {}) {
         // Get the associated pending request handlers
         const handlers = pendingRequests.get(requestId);
         if (!handlers) {
-            throw new Error(`[SWARPC Client] ${requestId} has no active request 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)
@@ -152,6 +163,7 @@ async function startClientListener(l, worker, hooks = {}) {
 }
 /**
  * Generate a random request ID, used to identify requests between client and server.
+ * @source
  * @returns a 6-character hexadecimal string
  */
 export function makeRequestId() {

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 export * from "./client.js";
 export * from "./server.js";
 export type { ProceduresMap, CancelablePromise } from "./types.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -1,2 +1,6 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 export * from "./client.js";
 export * from "./server.js";

package/dist/log.d.ts

@@ -1,20 +1,28 @@
-export declare function createLogger(side: "server" | "client", level?: LogLevel): {
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+/**
+ * @ignore
+ */
+export declare function createLogger(side: "server" | "client", level: LogLevel): Logger;
+export declare function createLogger(side: "server" | "client", level: LogLevel, 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 Logger = ReturnType<typeof createLogger>;
-declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+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 */
+export declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
 export type LogLevel = (typeof LOG_LEVELS)[number];
-/**
- * Send log messages to the console, with a helpful prefix.
- * @param severity
- * @param side
- * @param rqid request ID
- * @param message
- * @param args passed to console methods directly
- */
-export declare function log(severity: "debug" | "info" | "warn" | "error", side: "server" | "client", rqid: string | null, message: string, ...args: any[]): void;
-export {};
 //# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,KAAK,GAAE,QAAkB;kBAwBX,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;iBAA9C,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;iBAA9C,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;kBAA9C,MAAM,GAAG,IAAI,WAAW,MAAM,WAAW,GAAG,EAAE;EAd7D;AAED,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAA;AAEpD,QAAA,MAAM,UAAU,6CAA8C,CAAA;AAC9D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAalD;;;;;;;GAOG;AACH,wBAAgB,GAAG,CACjB,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EAC7C,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,EAAE,MAAM,EACf,GAAG,IAAI,EAAE,GAAG,EAAE,QAkBf"}
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAAA;AAChF,wBAAgB,YAAY,CAC1B,IAAI,EAAE,QAAQ,GAAG,QAAQ,EACzB,KAAK,EAAE,QAAQ,EACf,IAAI,EAAE,MAAM,GACX,kBAAkB,CAAA;AAyBrB;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG;IACnB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACrE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACpE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IACpE,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CACtE,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAChD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/C,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;IAC/C,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,CAAA;CACjD,CAAA;AAED,cAAc;AACd,eAAO,MAAM,UAAU,6CAA8C,CAAA;AAErE,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA"}

package/dist/log.js

@@ -1,21 +1,31 @@
-export function createLogger(side, level = "debug") {
-    const enabledLevels = LOG_LEVELS.slice(LOG_LEVELS.indexOf(level));
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+export function createLogger(side, level = "debug", rqid) {
+    const lvls = LOG_LEVELS.slice(LOG_LEVELS.indexOf(level));
+    if (rqid) {
+        return {
+            debug: lvls.includes("debug") ? logger("debug", side, rqid) : () => { },
+            info: lvls.includes("info") ? logger("info", side, rqid) : () => { },
+            warn: lvls.includes("warn") ? logger("warn", side, rqid) : () => { },
+            error: lvls.includes("error") ? logger("error", side, rqid) : () => { },
+        };
+    }
     return {
-        debug: enabledLevels.includes("debug") ? logger("debug", side) : () => { },
-        info: enabledLevels.includes("info") ? logger("info", side) : () => { },
-        warn: enabledLevels.includes("warn") ? logger("warn", side) : () => { },
-        error: enabledLevels.includes("error") ? logger("error", side) : () => { },
+        debug: lvls.includes("debug") ? logger("debug", side) : () => { },
+        info: lvls.includes("info") ? logger("info", side) : () => { },
+        warn: lvls.includes("warn") ? logger("warn", side) : () => { },
+        error: lvls.includes("error") ? logger("error", side) : () => { },
     };
 }
-const LOG_LEVELS = ["debug", "info", "warn", "error"];
-/**
- * Creates partially-applied logging functions given the first 2 args
- * @param severity
- * @param side
- * @returns
- */
-function logger(severity, side) {
-    return (rqid, message, ...args) => log(severity, side, rqid, message, ...args);
+/** @source */
+export const LOG_LEVELS = ["debug", "info", "warn", "error"];
+function logger(severity, side, rqid) {
+    if (rqid === undefined) {
+        return (rqid, message, ...args) => log(severity, side, rqid, message, ...args);
+    }
+    return (message, ...args) => log(severity, side, rqid, message, ...args);
 }
 /**
  * Send log messages to the console, with a helpful prefix.
@@ -25,7 +35,7 @@ function logger(severity, side) {
  * @param message
  * @param args passed to console methods directly
  */
-export function log(severity, side, rqid, message, ...args) {
+function log(severity, side, rqid, message, ...args) {
     const prefix = "[" +
         ["SWARPC", side, rqid ? `%c${rqid}%c` : ""].filter(Boolean).join(" ") +
         "]";

package/dist/server.d.ts

@@ -1,12 +1,29 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 import { type LogLevel } from "./log.js";
-import { type ProceduresMap, type SwarpcServer } from "./types.js";
-export type { SwarpcServer } from "./types.js";
+import { ImplementationsMap, ProcedureImplementation, zImplementations, zProcedures, type ProceduresMap } from "./types.js";
+/**
+ * The sw&rpc server instance, which provides methods to register {@link ProcedureImplementation | procedure implementations},
+ * and listens for incoming messages that call those procedures
+ */
+export type SwarpcServer<Procedures extends ProceduresMap> = {
+    [zProcedures]: Procedures;
+    [zImplementations]: ImplementationsMap<Procedures>;
+    start(self: Window | Worker): void;
+} & {
+    [F in keyof Procedures]: (impl: ProcedureImplementation<Procedures[F]["input"], Procedures[F]["progress"], Procedures[F]["success"]>) => void;
+};
 /**
  * Creates a sw&rpc server instance.
- * @param procedures procedures the server will implement
+ * @param procedures procedures the server will implement, see {@link ProceduresMap}
  * @param options various options
  * @param options.worker if provided, the server will use this worker to post messages, instead of sending it to all clients
- * @returns a SwarpcServer instance. Each property of the procedures map will be a method, that accepts a function implementing the procedure. There is also .start(), to be called after implementing all procedures.
+ * @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:
+ * {@includeCode ../example/src/service-worker.ts}
  */
 export declare function Server<Procedures extends ProceduresMap>(procedures: Procedures, { worker, loglevel }?: {
     worker?: Worker;

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAQL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAGnB,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAK9C;;;;;;GAMG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EAAE,MAAM,EAAE,QAAkB,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GAC5E,YAAY,CAAC,UAAU,CAAC,CAkK1B"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,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;AAGnB;;;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,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CACnC,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;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,UAAU,SAAS,aAAa,EACrD,UAAU,EAAE,UAAU,EACtB,EAAE,MAAM,EAAE,QAAkB,EAAE,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAAO,GAC5E,YAAY,CAAC,UAAU,CAAC,CA8J1B"}

package/dist/server.js

@@ -1,3 +1,7 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 import { type } from "arktype";
 import { createLogger } from "./log.js";
 import { PayloadHeaderSchema, PayloadSchema, zImplementations, zProcedures, } from "./types.js";
@@ -6,10 +10,13 @@ const abortControllers = new Map();
 const abortedRequests = new Set();
 /**
  * Creates a sw&rpc server instance.
- * @param procedures procedures the server will implement
+ * @param procedures procedures the server will implement, see {@link ProceduresMap}
  * @param options various options
  * @param options.worker if provided, the server will use this worker to post messages, instead of sending it to all clients
- * @returns a SwarpcServer instance. Each property of the procedures map will be a method, that accepts a function implementing the procedure. There is also .start(), to be called after implementing all procedures.
+ * @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:
+ * {@includeCode ../example/src/service-worker.ts}
  */
 export function Server(procedures, { worker, loglevel = "debug" } = {}) {
     const l = createLogger("server", loglevel);
@@ -27,17 +34,15 @@ export function Server(procedures, { worker, loglevel = "debug" } = {}) {
             if (!instance[zProcedures][functionName]) {
                 throw new Error(`No procedure found for function name: ${functionName}`);
             }
-            instance[zImplementations][functionName] = (input, onProgress, abortSignal) => {
-                abortSignal?.throwIfAborted();
+            instance[zImplementations][functionName] = (input, onProgress, tools) => {
+                tools.abortSignal?.throwIfAborted();
                 return new Promise((resolve, reject) => {
-                    abortSignal?.addEventListener("abort", () => {
-                        let { requestId, reason } = abortSignal?.reason;
+                    tools.abortSignal?.addEventListener("abort", () => {
+                        let { requestId, reason } = tools.abortSignal?.reason;
                         l.debug(requestId, `Aborted ${functionName} request: ${reason}`);
                         reject({ aborted: reason });
                     });
-                    implementation(input, onProgress, abortSignal)
-                        .then(resolve)
-                        .catch(reject);
+                    implementation(input, onProgress, tools).then(resolve).catch(reject);
                 });
             };
         });
@@ -101,13 +106,21 @@ export function Server(procedures, { worker, loglevel = "debug" } = {}) {
                 await postError("No input provided");
                 return;
             }
-            // Call the implementation with the input and a progress callback
-            await implementation(payload.input, async (progress) => {
-                l.debug(requestId, `Progress for ${functionName}`, progress);
-                await postMsg({ progress });
-            }, abortControllers.get(requestId)?.signal)
+            try {
+                // Call the implementation with the input and a progress callback
+                const result = await implementation(payload.input, async (progress) => {
+                    l.debug(requestId, `Progress for ${functionName}`, progress);
+                    await postMsg({ progress });
+                }, {
+                    abortSignal: abortControllers.get(requestId)?.signal,
+                    logger: createLogger("server", loglevel, requestId),
+                });
+                // Send results
+                l.debug(requestId, `Result for ${functionName}`, result);
+                await postMsg({ result });
+            }
+            catch (error) {
                 // Send errors
-                .catch(async (error) => {
                 // Handle errors caused by abortions
                 if ("aborted" in error) {
                     l.debug(requestId, `Received abort error for ${functionName}`, error.aborted);
@@ -115,17 +128,12 @@ export function Server(procedures, { worker, loglevel = "debug" } = {}) {
                     abortControllers.delete(requestId);
                     return;
                 }
-                l.error(requestId, `Error in ${functionName}`, error);
+                l.info(requestId, `Error in ${functionName}`, error);
                 await postError(error);
-            })
-                // Send results
-                .then(async (result) => {
-                l.debug(requestId, `Result for ${functionName}`, result);
-                await postMsg({ result });
-            })
-                .finally(() => {
+            }
+            finally {
                 abortedRequests.delete(requestId);
-            });
+            }
         });
     };
     return instance;

package/dist/types.d.ts

@@ -1,4 +1,9 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 import { type Type } from "arktype";
+import { RequestBoundLogger } from "./log.js";
 /**
  * A procedure declaration
  */
@@ -37,7 +42,7 @@ export type Procedure<I extends Type, P extends Type, S extends Type> = {
  * const result = await request
  * ```
  */
-export type CancelablePromise<T> = {
+export type CancelablePromise<T = unknown> = {
     request: Promise<T>;
     /**
      * Abort the request.
@@ -48,9 +53,33 @@ export type CancelablePromise<T> = {
 /**
  * An implementation of a procedure
  */
-export type ProcedureImplementation<I extends Type, P extends Type, S extends Type> = (input: I["inferOut"], onProgress: (progress: P["inferIn"]) => void, abortSignal?: AbortSignal) => Promise<S["inferIn"]>;
+export type ProcedureImplementation<I extends Type, P extends Type, S extends Type> = (
+/**
+ * Input data for the procedure
+ */
+input: I["inferOut"], 
+/**
+ * Callback to call with progress updates.
+ */
+onProgress: (progress: P["inferIn"]) => void, 
+/**
+ * Additional tools useful when implementing the procedure.
+ */
+tools: {
+    /**
+     * AbortSignal that can be used to handle request cancellation -- see [Make cancellable requests](https://gwennlbh.github.io/swarpc/docs/#make-cancelable-requests)
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Logger instance to use for logging messages related to this procedure call, using the same format as SWARPC's built-in logging.
+     */
+    logger: RequestBoundLogger;
+}) => Promise<S["inferIn"]>;
 /**
  * Declarations of procedures by name.
+ *
+ * An example of declaring procedures:
+ * {@includeCode ../example/src/lib/procedures.ts}
  */
 export type ProceduresMap = Record<string, Procedure<Type, Type, Type>>;
 /**
@@ -76,6 +105,9 @@ export type Hooks<Procedures extends ProceduresMap> = {
      */
     progress?: <Procedure extends keyof ProceduresMap>(procedure: Procedure, data: Procedures[Procedure]["progress"]["inferOut"]) => void;
 };
+/**
+ * @source
+ */
 export declare const PayloadHeaderSchema: import("arktype").Generic<[["Name", string]], {
     readonly by: "\"sw&rpc\"";
     readonly functionName: "Name";
@@ -86,6 +118,9 @@ export type PayloadHeader<PM extends ProceduresMap, Name extends keyof PM = keyo
     functionName: Name & string;
     requestId: string;
 };
+/**
+ * @source
+ */
 export declare const PayloadCoreSchema: import("arktype").Generic<[["I", unknown], ["P", unknown], ["S", unknown]], {
     readonly "input?": "I";
     readonly "progress?": "P";
@@ -112,6 +147,9 @@ export type PayloadCore<PM extends ProceduresMap, Name extends keyof PM = keyof
         message: string;
     };
 };
+/**
+ * @source
+ */
 export declare const PayloadSchema: import("arktype").Generic<[["Name", string], ["I", unknown], ["P", unknown], ["S", unknown]], readonly ["PayloadHeaderSchema<Name>", "&", "PayloadCoreSchema<I, P, S>"], {
     PayloadCoreSchema: import("arktype/internal/scope.ts").bindGenericToScope<import("@ark/schema").GenericAst<[["I", unknown], ["P", unknown], ["S", unknown]], {
         readonly "input?": "I";
@@ -230,31 +268,14 @@ export type ClientMethod<P extends Procedure<Type, Type, Type>> = ((input: P["in
 };
 /**
  * Symbol used as the key for the procedures map on the server instance
+ * @internal
+ * @source
  */
 export declare const zImplementations: unique symbol;
 /**
  * Symbol used as the key for the procedures map on instances
+ * @internal
+ * @source
  */
 export declare const zProcedures: unique symbol;
-/**
- * The sw&rpc client instance, which provides 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.
- * If you want to be able to cancel the request, you can set the request's ID yourself, and call `.abort(requestId, reason)` on the client instance to cancel it.
- */
-export type SwarpcClient<Procedures extends ProceduresMap> = {
-    [zProcedures]: Procedures;
-} & {
-    [F in keyof Procedures]: ClientMethod<Procedures[F]>;
-};
-/**
- * The sw&rpc server instance, which provides methods to register procedure implementations,
- * and listens for incoming messages that call those procedures
- */
-export type SwarpcServer<Procedures extends ProceduresMap> = {
-    [zProcedures]: Procedures;
-    [zImplementations]: ImplementationsMap<Procedures>;
-    start(self: Window | Worker): void;
-} & {
-    [F in keyof Procedures]: (impl: ProcedureImplementation<Procedures[F]["input"], Procedures[F]["progress"], Procedures[F]["success"]>) => void;
-};
 //# sourceMappingURL=types.d.ts.map

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

@@ -1,9 +1,19 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
 import { type } from "arktype";
+/**
+ * @source
+ */
 export const PayloadHeaderSchema = type("<Name extends string>", {
     by: '"sw&rpc"',
     functionName: "Name",
     requestId: "string >= 1",
 });
+/**
+ * @source
+ */
 export const PayloadCoreSchema = type("<I, P, S>", {
     "input?": "I",
     "progress?": "P",
@@ -11,6 +21,9 @@ export const PayloadCoreSchema = type("<I, P, S>", {
     "abort?": { reason: "string" },
     "error?": { message: "string" },
 });
+/**
+ * @source
+ */
 export const PayloadSchema = type
     .scope({ PayloadCoreSchema, PayloadHeaderSchema })
     .type("<Name extends string, I, P, S>", [
@@ -20,9 +33,13 @@ export const PayloadSchema = type
 ]);
 /**
  * Symbol used as the key for the procedures map on the server instance
+ * @internal
+ * @source
  */
 export const zImplementations = Symbol("SWARPC implementations");
 /**
  * Symbol used as the key for the procedures map on instances
+ * @internal
+ * @source
  */
 export const zProcedures = Symbol("SWARPC procedures");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarpc",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Full type-safe RPC library for service worker -- move things off of the UI thread with ease!",
   "keywords": [
     "service-workers",
@@ -31,19 +31,36 @@
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest",
-    "typedoc": "typedoc src/index.ts src/types.ts --readme README.md",
-    "version": "kacl release && prettier -w CHANGELOG.md && git add CHANGELOG.md"
+    "typedoc": "typedoc",
+    "version": "kacl release && prettier -w CHANGELOG.md && git add CHANGELOG.md",
+    "typedoc:dev": "nodemon --watch src --watch README.md --watch typedoc.json --watch typedoc.css --exec npm run typedoc:withplugins",
+    "typedoc:serve": "npx sirv-cli --dev docs",
+    "typedoc:plugins": "node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('typedoc.json')).plugin||[];if(p.length)require('child_process').execSync('npm add --legacy-peer-deps -D '+p.join(' '),{stdio:'inherit'});else console.log('No plugins found');\"",
+    "typedoc:withplugins": "npm run typedoc:plugins && npm run typedoc"
   },
   "dependencies": {
     "arktype": "^2.1.20"
   },
   "devDependencies": {
+    "@8hobbies/typedoc-plugin-plausible": "^2.2.0",
     "@vitest/web-worker": "^3.2.4",
     "kacl": "^1.1.1",
+    "nodemon": "^3.1.10",
     "prettier": "^3.6.2",
+    "sirv-cli": "^3.0.1",
     "typedoc": "^0.28.9",
+    "typedoc-material-theme": "^1.4.0",
+    "typedoc-plugin-dt-links": "^2.0.12",
+    "typedoc-plugin-extras": "^4.0.1",
+    "typedoc-plugin-inline-sources": "^1.3.0",
+    "typedoc-plugin-mdn-links": "^5.0.6",
+    "typedoc-plugin-redirect": "^1.2.0",
     "typescript": "^5.9.2",
     "vite": "^7.0.6",
     "vitest": "^3.2.4"
+  },
+  "volta": {
+    "node": "22.18.0",
+    "npm": "11.5.2"
   }
 }

package/src/client.ts

@@ -1,15 +1,29 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
 import { createLogger, type Logger, type LogLevel } from "./log.js"
 import {
+  ClientMethod,
   Hooks,
   Payload,
   PayloadCore,
   zProcedures,
   type ProceduresMap,
-  type SwarpcClient
 } from "./types.js"
 import { findTransferables } from "./utils.js"
 
-export type { SwarpcClient } 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.
+ * If you want to be able to cancel the request, you can set the request's ID yourself, and call `.abort(requestId, reason)` on the client instance to cancel it.
+ */
+export type SwarpcClient<Procedures extends ProceduresMap> = {
+  [zProcedures]: Procedures
+} & {
+  [F in keyof Procedures]: ClientMethod<Procedures[F]>
+}
 
 /**
  * Pending requests are stored in a map, where the key is the request ID.
@@ -29,22 +43,34 @@ let _clientListenerStarted = false
 
 /**
  *
- * @param procedures procedures the client will be able to call
+ * @param procedures procedures the client will be able to call, see {@link ProceduresMap}
  * @param options various options
  * @param options.worker if provided, the client will use this worker to post messages.
  * @param options.hooks hooks to run on messages received from the server
- * @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.
+ * @param options.restartListener if true, will force the listener to restart even if it has already been started
+ * @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 extends ProceduresMap>(
   procedures: Procedures,
   {
     worker,
     loglevel = "debug",
+    restartListener = false,
     hooks = {},
-  }: { worker?: Worker; hooks?: Hooks<Procedures>; loglevel?: LogLevel } = {}
+  }: {
+    worker?: Worker
+    hooks?: Hooks<Procedures>
+    loglevel?: LogLevel
+    restartListener?: boolean
+  } = {}
 ): SwarpcClient<Procedures> {
   const l = createLogger("client", loglevel)
 
+  if (restartListener) _clientListenerStarted = false
+
   // Store procedures on a symbol key, to avoid conflicts with procedure names
   const instance = { [zProcedures]: procedures } as Partial<
     SwarpcClient<Procedures>
@@ -169,9 +195,10 @@ async function postMessage<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
  * @returns
  */
-async function startClientListener<Procedures extends ProceduresMap>(
+export async function startClientListener<Procedures extends ProceduresMap>(
   l: Logger,
   worker?: Worker,
   hooks: Hooks<Procedures> = {}
@@ -193,7 +220,7 @@ async function startClientListener<Procedures extends ProceduresMap>(
   const w = worker ?? navigator.serviceWorker
 
   // Start listening for messages
-  l.debug("", "Starting client listener on", w)
+  l.debug(null, "Starting client listener", { worker, w, hooks })
   w.addEventListener("message", (event) => {
     // Get the data from the event
     const eventData = (event as MessageEvent).data || {}
@@ -213,7 +240,7 @@ async function startClientListener<Procedures extends ProceduresMap>(
     const handlers = pendingRequests.get(requestId)
     if (!handlers) {
       throw new Error(
-        `[SWARPC Client] ${requestId} has no active request handlers`
+        `[SWARPC Client] ${requestId} has no active request handlers, cannot process ${JSON.stringify(data)}`,
       )
     }
 
@@ -238,6 +265,7 @@ async function startClientListener<Procedures extends ProceduresMap>(
 
 /**
  * Generate a random request ID, used to identify requests between client and server.
+ * @source
  * @returns a 6-character hexadecimal string
  */
 export function makeRequestId(): string {

package/src/index.ts

@@ -1,3 +1,8 @@
+/**
+ * @module 
+ * @mergeModuleWith <project>
+ */
+
 export * from "./client.js"
 export * from "./server.js"
 export type { ProceduresMap, CancelablePromise } from "./types.js"

package/src/log.ts

@@ -1,30 +1,86 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
+/**
+ * @ignore
+ */
+export function createLogger(side: "server" | "client", level: LogLevel): Logger
 export function createLogger(
   side: "server" | "client",
-  level: LogLevel = "debug"
+  level: LogLevel,
+  rqid: string
+): RequestBoundLogger
+export function createLogger(
+  side: "server" | "client",
+  level: LogLevel = "debug",
+  rqid?: string
 ) {
-  const enabledLevels = LOG_LEVELS.slice(LOG_LEVELS.indexOf(level))
+  const lvls = LOG_LEVELS.slice(LOG_LEVELS.indexOf(level))
+
+  if (rqid) {
+    return {
+      debug: lvls.includes("debug") ? logger("debug", side, rqid) : () => {},
+      info: lvls.includes("info") ? logger("info", side, rqid) : () => {},
+      warn: lvls.includes("warn") ? logger("warn", side, rqid) : () => {},
+      error: lvls.includes("error") ? logger("error", side, rqid) : () => {},
+    } as RequestBoundLogger
+  }
 
   return {
-    debug: enabledLevels.includes("debug") ? logger("debug", side) : () => {},
-    info: enabledLevels.includes("info") ? logger("info", side) : () => {},
-    warn: enabledLevels.includes("warn") ? logger("warn", side) : () => {},
-    error: enabledLevels.includes("error") ? logger("error", side) : () => {},
+    debug: lvls.includes("debug") ? logger("debug", side) : () => {},
+    info: lvls.includes("info") ? logger("info", side) : () => {},
+    warn: lvls.includes("warn") ? logger("warn", side) : () => {},
+    error: lvls.includes("error") ? logger("error", side) : () => {},
   }
 }
 
-export type Logger = ReturnType<typeof createLogger>
+/**
+ * @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 */
+export const LOG_LEVELS = ["debug", "info", "warn", "error"] as const
 
-const LOG_LEVELS = ["debug", "info", "warn", "error"] as const
 export type LogLevel = (typeof LOG_LEVELS)[number]
 
 /**
- * Creates partially-applied logging functions given the first 2 args
+ * Creates partially-applied logging functions given the first 2 or 3 args
  * @param severity
  * @param side
+ * @param rqid request ID, or null to not bind it
  * @returns
  */
-function logger(severity: LogLevel, side: "server" | "client") {
-  return (rqid: string | null, message: string, ...args: any[]) =>
+function logger(
+  severity: LogLevel,
+  side: "server" | "client",
+  rqid: string
+): (message: string, ...args: any[]) => void
+function logger(
+  severity: LogLevel,
+  side: "server" | "client"
+): (rqid: string | null, message: string, ...args: any[]) => void
+function logger(severity: LogLevel, side: "server" | "client", rqid?: string) {
+  if (rqid === undefined) {
+    return (rqid: string | null, message: string, ...args: any[]) =>
+      log(severity, side, rqid, message, ...args)
+  }
+
+  return (message: string, ...args: any[]) =>
     log(severity, side, rqid, message, ...args)
 }
 
@@ -36,7 +92,7 @@ function logger(severity: LogLevel, side: "server" | "client") {
  * @param message
  * @param args passed to console methods directly
  */
-export function log(
+function log(
   severity: "debug" | "info" | "warn" | "error",
   side: "server" | "client",
   rqid: string | null,

package/src/server.ts

@@ -1,3 +1,8 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
 import { type } from "arktype"
 import { createLogger, type LogLevel } from "./log.js"
 import {
@@ -6,24 +11,43 @@ import {
   PayloadCore,
   PayloadHeaderSchema,
   PayloadSchema,
+  ProcedureImplementation,
   zImplementations,
   zProcedures,
   type ProceduresMap,
-  type SwarpcServer,
 } from "./types.js"
 import { findTransferables } from "./utils.js"
 
-export type { SwarpcServer } from "./types.js"
+/**
+ * The sw&rpc server instance, which provides methods to register {@link ProcedureImplementation | procedure implementations},
+ * and listens for incoming messages that call those procedures
+ */
+export type SwarpcServer<Procedures extends ProceduresMap> = {
+  [zProcedures]: Procedures
+  [zImplementations]: ImplementationsMap<Procedures>
+  start(self: Window | Worker): void
+} & {
+  [F in keyof Procedures]: (
+    impl: ProcedureImplementation<
+      Procedures[F]["input"],
+      Procedures[F]["progress"],
+      Procedures[F]["success"]
+    >
+  ) => void
+}
 
 const abortControllers = new Map<string, AbortController>()
 const abortedRequests = new Set<string>()
 
 /**
  * Creates a sw&rpc server instance.
- * @param procedures procedures the server will implement
+ * @param procedures procedures the server will implement, see {@link ProceduresMap}
  * @param options various options
  * @param options.worker if provided, the server will use this worker to post messages, instead of sending it to all clients
- * @returns a SwarpcServer instance. Each property of the procedures map will be a method, that accepts a function implementing the procedure. There is also .start(), to be called after implementing all procedures.
+ * @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:
+ * {@includeCode ../example/src/service-worker.ts}
  */
 export function Server<Procedures extends ProceduresMap>(
   procedures: Procedures,
@@ -46,22 +70,16 @@ export function Server<Procedures extends ProceduresMap>(
       if (!instance[zProcedures][functionName]) {
         throw new Error(`No procedure found for function name: ${functionName}`)
       }
-      instance[zImplementations][functionName] = (
-        input,
-        onProgress,
-        abortSignal
-      ) => {
-        abortSignal?.throwIfAborted()
+      instance[zImplementations][functionName] = (input, onProgress, tools) => {
+        tools.abortSignal?.throwIfAborted()
         return new Promise((resolve, reject) => {
-          abortSignal?.addEventListener("abort", () => {
-            let { requestId, reason } = abortSignal?.reason
+          tools.abortSignal?.addEventListener("abort", () => {
+            let { requestId, reason } = tools.abortSignal?.reason
             l.debug(requestId, `Aborted ${functionName} request: ${reason}`)
             reject({ aborted: reason })
           })
 
-          implementation(input, onProgress, abortSignal)
-            .then(resolve)
-            .catch(reject)
+          implementation(input, onProgress, tools).then(resolve).catch(reject)
         })
       }
     }) as SwarpcServer<Procedures>[typeof functionName]
@@ -152,40 +170,42 @@ export function Server<Procedures extends ProceduresMap>(
         return
       }
 
-      // Call the implementation with the input and a progress callback
-      await implementation(
-        payload.input,
-        async (progress: any) => {
-          l.debug(requestId, `Progress for ${functionName}`, progress)
-          await postMsg({ progress })
-        },
-        abortControllers.get(requestId)?.signal
-      )
-        // Send errors
-        .catch(async (error: any) => {
-          // Handle errors caused by abortions
-          if ("aborted" in error) {
-            l.debug(
-              requestId,
-              `Received abort error for ${functionName}`,
-              error.aborted
-            )
-            abortedRequests.add(requestId)
-            abortControllers.delete(requestId)
-            return
+      try {
+        // Call the implementation with the input and a progress callback
+        const result = await implementation(
+          payload.input,
+          async (progress: any) => {
+            l.debug(requestId, `Progress for ${functionName}`, progress)
+            await postMsg({ progress })
+          },
+          {
+            abortSignal: abortControllers.get(requestId)?.signal,
+            logger: createLogger("server", loglevel, requestId),
           }
+        )
 
-          l.error(requestId, `Error in ${functionName}`, error)
-          await postError(error)
-        })
         // Send results
-        .then(async (result: any) => {
-          l.debug(requestId, `Result for ${functionName}`, result)
-          await postMsg({ result })
-        })
-        .finally(() => {
-          abortedRequests.delete(requestId)
-        })
+        l.debug(requestId, `Result for ${functionName}`, result)
+        await postMsg({ result })
+      } catch (error: any) {
+        // Send errors
+        // Handle errors caused by abortions
+        if ("aborted" in error) {
+          l.debug(
+            requestId,
+            `Received abort error for ${functionName}`,
+            error.aborted
+          )
+          abortedRequests.add(requestId)
+          abortControllers.delete(requestId)
+          return
+        }
+
+        l.info(requestId, `Error in ${functionName}`, error)
+        await postError(error)
+      } finally {
+        abortedRequests.delete(requestId)
+      }
     })
   }
 

package/src/types.ts

@@ -1,4 +1,10 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+
 import { type, type Type } from "arktype"
+import { Logger, RequestBoundLogger } from "./log.js"
 
 /**
  * A procedure declaration
@@ -39,7 +45,7 @@ export type Procedure<I extends Type, P extends Type, S extends Type> = {
  * const result = await request
  * ```
  */
-export type CancelablePromise<T> = {
+export type CancelablePromise<T = unknown> = {
   request: Promise<T>
   /**
    * Abort the request.
@@ -56,13 +62,34 @@ export type ProcedureImplementation<
   P extends Type,
   S extends Type,
 > = (
+  /**
+   * Input data for the procedure
+   */
   input: I["inferOut"],
+  /**
+   * Callback to call with progress updates.
+   */
   onProgress: (progress: P["inferIn"]) => void,
-  abortSignal?: AbortSignal
+  /**
+   * Additional tools useful when implementing the procedure.
+   */
+  tools: {
+    /**
+     * AbortSignal that can be used to handle request cancellation -- see [Make cancellable requests](https://gwennlbh.github.io/swarpc/docs/#make-cancelable-requests)
+     */
+    abortSignal?: AbortSignal
+    /**
+     * Logger instance to use for logging messages related to this procedure call, using the same format as SWARPC's built-in logging.
+     */
+    logger: RequestBoundLogger
+  }
 ) => Promise<S["inferIn"]>
 
 /**
  * Declarations of procedures by name.
+ * 
+ * An example of declaring procedures:
+ * {@includeCode ../example/src/lib/procedures.ts}
  */
 export type ProceduresMap = Record<string, Procedure<Type, Type, Type>>
 
@@ -104,6 +131,9 @@ export type Hooks<Procedures extends ProceduresMap> = {
   ) => void
 }
 
+/**
+ * @source
+ */
 export const PayloadHeaderSchema = type("<Name extends string>", {
   by: '"sw&rpc"',
   functionName: "Name",
@@ -119,6 +149,9 @@ export type PayloadHeader<
   requestId: string
 }
 
+/**
+ * @source
+ */
 export const PayloadCoreSchema = type("<I, P, S>", {
   "input?": "I",
   "progress?": "P",
@@ -147,6 +180,9 @@ export type PayloadCore<
       error: { message: string }
     }
 
+/**
+ * @source
+ */
 export const PayloadSchema = type
   .scope({ PayloadCoreSchema, PayloadHeaderSchema })
   .type("<Name extends string, I, P, S>", [
@@ -182,38 +218,14 @@ export type ClientMethod<P extends Procedure<Type, Type, Type>> = ((
 
 /**
  * Symbol used as the key for the procedures map on the server instance
+ * @internal
+ * @source
  */
 export const zImplementations = Symbol("SWARPC implementations")
+
 /**
  * Symbol used as the key for the procedures map on instances
+ * @internal
+ * @source
  */
 export const zProcedures = Symbol("SWARPC procedures")
-
-/**
- * The sw&rpc client instance, which provides 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.
- * If you want to be able to cancel the request, you can set the request's ID yourself, and call `.abort(requestId, reason)` on the client instance to cancel it.
- */
-export type SwarpcClient<Procedures extends ProceduresMap> = {
-  [zProcedures]: Procedures
-} & {
-  [F in keyof Procedures]: ClientMethod<Procedures[F]>
-}
-
-/**
- * The sw&rpc server instance, which provides methods to register procedure implementations,
- * and listens for incoming messages that call those procedures
- */
-export type SwarpcServer<Procedures extends ProceduresMap> = {
-  [zProcedures]: Procedures
-  [zImplementations]: ImplementationsMap<Procedures>
-  start(self: Window | Worker): void
-} & {
-  [F in keyof Procedures]: (
-    impl: ProcedureImplementation<
-      Procedures[F]["input"],
-      Procedures[F]["progress"],
-      Procedures[F]["success"]
-    >
-  ) => void
-}