@igoforth/ws-rpc 1.0.0

package/dist/durable-MZjkvyS6.js

@@ -0,0 +1,165 @@
+import { t as RpcPeer } from "./default-BkrMd28n.js";
+
+//#region src/peers/durable.ts
+/**
+* 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
+*/
+var DurableRpcPeer = class extends RpcPeer {
+	storage;
+	actor;
+	durableTimeout;
+	durableRequestCounter = 0;
+	/**
+	* Create a durable RPC peer
+	*
+	* @param options - Combined RPC peer and durable options
+	*/
+	constructor(options) {
+		super(options);
+		this.storage = options.storage;
+		this.actor = options.actor;
+		this.durableTimeout = options.durableTimeout ?? options.timeout ?? 3e4;
+	}
+	/**
+	* 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(method, params, callback, timeout) {
+		if (typeof this.actor[callback] !== "function") throw new Error(`Callback '${callback}' is not a function on the actor`);
+		const now = Date.now();
+		const timeoutMs = timeout ?? this.durableTimeout;
+		const call = {
+			id: `durable-${++this.durableRequestCounter}`,
+			method,
+			params,
+			callback,
+			sentAt: now,
+			timeoutAt: now + timeoutMs
+		};
+		this.storage.save(call);
+		const ws = this.getWebSocket();
+		if (ws.readyState === 1) ws.send(this.protocol.createRequest(call.id, method, params));
+		else console.warn(`Cannot send durable call '${method}': connection not open`);
+	}
+	/**
+	* 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) {
+		const message = this.protocol.safeDecodeMessage(data);
+		if (!message) {
+			super.handleMessage(data);
+			return;
+		}
+		if (message.type === "rpc:response" || message.type === "rpc:error") {
+			const id = message.id;
+			const call = this.storage.get(id);
+			if (call) {
+				this.storage.delete(id);
+				const context = {
+					call,
+					latencyMs: Date.now() - call.sentAt
+				};
+				const callbackFn = this.actor[call.callback];
+				if (typeof callbackFn === "function") if (message.type === "rpc:response") callbackFn.call(this.actor, message.result, context);
+				else callbackFn.call(this.actor, new Error(message.message), context);
+				return;
+			}
+		}
+		super.handleMessage(data);
+	}
+	/**
+	* Get all pending durable calls (for debugging/monitoring)
+	*
+	* @returns Array of all pending calls
+	*/
+	getPendingCalls() {
+		return this.storage.listAll();
+	}
+	/**
+	* Get expired calls that have exceeded their timeout
+	*
+	* @returns Array of calls that have exceeded their timeout
+	*/
+	getExpiredCalls() {
+		return this.storage.listExpired(Date.now());
+	}
+	/**
+	* 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() {
+		const expired = this.getExpiredCalls();
+		for (const call of expired) this.storage.delete(call.id);
+		return expired;
+	}
+	/**
+	* Clear all pending durable calls
+	*/
+	clearPendingCalls() {
+		this.storage.clear();
+	}
+};
+/**
+* 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,
+* });
+* ```
+*/
+const createDurableRpcPeerFactory = (durableOptions) => (rpcOptions) => new DurableRpcPeer({
+	...durableOptions,
+	...rpcOptions
+});
+
+//#endregion
+export { createDurableRpcPeerFactory as n, DurableRpcPeer as t };

package/dist/errors-5BfreE63.js

