@igoforth/ws-rpc 1.0.0

package/dist/interface-C4S-WCqW.d.ts

@@ -0,0 +1,120 @@
+import { m as RpcSchema } from "./schema-CN5HHHku.js";
+
+//#region src/storage/interface.d.ts
+
+/**
+ * A pending RPC call awaiting a response
+ */
+interface PendingCall {
+  /** Unique request ID */
+  id: string;
+  /** Remote method name */
+  method: string;
+  /** Serialized parameters */
+  params: unknown;
+  /** Method name on actor to call with response */
+  callback: string;
+  /** When the call was sent (Unix ms) */
+  sentAt: number;
+  /** When the call should timeout (Unix ms) */
+  timeoutAt: number;
+}
+/**
+ * Storage mode discriminant
+ */
+type StorageMode = "sync" | "async";
+/**
+ * Conditional return type based on storage mode
+ */
+type MaybePromise<T, TMode extends StorageMode> = TMode extends "sync" ? T : Promise<T>;
+/**
+ * Pending call storage interface
+ *
+ * Generic over sync/async mode to preserve type information about
+ * whether operations block or return promises.
+ *
+ * @typeParam TMode - 'sync' for synchronous storage (DO SQL/KV), 'async' for file/external
+ */
+interface PendingCallStorage<TMode extends StorageMode = "async"> {
+  /** Storage mode discriminant for runtime checks */
+  readonly mode: TMode;
+  /**
+   * Save a pending call
+   */
+  save(call: PendingCall): MaybePromise<void, TMode>;
+  /**
+   * Get a pending call by ID
+   */
+  get(id: string): MaybePromise<PendingCall | null, TMode>;
+  /**
+   * Delete a pending call by ID
+   */
+  delete(id: string): MaybePromise<boolean, TMode>;
+  /**
+   * List all calls that have exceeded their timeout
+   */
+  listExpired(before: number): MaybePromise<PendingCall[], TMode>;
+  /**
+   * List all pending calls (for debugging/recovery)
+   */
+  listAll(): MaybePromise<PendingCall[], TMode>;
+  /**
+   * Delete all pending calls (for cleanup)
+   */
+  clear(): MaybePromise<void, TMode>;
+}
+/**
+ * Convenience alias for synchronous storage (DO SQL/KV)
+ */
+type SyncPendingCallStorage = PendingCallStorage<"sync">;
+/**
+ * Convenience alias for asynchronous storage (file, external KV)
+ */
+type AsyncPendingCallStorage = PendingCallStorage<"async">;
+interface IContinuationHandler<TRemoteSchema extends RpcSchema> {
+  /**
+   * Make a hibernation-safe RPC call using continuation-passing style
+   *
+   * Instead of returning a Promise, the result will be passed to the
+   * named callback method on the actor. This survives DO hibernation.
+   *
+   * @param method - Remote method to call
+   * @param params - Parameters for the method
+   * @param callback - Name of method on actor to call with result
+   * @param timeout - Optional timeout override (ms)
+   *
+   * @example
+   * ```ts
+   * // Make the call
+   * peer.callWithCallback('executeOrder', { market, side }, 'onOrderExecuted');
+   *
+   * // Define the callback on your actor
+   * onOrderExecuted(result: OrderResult, context: CallContext) {
+   *   console.log('Order executed:', result);
+   *   console.log('Latency:', context.latencyMs, 'ms');
+   * }
+   * ```
+   */
+  callWithCallback<K extends keyof TRemoteSchema["methods"] & string>(method: K, params: unknown, callback: keyof this & string, timeout?: number): void;
+  /**
+   * Get all pending durable calls (for debugging/monitoring)
+   */
+  getPendingCalls(): PendingCall[];
+  /**
+   * Get expired calls that have exceeded their timeout
+   */
+  getExpiredCalls(): PendingCall[];
+  /**
+   * Clean up expired calls
+   *
+   * Call this periodically (e.g., on alarm) to remove stale calls.
+   * Returns the expired calls for optional error handling.
+   */
+  cleanupExpired(): PendingCall[];
+  /**
+   * Clear all pending durable calls
+   */
+  clearPendingCalls(): void;
+}
+//#endregion
+export { PendingCallStorage as a, PendingCall as i, IContinuationHandler as n, StorageMode as o, MaybePromise as r, SyncPendingCallStorage as s, AsyncPendingCallStorage as t };

