swarpc 0.7.0 → 0.8.0

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { 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, 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, 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, }?: {
+    worker?: Worker;
+    hooks?: Hooks<Procedures>;
+    loglevel?: LogLevel;
+}): SwarpcClient<Procedures>;
+/**
+ * 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;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAA6B,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;;;;;;;;;;GAUG;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;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/{src/client.js → 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,11 +15,14 @@ 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.
+ * @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 = {}, } = {}) {
     const l = createLogger("client", loglevel);
@@ -152,6 +159,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/{src/index.d.ts → 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

@@ -0,0 +1 @@
+{"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/{src/index.js → index.js}

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

package/dist/log.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @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 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];
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

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

@@ -0,0 +1,55 @@
+/**
+ * @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: 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) : () => { },
+    };
+}
+/** @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.
+ * @param severity
+ * @param side
+ * @param rqid request ID
+ * @param message
+ * @param args passed to console methods directly
+ */
+function log(severity, side, rqid, message, ...args) {
+    const prefix = "[" +
+        ["SWARPC", side, rqid ? `%c${rqid}%c` : ""].filter(Boolean).join(" ") +
+        "]";
+    const prefixStyles = rqid ? ["color: cyan;", "color: inherit;"] : [];
+    if (severity === "debug") {
+        console.debug(prefix, ...prefixStyles, message, ...args);
+    }
+    else if (severity === "info") {
+        console.info(prefix, ...prefixStyles, message, ...args);
+    }
+    else if (severity === "warn") {
+        console.warn(prefix, ...prefixStyles, message, ...args);
+    }
+    else if (severity === "error") {
+        console.error(prefix, ...prefixStyles, message, ...args);
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @module
+ * @mergeModuleWith <project>
+ */
+import { type LogLevel } from "./log.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, 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 (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;
+    loglevel?: LogLevel;
+}): SwarpcServer<Procedures>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"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,CA+J1B"}

package/dist/{src/server.js → 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);
                 });
             };
         });
@@ -105,7 +110,10 @@ export function Server(procedures, { worker, loglevel = "debug" } = {}) {
             await implementation(payload.input, async (progress) => {
                 l.debug(requestId, `Progress for ${functionName}`, progress);
                 await postMsg({ progress });
-            }, abortControllers.get(requestId)?.signal)
+            }, {
+                abortSignal: abortControllers.get(requestId)?.signal,
+                logger: createLogger("server", loglevel, requestId),
+            })
                 // Send errors
                 .catch(async (error) => {
                 // Handle errors caused by abortions

package/dist/{src/types.d.ts → 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

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

package/dist/{src/types.js → 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/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAWA,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,GAAG,GAAG,YAAY,EAAE,CAsB5D"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarpc",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Full type-safe RPC library for service worker -- move things off of the UI thread with ease!",
   "keywords": [
     "service-workers",
@@ -31,18 +31,31 @@
     "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",
-    "typedoc": "^0.28.7",
-    "typescript": "^5.8.3",
+    "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"
   }

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,11 +43,14 @@ 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.
+ * @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,
@@ -238,6 +255,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"