@igoforth/ws-rpc 1.0.0

package/dist/utils/reconnect.d.ts

@@ -0,0 +1,2 @@
+import { n as calculateReconnectDelay, r as defaultReconnectOptions, t as ReconnectOptions } from "../reconnect-DbcN0R_1.js";
+export { ReconnectOptions, calculateReconnectDelay, defaultReconnectOptions };

package/dist/utils/reconnect.js

@@ -0,0 +1,3 @@
+import { n as defaultReconnectOptions, t as calculateReconnectDelay } from "../reconnect-CGAA_1Gf.js";
+
+export { calculateReconnectDelay, defaultReconnectOptions };

package/package.json

@@ -0,0 +1,156 @@
+{
+  "name": "@igoforth/ws-rpc",
+  "version": "1.0.0",
+  "description": "Bidirectional RPC over WebSocket with Zod schema validation, TypeScript inference, and Cloudflare Durable Object support",
+  "type": "module",
+  "license": "MIT",
+  "author": {
+    "name": "Ian Goforth",
+    "email": "ian.goforth@gmail.com",
+    "url": "https://ian.goforth.systems/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/igoforth/ws-rpc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/igoforth/ws-rpc/issues"
+  },
+  "homepage": "https://github.com/igoforth/ws-rpc#readme",
+  "keywords": [
+    "rpc",
+    "websocket",
+    "bidirectional",
+    "zod",
+    "typescript",
+    "cloudflare",
+    "durable-objects",
+    "workers",
+    "json-rpc",
+    "msgpack",
+    "cbor",
+    "realtime"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
+    "./errors": {
+      "types": "./dist/errors.d.ts",
+      "import": "./dist/errors.js"
+    },
+    "./peer": {
+      "types": "./dist/peers/index.d.ts",
+      "import": "./dist/peers/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "import": "./dist/adapters/index.js"
+    },
+    "./adapters/client": {
+      "types": "./dist/adapters/client.d.ts",
+      "import": "./dist/adapters/client.js"
+    },
+    "./adapters/server": {
+      "types": "./dist/adapters/server.d.ts",
+      "import": "./dist/adapters/server.js"
+    },
+    "./adapters/cloudflare-do": {
+      "types": "./dist/adapters/cloudflare-do.d.ts",
+      "import": "./dist/adapters/cloudflare-do.js"
+    },
+    "./codecs": {
+      "types": "./dist/codecs/index.d.ts",
+      "import": "./dist/codecs/index.js"
+    },
+    "./codecs/json": {
+      "types": "./dist/codecs/json.d.ts",
+      "import": "./dist/codecs/json.js"
+    },
+    "./codecs/msgpack": {
+      "types": "./dist/codecs/msgpack.d.ts",
+      "import": "./dist/codecs/msgpack.js"
+    },
+    "./codecs/cbor": {
+      "types": "./dist/codecs/cbor.d.ts",
+      "import": "./dist/codecs/cbor.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js"
+    }
+  },
+  "dependencies": {
+    "type-fest": "^5.3.1",
+    "uuid": "^13.0.0",
+    "zod": "^4.2.0"
+  },
+  "peerDependencies": {
+    "@cloudflare/actors": ">=0.0.1-beta.6",
+    "@msgpack/msgpack": "^3.1.2",
+    "cbor-x": "^1.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@cloudflare/actors": {
+      "optional": true
+    },
+    "@msgpack/msgpack": {
+      "optional": true
+    },
+    "cbor-x": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@cloudflare/actors": "^0.0.1-beta.6",
+    "@cloudflare/vitest-pool-workers": "^0.11.1",
+    "@msgpack/msgpack": "^3.1.2",
+    "@types/node": "^22.10.2",
+    "@types/ws": "^8.18.1",
+    "cbor-x": "^1.6.0",
+    "tsdown": "^0.18.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "wrangler": "^4.56.0",
+    "ws": "^8.18.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "bench": "vitest bench --config vitest.config.bench.ts",
+    "typecheck": "tsc --noEmit",
+    "typegen": "wrangler types",
+    "lint": "biome check .",
+    "format": "biome format --write ."
+  }
+}