@@ -0,0 +1,96 @@
+import { n as RpcErrorCodes } from "./protocol-_mpoOPp6.js";
+
+//#region src/errors.ts
+/**
+* RPC Error Classes
+*
+* Custom error types for RPC operations.
+*/
+/**
+* Base class for all RPC errors
+*
+* @param code - RPC error code (from RpcErrorCodes)
+* @param message - Human-readable error message
+* @param data - Optional additional error data
+*/
+var RpcError = class extends Error {
+	code;
+	data;
+	constructor(code, message, data) {
+		super(message);
+		this.name = "RpcError";
+		this.code = code;
+		this.data = data;
+	}
+};
+/**
+* Thrown when an RPC request times out waiting for a response
+*
+* @param method - Name of the method that timed out
+* @param timeoutMs - Timeout duration in milliseconds
+*/
+var RpcTimeoutError = class extends RpcError {
+	method;
+	timeoutMs;
+	constructor(method, timeoutMs) {
+		super(RpcErrorCodes.TIMEOUT, `RPC request '${method}' timed out after ${timeoutMs}ms`);
+		this.name = "RpcTimeoutError";
+		this.method = method;
+		this.timeoutMs = timeoutMs;
+	}
+};
+/**
+* Thrown when the remote handler returns an error
+*
+* @param method - Name of the remote method that failed
+* @param code - RPC error code from the remote
+* @param message - Error message from the remote
+* @param data - Optional additional error data from the remote
+*/
+var RpcRemoteError = class extends RpcError {
+	method;
+	constructor(method, code, message, data) {
+		super(code, message, data);
+		this.name = "RpcRemoteError";
+		this.method = method;
+	}
+};
+/**
+* Thrown when the WebSocket connection closes while a request is pending
+*
+* @param message - Optional custom message (defaults to "WebSocket connection closed")
+*/
+var RpcConnectionClosed = class extends RpcError {
+	constructor(message = "WebSocket connection closed") {
+		super(RpcErrorCodes.CONNECTION_CLOSED, message);
+		this.name = "RpcConnectionClosed";
+	}
+};
+/**
+* Thrown when input or output validation fails
+*
+* @param message - Description of the validation failure
+* @param data - Optional Zod error or validation details
+*/
+var RpcValidationError = class extends RpcError {
+	constructor(message, data) {
+		super(RpcErrorCodes.VALIDATION_ERROR, message, data);
+		this.name = "RpcValidationError";
+	}
+};
+/**
+* Thrown when a requested method doesn't exist on the provider
+*
+* @param method - Name of the method that was not found
+*/
+var RpcMethodNotFoundError = class extends RpcError {
+	method;
+	constructor(method) {
+		super(RpcErrorCodes.METHOD_NOT_FOUND, `Method '${method}' not found`);
+		this.name = "RpcMethodNotFoundError";
+		this.method = method;
+	}
+};
+
+//#endregion
+export { RpcTimeoutError as a, RpcRemoteError as i, RpcError as n, RpcValidationError as o, RpcMethodNotFoundError as r, RpcConnectionClosed as t };

package/dist/errors.d.ts

@@ -0,0 +1,69 @@
+//#region src/errors.d.ts
+/**
+ * RPC Error Classes
+ *
+ * Custom error types for RPC operations.
+ */
+/**
+ * Base class for all RPC errors
+ *
+ * @param code - RPC error code (from RpcErrorCodes)
+ * @param message - Human-readable error message
+ * @param data - Optional additional error data
+ */
+declare class RpcError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+  constructor(code: number, message: string, data?: unknown);
+}
+/**
+ * Thrown when an RPC request times out waiting for a response
+ *
+ * @param method - Name of the method that timed out
+ * @param timeoutMs - Timeout duration in milliseconds
+ */
+declare class RpcTimeoutError extends RpcError {
+  readonly method: string;
+  readonly timeoutMs: number;
+  constructor(method: string, timeoutMs: number);
+}
+/**
+ * Thrown when the remote handler returns an error
+ *
+ * @param method - Name of the remote method that failed
+ * @param code - RPC error code from the remote
+ * @param message - Error message from the remote
+ * @param data - Optional additional error data from the remote
+ */
+declare class RpcRemoteError extends RpcError {
+  readonly method: string;
+  constructor(method: string, code: number, message: string, data?: unknown);
+}
+/**
+ * Thrown when the WebSocket connection closes while a request is pending
+ *
+ * @param message - Optional custom message (defaults to "WebSocket connection closed")
+ */
+declare class RpcConnectionClosed extends RpcError {
+  constructor(message?: string);
+}
+/**
+ * Thrown when input or output validation fails
+ *
+ * @param message - Description of the validation failure
+ * @param data - Optional Zod error or validation details
+ */
+declare class RpcValidationError extends RpcError {
+  constructor(message: string, data?: unknown);
+}
+/**
+ * Thrown when a requested method doesn't exist on the provider
+ *
+ * @param method - Name of the method that was not found
+ */
+declare class RpcMethodNotFoundError extends RpcError {
+  readonly method: string;
+  constructor(method: string);
+}
+//#endregion
+export { RpcConnectionClosed, RpcError, RpcMethodNotFoundError, RpcRemoteError, RpcTimeoutError, RpcValidationError };

package/dist/errors.js

@@ -0,0 +1,7 @@
+import "./factory-3ziwTuZe.js";
+import "./json-Bshec-bZ.js";
+import "./codecs-BmYG2d_U.js";
+import "./protocol-_mpoOPp6.js";
+import { a as RpcTimeoutError, i as RpcRemoteError, n as RpcError, o as RpcValidationError, r as RpcMethodNotFoundError, t as RpcConnectionClosed } from "./errors-5BfreE63.js";
+
+export { RpcConnectionClosed, RpcError, RpcMethodNotFoundError, RpcRemoteError, RpcTimeoutError, RpcValidationError };