package/dist/json-54Z2bIIs.d.ts

@@ -0,0 +1,22 @@
+import { n as CodecFactory } from "./factory-C1v0AEHY.js";
+import * as z from "zod";
+
+//#region src/codecs/json.d.ts
+
+/**
+ * Factory for creating JSON codecs with Zod schema validation
+ *
+ * @param schema - Zod schema for validation
+ * @param options - Optional codec configuration
+ * @returns A codec that encodes to JSON string and validates on decode
+ */
+declare const createJsonCodec: CodecFactory<string>;
+/**
+ * Default JSON codec for unknown values
+ *
+ * Use when you need to serialize arbitrary data without schema validation.
+ * The decoded value will be `unknown` and should be validated separately.
+ */
+declare const JsonCodec: z.ZodCodec<z.ZodString, z.ZodUnknown>;
+//#endregion
+export { createJsonCodec as n, JsonCodec as t };

package/dist/json-Bshec-bZ.js

@@ -0,0 +1,41 @@
+import { n as createStringCodecFactory } from "./factory-3ziwTuZe.js";
+import * as z from "zod";
+
+//#region src/codecs/json.ts
+/**
+* JSON Codec
+*
+* String-based codec using native JSON serialization.
+* Suitable for simple data types (no Date, Map, Set, BigInt support).
+*
+* @example
+* ```ts
+* import { createJsonCodec } from "@igoforth/ws-rpc/codecs";
+*
+* const UserCodec = createJsonCodec(z.object({
+*   id: z.string(),
+*   name: z.string(),
+* }));
+*
+* const encoded = UserCodec.encode({ id: "1", name: "John" });
+* const decoded = UserCodec.decode(encoded);
+* ```
+*/
+/**
+* Factory for creating JSON codecs with Zod schema validation
+*
+* @param schema - Zod schema for validation
+* @param options - Optional codec configuration
+* @returns A codec that encodes to JSON string and validates on decode
+*/
+const createJsonCodec = createStringCodecFactory(JSON.stringify, JSON.parse, "json_string");
+/**
+* Default JSON codec for unknown values
+*
+* Use when you need to serialize arbitrary data without schema validation.
+* The decoded value will be `unknown` and should be validated separately.
+*/
+const JsonCodec = createJsonCodec(z.unknown());
+
+//#endregion
+export { createJsonCodec as n, JsonCodec as t };

package/dist/memory-Bqb3KEVr.js

@@ -0,0 +1,48 @@
+//#region src/storage/memory.ts
+/**
+* In-memory pending call storage for testing
+*
+* Optionally round-trips params through a codec for consistency testing.
+*/
+var MemoryPendingCallStorage = class {
+	mode = "sync";
+	calls = /* @__PURE__ */ new Map();
+	paramsCodec;
+	constructor(options) {
+		this.paramsCodec = options?.paramsCodec ?? null;
+	}
+	save(call) {
+		const params = this.paramsCodec ? this.paramsCodec.decode(this.paramsCodec.encode(call.params)) : call.params;
+		this.calls.set(call.id, {
+			...call,
+			params
+		});
+	}
+	get(id) {
+		const call = this.calls.get(id);
+		return call ? { ...call } : null;
+	}
+	delete(id) {
+		return this.calls.delete(id);
+	}
+	listExpired(before) {
+		const expired = [];
+		for (const call of this.calls.values()) if (call.timeoutAt <= before) expired.push({ ...call });
+		return expired.sort((a, b) => a.timeoutAt - b.timeoutAt);
+	}
+	listAll() {
+		return [...this.calls.values()].map((c) => ({ ...c })).sort((a, b) => a.sentAt - b.sentAt);
+	}
+	clear() {
+		this.calls.clear();
+	}
+	/**
+	* Get the number of stored calls (for testing)
+	*/
+	get size() {
+		return this.calls.size;
+	}
+};
+
+//#endregion
+export { MemoryPendingCallStorage as t };

