@igoforth/ws-rpc 1.0.0

package/src/adapters/types.ts

@@ -0,0 +1,202 @@
+/**
+ * Adapter Type Definitions
+ *
+ * Common interfaces and types for WebSocket adapters.
+ */
+
+import type { RpcPeer } from "../peers/default.js";
+import type {
+	Driver,
+	EventHandler,
+	InferInput,
+	InferOutput,
+	MethodDef,
+	RpcSchema,
+	StringKeys,
+} from "../schema.js";
+import type {
+	IEventController,
+	IMethodController,
+	IRpcOptions,
+} from "../types.js";
+
+// =============================================================================
+// Multi-Connection Adapter Types
+// =============================================================================
+
+/**
+ * Options for driver method calls on multi-connection adapters
+ */
+export interface MultiCallOptions {
+	/** Connection ID(s) to call. If omitted, calls all connections. */
+	ids?: string | string[];
+	/** Request timeout in milliseconds */
+	timeout?: number;
+}
+
+/**
+ * Result of a driver method call on a multi-connection adapter
+ *
+ * Each result contains the peer ID and either a success value or an error.
+ *
+ * @typeParam T - The expected return type of the remote method
+ *
+ * @example
+ * ```ts
+ * const results = await server.driver.ping({});
+ * for (const { id, result } of results) {
+ *   if (result.success) {
+ *     console.log(`Peer ${id} responded:`, result.value);
+ *   } else {
+ *     console.error(`Peer ${id} failed:`, result.error);
+ *   }
+ * }
+ * ```
+ */
+export type MultiCallResult<T> = {
+	/** Peer ID that this result is from */
+	id: string;
+	/** Success or failure result */
+	result: { success: true; value: T } | { success: false; error: Error };
+};
+
+/**
+ * Driver type for multi-connection adapters
+ *
+ * Methods accept an optional second argument with `ids` and `timeout`.
+ * Returns an array of results, one per connection called.
+ *
+ * @typeParam TRemoteSchema - Schema defining the remote methods available
+ *
+ * @example
+ * ```ts
+ * // Call all connected peers
+ * const allResults = await server.driver.getData({});
+ *
+ * // Call specific peer by ID
+ * const oneResult = await server.driver.getData({}, { ids: "peer-123" });
+ *
+ * // Call multiple peers with timeout
+ * const someResults = await server.driver.getData({}, {
+ *   ids: ["peer-1", "peer-2"],
+ *   timeout: 5000,
+ * });
+ * ```
+ */
+export type MultiDriver<TRemoteSchema extends RpcSchema> =
+	TRemoteSchema["methods"] extends Record<string, MethodDef>
+		? {
+				[K in StringKeys<TRemoteSchema["methods"]>]: <
+					O extends MultiCallOptions,
+				>(
+					input: TRemoteSchema["methods"] extends Record<string, MethodDef>
+						? InferInput<TRemoteSchema["methods"][K]>
+						: never,
+					options?: O,
+				) => Promise<
+					O extends { ids: infer I }
+						? string extends I
+							? MultiCallResult<
+									TRemoteSchema["methods"] extends Record<string, MethodDef>
+										? InferOutput<TRemoteSchema["methods"][K]>
+										: never
+								>
+							: Array<
+									MultiCallResult<
+										TRemoteSchema["methods"] extends Record<string, MethodDef>
+											? InferOutput<TRemoteSchema["methods"][K]>
+											: never
+									>
+								>
+						: never
+				>;
+			}
+		: never;
+
+/**
+ * Event emitter type for client callbacks
+ */
+export interface IAdapterHooks<TRemoteSchema extends RpcSchema> {
+	/** Called when WebSocket connection opens */
+	onConnect?(): void;
+
+	/** Called when WebSocket connection closes */
+	onDisconnect?(code: number, reason: string): void;
+
+	/** Called when attempting to reconnect */
+	onReconnect?(attempt: number, delay: number): void;
+
+	/** Called when reconnection fails after max attempts */
+	onReconnectFailed?(): void;
+
+	/** Called when receiving an event from the server */
+	onEvent?: EventHandler<TRemoteSchema>;
+}
+
+export interface IMultiAdapterHooks<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> {
+	/** Called when a peer connects */
+	onConnect?(peer: RpcPeer<TLocalSchema, TRemoteSchema>): void;
+
+	/** Called when a peer disconnects */
+	onDisconnect?(peer: RpcPeer<TLocalSchema, TRemoteSchema>): void;
+
+	/** Called when an event is received from a peer */
+	onEvent?: EventHandler<
+		TRemoteSchema,
+		[peer: RpcPeer<TLocalSchema, TRemoteSchema>]
+	>;
+
+	/** Called when a peer encounters an error */
+	onError?(
+		peer: RpcPeer<TLocalSchema, TRemoteSchema> | null,
+		error: Error,
+	): void;
+
+	onClose?(): void;
+}
+
+export interface IConnectionAdapter<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> extends IRpcOptions<TLocalSchema, TRemoteSchema>,
+		IMethodController<TLocalSchema>,
+		IEventController<TLocalSchema, TRemoteSchema> {
+	/** Driver for calling remote methods on connected peer */
+	readonly driver: Driver<TRemoteSchema>;
+
+	readonly hooks: IAdapterHooks<TRemoteSchema>;
+}
+
+/**
+ * Interface for adapters that manage multiple connections
+ *
+ * Extends IRpcConnection - `emit()` broadcasts to all connected peers.
+ * Implemented by RpcServer and Cloudflare DO adapter.
+ */
+export interface IMultiConnectionAdapter<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> extends IRpcOptions<TLocalSchema, TRemoteSchema>,
+		IMethodController<TLocalSchema>,
+		IEventController<TLocalSchema, TRemoteSchema, [ids?: string[]]> {
+	/** Driver for calling remote methods on connected peers */
+	readonly driver: MultiDriver<TRemoteSchema>;
+
+	readonly hooks: IMultiAdapterHooks<TLocalSchema, TRemoteSchema>;
+
+	/** Get count of connected peers */
+	getConnectionCount(): number;
+
+	/** Get all connected peer IDs */
+	getConnectionIds(): string[];
+}
+
+// Re-export reconnection utilities from utils
+export {
+	calculateReconnectDelay,
+	defaultReconnectOptions,
+	type ReconnectOptions,
+} from "../utils/reconnect.js";

