feat(kkrpc): add WebSocketLike interface for adapter compatibility

Add WebSocketLike interface to support multiple WebSocket implementations
including DOM WebSocket, ws library, and Bun native WebSocket. This allows
WebSocketServerIO to work with different WebSocket backends without type
casting or adapter code.

- Add WebSocketLike interface in websocket adapter
- Add Bun native WebSocket server example
- Configure strict TypeScript mode for streaming demo
- Update documentation with Bun server option

Author: HuakunShen

.journal/2026-02-07.md

@@ -128,3 +128,36 @@ The initial response carries `{ __stream: true }` to signal the consumer to crea
 - **Bidirectional streaming** — current design is server→client only. Client→server streaming would need a `sendStream()` API on the proxy
 - **Stream timeout** — currently streams can run indefinitely. A per-stream idle timeout could auto-cancel stalled streams
 - **PLANNING.md removed** — all 4 major roadmap items (middleware, streaming, timeout, type safety) are complete
+
+## 01:47 — WebSocketLike interface + Bun native WebSocket support
+
+### Core Decision/Topic
+
+Fixed a type issue where `WebSocketServerIO` required a DOM `WebSocket` but the `ws` library's `WebSocket` type didn't fully match (missing `dispatchEvent`, `URL`). Added a structural `WebSocketLike` interface and created a Bun-native WebSocket server example.
+
+### Options Considered
+
+- **Cast in user code** (`ws as unknown as WebSocket`) — works but ugly, leaks implementation detail to users
+- **Structural interface** (`WebSocketLike`) — defines only the members actually used (`onmessage`, `onerror`, `send`, `close`). Works with DOM WebSocket, `ws` library, and Bun's `ServerWebSocket` via a thin wrapper. Chosen approach.
+
+### Final Decision & Rationale
+
+**Structural typing over nominal:** The adapter only needs 4 operations. By defining `WebSocketLike` with those exact members, we accept anything that quacks like a WebSocket — no casts needed.
+
+**Bun's callback-based API:** Bun uses `websocket: { message(ws, msg) }` callbacks rather than event setters. We bridge this with a wrapper stored in a `Map<ServerWebSocket, WebSocketLike>` — Bun's callbacks route to our wrapper's `onmessage` handler.
+
+### Key Changes Made
+
+| File | Change |
+|---|---|
+| `packages/kkrpc/src/adapters/websocket.ts` | Added exported `WebSocketLike` interface; changed `WebSocketServerIO` constructor to accept `WebSocketLike` instead of DOM `WebSocket` |
+| `examples/streaming-middleware-demo/server.ts` | Removed cast; now passes `ws` directly |
+| `examples/streaming-middleware-demo/server-bun.ts` | New file — Bun native WebSocket server using `Bun.serve()` with WebSocket upgrade |
+| `examples/streaming-middleware-demo/package.json` | Added `server:bun` script; added `typescript` devDependency |
+| `examples/streaming-middleware-demo/tsconfig.json` | New file — strict TypeScript config with `noUncheckedIndexedAccess` |
+
+### Future Considerations
+
+- **First-party Bun adapter** — could add `BunWebSocketIO` to kkrpc core that wraps Bun's native API directly, avoiding the user-space wrapper
+- **Deno WebSocket** — similar pattern could work for Deno's native WebSocket server
+- **WebSocketLike in client** — currently only server uses this; client still creates `new WebSocket()`. Could extend pattern if needed for non-DOM environments

bun.lock

@@ -21,6 +21,8 @@ Demonstrates kkrpc's AsyncIterable streaming and interceptor middleware over Web
 
 ## Run
 
+### Option 1: `ws` library (works with Node.js, Bun, Deno)
+
 ```bash
 # Terminal 1 — start the server
 bun run server.ts
@@ -29,6 +31,18 @@ bun run server.ts
 bun run client.ts
 ```
 
+### Option 2: Bun native WebSocket (Bun only)
+
+```bash
+# Terminal 1 — start the Bun native server
+bun run server-bun.ts
+
+# Terminal 2 — run the client (same client works with both servers)
+bun run client.ts
+```
+
+Both servers are interchangeable — the client connects to `ws://localhost:3100` and works the same way.
+
 ## How middleware works in kkrpc
 
 Interceptors follow the **onion model** (like Koa, tRPC). Each interceptor wraps the next, and the innermost layer is the actual handler.