package/dist/memory-D1nGjzzH.d.ts

@@ -0,0 +1,41 @@
+import { i as StringCodec } from "./factory-C1v0AEHY.js";
+import { i as PendingCall, s as SyncPendingCallStorage } from "./interface-C4S-WCqW.js";
+
+//#region src/storage/memory.d.ts
+
+/**
+ * Options for memory pending call storage
+ */
+interface MemoryPendingCallStorageOptions {
+  /**
+   * Codec for serializing/deserializing params
+   *
+   * While memory storage doesn't strictly need serialization,
+   * using a codec ensures consistency with SQL storage and
+   * validates that params can be round-tripped.
+   */
+  paramsCodec?: StringCodec;
+}
+/**
+ * In-memory pending call storage for testing
+ *
+ * Optionally round-trips params through a codec for consistency testing.
+ */
+declare class MemoryPendingCallStorage implements SyncPendingCallStorage {
+  readonly mode: "sync";
+  private readonly calls;
+  private readonly paramsCodec;
+  constructor(options?: MemoryPendingCallStorageOptions);
+  save(call: PendingCall): void;
+  get(id: string): PendingCall | null;
+  delete(id: string): boolean;
+  listExpired(before: number): PendingCall[];
+  listAll(): PendingCall[];
+  clear(): void;
+  /**
+   * Get the number of stored calls (for testing)
+   */
+  get size(): number;
+}
+//#endregion
+export { MemoryPendingCallStorageOptions as n, MemoryPendingCallStorage as t };

package/dist/multi-peer-BAi9yVzp.js

