@firtoz/websocket-do 2.0.0 → 4.0.0

package/README.md

@@ -9,11 +9,14 @@ Type-safe WebSocket session management for Cloudflare Durable Objects with Hono
 ## Features
 
 - 🔒 **Type-safe** - Full TypeScript support with generic types for messages and session data
+- ✨ **Zod Validation** - Runtime message validation with `ZodWebSocketClient` and `ZodSession`
 - 🌐 **WebSocket Management** - Built on Cloudflare Durable Objects for stateful WebSocket connections
 - 🎯 **Session-based** - Abstract session class for easy implementation of custom WebSocket logic
 - 🔄 **State Persistence** - Automatic serialization/deserialization of session data
 - 📡 **Broadcasting** - Built-in support for broadcasting messages to all connected clients
+- 📦 **Buffer Mode** - Efficient binary messaging with msgpack serialization
 - 🚀 **Hono Integration** - Seamless integration with Hono framework for routing
+- 🔗 **DO Client Integration** - Works seamlessly with `@firtoz/hono-fetcher` for type-safe DO communication
 
 ## Installation
 
@@ -26,9 +29,22 @@ bun add @firtoz/websocket-do
 This package requires the following peer dependencies:
 
 ```bash
-bun add hono @cloudflare/workers-types @firtoz/hono-fetcher
+bun add hono @firtoz/hono-fetcher
 ```
 
+**For Zod validation features** (ZodWebSocketClient, ZodSession):
+```bash
+bun add zod msgpackr
+```
+
+For TypeScript support, use `wrangler types` to generate accurate types from your `wrangler.jsonc`:
+
+```bash
+wrangler types
+```
+
+This generates `worker-configuration.d.ts` with types for your specific environment bindings, replacing the need for `@cloudflare/workers-types`.
+
 ## Quick Start
 
 ### 1. Define Your Message Types
@@ -115,16 +131,24 @@ export class ChatRoomDO extends BaseWebSocketDO<Env, ChatSession> {
 
 ### 4. Configure Your Worker
 
-```typescript
-// wrangler.toml
-[[durable_objects.bindings]]
-name = "CHAT_ROOM"
-class_name = "ChatRoomDO"
-script_name = "your-worker-name"
-
-[[migrations]]
-tag = "v1"
-new_classes = ["ChatRoomDO"]
+```jsonc
+// wrangler.jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "CHAT_ROOM",
+        "class_name": "ChatRoomDO"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_classes": ["ChatRoomDO"]
+    }
+  ]
+}
 ```
 
 ### 5. Access from Your Worker
@@ -135,8 +159,8 @@ export default {
     const url = new URL(request.url);
     
     if (url.pathname === '/chat') {
-      const id = env.CHAT_ROOM.idFromName('global-chat');
-      const stub = env.CHAT_ROOM.get(id);
+      // Use getByName() for deterministic DO routing (2025+ compatibility)
+      const stub = env.CHAT_ROOM.getByName('global-chat');
       
       // Proxy to the Durable Object
       return stub.fetch(request);
@@ -147,6 +171,231 @@ export default {
 };
 ```
 