deno.lock

@@ -61,8 +61,8 @@ export function createApi(session: { authenticated: boolean; username: string })
 			let seq = 0
 			while (true) {
 				await sleep(300 + Math.random() * 700)
-				const level = levels[Math.floor(Math.random() * levels.length)]
-				const message = messages[Math.floor(Math.random() * messages.length)]
+				const level = levels[Math.floor(Math.random() * levels.length)]!
+				const message = messages[Math.floor(Math.random() * messages.length)]!
 				yield {
 					timestamp: new Date().toISOString(),
 					level,

examples/streaming-middleware-demo/README.md

@@ -3,13 +3,16 @@
 	"private": true,
 	"scripts": {
 		"server": "bun run server.ts",
-		"client": "bun run client.ts"
+		"server:bun": "bun run server-bun.ts",
+		"client": "bun run client.ts",
+		"check-types": "tsc --noEmit"
 	},
 	"dependencies": {
 		"kkrpc": "workspace:*",
 		"ws": "^8.18.0"
 	},
 	"devDependencies": {
-		"@types/bun": "latest"
+		"@types/bun": "latest",
+		"typescript": "^5.0.0"
 	}
 }

examples/streaming-middleware-demo/api.ts

@@ -0,0 +1,133 @@
+/**
+ * Streaming + Middleware demo — Bun native WebSocket server.
+ *
+ * Demonstrates four interceptor patterns:
+ *   1. Logging    — logs every RPC call with method name and args
+ *   2. Timing     — measures and logs execution time per call
+ *   3. Auth       — blocks protected methods unless the session is authenticated
+ *   4. Rate limit — limits calls per second, rejects excess with an error
+ *
+ * Run with: bun run server-bun.ts
+ * Then in another terminal: bun run client.ts
+ */
+import { RPCChannel, WebSocketServerIO, type RPCInterceptor, type WebSocketLike } from "kkrpc"
+import { createApi, type StreamingMiddlewareAPI } from "./api.ts"
+
+const PORT = 3100
+
+// Map to track Bun ServerWebSocket -> our wrapper
+const connections = new Map<any, WebSocketLike>()
+
+// ─── Interceptor factories ───────────────────────────────────────────────────
+
+const logger: RPCInterceptor = async (ctx, next) => {
+	const argsStr = ctx.args.map((a) => (typeof a === "object" ? JSON.stringify(a) : String(a))).join(", ")
+	console.log(`  [log]  ${ctx.method}(${argsStr})`)
+	return next()
+}
+
+const timing: RPCInterceptor = async (ctx, next) => {
+	const start = performance.now()
+	const result = await next()
+	const elapsed = (performance.now() - start).toFixed(1)
+	console.log(`  [time] ${ctx.method} → ${elapsed}ms`)
+	return result
+}
+
+function createAuthInterceptor(session: { authenticated: boolean; username: string }): RPCInterceptor {
+	const protectedMethods = new Set(["getSecretData"])
+	return async (ctx, next) => {
+		if (protectedMethods.has(ctx.method) && !session.authenticated) {
+			throw new Error(`Unauthorized: '${ctx.method}' requires authentication. Call login() first.`)
+		}
+		return next()
+	}
+}
+
+function createRateLimiter(max: number, windowMs: number = 1000): RPCInterceptor {
+	const calls: number[] = []
+	return async (ctx, next) => {
+		const now = Date.now()
+		while (calls.length > 0 && calls[0]! <= now - windowMs) {
+			calls.shift()
+		}
+		if (calls.length >= max) {
+			throw new Error(`Rate limit exceeded: max ${max} calls per ${windowMs}ms. Try again shortly.`)
+		}
+		calls.push(now)
+		return next()
+	}
+}
+
+// ─── Bun WebSocket wrapper ───────────────────────────────────────────────────
+
+/**
+ * Creates a WebSocketLike wrapper around Bun's ServerWebSocket.
+ * Bun uses a different pattern (callback-based) vs DOM WebSocket (event setters).
+ * This wrapper bridges the two patterns.
+ */
+function createBunWebSocketLike(bunWs: any): WebSocketLike {
+	return {
+		onmessage: null,
+		onerror: null,
+		send(data: string) {
+			bunWs.send(data)
+		},
+		close() {
+			bunWs.close()
+		}
+	}
+}
+
+// ─── Bun server setup ────────────────────────────────────────────────────────
+
+console.log(`[server] Streaming + Middleware demo (Bun native) listening on ws://localhost:${PORT}`)
+console.log(`[server] Interceptors: logger → timing → auth → rateLimiter`)
+
+Bun.serve({
+	port: PORT,
+	fetch(req, server) {
+		// Upgrade HTTP request to WebSocket
+		if (server.upgrade(req)) {
+			return // Upgraded successfully
+		}
+		return new Response("WebSocket upgrade failed", { status: 400 })
+	},
+	websocket: {
+		open(bunWs) {
+			console.log("[server] Client connected")
+
+			// Create wrapper that implements WebSocketLike
+			const wrapper = createBunWebSocketLike(bunWs)
+			connections.set(bunWs, wrapper)
+
+			// Each connection gets its own session and interceptors
+			const session = { authenticated: false, username: "" }
+			const api = createApi(session)
+			const auth = createAuthInterceptor(session)
+			const rateLimiter = createRateLimiter(5)
+
+			new RPCChannel<StreamingMiddlewareAPI, {}>(new WebSocketServerIO(wrapper), {
+				expose: api,
+				interceptors: [logger, timing, auth, rateLimiter]
+			})
+		},
+		message(bunWs, message) {
+			// Route Bun message to our wrapper's onmessage handler
+			const wrapper = connections.get(bunWs)
+			if (wrapper?.onmessage) {
+				wrapper.onmessage({ data: message })
+			}
+		},
+		close(bunWs, code, reason) {
+			const wrapper = connections.get(bunWs)
+			if (wrapper) {
+				// Trigger any cleanup
+				wrapper.onmessage = null
+				wrapper.onerror = null
+				connections.delete(bunWs)
+			}
+			console.log(`[server] Client disconnected`)
+		}
+	}
+})

examples/streaming-middleware-demo/package.json

@@ -69,7 +69,7 @@ function createRateLimiter(max: number, windowMs: number = 1000): RPCInterceptor
 	return async (ctx, next) => {
 		const now = Date.now()
 		// Evict timestamps outside the window
-		while (calls.length > 0 && calls[0] <= now - windowMs) {
+		while (calls.length > 0 && calls[0]! <= now - windowMs) {
 			calls.shift()
 		}
 		if (calls.length >= max) {

examples/streaming-middleware-demo/server-bun.ts

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}

examples/streaming-middleware-demo/server.ts

@@ -113,6 +113,30 @@ export class WebSocketClientIO implements IoInterface {
 	}
 }
 
+/**
+ * Minimal WebSocket interface accepted by WebSocketServerIO.
+ *
+ * This is a structural type covering only the members actually used,
+ * so it works with both the DOM WebSocket and the `ws` library's WebSocket
+ * without requiring a cast.
+ */
+/**
+ * Minimal WebSocket interface accepted by WebSocketServerIO.
+ *
+ * This is a structural type covering only the members actually used,
+ * so it works with both the DOM WebSocket and the `ws` library's WebSocket
+ * without requiring a cast.
+ *
+ * NOTE: The handler types use `any` for event parameters to allow assignment
+ * from both DOM WebSocket (MessageEvent) and ws library (any) types.
+ */
+export interface WebSocketLike {
+	onmessage: ((event: any) => void) | null
+	onerror: ((event: any) => void) | null
+	send(data: string): void
+	close(): void
+}
+
 /**
  * WebSocket Server implementation of IoInterface
  */
@@ -127,7 +151,7 @@ export class WebSocketServerIO implements IoInterface {
 		transfer: false
 	}
 
-	constructor(private ws: WebSocket) {
+	constructor(private ws: WebSocketLike) {
 		this.ws.onmessage = (event) => {
 			let message = event.data
 			if (typeof message === "object" && message !== null && "toString" in message) {