package/src/adapters/client.ts

@@ -0,0 +1,396 @@
+/**
+ * RPC Client Adapter
+ *
+ * WebSocket client with auto-reconnect for Node.js/Bun environments.
+ * Wraps RpcPeer with connection management.
+ */
+
+import type { Constructor } from "type-fest";
+import { RpcPeer } from "../peers/default.js";
+import type { WireInput } from "../protocol.js";
+import type {
+	Driver,
+	EventDef,
+	InferEventData,
+	Provider,
+	RpcSchema,
+	StringKeys,
+} from "../schema.js";
+import {
+	type IRpcOptions,
+	type IWebSocket,
+	type WebSocketOptions,
+	WebSocketReadyState,
+} from "../types.js";
+import {
+	calculateReconnectDelay,
+	defaultReconnectOptions,
+	type IAdapterHooks,
+	type IConnectionAdapter,
+	type ReconnectOptions,
+} from "./types.js";
+
+/**
+ * Options for creating an RpcClient
+ */
+export interface RpcClientOptions<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> extends IAdapterHooks<TRemoteSchema>,
+		IRpcOptions<TLocalSchema, TRemoteSchema> {
+	/** WebSocket URL to connect to */
+	url: string;
+	/** Implementation of local methods */
+	provider: Provider<TLocalSchema>;
+	/** Auto-reconnect options (set to false to disable) */
+	reconnect?: ReconnectOptions | false;
+	/** Automatically connect when client is created (default: false) */
+	autoConnect?: boolean;
+	/** WebSocket subprotocols */
+	protocols?: string | string[];
+	/** HTTP headers for WebSocket upgrade request (Bun/Node.js only) */
+	headers?: Record<string, string>;
+	/** Custom WebSocket constructor (defaults to global WebSocket) */
+	WebSocket?: new (
+		url: string,
+		options?: string | string[] | WebSocketOptions,
+	) => IWebSocket;
+}
+
+/**
+ * Connection state
+ */
+export type ConnectionState =
+	| "disconnected"
+	| "connecting"
+	| "connected"
+	| "reconnecting";
+
+/**
+ * RPC Client with auto-reconnect
+ *
+ * Manages WebSocket connection lifecycle and provides RPC capabilities.
+ */
+export class RpcClient<
+	TLocalSchema extends RpcSchema,
+	TRemoteSchema extends RpcSchema,
+> implements IConnectionAdapter<TLocalSchema, TRemoteSchema>
+{
+	readonly localSchema: TLocalSchema;
+	readonly remoteSchema: TRemoteSchema;
+	readonly provider: Provider<TLocalSchema>;
+	readonly hooks: IAdapterHooks<TRemoteSchema> = {};
+
+	private readonly url: string;
+	private readonly reconnectOptions: Required<ReconnectOptions> | false;
+	private readonly defaultTimeout: number;
+	private readonly protocols: string | string[] | undefined;
+	private readonly headers: Record<string, string> | undefined;
+	private readonly WebSocketImpl: new (
+		url: string,
+		options?: string | string[] | WebSocketOptions,
+	) => IWebSocket;
+
+	// Connection state
+	private ws: IWebSocket | null = null;
+	private peer: RpcPeer<TLocalSchema, TRemoteSchema> | null = null;
+	private _state: ConnectionState = "disconnected";
+	private reconnectAttempt = 0;
+	private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
+	private intentionalClose = false;
+
+	constructor(options: RpcClientOptions<TLocalSchema, TRemoteSchema>) {
+		this.url = options.url;
+		this.localSchema = options.localSchema;
+		this.remoteSchema = options.remoteSchema;
+		this.provider = options.provider;
+		this.reconnectOptions =
+			options.reconnect === false
+				? false
+				: { ...defaultReconnectOptions, ...options.reconnect };
+		this.defaultTimeout = options.timeout ?? 30000;
+		this.protocols = options.protocols;
+		this.headers = options.headers;
+		this.WebSocketImpl =
+			options.WebSocket ?? (globalThis.WebSocket as Constructor<IWebSocket>);
+
+		if (options.onConnect) this.hooks.onConnect = options.onConnect;
+		if (options.onDisconnect) this.hooks.onDisconnect = options.onDisconnect;
+		if (options.onReconnect) this.hooks.onReconnect = options.onReconnect;
+		if (options.onReconnectFailed)
+			this.hooks.onReconnectFailed = options.onReconnectFailed;
+		if (options.onEvent) this.hooks.onEvent = options.onEvent;
+
+		if (options.autoConnect) {
+			void this.connect();
+		}
+	}
+
+	/**
+	 * Current connection state
+	 */
+	get state(): ConnectionState {
+		return this._state;
+	}
+
+	/**
+	 * Whether the client is currently connected
+	 */
+	get isConnected(): boolean {
+		return this._state === "connected" && this.peer?.isOpen === true;
+	}
+
+	/**
+	 * Get the driver for calling remote methods
+	 *
+	 * @returns Driver proxy for calling remote methods
+	 * @throws Error if not connected
+	 */
+	get driver(): Driver<TRemoteSchema> {
+		if (!this.peer) {
+			throw new Error("Not connected - call connect() first");
+		}
+		return this.peer.driver;
+	}
+
+	/**
+	 * Emit an event to the server (fire-and-forget)
+	 *
+	 * @param event - Event name from local schema
+	 * @param data - Event data matching the schema
+	 */
+	emit<K extends StringKeys<TLocalSchema["events"]>>(
+		event: K,
+		data: TLocalSchema["events"] extends Record<string, EventDef>
+			? InferEventData<TLocalSchema["events"][K]>
+			: never,
+	): void {
+		if (!this.peer) {
+			console.warn(`Cannot emit event '${String(event)}': not connected`);
+			return;
+		}
+		this.peer.emit(event, data);
+	}
+
+	/**
+	 * Connect to the WebSocket server
+	 *
+	 * @returns Promise that resolves when connected
+	 * @throws Error if connection fails
+	 */
+	async connect(): Promise<void> {
+		if (this._state === "connected" || this._state === "connecting") {
+			return;
+		}
+
+		this.intentionalClose = false;
+		this._state = "connecting";
+
+		return new Promise<void>((resolve, reject) => {
+			try {
+				// Use options object when headers are present (Bun/Node.js)
+				// Fall back to protocols-only for browser compatibility
+				let wsOptions: WebSocketOptions | string | string[] | undefined;
+				if (this.headers) {
+					wsOptions = { headers: this.headers };
+					if (this.protocols) {
+						wsOptions.protocols = this.protocols;
+					}
+				} else {
+					wsOptions = this.protocols;
+				}
+				this.ws = new this.WebSocketImpl(this.url, wsOptions);
+			} catch (error) {
+				this._state = "disconnected";
+				reject(error);
+				return;
+			}
+
+			const onOpen = () => {
+				cleanup();
+				this.handleOpen();
+				resolve();
+			};
+
+			const onError = (event: unknown) => {
+				cleanup();
+				this._state = "disconnected";
+				reject(new Error(`WebSocket connection failed: ${event}`));
+			};
+
+			const onClose = (event: unknown) => {
+				cleanup();
+				this._state = "disconnected";
+				const code =
+					typeof event === "object" && event != null && "code" in event
+						? event.code
+						: "Unknown code";
+				const reason =
+					typeof event === "object" && event != null && "reason" in event
+						? event.reason
+						: "Unknown reason";
+				reject(new Error(`WebSocket closed: ${code} ${reason}`));
+			};
+
+			const cleanup = () => {
+				this.ws?.removeEventListener?.("open", onOpen);
+				this.ws?.removeEventListener?.("error", onError);
+				this.ws?.removeEventListener?.("close", onClose);
+			};
+
+			this.ws.addEventListener?.("open", onOpen);
+			this.ws.addEventListener?.("error", onError);
+			this.ws.addEventListener?.("close", onClose);
+		});
+	}
+
+	/**
+	 * Disconnect from the server
+	 *
+	 * @param code - WebSocket close code (default: 1000)
+	 * @param reason - Close reason message (default: "Client disconnect")
+	 */
+	disconnect(code = 1000, reason = "Client disconnect"): void {
+		this.intentionalClose = true;
+		this.cancelReconnect();
+
+		if (this.peer) {
+			this.peer.close();
+			this.peer = null;
+		}
+
+		if (this.ws && this.ws.readyState !== WebSocketReadyState.CLOSED) {
+			this.ws.close(code, reason);
+		}
+		this.ws = null;
+
+		this._state = "disconnected";
+	}
+
+	/**
+	 * Handle WebSocket open event
+	 */
+	private handleOpen(): void {
+		if (!this.ws) return;
+
+		this._state = "connected";
+		this.reconnectAttempt = 0;
+
+		// Create RPC peer
+		this.peer = new RpcPeer({
+			ws: this.ws,
+			localSchema: this.localSchema,
+			remoteSchema: this.remoteSchema,
+			provider: this.provider,
+			onEvent: this.hooks.onEvent,
+			timeout: this.defaultTimeout,
+		});
+
+		// Set up WebSocket event handlers
+		this.ws.onmessage = (event) => {
+			if (typeof event === "object" && event != null && "data" in event)
+				this.peer?.handleMessage(event.data as WireInput);
+			else
+				throw new Error(
+					`Received invalid event type in RpcClient.ws.onmessage ${JSON.stringify(event)}`,
+				);
+		};
+
+		this.ws.onclose = (event) => {
+			if (
+				typeof event === "object" &&
+				event != null &&
+				"code" in event &&
+				"reason" in event &&
+				typeof event.code === "number" &&
+				typeof event.reason === "string"
+			)
+				this.handleClose(event.code, event.reason);
+			else
+				throw new Error(
+					`Received invalid event type in RpcClient.ws.onclose ${JSON.stringify(event)}`,
+				);
+		};
+
+		this.ws.onerror = (event) => {
+			console.error("WebSocket error:", event);
+		};
+
+		this.hooks.onConnect?.();
+	}
+
+	/**
+	 * Handle WebSocket close event
+	 */
+	private handleClose(code: number, reason: string): void {
+		this.peer?.close();
+		this.peer = null;
+		this.ws = null;
+
+		this.hooks.onDisconnect?.(code, reason);
+
+		if (this.intentionalClose) {
+			this._state = "disconnected";
+			return;
+		}
+
+		// Attempt reconnection
+		if (this.reconnectOptions !== false) {
+			this.scheduleReconnect();
+		} else {
+			this._state = "disconnected";
+		}
+	}
+
+	/**
+	 * Schedule a reconnection attempt
+	 */
+	private scheduleReconnect(): void {
+		if (this.reconnectOptions === false) return;
+
+		const { maxAttempts } = this.reconnectOptions;
+		if (maxAttempts > 0 && this.reconnectAttempt >= maxAttempts) {
+			this._state = "disconnected";
+			this.hooks.onReconnectFailed?.();
+			return;
+		}
+
+		this._state = "reconnecting";
+		const delay = calculateReconnectDelay(
+			this.reconnectAttempt,
+			this.reconnectOptions,
+		);
+		this.reconnectAttempt++;
+
+		this.hooks.onReconnect?.(this.reconnectAttempt, delay);
+
+		this.reconnectTimeout = setTimeout(() => {
+			this.reconnectTimeout = null;
+			void this.attemptReconnect();
+		}, delay);
+	}
+
+	/**
+	 * Attempt to reconnect
+	 */
+	private async attemptReconnect(): Promise<void> {
+		try {
+			await this.connect();
+		} catch {
+			// connect() failed during reconnection - schedule another attempt
+			if (!this.intentionalClose && this.reconnectOptions !== false) {
+				this.scheduleReconnect();
+			}
+		}
+	}
+
+	/**
+	 * Cancel any pending reconnection
+	 */
+	private cancelReconnect(): void {
+		if (this.reconnectTimeout) {
+			clearTimeout(this.reconnectTimeout);
+			this.reconnectTimeout = null;
+		}
+	}
+}