@igoforth/ws-rpc 1.0.0 → 1.0.1

package/README.md

@@ -187,13 +187,10 @@ import { Actor } from "@cloudflare/actors";
 import { withRpc } from "@igoforth/ws-rpc/adapters/cloudflare-do";
 import { ServerSchema, ClientSchema } from "./schemas";
 
-// The mixin adds RPC capabilities to your Actor
-// Your class must implement the methods defined in localSchema
-export class GameRoom extends withRpc(Actor, {
-  localSchema: ServerSchema,
-  remoteSchema: ClientSchema,
-}) {
-  private gameState = { players: [] as string[] };
+// First, create an Actor with the RPC method implementations
+// Methods from localSchema MUST be defined here for type checking
+class GameRoomActor extends Actor<Env> {
+  protected gameState = { players: [] as string[] };
 
   // Implement methods from ServerSchema
   async getUser({ id }: { id: string }) {
@@ -203,10 +200,15 @@ export class GameRoom extends withRpc(Actor, {
   async createOrder({ product, quantity }: { product: string; quantity: number }) {
     return { orderId: crypto.randomUUID() };
   }
+}
 
+// Then apply the RPC mixin to get driver, emit, etc.
+export class GameRoom extends withRpc(GameRoomActor, {
+  localSchema: ServerSchema,
+  remoteSchema: ClientSchema,
+}) {
   // Use this.driver to call methods on connected clients
   async notifyAllPlayers() {
-    // Call ping on all connected clients
     const results = await this.driver.ping({});
     console.log("Ping results:", results);
   }
@@ -396,25 +398,24 @@ class MyDO extends Actor<Env> {
 
 ## Performance
 
-Real WebSocket RPC round-trip benchmarks (localhost, Node.js):
+Real WebSocket RPC round-trip benchmarks (GitHub Actions runner, Node.js 22):
 
 **Wire sizes:**
 | Payload | JSON | MessagePack | CBOR |
 |---------|------|-------------|------|
 | Small | 93 B | 71 B | 112 B |
-| Medium | 3.5 KB | 2.1 KB | 1.4 KB |
-| Large | 24.5 KB | 19.6 KB | 14.1 KB |
+| Medium | 3.4 KB | 2.1 KB | 1.3 KB |
+| Large | 24.4 KB | 19.5 KB | 14.1 KB |
 
 **Throughput (ops/sec):**
-| Payload | JSON | MessagePack | CBOR |
-|---------|------|-------------|------|
-| Small | 1,371 | 2,208 | **2,423** |
-| Medium | 2,218 | 2,221 | **2,249** |
-| Large | 1,334 | 1,245 | **1,562** |
-
-CBOR provides the best balance of speed and wire size for most payloads. MessagePack excels with smaller payloads. JSON is the most portable but largest.
-
-Run benchmarks yourself: `pnpm bench`
+| Payload | JSON | MessagePack | CBOR | Fastest |
+|---------|------|-------------|------|---------|
+| Small | 0 | 0 | 0 | JSON |
+| Medium | 0 | 0 | 0 | JSON |
+| Large | 0 | 0 | 0 | JSON |
+
+> Benchmarks run automatically via GitHub Actions. Results may vary based on runner load.
+> Run locally with `pnpm bench` for your environment.
 
 ## Multi-Peer Driver Results
 

package/dist/adapters/cloudflare-do.d.ts

@@ -49,15 +49,20 @@ type RpcActorConstructor<TBase extends Constructor<Actor<unknown>>, TLocalSchema
  *   events: {},
  * } as const;
  *
- * class MyDO extends withRpc(Actor, {
- *   localSchema: ServerSchema,
- *   remoteSchema: ClientSchema,
- * }) {
- *   // Required: implement methods from ServerSchema
+ * // Define methods on the base Actor class
+ * class MyActorBase extends Actor<Env> {
+ *   protected dataList: string[] = [];
+ *
  *   async getData() {
  *     return { data: this.dataList };
  *   }
+ * }
  *
+ * // Apply the RPC mixin
+ * class MyDO extends withRpc(MyActorBase, {
+ *   localSchema: ServerSchema,
+ *   remoteSchema: ClientSchema,
+ * }) {
  *   // Call methods on connected clients
  *   async notifyClients() {
  *     const results = await this.driver.clientMethod({ info: "update" });

package/dist/adapters/cloudflare-do.js

@@ -102,15 +102,20 @@ var DOMultiPeer = class extends MultiPeerBase {
 *   events: {},
 * } as const;
 *
-* class MyDO extends withRpc(Actor, {
-*   localSchema: ServerSchema,
-*   remoteSchema: ClientSchema,
-* }) {
-*   // Required: implement methods from ServerSchema
+* // Define methods on the base Actor class
+* class MyActorBase extends Actor<Env> {
+*   protected dataList: string[] = [];
+*
 *   async getData() {
 *     return { data: this.dataList };
 *   }
+* }
 *
+* // Apply the RPC mixin
+* class MyDO extends withRpc(MyActorBase, {
+*   localSchema: ServerSchema,
+*   remoteSchema: ClientSchema,
+* }) {
 *   // Call methods on connected clients
 *   async notifyClients() {
 *     const results = await this.driver.clientMethod({ info: "update" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igoforth/ws-rpc",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Bidirectional RPC over WebSocket with Zod schema validation, TypeScript inference, and Cloudflare Durable Object support",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,6 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src",
     "LICENSE",
     "README.md"
   ],

package/src/adapters/client.ts

@@ -1,396 +0,0 @@
-/**
- * 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;
-		}
-	}
-}