package/dist/factory-3ziwTuZe.js

@@ -0,0 +1,132 @@
+import * as z from "zod";
+
+//#region src/codecs/factory.ts
+/**
+* RPC Codecs
+*
+* Zod-based codecs for serialization with built-in validation.
+* Provides factories for creating codecs that encode to string or binary.
+*
+* @example
+* ```ts
+* // JSON codec with validation
+* const MyDataCodec = jsonCodec(MyDataSchema);
+* const encoded = MyDataCodec.encode(data); // string
+* const decoded = MyDataCodec.decode(encoded); // validated MyData
+*
+* // Safe decode with error handling
+* const result = MyDataCodec.safeDecode(encoded);
+* if (result.success) {
+*   console.log(result.data);
+* } else {
+*   console.error(result.error);
+* }
+* ```
+*/
+/**
+* Create a custom string codec factory
+*
+* Use this to integrate custom serialization libraries that encode to strings.
+*
+* @param serialize - Function to serialize a value to string
+* @param deserialize - Function to deserialize a string to a value
+* @param formatName - Name of the format for error messages
+* @returns A codec factory function
+*
+* @example
+* ```ts
+* import superjson from "superjson";
+*
+* const superJsonCodec = createStringCodecFactory(
+*   superjson.stringify,
+*   superjson.parse,
+*   "superjson"
+* );
+*
+* // Now supports Date, Map, Set, BigInt, etc.
+* const DataCodec = superJsonCodec(z.object({
+*   timestamp: z.date(),
+*   values: z.map(z.string(), z.number()),
+* }));
+* ```
+*/
+function createStringCodecFactory(serialize, deserialize, formatName) {
+	return (schema, options) => {
+		return z.codec(z.string(), schema, {
+			decode: (text, ctx) => {
+				try {
+					return deserialize(text);
+				} catch (err) {
+					ctx.issues.push({
+						code: "invalid_format",
+						format: formatName,
+						input: text,
+						message: options?.errorMessage ?? (err instanceof Error ? err.message : `Invalid ${formatName}`)
+					});
+					return z.NEVER;
+				}
+			},
+			encode: (value) => serialize(value)
+		});
+	};
+}
+/**
+* Create a custom binary codec factory
+*
+* Use this to integrate binary serialization libraries like MessagePack or CBOR.
+*
+* @param serialize - Function to serialize a value to Uint8Array
+* @param deserialize - Function to deserialize a Uint8Array to a value
+* @param formatName - Name of the format for error messages
+* @returns A codec factory function
+*
+* @example
+* ```ts
+* import { encode, decode } from "@msgpack/msgpack";
+*
+* const msgpackCodec = createBinaryCodecFactory(
+*   (v) => new Uint8Array(encode(v)),
+*   decode,
+*   "msgpack"
+* );
+*
+* const DataCodec = msgpackCodec(MySchema);
+* const bytes = DataCodec.encode(data); // Uint8Array
+* const data = DataCodec.decode(bytes); // validated
+* ```
+*/
+function createBinaryCodecFactory(serialize, deserialize, formatName) {
+	return (schema, options) => {
+		return z.codec(z.instanceof(Uint8Array), schema, {
+			decode: (bytes, ctx) => {
+				try {
+					return deserialize(bytes);
+				} catch (err) {
+					ctx.issues.push({
+						code: "invalid_format",
+						format: formatName,
+						input: String(bytes),
+						message: options?.errorMessage ?? (err instanceof Error ? err.message : `Invalid ${formatName}`)
+					});
+					return z.NEVER;
+				}
+			},
+			encode: (value) => serialize(value)
+		});
+	};
+}
+/**
+* Helper to check if a codec encodes to string
+*/
+function isStringCodec(codec) {
+	return codec._zod.def.in._zod.def.type === "string";
+}
+/**
+* Helper to check if a codec encodes to binary
+*/
+function isBinaryCodec(codec) {
+	return !isStringCodec(codec);
+}
+
+//#endregion
+export { isStringCodec as i, createStringCodecFactory as n, isBinaryCodec as r, createBinaryCodecFactory as t };

package/dist/factory-C1v0AEHY.d.ts