package/src/codecs/cbor.ts

@@ -0,0 +1,42 @@
+/**
+ * CBOR codec using cbor-x
+ *
+ * Requires optional peer dependency: cbor-x
+ *
+ * @example
+ * ```ts
+ * import { createCborCodec, CborCodec } from "@igoforth/ws-rpc/codecs/cbor";
+ *
+ * // Create a typed codec
+ * const MyDataCodec = createCborCodec(MyDataSchema);
+ * const bytes = MyDataCodec.encode(data); // Uint8Array
+ * const decoded = MyDataCodec.decode(bytes); // validated MyData
+ *
+ * // Or use the generic codec
+ * const bytes = CborCodec.encode({ any: "data" });
+ * ```
+ */
+
+import { Decoder, Encoder } from "cbor-x";
+import * as z from "zod";
+import { createBinaryCodecFactory } from "./factory";
+
+const decode = <T>(data: Uint8Array<ArrayBuffer>): T =>
+	new Decoder({ bundleStrings: true }).decode(data) as T;
+
+const encode = (data: unknown): Uint8Array<ArrayBuffer> =>
+	new Encoder({ bundleStrings: true }).encode(data) as Uint8Array<ArrayBuffer>;
+
+export const createCborCodec = createBinaryCodecFactory(
+	(value) => encode(value),
+	(bytes) => decode(bytes),
+	"cbor",
+);
+
+/**
+ * Default CBOR 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.
+ */
+export const CborCodec = createCborCodec(z.unknown());

package/src/codecs/factory.ts

@@ -0,0 +1,210 @@
+/**
+ * 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);
+ * }
+ * ```
+ */
+
+import * as z from "zod";
+import type { LiteralStringUnion } from "../schema";
+
+/**
+ * Type alias for a Zod codec that encodes to string
+ */
+export type StringCodec<T extends z.ZodType = z.ZodType> = z.ZodCodec<
+	z.ZodString,
+	T
+>;
+
+/**
+ * Type alias for a Zod codec that encodes to Uint8Array
+ */
+export type BinaryCodec<T extends z.ZodType = z.ZodType> = z.ZodCodec<
+	z.ZodCustom<Uint8Array<ArrayBuffer>>,
+	T
+>;
+
+// ZodCodec<ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, T>;
+
+/**
+ * Options for codec factories
+ */
+export 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.
+ */
+export 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()),
+ * }));
+ * ```
+ */
+export function createStringCodecFactory(
+	serialize: (value: unknown) => string,
+	deserialize: (text: string) => unknown,
+	formatName: LiteralStringUnion<z.core.$ZodStringFormats>,
+): CodecFactory<string> {
+	return <T extends z.ZodType>(
+		schema: T,
+		options?: CodecOptions,
+	): StringCodec<T> => {
+		return z.codec(z.string(), schema, {
+			decode: (text, ctx) => {
+				try {
+					return deserialize(text) as z.util.MaybeAsync<z.input<T>>;
+				} 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
+ * ```
+ */
+export function createBinaryCodecFactory(
+	serialize: (value: unknown) => Uint8Array<ArrayBuffer>,
+	deserialize: (bytes: Uint8Array<ArrayBuffer>) => unknown,
+	formatName: string,
+): CodecFactory<Uint8Array<ArrayBuffer>> {
+	return <T extends z.ZodType>(
+		schema: T,
+		options?: CodecOptions,
+	): BinaryCodec<T> => {
+		return z.codec(z.instanceof(Uint8Array), schema, {
+			decode: (bytes, ctx) => {
+				try {
+					return deserialize(bytes) as z.util.MaybeAsync<z.input<T>>;
+				} 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),
+		});
+	};
+}
+
+/**
+ * Wire codec - either string or binary
+ */
+export type WireCodec<T extends z.ZodType = z.ZodType> =
+	| StringCodec<T>
+	| BinaryCodec<T>;
+
+/**
+ * Wire data - what gets sent over WebSocket
+ */
+export type WireData = string | Uint8Array<ArrayBuffer>;
+
+/**
+ * Helper to check if a codec encodes to string
+ */
+export function isStringCodec(
+	codec: z.ZodCodec<z.ZodType, z.ZodType>,
+): codec is StringCodec {
+	// Check if the "from" schema accepts strings
+	return codec._zod.def.in._zod.def.type === "string";
+}
+
+/**
+ * Helper to check if a codec encodes to binary
+ */
+export function isBinaryCodec(
+	codec: z.ZodCodec<z.ZodType, z.ZodType>,
+): codec is BinaryCodec {
+	return !isStringCodec(codec);
+}

