kkrpc 0.6.1 → 0.6.3

package/README.md

@@ -29,6 +29,29 @@ Call remote functions as if they were local, with full TypeScript type safety an
 
 [**Quick Start**](#-quick-start) • [**Documentation**](https://kunkunsh.github.io/kkrpc/) • [**Examples**](#-examples) • [**API Reference**](https://jsr.io/@kunkun/kkrpc/doc) • [**LLM Docs**](https://docs.kkrpc.kunkun.sh/llms.txt) • [**中文文档**](./README.zh.md)
 
+## 🎥 Video Tutorial
+
+[![kkrpc Tutorial](https://img.youtube.com/vi/CF8lji8eB30/0.jpg)](https://youtu.be/CF8lji8eB30)
+
+Watch this video for a comprehensive introduction to kkrpc and how to use it in your projects.
+
+## 🤖 AI Support
+
+Working with kkrpc in your AI-powered editor? Add these skills to your Claude Code configuration to get intelligent assistance:
+
+```bash
+# Copy kkrpc skills to your global Claude Code skills folder
+cp -r skills/kkrpc ~/.claude/skills/
+cp -r skills/interop ~/.claude/skills/
+```
+
+This provides your AI assistant with:
+
+- **kkrpc skill**: How to use kkrpc in TypeScript projects
+- **interop skill**: How to implement kkrpc clients/servers in other languages (Go, Python, Rust, Swift)
+
+See [`skills/`](./skills/) directory for details.
+
 <div align="center">
 
 <img src="https://imgur.com/19XswxO.jpg" style="max-width: 800px; width: 100%; margin-bottom: 20px;"/>
@@ -61,6 +84,10 @@ kkrpc stands out in the crowded RPC landscape by offering **true cross-runtime c
 | **🔗 Nested Calls**         | Deep method chaining like `api.math.operations.calculate()`    |
 | **📦 Auto Serialization**   | Intelligent JSON/superjson detection                           |
 | **⚡ Zero Config**          | No schema files or code generation required                    |
+| **🔒 Data Validation**      | Optional runtime validation with Zod, Valibot, ArkType, etc.   |
+| **🔌 Middleware**           | Interceptor chain for logging, auth, timing, and more          |
+| **⏱️ Request Timeout**      | Auto-reject pending calls after a configurable deadline        |
+| **🔁 Streaming**            | Return `AsyncIterable` from methods, consume with `for await`  |
 | **🚀 Transferable Objects** | Zero-copy transfers for large data (40-100x faster)            |
 
 </div>
@@ -167,11 +194,188 @@ const rpc = new RPCChannel(io, {
 
 For backward compatibility, the receiving side will automatically detect the serialization format so older clients can communicate with newer servers and vice versa.
 
-## 🚀 Quick Start
+## Data Validation
 
-### Installation
+kkrpc supports optional runtime validation of RPC inputs and outputs using any [Standard Schema](https://standardschema.dev)-compatible library (Zod, Valibot, ArkType, etc.). Validation is fully opt-in — without it, kkrpc behaves exactly as before.
+
+There are two approaches:
+
+### Type-first (add validators to existing code)
+
+Define your API as usual, then add a `validators` map that mirrors the API shape:
+
+```ts
+import { RPCChannel, type RPCValidators } from "kkrpc"
+import { z } from "zod"
+
+type MathAPI = {
+	add(a: number, b: number): Promise<number>
+	divide(a: number, b: number): Promise<number>
+}
+
+const api: MathAPI = {
+	add: async (a, b) => a + b,
+	divide: async (a, b) => a / b
+}
 
+const validators: RPCValidators<MathAPI> = {
+	add: {
+		input: z.tuple([z.number(), z.number()]),
+		output: z.number()
+	},
+	divide: {
+		input: z.tuple([z.number(), z.number().refine((n) => n !== 0, "Divisor cannot be zero")]),
+		output: z.number()
+	}
+}
+
+new RPCChannel(io, { expose: api, validators })
+```
+
+### Schema-first (types inferred from schemas)
+
+Use `defineMethod` and `defineAPI` to define your API with schemas — types are inferred automatically:
+
+```ts
+import { defineAPI, defineMethod, extractValidators, RPCChannel, type InferAPI } from "kkrpc"
+import { z } from "zod"
+
+const api = defineAPI({
+	add: defineMethod(
+		{ input: z.tuple([z.number(), z.number()]), output: z.number() },
+		async (a, b) => a + b // a, b are typed as number
+	),
+	greet: defineMethod(
+		{ input: z.tuple([z.string()]), output: z.string() },
+		async (name) => `Hello, ${name}!`
+	)
+})
+
+type MyAPI = InferAPI<typeof api>
+
+new RPCChannel(io, { expose: api, validators: extractValidators(api) })
+```
+
+### Validation errors
+
+When validation fails, the caller receives an `RPCValidationError` with structured issue details:
+
+```ts
+import { isRPCValidationError } from "kkrpc"
+
+try {
+	await api.add("not", "numbers") // wrong types
+} catch (error) {
+	if (isRPCValidationError(error)) {
+		error.phase // "input" or "output"
+		error.method // "add"
+		error.issues // [{ message: "Expected number, received string", path: [0] }]
+	}
+}
+```
 
+Validators support nested APIs (`math.divide`), custom refinements (`.email()`, `.min(1)`, `.refine()`), and output validation. Since kkrpc is bidirectional, both sides can independently validate their own exposed API.
+
+## Middleware / Interceptors
+
+kkrpc supports an optional interceptor chain that wraps handler invocation on the receiving side. Interceptors use the standard onion model (like Koa or tRPC) — each interceptor calls `next()` to proceed, and can inspect args, transform return values, measure timing, or throw to abort.
+
+```ts
+import { RPCChannel, type RPCInterceptor } from "kkrpc"
+
+const logger: RPCInterceptor = async (ctx, next) => {
+	console.log(`→ ${ctx.method}`, ctx.args)
+	const result = await next()
+	console.log(`← ${ctx.method}`, result)
+	return result
+}
+
+const auth: RPCInterceptor = async (ctx, next) => {
+	if (ctx.method.startsWith("admin.")) throw new Error("Unauthorized")
+	return next()
+}
+
+new RPCChannel(io, {
+	expose: api,
+	interceptors: [logger, auth]
+})
+```
+
+Interceptors run **after** input validation and **before** output validation, so they always see clean, validated data. Each interceptor receives a `ctx` object with `method`, `args`, and a shared `state` bag for passing data between interceptors. When no interceptors are configured, there is zero overhead.
+
+## Request Timeout
+
+kkrpc supports optional request timeouts to prevent pending calls from hanging forever if the remote side crashes or the transport drops:
+
+```ts
+import { isRPCTimeoutError, RPCChannel } from "kkrpc"
+
+const rpc = new RPCChannel(io, {
+	expose: api,
+	timeout: 5000 // 5 second timeout for all outgoing calls
+})
+
+try {
+	await api.slowOperation()
+} catch (error) {
+	if (isRPCTimeoutError(error)) {
+		console.log(error.method) // "slowOperation"
+		console.log(error.timeoutMs) // 5000
+	}
+}
+```
+
+When `destroy()` is called, all pending requests are immediately rejected with `"RPC channel destroyed"`. The default is `0` (no timeout).
+
+## Streaming / AsyncIterable
+
+kkrpc supports first-class streaming via `AsyncIterable`. If an RPC method returns an `AsyncIterable` (e.g. an async generator), the values are streamed chunk-by-chunk to the consumer, who can read them with `for await...of`:
+
+```ts
+// Server: return an async generator
+const api = {
+	async *countdown(from: number) {
+		for (let i = from; i >= 0; i--) {
+			yield i
+		}
+	},
+	async *watchFiles(path: string) {
+		const watcher = fs.watch(path)
+		try {
+			for await (const event of watcher) {
+				yield event
+			}
+		} finally {
+			watcher.close()
+		}
+	}
+}
+
+new RPCChannel(io, { expose: api })
+```
+
+```ts
+// Client: consume with for-await-of
+const api = rpc.getAPI()
+
+const values: number[] = []
+for await (const n of await api.countdown(5)) {
+	values.push(n)
+}
+// values = [5, 4, 3, 2, 1, 0]
+
+// Consumer cancellation: break stops the producer
+for await (const event of await api.watchFiles("/tmp")) {
+	console.log(event)
+	if (shouldStop) break // sends cancel signal to producer
+}
+```
+
+Streaming works alongside regular methods, interceptors, and validation. Producer errors propagate to the consumer, and `break` sends a cancel signal back to stop production. When `destroy()` is called, all active streams are cleaned up.
+
+## 🚀 Quick Start
+
+### Installation
 
 ```bash
 # npm
@@ -275,6 +479,140 @@ console.log(await api.counter) // 42
 console.log(await api.settings.theme) // "dark"
 ```
 
+### Validation Example (Type-first)
+
+Add runtime validation to an existing API using the `validators` option:
+
+```ts
+// api.ts
+import type { RPCValidators } from "kkrpc"
+import { z } from "zod"
+
+export type API = {
+	add(a: number, b: number): Promise<number>
+	createUser(user: {
+		name: string
+		email: string
+	}): Promise<{ id: string; name: string; email: string }>
+}
+
+export const api: API = {
+	add: async (a, b) => a + b,
+	createUser: async (user) => ({ id: crypto.randomUUID(), ...user })
+}
+
+export const validators: RPCValidators<API> = {
+	add: {
+		input: z.tuple([z.number(), z.number()]),
+		output: z.number()
+	},
+	createUser: {
+		input: z.tuple([z.object({ name: z.string().min(1), email: z.string().email() })]),
+		output: z.object({ id: z.string(), name: z.string(), email: z.string() })
+	}
+}
+```
+
+```ts
+// server.ts
+import { RPCChannel, WebSocketServerIO } from "kkrpc"
+import { api, validators, type API } from "./api"
+
+wss.on("connection", (ws) => {
+	const io = new WebSocketServerIO(ws)
+	new RPCChannel<API, API>(io, { expose: api, validators })
+})
+```
+
+```ts
+// client.ts
+import { isRPCValidationError, RPCChannel, WebSocketClientIO } from "kkrpc"
+import type { API } from "./api"
+
+const io = new WebSocketClientIO({ url: "ws://localhost:3000" })
+const rpc = new RPCChannel<{}, API>(io)
+const api = rpc.getAPI()
+
+// Valid calls work as usual
+console.log(await api.add(1, 2)) // 3
+
+// Invalid calls throw RPCValidationError
+try {
+	await api.createUser({ name: "", email: "not-an-email" })
+} catch (error) {
+	if (isRPCValidationError(error)) {
+		console.log(error.phase) // "input"
+		console.log(error.issues) // validation issues from Zod
+	}
+}
+```
+
+### Validation Example (Schema-first)
+
+Define your API with schemas — types are inferred automatically, no separate type definition needed:
+
+```ts
+// api.ts
+import { defineAPI, defineMethod, extractValidators, type InferAPI } from "kkrpc"
+import { z } from "zod"
+
+export const api = defineAPI({
+	add: defineMethod(
+		{ input: z.tuple([z.number(), z.number()]), output: z.number() },
+		async (a, b) => a + b
+	),
+	greet: defineMethod(
+		{ input: z.tuple([z.string()]), output: z.string() },
+		async (name) => `Hello, ${name}!`
+	),
+	math: {
+		divide: defineMethod(
+			{
+				input: z.tuple([z.number(), z.number().refine((n) => n !== 0, "Cannot divide by zero")]),
+				output: z.number()
+			},
+			async (a, b) => a / b
+		)
+	}
+})
+
+export type API = InferAPI<typeof api>
+export const validators = extractValidators(api)
+```
+
+```ts
+// server.ts
+import { RPCChannel, WebSocketServerIO } from "kkrpc"
+import { api, validators } from "./api"
+
+wss.on("connection", (ws) => {
+	const io = new WebSocketServerIO(ws)
+	new RPCChannel(io, { expose: api, validators })
+})
+```
+
+```ts
+// client.ts
+import { isRPCValidationError, RPCChannel, WebSocketClientIO } from "kkrpc"
+import type { API } from "./api"
+
+const io = new WebSocketClientIO({ url: "ws://localhost:3000" })
+const rpc = new RPCChannel<{}, API>(io)
+const api = rpc.getAPI()
+
+console.log(await api.greet("World")) // "Hello, World!"
+console.log(await api.math.divide(10, 2)) // 5
+
+try {
+	await api.math.divide(10, 0)
+} catch (error) {
+	if (isRPCValidationError(error)) {
+		console.log(error.method) // "math.divide"
+		console.log(error.issues[0].message) // "Cannot divide by zero"
+	}
+}
+```
+
 ### Enhanced Error Preservation
 
 kkrpc preserves complete error information across RPC boundaries:
@@ -1250,6 +1588,92 @@ const rpc = new RPCChannel<WorkerAPI, {}>(io, {
 - **Multiple channels**: Can create multiple relays on different IPC channels
 - **Composable**: Can chain relays through multiple processes
 
+## 📊 Benchmarks
+
+kkrpc includes comprehensive benchmarks to measure throughput and data transfer performance across different transports and runtimes.
+
+### Running Benchmarks
+
+```bash
+# Run all benchmarks
+bun test __tests__/stdio-benchmark.test.ts
+bun test __tests__/websocket-benchmark.test.ts
+bun test __tests__/stdio-large-data-benchmark.test.ts
+bun test __tests__/websocket-large-data-benchmark.test.ts
+
+# Or run all tests including benchmarks
+bun test
+```
+
+### Benchmark Design
+
+The benchmarks are designed to measure two key aspects of RPC performance:
+
+1. **Call Throughput** (`stdio-benchmark.test.ts`, `websocket-benchmark.test.ts`)
+   - **Sequential Operations**: Measures latency per call when making blocking calls one after another
+   - **Concurrent Operations**: Measures throughput when making many calls in parallel using `Promise.all`
+   - **Batch Operations**: Tests batching multiple operations into a single RPC call
+   - **Latency Distribution**: Pings the server 1,000 times to calculate min/avg/p99/max latency
+
+2. **Data Transfer Throughput** (`stdio-large-data-benchmark.test.ts`, `websocket-large-data-benchmark.test.ts`)
+   - **Upload**: Client sends large data payloads to the server
+   - **Download**: Server generates and sends large data to the client
+   - **Echo**: Bidirectional transfer (client sends, server echoes back)
+   - Tests various payload sizes: 1KB, 10KB, 100KB, 1MB, 10MB
+
+### Benchmark Results
+
+Results from running on a MacBook Pro (Apple Silicon):
+
+#### Stdio Adapter (Process-to-Process)
+
+| Runtime     | Operation       | Calls/sec         | Latency (avg) |
+| ----------- | --------------- | ----------------- | ------------- |
+| **Bun**     | Sequential Echo | 22,234            | 0.046ms       |
+| **Bun**     | Concurrent Echo | 151,069           | -             |
+| **Bun**     | Batch (100 ops) | 453,042 effective | -             |
+| **Node.js** | Sequential Echo | 23,985            | 0.038ms       |
+| **Node.js** | Concurrent Echo | 145,516           | -             |
+| **Deno**    | Sequential Echo | 20,028            | 0.047ms       |
+| **Deno**    | Concurrent Echo | 123,079           | -             |
+
+#### Stdio Large Data Transfer
+
+| Runtime     | Operation    | 1MB Payload | 10MB Payload |
+| ----------- | ------------ | ----------- | ------------ |
+| **Bun**     | Upload       | ~1,010 MB/s | ~658 MB/s    |
+| **Bun**     | Download     | ~134 MB/s   | ~132 MB/s    |
+| **Bun**     | Echo (100KB) | ~1,132 MB/s | -            |
+| **Node.js** | Upload       | ~382 MB/s   | ~92 MB/s     |
+| **Node.js** | Download     | ~75 MB/s    | ~30 MB/s     |
+| **Deno**    | Upload       | ~358 MB/s   | ~91 MB/s     |
+| **Deno**    | Download     | ~74 MB/s    | ~33 MB/s     |
+
+#### WebSocket Adapter
+
+| Operation       | Calls/sec         | Latency (avg) |
+| --------------- | ----------------- | ------------- |
+| Sequential Echo | 22,314            | 0.040ms       |
+| Concurrent Echo | 74,954            | -             |
+| Batch (100 ops) | 483,318 effective | -             |
+
+#### WebSocket Large Data Transfer
+
+| Operation    | 1MB Payload | 10MB Payload |
+| ------------ | ----------- | ------------ |
+| Upload       | ~577 MB/s   | ~927 MB/s    |
+| Download     | ~137 MB/s   | ~149 MB/s    |
+| Echo (100KB) | ~799 MB/s   | -            |
+
+### Key Findings
+
+- **Bun** consistently outperforms Node.js and Deno for stdio communication, especially for large data transfers
+- **Stdio** is significantly faster than WebSocket for local process communication (2-3x higher throughput)
+- **Concurrent operations** achieve 6-7x higher throughput than sequential operations
+- **Batching** is highly effective - 100 operations per batch achieves 400K+ effective calls/sec
+- **Upload** is faster than download due to JSON serialization overhead on the response path
+- **WebSocket** performance is excellent for network communication, nearly matching stdio for small payloads
+
 ## 🆚 Comparison with Alternatives
 
 <div align="center">
@@ -1264,6 +1688,10 @@ const rpc = new RPCChannel<WorkerAPI, {}>(io, {
 | **Property Access**      | ✅ Remote getters/setters                                          | ❌ Methods only                | ❌ Methods only                |
 | **Zero Config**          | ✅ No code generation                                              | ✅ No code generation          | ✅ No code generation          |
 | **Callbacks**            | ✅ Function parameters                                             | ❌ No callbacks                | ✅ Function parameters         |
+| **Data Validation**      | ✅ Optional, any Standard Schema library                           | ✅ Built-in Zod support        | ❌ Not supported               |
+| **Middleware**           | ✅ Interceptor chain (onion model)                                 | ✅ `.use()` middleware         | ❌ Not supported               |
+| **Request Timeout**      | ✅ Per-channel timeout + destroy cleanup                           | ❌ Not built-in                | ❌ Not supported               |
+| **Streaming**            | ✅ AsyncIterable with cancel + error propagation                   | ✅ SSE subscriptions           | ❌ Not supported               |
 | **Transferable Objects** | ✅ Zero-copy transfers (40-100x faster)                            | ❌ Not supported               | ✅ Basic support               |
 
 </div>