@@ -0,0 +1,101 @@
+import { d as LiteralStringUnion } from "./schema-CN5HHHku.js";
+import * as z from "zod";
+
+//#region src/codecs/factory.d.ts
+
+/**
+ * Type alias for a Zod codec that encodes to string
+ */
+type StringCodec<T extends z.ZodType = z.ZodType> = z.ZodCodec<z.ZodString, T>;
+/**
+ * Type alias for a Zod codec that encodes to Uint8Array
+ */
+type BinaryCodec<T extends z.ZodType = z.ZodType> = z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>>, T>;
+/**
+ * Options for codec factories
+ */
+interface CodecOptions {
+  /** Custom error message for parse failures */
+  errorMessage?: string;
+}
+/**
+ * Codec factory signature for custom serialization libraries
+ *
+ * Implement this interface to create codecs using libraries like
+ * superjson, devalue, or MessagePack.
+ */
+interface CodecFactory<TEncoded> {
+  <T extends z.ZodType>(schema: T, options?: CodecOptions): z.ZodCodec<string extends TEncoded ? z.ZodString : z.ZodCustom<TEncoded>, T>;
+}
+/**
+ * Create a custom string codec factory
+ *
+ * Use this to integrate custom serialization libraries that encode to strings.
+ *
+ * @param serialize - Function to serialize a value to string
+ * @param deserialize - Function to deserialize a string to a value
+ * @param formatName - Name of the format for error messages
+ * @returns A codec factory function
+ *
+ * @example
+ * ```ts
+ * import superjson from "superjson";
+ *
+ * const superJsonCodec = createStringCodecFactory(
+ *   superjson.stringify,
+ *   superjson.parse,
+ *   "superjson"
+ * );
+ *
+ * // Now supports Date, Map, Set, BigInt, etc.
+ * const DataCodec = superJsonCodec(z.object({
+ *   timestamp: z.date(),
+ *   values: z.map(z.string(), z.number()),
+ * }));
+ * ```
+ */
+declare function createStringCodecFactory(serialize: (value: unknown) => string, deserialize: (text: string) => unknown, formatName: LiteralStringUnion<z.core.$ZodStringFormats>): CodecFactory<string>;
+/**
+ * Create a custom binary codec factory
+ *
+ * Use this to integrate binary serialization libraries like MessagePack or CBOR.
+ *
+ * @param serialize - Function to serialize a value to Uint8Array
+ * @param deserialize - Function to deserialize a Uint8Array to a value
+ * @param formatName - Name of the format for error messages
+ * @returns A codec factory function
+ *
+ * @example
+ * ```ts
+ * import { encode, decode } from "@msgpack/msgpack";
+ *
+ * const msgpackCodec = createBinaryCodecFactory(
+ *   (v) => new Uint8Array(encode(v)),
+ *   decode,
+ *   "msgpack"
+ * );
+ *
+ * const DataCodec = msgpackCodec(MySchema);
+ * const bytes = DataCodec.encode(data); // Uint8Array
+ * const data = DataCodec.decode(bytes); // validated
+ * ```
+ */
+declare function createBinaryCodecFactory(serialize: (value: unknown) => Uint8Array<ArrayBuffer>, deserialize: (bytes: Uint8Array<ArrayBuffer>) => unknown, formatName: string): CodecFactory<Uint8Array<ArrayBuffer>>;
+/**
+ * Wire codec - either string or binary
+ */
+type WireCodec<T extends z.ZodType = z.ZodType> = StringCodec<T> | BinaryCodec<T>;
+/**
+ * Wire data - what gets sent over WebSocket
+ */
+type WireData = string | Uint8Array<ArrayBuffer>;
+/**
+ * Helper to check if a codec encodes to string
+ */
+declare function isStringCodec(codec: z.ZodCodec<z.ZodType, z.ZodType>): codec is StringCodec;
+/**
+ * Helper to check if a codec encodes to binary
+ */
+declare function isBinaryCodec(codec: z.ZodCodec<z.ZodType, z.ZodType>): codec is BinaryCodec;
+//#endregion
+export { WireCodec as a, createStringCodecFactory as c, StringCodec as i, isBinaryCodec as l, CodecFactory as n, WireData as o, CodecOptions as r, createBinaryCodecFactory as s, BinaryCodec as t, isStringCodec as u };