package/src/codecs/index.ts

@@ -0,0 +1,30 @@
+/**
+ * RPC Codecs
+ *
+ * Zod-based codecs for serialization with built-in validation.
+ *
+ * Core exports (always available):
+ * - Factory functions for creating custom codecs
+ * - JSON codec (uses built-in JSON.stringify/parse)
+ *
+ * Optional binary codecs (require peer dependencies):
+ * - MessagePack: import from "@igoforth/ws-rpc/codecs/msgpack"
+ * - CBOR: import from "@igoforth/ws-rpc/codecs/cbor"
+ */
+
+// Core types and factories
+export {
+	type BinaryCodec,
+	type CodecFactory,
+	type CodecOptions,
+	createBinaryCodecFactory,
+	createStringCodecFactory,
+	isBinaryCodec,
+	isStringCodec,
+	type StringCodec,
+	type WireCodec,
+	type WireData,
+} from "./factory";
+
+// JSON codec (always available)
+export { createJsonCodec, JsonCodec } from "./json";

package/src/codecs/json.ts

@@ -0,0 +1,42 @@
+/**
+ * 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);
+ * ```
+ */
+import * as z from "zod";
+import { createStringCodecFactory } from "./factory";
+
+/**
+ * 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
+ */
+export 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.
+ */
+export const JsonCodec = createJsonCodec(z.unknown());

package/src/codecs/msgpack.ts

@@ -0,0 +1,36 @@
+/**
+ * MessagePack codec using @msgpack/msgpack
+ *
+ * Requires optional peer dependency: @msgpack/msgpack
+ *
+ * @example
+ * ```ts
+ * import { createMsgpackCodec, MsgpackCodec } from "@igoforth/ws-rpc/codecs/msgpack";
+ *
+ * // Create a typed codec
+ * const MyDataCodec = createMsgpackCodec(MyDataSchema);
+ * const bytes = MyDataCodec.encode(data); // Uint8Array
+ * const decoded = MyDataCodec.decode(bytes); // validated MyData
+ *
+ * // Or use the generic codec
+ * const bytes = MsgpackCodec.encode({ any: "data" });
+ * ```
+ */
+
+import { decode, encode } from "@msgpack/msgpack";
+import * as z from "zod";
+import { createBinaryCodecFactory } from "./factory";
+
+export const createMsgpackCodec = createBinaryCodecFactory(
+	(value) => encode(value) as Uint8Array<ArrayBuffer>,
+	(bytes) => decode(bytes),
+	"msgpack",
+);
+
+/**
+ * Default MessagePack 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.
+ */
+export const MsgpackCodec = createMsgpackCodec(z.unknown());

package/src/errors.ts

@@ -0,0 +1,105 @@
+/**
+ * RPC Error Classes
+ *
+ * Custom error types for RPC operations.
+ */
+
+import { RpcErrorCodes } from "./protocol.js";
+
+/**
+ * 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
+ */
+export class RpcError extends Error {
+	readonly code: number;
+	readonly data?: unknown;
+
+	constructor(code: number, message: string, data?: unknown) {
+		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
+ */
+export class RpcTimeoutError extends RpcError {
+	readonly method: string;
+	readonly timeoutMs: number;
+
+	constructor(method: string, timeoutMs: number) {
+		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
+ */
+export class RpcRemoteError extends RpcError {
+	readonly method: string;
+
+	constructor(method: string, code: number, message: string, data?: unknown) {
+		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")
+ */
+export class RpcConnectionClosed 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
+ */
+export class RpcValidationError extends RpcError {
+	constructor(message: string, data?: unknown) {
+		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
+ */
+export class RpcMethodNotFoundError extends RpcError {
+	readonly method: string;
+
+	constructor(method: string) {
+		super(RpcErrorCodes.METHOD_NOT_FOUND, `Method '${method}' not found`);
+		this.name = "RpcMethodNotFoundError";
+		this.method = method;
+	}
+}