+## ZodWebSocketClient (Type-Safe Client)
+
+`ZodWebSocketClient` provides a type-safe WebSocket client with automatic Zod validation for both incoming and outgoing messages.
+
+### Features
+
+- ✅ **Automatic validation** - All messages validated with Zod schemas
+- 🎯 **Full type inference** - TypeScript types automatically inferred from schemas
+- 📦 **Dual mode** - Supports both JSON and msgpack (buffer) serialization
+- 🔗 **DO Integration** - Works seamlessly with `honoDoFetcher` WebSocket connections
+- 🛡️ **Error handling** - Validation errors caught and reported via callbacks
+
+### Basic Usage
+
+```typescript
+import { ZodWebSocketClient } from '@firtoz/websocket-do';
+import { z } from 'zod';
+
+// Define your message schemas
+const ClientMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('chat'), text: z.string() }),
+  z.object({ type: z.literal('ping') }),
+]);
+
+const ServerMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('chat'), text: z.string(), from: z.string() }),
+  z.object({ type: z.literal('pong') }),
+]);
+
+type ClientMessage = z.infer<typeof ClientMessageSchema>;
+type ServerMessage = z.infer<typeof ServerMessageSchema>;
+
+// Create WebSocket connection (regular or via honoDoFetcher)
+const ws = new WebSocket('wss://example.com/chat');
+
+// Wrap with ZodWebSocketClient
+const client = new ZodWebSocketClient({
+  webSocket: ws, // Can also use 'url' instead
+  clientSchema: ClientMessageSchema,
+  serverSchema: ServerMessageSchema,
+  onMessage: (message) => {
+    // Fully typed and validated!
+    if (message.type === 'chat') {
+      console.log(`${message.from}: ${message.text}`);
+    }
+  },
+});
+
+// Send type-safe messages (automatically validated!)
+client.send({ type: 'chat', text: 'Hello!' });
+```
+
+### Integration with honoDoFetcher
+
+Perfect for connecting to Durable Objects:
+
+```typescript
+import { honoDoFetcherWithName } from '@firtoz/hono-fetcher';
+import { ZodWebSocketClient } from '@firtoz/websocket-do';
+
+// 1. Connect to DO via honoDoFetcher
+const api = honoDoFetcherWithName(env.CHAT_ROOM, 'room-1');
+const wsResp = await api.websocket({
+  url: '/websocket',
+  config: { autoAccept: false }, // Let client control acceptance
+});
+
+// 2. Wrap with ZodWebSocketClient for type safety!
+const client = new ZodWebSocketClient({
+  webSocket: wsResp.webSocket,
+  clientSchema: ClientMessageSchema,
+  serverSchema: ServerMessageSchema,
+  onMessage: (message) => {
+    // Fully typed and validated
+    console.log('Received:', message);
+  },
+  onValidationError: (error) => {
+    console.error('Invalid message:', error);
+  },
+});
+
+// 3. Accept the WebSocket
+wsResp.webSocket?.accept();
+
+// 4. Send validated messages
+client.send({ type: 'chat', text: 'Hello from typed client!' });
+```
+
+### Buffer Mode (msgpack)
+
+For better performance and smaller payloads, use buffer mode with msgpack:
+
+```typescript
+const client = new ZodWebSocketClient({
+  webSocket: ws,
+  clientSchema: ClientMessageSchema,
+  serverSchema: ServerMessageSchema,
+  enableBufferMessages: true, // Enable msgpack serialization
+  onMessage: (message) => {
+    // Still fully typed!
+    console.log('Received via msgpack:', message);
+  },
+});
+
+// Messages automatically serialized with msgpack
+client.send({ type: 'chat', text: 'Efficient binary message!' });
+```
+
+### API Reference
+
+#### Constructor Options
+
+```typescript
+interface ZodWebSocketClientOptions<TClientMessage, TServerMessage> {
+  // Connection (provide one)
+  url?: string;                    // Create new WebSocket
+  webSocket?: WebSocket;           // Use existing WebSocket (e.g., from honoDoFetcher)
+  
+  // Schemas (required)
+  clientSchema: z.ZodType<TClientMessage>;
+  serverSchema: z.ZodType<TServerMessage>;
+  
+  // Serialization
+  enableBufferMessages?: boolean;  // Use msgpack instead of JSON (default: false)
+  
+  // Callbacks
+  onMessage: (message: TServerMessage) => void;
+  onOpen?: () => void;
+  onClose?: (event: CloseEvent) => void;
+  onError?: (event: Event) => void;
+  onValidationError?: (error: unknown) => void;
+}
+```
+
+#### Methods
+
+- `send(message: TClientMessage): void` - Send a validated message
+- `close(code?: number, reason?: string): void` - Close the connection
+- `waitForOpen(): Promise<void>` - Wait for connection to open
+
+## ZodSession (Validated Sessions)
+
+`ZodSession` extends `BaseSession` with automatic Zod validation for incoming messages.
+
+### Basic Usage
+
+```typescript
+import { ZodSession } from '@firtoz/websocket-do';
+import { z } from 'zod';
+
+// Define schemas
+const ClientMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('setName'), name: z.string().min(1).max(50) }),
+  z.object({ type: z.literal('message'), text: z.string().max(1000) }),
+]);
+
+const ServerMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('nameChanged'), newName: z.string() }),
+  z.object({ type: z.literal('message'), text: z.string(), from: z.string() }),
+  z.object({ type: z.literal('error'), message: z.string() }),
+]);
+
+type ClientMessage = z.infer<typeof ClientMessageSchema>;
+type ServerMessage = z.infer<typeof ServerMessageSchema>;
+
+interface SessionData {
+  name: string;
+}
+
+// Implement validated session
+class ChatSession extends ZodSession<
+  Env,
+  SessionData,
+  ServerMessage,
+  ClientMessage
+> {
+  protected clientSchema = ClientMessageSchema;
+  protected serverSchema = ServerMessageSchema;
+
+  protected createData(ctx: Context<{ Bindings: Env }>): SessionData {
+    return { name: 'Anonymous' };
+  }
+
+  async handleMessage(message: ClientMessage): Promise<void> {
+    // Message is already validated!
+    switch (message.type) {
+      case 'setName':
+        this.data.name = message.name;
+        this.update();
+        this.send({ type: 'nameChanged', newName: message.name });
+        break;
+      
+      case 'message':
+        this.broadcast({
+          type: 'message',
+          text: message.text,
+          from: this.data.name,
+        });
+        break;
+    }
+  }
+
+  async handleClose(): Promise<void> {
+    console.log(`${this.data.name} disconnected`);
+  }
+}
+```
+
+### Buffer Mode with ZodSession
+
+```typescript
+class ChatSession extends ZodSession<...> {
+  // Enable buffer mode for msgpack
+  protected enableBufferMessages = true;
+  
+  protected clientSchema = ClientMessageSchema;
+  protected serverSchema = ServerMessageSchema;
+  
+  // Messages automatically decoded from msgpack
+  async handleMessage(message: ClientMessage): Promise<void> {
+    // Handle validated message
+  }
+}
+```
+
 ## API Reference
 
 ### `BaseWebSocketDO<TEnv, TSession>`