@@ -0,0 +1,242 @@
+import { t as RpcPeer } from "./default-BkrMd28n.js";
+
+//#region src/adapters/multi-peer.ts
+/**
+* Multi-Peer Base Class
+*
+* Abstract base class for adapters managing multiple RPC peers.
+* Extended by RpcServer and Cloudflare DO adapter.
+*/
+/**
+* Abstract base class for multi-peer adapters
+*
+* Provides shared functionality for managing multiple RPC peers:
+* - Driver for calling methods on multiple peers
+* - Broadcast emit to all peers
+* - Peer lookup by ID
+* - Connection count/IDs
+*
+* @typeParam TLocalSchema - Schema for methods/events this side provides
+* @typeParam TRemoteSchema - Schema for methods/events the remote side provides
+* @typeParam TConnection - Connection type (IWebSocket, WebSocket, etc.)
+*/
+var MultiPeerBase = class {
+	peers = /* @__PURE__ */ new Map();
+	/** Local schema */
+	localSchema;
+	/** Remote schema */
+	remoteSchema;
+	/** Implementation of local methods */
+	provider;
+	/** Default timeout for RPC calls */
+	timeout;
+	/** Lifecycle hooks */
+	hooks;
+	constructor(options) {
+		this.localSchema = options.localSchema;
+		this.remoteSchema = options.remoteSchema;
+		this.provider = options.provider;
+		this.timeout = options.timeout ?? 3e4;
+		this.hooks = options.hooks ?? {};
+	}
+	/**
+	* Create an RPC peer for a WebSocket connection.
+	* Subclasses can override to customize peer creation.
+	*/
+	createPeer(ws) {
+		return new RpcPeer({
+			ws,
+			localSchema: this.localSchema,
+			remoteSchema: this.remoteSchema,
+			provider: this.provider,
+			onEvent: this.hooks.onEvent ? (event, data) => {
+				const peer = this.findPeerByWs(ws);
+				if (peer) this.hooks.onEvent(peer, event, data);
+			} : void 0,
+			timeout: this.timeout
+		});
+	}
+	/**
+	* Find peer by WebSocket (internal helper for event routing)
+	*/
+	findPeerByWs(ws) {
+		for (const peer of this.peers.values()) if (peer.getWebSocket() === ws) return peer;
+		return null;
+	}
+	/**
+	* Add a peer (called by subclass when connection established)
+	*/
+	addPeer(connection, peer) {
+		this.peers.set(connection, peer);
+		this.hooks.onConnect?.(peer);
+	}
+	/**
+	* Remove a peer (called by subclass when connection closes)
+	*/
+	removePeer(connection) {
+		const peer = this.peers.get(connection);
+		if (peer) {
+			peer.close();
+			this.peers.delete(connection);
+			this.hooks.onDisconnect?.(peer);
+			return peer;
+		}
+		return null;
+	}
+	/**
+	* Get peer by connection object
+	*/
+	getPeerFor(connection) {
+		return this.peers.get(connection) ?? null;
+	}
+	/**
+	* Get peer by ID
+	*/
+	getPeer(id) {
+		for (const peer of this.peers.values()) if (peer.id === id) return peer;
+		return null;
+	}
+	/**
+	* Find peer entry by ID (internal - includes connection)
+	*/
+	findPeerEntry(id) {
+		for (const [connection, peer] of this.peers) if (peer.id === id) return {
+			peer,
+			connection
+		};
+		return null;
+	}
+	/**
+	* Get all peers
+	*/
+	getPeers() {
+		return this.peers.values();
+	}
+	/**
+	* Get all open peer entries (internal)
+	*/
+	getOpenEntries() {
+		const result = [];
+		for (const [connection, peer] of this.peers) if (peer.isOpen) result.push({
+			peer,
+			connection
+		});
+		return result;
+	}
+	/**
+	* Get count of open connections
+	*/
+	getConnectionCount() {
+		let count = 0;
+		for (const peer of this.peers.values()) if (peer.isOpen) count++;
+		return count;
+	}
+	/**
+	* Get all open peer IDs
+	*/
+	getConnectionIds() {
+		const ids = [];
+		for (const peer of this.peers.values()) if (peer.isOpen) ids.push(peer.id);
+		return ids;
+	}
+	/**
+	* Driver for calling remote methods on connected peers
+	*
+	* @returns MultiDriver proxy for calling methods on all or specific peers
+	*/
+	get driver() {
+		return this.createMultiDriver();
+	}
+	/**
+	* Emit an event to connected peers
+	*
+	* @param event - Event name from local schema
+	* @param data - Event data matching the schema
+	* @param ids - Optional array of peer IDs to emit to (broadcasts to all if omitted)
+	*/
+	emit(event, data, ids) {
+		const validPeers = ids ? this.peers.values().filter((p) => ids.includes(p.id) && p.isOpen) : this.peers.values().filter((p) => p.isOpen);
+		for (const peer of validPeers) peer.emit(event, data);
+	}
+	/**
+	* Close a specific peer by ID
+	*
+	* @param id - Peer ID to close
+	* @returns true if peer was found and closed, false otherwise
+	*/
+	closePeer(id) {
+		const entry = this.findPeerEntry(id);
+		if (entry) {
+			entry.peer.close();
+			this.peers.delete(entry.connection);
+			this.hooks.onDisconnect?.(entry.peer);
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Close all peers
+	*/
+	closeAll() {
+		for (const peer of this.peers.values()) {
+			peer.close();
+			this.hooks.onDisconnect?.(peer);
+		}
+		this.peers.clear();
+		this.hooks.onClose?.();
+	}
+	/**
+	* Create a driver proxy for calling remote methods on multiple peers
+	*/
+	createMultiDriver() {
+		const methods = this.remoteSchema.methods ?? {};
+		const driver = {};
+		for (const methodName of Object.keys(methods)) driver[methodName] = async (input, options) => {
+			return this.callMethod(methodName, input, options);
+		};
+		return driver;
+	}
+	/**
+	* Call a method on multiple peers with timeout handling
+	*
+	* @param method - Method name to call
+	* @param input - Method input parameters
+	* @param options - Call options including target peer IDs and timeout
+	* @returns Array of results from each peer (success or error)
+	*/
+	async callMethod(method, input, options) {
+		const ids = options?.ids;
+		const timeout = options?.timeout ?? this.timeout;
+		let targetPeers;
+		if (ids === void 0) targetPeers = Array.from(this.peers.values()).filter((p) => p.isOpen);
+		else if (typeof ids === "string") {
+			const peer = this.getPeer(ids);
+			targetPeers = peer?.isOpen ? [peer] : [];
+		} else targetPeers = ids.map((id) => this.getPeer(id)).filter((p) => p?.isOpen === true);
+		const promises = targetPeers.map(async (peer) => {
+			try {
+				const callPromise = peer.driver[method](input);
+				const value = await Promise.race([callPromise, new Promise((_, reject) => setTimeout(() => reject(/* @__PURE__ */ new Error(`Timeout after ${timeout}ms`)), timeout))]);
+				return {
+					id: peer.id,
+					result: {
+						success: true,
+						value
+					}
+				};
+			} catch (error) {
+				return {
+					id: peer.id,
+					result: {
+						success: false,
+						error: error instanceof Error ? error : new Error(String(error))
+					}
+				};
+			}
+		});
+		return Promise.all(promises);
+	}
+};
+
+//#endregion
+export { MultiPeerBase as t };

package/dist/peers/default.d.ts

@@ -0,0 +1,8 @@
+import "../schema-CN5HHHku.js";
+import "../factory-C1v0AEHY.js";
+import "../json-54Z2bIIs.js";
+import "../index-Be7jjS77.js";
+import "../protocol-DA84zrc2.js";
+import "../types-Be-qmQu0.js";
+import { n as RpcPeerOptions, t as RpcPeer } from "../default-xDNNMrg0.js";
+export { RpcPeer, RpcPeerOptions };

package/dist/peers/default.js

@@ -0,0 +1,8 @@
+import "../factory-3ziwTuZe.js";
+import "../json-Bshec-bZ.js";
+import "../codecs-BmYG2d_U.js";
+import "../protocol-_mpoOPp6.js";
+import "../errors-5BfreE63.js";
+import { t as RpcPeer } from "../default-BkrMd28n.js";
+
+export { RpcPeer };

package/dist/peers/durable.d.ts

@@ -0,0 +1,136 @@
+import { m as RpcSchema } from "../schema-CN5HHHku.js";
+import "../factory-C1v0AEHY.js";
+import "../json-54Z2bIIs.js";
+import "../index-Be7jjS77.js";
+import { g as WireInput } from "../protocol-DA84zrc2.js";
+import "../types-Be-qmQu0.js";
+import { n as RpcPeerOptions, t as RpcPeer } from "../default-xDNNMrg0.js";
+import { i as PendingCall, s as SyncPendingCallStorage } from "../interface-C4S-WCqW.js";
+
+//#region src/peers/durable.d.ts
+
+/**
+ * Options for creating a DurableRpcPeer
+ */
+interface DurableRpcPeerOptions<TActor> {
+  /** Synchronous storage for persisting pending calls */
+  storage: SyncPendingCallStorage;
+  /** The actor instance (for resolving callback methods) */
+  actor: TActor;
+  /** Default timeout for continuation-based calls (ms) */
+  durableTimeout?: number;
+}
+/**
+ * Context passed to callback methods along with the result
+ */
+interface CallContext {
+  /** The original pending call */
+  call: PendingCall;
+  /** Time from send to response (ms) */
+  latencyMs: number;
+}
+/**
+ * Durable RPC Peer
+ *
+ * Extends RpcPeer to add:
+ * - Hibernation-safe continuation-based calls via `callWithCallback`
+ * - Automatic recovery of pending calls after hibernation
+ * - Timeout cleanup for stale calls
+ */
+declare class DurableRpcPeer<TLocalSchema extends RpcSchema, TRemoteSchema extends RpcSchema, TActor> extends RpcPeer<TLocalSchema, TRemoteSchema> {
+  private readonly storage;
+  private readonly actor;
+  private readonly durableTimeout;
+  private durableRequestCounter;
+  /**
+   * Create a durable RPC peer
+   *
+   * @param options - Combined RPC peer and durable options
+   */
+  constructor(options: RpcPeerOptions<TLocalSchema, TRemoteSchema> & DurableRpcPeerOptions<TActor>);
+  /**
+   * Make a hibernation-safe RPC call using continuation-passing style
+   *
+   * Instead of returning a Promise, the result will be passed to the
+   * named callback method on the actor. This survives DO hibernation.
+   *
+   * @param method - Remote method to call
+   * @param params - Parameters for the method
+   * @param callback - Name of method on actor to call with result
+   * @param timeout - Optional timeout override (ms)
+   *
+   * @example
+   * ```ts
+   * // Make the call
+   * peer.callWithCallback('executeOrder', { market, side }, 'onOrderExecuted');
+   *
+   * // Define the callback on your actor
+   * onOrderExecuted(result: OrderResult, context: CallContext) {
+   *   console.log('Order executed:', result);
+   *   console.log('Latency:', context.latencyMs, 'ms');
+   * }
+   * ```
+   */
+  callWithCallback<K extends keyof TRemoteSchema["methods"] & string>(method: K, params: unknown, callback: keyof TActor & string, timeout?: number): void;
+  /**
+   * Handle an incoming WebSocket message
+   *
+   * Checks durable storage for continuation-based calls before
+   * delegating to the base class for promise-based calls.
+   *
+   * @param data - Raw WebSocket message data
+   */
+  handleMessage(data: WireInput): void;
+  /**
+   * Get all pending durable calls (for debugging/monitoring)
+   *
+   * @returns Array of all pending calls
+   */
+  getPendingCalls(): PendingCall[];
+  /**
+   * Get expired calls that have exceeded their timeout
+   *
+   * @returns Array of calls that have exceeded their timeout
+   */
+  getExpiredCalls(): PendingCall[];
+  /**
+   * Clean up expired calls
+   *
+   * Call this periodically (e.g., on alarm) to remove stale calls.
+   *
+   * @returns The expired calls that were removed (for optional error handling)
+   */
+  cleanupExpired(): PendingCall[];
+  /**
+   * Clear all pending durable calls
+   */
+  clearPendingCalls(): void;
+}
+/**
+ * Create a factory function for DurableRpcPeer instances
+ *
+ * Pre-configures the durable storage and actor, returning a function
+ * that only needs RPC options to create a new peer.
+ *
+ * @param durableOptions - Durable configuration (storage, actor, timeout)
+ * @returns Factory function that creates DurableRpcPeer instances
+ *
+ * @example
+ * ```ts
+ * const createPeer = createDurableRpcPeerFactory({
+ *   storage: new SqlPendingCallStorage(sql),
+ *   actor: this,
+ * });
+ *
+ * // Later, create peers for each connection
+ * const peer = createPeer({
+ *   ws,
+ *   localSchema,
+ *   remoteSchema,
+ *   provider,
+ * });
+ * ```
+ */
+declare const createDurableRpcPeerFactory: <TActor>(durableOptions: DurableRpcPeerOptions<TActor>) => <TLocalSchema extends RpcSchema, TRemoteSchema extends RpcSchema>(rpcOptions: RpcPeerOptions<TLocalSchema, TRemoteSchema>) => DurableRpcPeer<TLocalSchema, TRemoteSchema, TActor>;
+//#endregion
+export { CallContext, DurableRpcPeer, DurableRpcPeerOptions, createDurableRpcPeerFactory };

package/dist/peers/durable.js

@@ -0,0 +1,9 @@
+import "../factory-3ziwTuZe.js";
+import "../json-Bshec-bZ.js";
+import "../codecs-BmYG2d_U.js";
+import "../protocol-_mpoOPp6.js";
+import "../errors-5BfreE63.js";
+import "../default-BkrMd28n.js";
+import { n as createDurableRpcPeerFactory, t as DurableRpcPeer } from "../durable-MZjkvyS6.js";
+
+export { DurableRpcPeer, createDurableRpcPeerFactory };

package/dist/peers/index.d.ts

@@ -0,0 +1,10 @@
+import "../schema-CN5HHHku.js";
+import "../factory-C1v0AEHY.js";
+import "../json-54Z2bIIs.js";
+import "../index-Be7jjS77.js";
+import "../protocol-DA84zrc2.js";
+import "../types-Be-qmQu0.js";
+import { n as RpcPeerOptions, t as RpcPeer } from "../default-xDNNMrg0.js";
+import "../interface-C4S-WCqW.js";
+import { CallContext, DurableRpcPeer, DurableRpcPeerOptions } from "./durable.js";
+export { type CallContext, DurableRpcPeer, type DurableRpcPeerOptions, RpcPeer, type RpcPeerOptions };