package/dist/index-Be7jjS77.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { _ as method, a as InferEventData, c as InferMethods, f as MethodDef, g as event, i as EventHandler, l as InferOutput, m as RpcSchema, n as EventDef, o as InferEvents, p as Provider, s as InferInput, t as Driver } from "./schema-CN5HHHku.js";
+import "./factory-C1v0AEHY.js";
+import "./json-54Z2bIIs.js";
+import "./index-Be7jjS77.js";
+import { _ as createProtocol, a as RpcEvent, c as RpcMessageCodec, d as RpcRequest, f as RpcRequestSchema, h as RpcWireCodec, i as RpcErrorSchema, l as RpcMessageSchema, m as RpcResponseSchema, n as RpcError$1, o as RpcEventSchema, p as RpcResponse, r as RpcErrorCodes, s as RpcMessage, t as JsonProtocol, u as RpcProtocol } from "./protocol-DA84zrc2.js";
+import { a as IRpcOptions, c as WebSocketOptions, i as IRpcConnection, l as WebSocketReadyState, n as IMethodController, o as IWebSocket, r as IMinWebSocket, s as IWebSocketServer, t as IEventController, u as WebSocketServerOptions } from "./types-Be-qmQu0.js";
+import { n as calculateReconnectDelay, r as defaultReconnectOptions, t as ReconnectOptions } from "./reconnect-DbcN0R_1.js";
+import { RpcConnectionClosed, RpcError, RpcMethodNotFoundError, RpcRemoteError, RpcTimeoutError, RpcValidationError } from "./errors.js";
+import { a as PendingCallStorage, i as PendingCall, o as StorageMode, r as MaybePromise, s as SyncPendingCallStorage, t as AsyncPendingCallStorage } from "./interface-C4S-WCqW.js";
+import { t as MemoryPendingCallStorage } from "./memory-D1nGjzzH.js";
+import { t as SqlPendingCallStorage } from "./sql-DPmHOeZy.js";
+import "./storage/index.js";
+import "./utils/index.js";
+export { type AsyncPendingCallStorage, type Driver, type EventDef, type EventHandler, type IEventController, type IMethodController, type IMinWebSocket, type IRpcConnection, type IRpcOptions, type IWebSocket, type IWebSocketServer, type InferEventData, type InferEvents, type InferInput, type InferMethods, type InferOutput, JsonProtocol, type MaybePromise, MemoryPendingCallStorage, type MethodDef, type PendingCall, type PendingCallStorage, type Provider, type ReconnectOptions, RpcConnectionClosed, RpcError, RpcErrorCodes, type RpcError$1 as RpcErrorMessage, RpcErrorSchema, type RpcEvent, RpcEventSchema, type RpcMessage, RpcMessageCodec, RpcMessageSchema, RpcMethodNotFoundError, type RpcProtocol, RpcRemoteError, type RpcRequest, RpcRequestSchema, type RpcResponse, RpcResponseSchema, type RpcSchema, RpcTimeoutError, RpcValidationError, type RpcWireCodec, SqlPendingCallStorage, type StorageMode, type SyncPendingCallStorage, type WebSocketOptions, WebSocketReadyState, type WebSocketServerOptions, calculateReconnectDelay, createProtocol, defaultReconnectOptions, event, method };

package/dist/index.js

@@ -0,0 +1,14 @@
+import "./factory-3ziwTuZe.js";
+import "./json-Bshec-bZ.js";
+import "./codecs-BmYG2d_U.js";
+import { a as RpcMessageCodec, c as RpcResponseSchema, i as RpcEventSchema, l as createProtocol, n as RpcErrorCodes, o as RpcMessageSchema, r as RpcErrorSchema, s as RpcRequestSchema, t as JsonProtocol } from "./protocol-_mpoOPp6.js";
+import { a as RpcTimeoutError, i as RpcRemoteError, n as RpcError, o as RpcValidationError, r as RpcMethodNotFoundError, t as RpcConnectionClosed } from "./errors-5BfreE63.js";
+import { event, method } from "./schema.js";
+import { t as MemoryPendingCallStorage } from "./memory-Bqb3KEVr.js";
+import { t as SqlPendingCallStorage } from "./sql-CCjc6Bid.js";
+import "./storage/index.js";
+import { t as WebSocketReadyState } from "./types-D_psiH09.js";
+import { n as defaultReconnectOptions, t as calculateReconnectDelay } from "./reconnect-CGAA_1Gf.js";
+import "./utils/index.js";
+
+export { JsonProtocol, MemoryPendingCallStorage, RpcConnectionClosed, RpcError, RpcErrorCodes, RpcErrorSchema, RpcEventSchema, RpcMessageCodec, RpcMessageSchema, RpcMethodNotFoundError, RpcRemoteError, RpcRequestSchema, RpcResponseSchema, RpcTimeoutError, RpcValidationError, SqlPendingCallStorage, WebSocketReadyState, calculateReconnectDelay, createProtocol, defaultReconnectOptions, event, method };