@@ -315,6 +564,176 @@ async handleMessage(message: ClientMessage): Promise<void> {
 }
 ```
 
+## Exports
+
+This package exports the following:
+
+### Classes
+- `BaseWebSocketDO` - Abstract base class for WebSocket Durable Objects
+- `BaseSession` - Abstract base class for WebSocket sessions
+- `ZodWebSocketClient` - Type-safe WebSocket client with Zod validation
+- `ZodSession` - Session base class with Zod validation built-in
+- `WebsocketWrapper` - Low-level WebSocket wrapper with typed attachments
+
+### Utilities
+- `zodMsgpack` - Msgpack encode/decode with Zod validation
+
+### Types
+All classes export their type parameters and interfaces for custom implementations.
+
+## Complete Example
+
+Here's a full example combining all features:
+
+```typescript
+// schemas.ts
+import { z } from 'zod';
+
+export const ClientMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('setName'), name: z.string().min(1).max(50) }),
+  z.object({ type: z.literal('message'), text: z.string().max(1000) }),
+]);
+
+export const ServerMessageSchema = z.discriminatedUnion('type', [
+  z.object({ type: z.literal('nameChanged'), newName: z.string() }),
+  z.object({ type: z.literal('message'), text: z.string(), from: z.string() }),
+  z.object({ type: z.literal('userJoined'), name: z.string() }),
+  z.object({ type: z.literal('error'), message: z.string() }),
+]);
+
+export type ClientMessage = z.infer<typeof ClientMessageSchema>;
+export type ServerMessage = z.infer<typeof ServerMessageSchema>;
+
+// do.ts - Server-side (Durable Object)
+import { BaseWebSocketDO, ZodSession } from '@firtoz/websocket-do';
+import { ClientMessageSchema, ServerMessageSchema } from './schemas';
+
+interface SessionData {
+  name: string;
+  joinedAt: number;
+}
+
+class ChatSession extends ZodSession<Env, SessionData, ServerMessage, ClientMessage> {
+  protected clientSchema = ClientMessageSchema;
+  protected serverSchema = ServerMessageSchema;
+  protected enableBufferMessages = true; // Use msgpack for efficiency
+
+  protected createData(): SessionData {
+    return {
+      name: 'Anonymous',
+      joinedAt: Date.now(),
+    };
+  }
+
+  async handleMessage(message: ClientMessage): Promise<void> {
+    switch (message.type) {
+      case 'setName':
+        const oldName = this.data.name;
+        this.data.name = message.name;
+        this.update();
+        
+        this.send({ type: 'nameChanged', newName: message.name });
+        this.broadcast({ type: 'userJoined', name: message.name }, true);
+        break;
+      
+      case 'message':
+        this.broadcast({
+          type: 'message',
+          text: message.text,
+          from: this.data.name,
+        });
+        break;
+    }
+  }
+
+  async handleClose(): Promise<void> {
+    console.log(`${this.data.name} disconnected`);
+  }
+}
+
+export class ChatRoomDO extends BaseWebSocketDO<Env, ChatSession> {
+  app = this.getBaseApp()
+    .get('/info', (ctx) => {
+      const users = Array.from(this.sessions.values()).map(s => ({
+        name: s.data.name,
+        joinedAt: s.data.joinedAt,
+      }));
+      return ctx.json({ users, count: users.length });
+    });
+
+  protected createSession(websocket: WebSocket): ChatSession {
+    return new ChatSession(websocket, this.sessions);
+  }
+}
+
+// client.ts - Client-side
+import { ZodWebSocketClient } from '@firtoz/websocket-do';
+import { honoDoFetcherWithName } from '@firtoz/hono-fetcher';
+import { ClientMessageSchema, ServerMessageSchema } from './schemas';
+
+async function connectToChat(env: Env, roomName: string) {
+  // 1. Connect via honoDoFetcher
+  const api = honoDoFetcherWithName(env.CHAT_ROOM, roomName);
+  const wsResp = await api.websocket({
+    url: '/websocket',
+    config: { autoAccept: false },
+  });
+
+  // 2. Wrap with ZodWebSocketClient
+  const client = new ZodWebSocketClient({
+    webSocket: wsResp.webSocket,
+    clientSchema: ClientMessageSchema,
+    serverSchema: ServerMessageSchema,
+    enableBufferMessages: true, // Match server setting
+    onMessage: (message) => {
+      switch (message.type) {
+        case 'message':
+          console.log(`${message.from}: ${message.text}`);
+          break;
+        case 'userJoined':
+          console.log(`${message.name} joined!`);
+          break;
+        case 'nameChanged':
+          console.log(`Name changed to ${message.newName}`);
+          break;
+        case 'error':
+          console.error('Error:', message.message);
+          break;
+      }
+    },
+    onValidationError: (error) => {
+      console.error('Validation error:', error);
+    },
+  });
+
+  // 3. Accept connection
+  wsResp.webSocket?.accept();
+
+  // 4. Use type-safe client
+  client.send({ type: 'setName', name: 'Alice' });
+  client.send({ type: 'message', text: 'Hello everyone!' });
+
+  return client;
+}
+```
+
+## Testing
+
+This package includes comprehensive integration tests in a separate test package using `@cloudflare/vitest-pool-workers`, which provides full WebSocket testing capabilities in a Miniflare-based environment that closely mirrors production.
+
+**What can be tested:**
+- ✅ Worker routing to Durable Objects
+- ✅ HTTP endpoints on DOs  
+- ✅ DO state management and isolation
+- ✅ Full WebSocket connection lifecycle
+- ✅ Real-time WebSocket message exchange
+- ✅ WebSocket session management
+- ✅ Type-safe DO client integration
+- ✅ Zod validation in both JSON and msgpack modes
+- ✅ Integration between honoDoFetcher and ZodWebSocketClient
+
+For detailed information about testing capabilities, example implementations, comprehensive test coverage, and setup instructions, see the [websocket-do-test](../../tests/websocket-do-test/) package.
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@firtoz/websocket-do",
-	"version": "2.0.0",
+	"version": "4.0.0",
 	"description": "Type-safe WebSocket session management for Cloudflare Durable Objects with Hono integration",
 	"main": "./src/index.ts",
 	"module": "./src/index.ts",
@@ -21,9 +21,7 @@
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
-		"format": "biome format src --write",
-		"test": "bun test",
-		"test:watch": "bun test --watch"
+		"format": "biome format src --write"
 	},
 	"keywords": [
 		"typescript",
@@ -51,6 +49,11 @@
 		"@firtoz/hono-fetcher": "workspace:*",
 		"hono": "^4.9.10"
 	},
+	"optionalDependencies": {
+		"msgpackr": "^1.11.5",
+		"react": "^19.2.0",
+		"zod": "^4.1.12"
+	},
 	"engines": {
 		"node": ">=18.0.0"
 	},
@@ -58,6 +61,8 @@
 		"access": "public"
 	},
 	"devDependencies": {
-		"bun-types": "^1.2.23"
+		"@types/react": "^19.2.2",
+		"bun-types": "^1.3.0",
+		"typescript": "^5.9.3"
 	}
 }

package/src/ZodSession.ts

@@ -0,0 +1,157 @@
+import type { ZodType } from "zod";
+import { BaseSession } from "./BaseSession";
+import { zodMsgpack } from "./zodMsgpack";
+
+export interface ZodSessionOptions<TClientMessage, TServerMessage> {
+	clientSchema: ZodType<TClientMessage>;
+	serverSchema: ZodType<TServerMessage>;
+	enableBufferMessages?: boolean;
+}
+
+export abstract class ZodSession<
+	TEnv extends object = any,
+	TData = any,
+	TServerMessage = any,
+	TClientMessage = any,
+> extends BaseSession<TEnv, TData, TServerMessage, TClientMessage> {
+	protected readonly clientCodec: ReturnType<typeof zodMsgpack<TClientMessage>>;
+	protected readonly serverCodec: ReturnType<typeof zodMsgpack<TServerMessage>>;
+	protected readonly enableBufferMessages: boolean;
+
+	constructor(
+		websocket: WebSocket,
+		sessions: Map<
+			WebSocket,
+			ZodSession<TEnv, TData, TServerMessage, TClientMessage>
+		>,
+		protected options: ZodSessionOptions<TClientMessage, TServerMessage>,
+	) {
+		super(websocket, sessions);
+
+		this.clientCodec = zodMsgpack(options.clientSchema);
+		this.serverCodec = zodMsgpack(options.serverSchema);
+		this.enableBufferMessages = options.enableBufferMessages ?? false;
+	}
+
+	// Override the base handleMessage to add validation
+	async handleMessage(message: TClientMessage): Promise<void> {
+		// If buffer messages are enabled, reject JSON messages
+		if (this.enableBufferMessages) {
+			console.error(
+				"String messages not allowed when buffer messages are enabled",
+			);
+			await this.sendProtocolError(
+				"String messages are not allowed. Please use buffer messages.",
+			);
+			return;
+		}
+
+		try {
+			// Validate the message using the client schema
+			const validatedMessage = this.options.clientSchema.parse(message);
+			await this.handleValidatedMessage(validatedMessage);
+		} catch (error) {
+			console.error("Invalid client message received:", error);
+			await this.handleValidationError(error, message);
+		}
+	}
+
+	// Override buffer message handling to support msgpack decoding
+	async handleBufferMessage(buffer: ArrayBuffer): Promise<void> {
+		// If buffer messages are disabled, reject buffer messages
+		if (!this.enableBufferMessages) {
+			console.error(
+				"Buffer messages not allowed when buffer messages are disabled",
+			);
+			// We can't use sendProtocolError here because it would send JSON
+			// Just close the connection or ignore
+			return;
+		}
+
+		try {
+			const bytes = new Uint8Array(buffer);
+			const decodedMessage = this.clientCodec.decode(bytes);
+			await this.handleValidatedMessage(decodedMessage);
+		} catch (error) {
+			console.error("Failed to decode buffer message:", error);
+			await this.handleValidationError(error, buffer);
+		}
+	}
+
+	// Type-safe send method that automatically uses the correct format
+	protected send(message: TServerMessage): void {
+		if (this.enableBufferMessages) {
+			this.sendBuffer(message);
+		} else {
+			this.sendJson(message);
+		}
+	}
+
+	// Explicitly send as JSON
+	private sendJson(message: TServerMessage): void {
+		try {
+			// Validate the message using the server schema
+			const validatedMessage = this.options.serverSchema.parse(message);
+
+			if (this.websocket.readyState !== WebSocket.OPEN) return;
+
+			this.websocket.send(JSON.stringify(validatedMessage));
+		} catch (error) {
+			console.error("Invalid server message to send:", error);
+		}
+	}
+
+	// Explicitly send as buffer using msgpack
+	private sendBuffer(message: TServerMessage): void {
+		try {
+			const encodedMessage = this.serverCodec.encode(message);
+
+			if (this.websocket.readyState !== WebSocket.OPEN) return;
+
+			this.websocket.send(encodedMessage);
+		} catch (error) {
+			console.error("Failed to encode buffer message:", error);
+		}
+	}
+
+	// Send a protocol error message (always as JSON for compatibility)
+	private async sendProtocolError(errorMessage: string): Promise<void> {
+		try {
+			// Send a simple error object - no schema validation needed
+			if (this.websocket.readyState !== WebSocket.OPEN) return;
+			this.websocket.send(JSON.stringify({ error: errorMessage }));
+		} catch (error) {
+			console.error("Failed to send protocol error:", error);
+		}
+	}
+
+	// Type-safe broadcast that validates server messages
+	// Automatically uses the correct format based on session configuration
+	protected broadcast(message: TServerMessage, excludeSelf = false): void {
+		for (const session of this.sessions.values()) {
+			if (excludeSelf && session === this) continue;
+			if (session instanceof ZodSession) {
+				session.send(message); // send() automatically uses correct format
+			}
+		}
+	}
+
+	// Abstract methods for implementers
+	protected abstract handleValidatedMessage(
+		message: TClientMessage,
+	): Promise<void>;
+
+	// Optional error handling - default implementation logs and continues
+	protected async handleValidationError(
+		error: unknown,
+		originalMessage: unknown,
+	): Promise<void> {
+		console.error(
+			"Validation error:",
+			error,
+			"Original message:",
+			originalMessage,
+		);
+		// Implementers can override this to send error responses to clients
+	}
+}

package/src/ZodWebSocketClient.ts

@@ -0,0 +1,201 @@
+import { pack, unpack } from "msgpackr";
+import type { ZodType } from "zod";
+
+export interface ZodWebSocketClientOptions<TClientMessage, TServerMessage> {
+	/**
+	 * URL to connect to (required if webSocket not provided)
+	 */
+	url?: string;
+	/**
+	 * Existing WebSocket to wrap (alternative to url)
+	 * Useful when getting a WebSocket from honoDoFetcher
+	 */
+	webSocket?: WebSocket;
+	clientSchema: ZodType<TClientMessage>;
+	serverSchema: ZodType<TServerMessage>;
+	enableBufferMessages?: boolean;
+	onMessage?: (message: TServerMessage) => void;
+	onOpen?: (event: Event) => void;
+	onClose?: (event: CloseEvent) => void;
+	onError?: (event: Event) => void;
+	onValidationError?: (error: unknown, rawMessage: unknown) => void;
+}
+
+export class ZodWebSocketClient<TClientMessage, TServerMessage> {
+	private ws: WebSocket;
+	private readonly clientSchema: ZodType<TClientMessage>;
+	private readonly serverSchema: ZodType<TServerMessage>;
+	private readonly enableBufferMessages: boolean;
+	private readonly onMessageCallback?: (message: TServerMessage) => void;
+	private readonly onValidationError?: (
+		error: unknown,
+		rawMessage: unknown,
+	) => void;
+
+	constructor(
+		options: ZodWebSocketClientOptions<TClientMessage, TServerMessage>,
+	) {
+		this.clientSchema = options.clientSchema;
+		this.serverSchema = options.serverSchema;
+		this.enableBufferMessages = options.enableBufferMessages ?? false;
+		this.onMessageCallback = options.onMessage;
+		this.onValidationError = options.onValidationError;
+
+		// Use provided WebSocket or create new one from URL
+		if (options.webSocket) {
+			// Use existing WebSocket (e.g., from honoDoFetcher)
+			this.ws = options.webSocket;
+		} else if (options.url) {
+			// Create new WebSocket from URL
+			this.ws = new WebSocket(options.url);
+		} else {
+			throw new Error("Either 'url' or 'webSocket' must be provided");
+		}
+
+		// Set binary type for buffer messages
+		if (this.enableBufferMessages) {
+			this.ws.binaryType = "arraybuffer";
+		}
+
+		// Setup event handlers
+		this.ws.addEventListener("open", (event) => {
+			options.onOpen?.(event);
+		});
+
+		this.ws.addEventListener("message", (event) => {
+			this.handleMessage(event);
+		});
+
+		this.ws.addEventListener("close", (event) => {
+			options.onClose?.(event);
+		});
+
+		this.ws.addEventListener("error", (event) => {
+			options.onError?.(event);
+		});
+	}
+
+	private handleMessage(event: MessageEvent): void {
+		try {
+			let parsedMessage: TServerMessage;
+
+			if (this.enableBufferMessages) {
+				// Buffer mode: expect ArrayBuffer
+				if (!(event.data instanceof ArrayBuffer)) {
+					console.error(
+						"Expected ArrayBuffer but received:",
+						typeof event.data,
+					);
+					this.onValidationError?.(
+						new Error("Expected ArrayBuffer in buffer mode"),
+						event.data,
+					);
+					return;
+				}
+
+				// Unpack and validate
+				const unpacked = unpack(new Uint8Array(event.data));
+				parsedMessage = this.serverSchema.parse(unpacked);
+			} else {
+				// JSON mode: expect string
+				if (typeof event.data !== "string") {
+					console.error("Expected string but received:", typeof event.data);
+					this.onValidationError?.(
+						new Error("Expected string in JSON mode"),
+						event.data,
+					);
+					return;
+				}
+
+				// Parse and validate
+				const parsed = JSON.parse(event.data);
+				parsedMessage = this.serverSchema.parse(parsed);
+			}
+
+			// Call message handler
+			this.onMessageCallback?.(parsedMessage);
+		} catch (error) {
+			console.error("Failed to process message:", error);
+			this.onValidationError?.(error, event.data);
+		}
+	}
+
+	/**
+	 * Send a message (automatically encodes based on mode)
+	 */
+	send(message: TClientMessage): void {
+		try {
+			// Validate message
+			const validatedMessage = this.clientSchema.parse(message);
+
+			if (this.enableBufferMessages) {
+				// Encode as msgpack
+				const packed = pack(validatedMessage);
+				this.ws.send(packed);
+			} else {
+				// Encode as JSON
+				this.ws.send(JSON.stringify(validatedMessage));
+			}
+		} catch (error) {
+			console.error("Failed to send message:", error);
+			throw error;
+		}
+	}
+
+	/**
+	 * Close the WebSocket connection
+	 */
+	close(code?: number, reason?: string): void {
+		this.ws.close(code, reason);
+	}
+
+	/**
+	 * Get the current WebSocket ready state
+	 */
+	get readyState(): number {
+		return this.ws.readyState;
+	}
+
+	/**
+	 * Get the underlying WebSocket instance (use with caution)
+	 */
+	get socket(): WebSocket {
+		return this.ws;
+	}
+
+	/**
+	 * Wait for the connection to open
+	 */
+	async waitForOpen(): Promise<void> {
+		if (this.ws.readyState === WebSocket.OPEN) {
+			return;
+		}
+
+		return new Promise((resolve, reject) => {
+			const abortController = new AbortController();
+			const { signal } = abortController;
+
+			const cleanup = () => {
+				abortController.abort();
+			};
+
+			this.ws.addEventListener(
+				"open",
+				() => {
+					cleanup();
+					resolve();
+				},
+				{ signal },
+			);
+
+			this.ws.addEventListener(
+				"error",
+				() => {
+					cleanup();
+					reject(new Error("WebSocket connection failed"));
+				},
+				{ signal },
+			);
+		});
+	}
+}

package/src/ZodWebSocketDO.ts

@@ -0,0 +1,24 @@
+import { BaseWebSocketDO } from "./BaseWebSocketDO";
+import type { ZodSession, ZodSessionOptions } from "./ZodSession";
+
+export abstract class ZodWebSocketDO<
+	TEnv extends object,
+	TSession extends ZodSession<TEnv, any, any, any>,
+	TClientMessage = any,
+	TServerMessage = any,
+> extends BaseWebSocketDO<TEnv, TSession> {
+	protected abstract getZodOptions(): ZodSessionOptions<
+		TClientMessage,
+		TServerMessage
+	>;
+
+	protected abstract createZodSession(
+		websocket: WebSocket,
+		options: ZodSessionOptions<TClientMessage, TServerMessage>,
+	): TSession | Promise<TSession>;
+
+	protected createSession(websocket: WebSocket): TSession | Promise<TSession> {
+		const options = this.getZodOptions();
+		return this.createZodSession(websocket, options);
+	}
+}

package/src/index.ts

@@ -1,3 +1,10 @@
 export { BaseSession, type SessionClientMessage } from "./BaseSession";
 export { BaseWebSocketDO } from "./BaseWebSocketDO";
 export { WebsocketWrapper } from "./WebsocketWrapper";
+export { ZodSession, type ZodSessionOptions } from "./ZodSession";
+export {
+	ZodWebSocketClient,
+	type ZodWebSocketClientOptions,
+} from "./ZodWebSocketClient";
+export { ZodWebSocketDO } from "./ZodWebSocketDO";
+export { zodMsgpack } from "./zodMsgpack";

package/src/zodMsgpack.ts

@@ -0,0 +1,13 @@
+import { pack, unpack } from "msgpackr";
+import type { ZodType } from "zod";
+
+export const zodMsgpack = <T>(schema: ZodType<T>) => ({
+	encode(value: T): Uint8Array {
+		const validated = schema.parse(value);
+		const packed = pack(validated);
+		return new Uint8Array(packed);
+	},
+	decode(bytes: Uint8Array): T {
+		return schema.parse(unpack(bytes));
+	},
+});