kkrpc 0.4.0 → 0.6.0

package/README.md

@@ -1,49 +1,109 @@
-# kkrpc
+<div align="center">
 
-> This project is created for building extension system for a Tauri app (https://github.com/kunkunsh/kunkun).
+
+# 🚀 kkrpc
+
+## TypeScript-First RPC Library
+
+[![NPM Version](https://img.shields.io/npm/v/kkrpc?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/kkrpc)
+[![JSR Version](https://img.shields.io/jsr/v/@kunkun/kkrpc?style=for-the-badge&logo=deno)](https://jsr.io/@kunkun/kkrpc)
+[![License](https://img.shields.io/npm/l/kkrpc?style=for-the-badge)](https://github.com/kunkunsh/kkrpc/blob/main/LICENSE)
+[![Downloads](https://img.shields.io/npm/dm/kkrpc?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/kkrpc)
+[![GitHub stars](https://img.shields.io/github/stars/kunkunsh/kkrpc?style=for-the-badge&logo=github)](https://github.com/kunkunsh/kkrpc)
+[![Typedoc Documentation](https://img.shields.io/badge/Docs-Typedoc-blue?style=for-the-badge&logo=typescript)](https://kunkunsh.github.io/kkrpc/)
+[![Excalidraw Diagrams](https://img.shields.io/badge/Diagrams-Excalidraw-orange?style=for-the-badge&logo=drawio)](https://excalidraw.com/#json=xp6GbAJVAx3nU-h3PhaxW,oYBNvYmCRsQ2XR3MQo73Ug)
+
+</div>
+
+> This project was created for building extension system for a Tauri app ([kunkun](https://github.com/kunkunsh/kunkun)).
 >
 > It can potentially be used in other types of apps, so I open sourced it as a standalone package.
 
-[![NPM Version](https://img.shields.io/npm/v/kkrpc)](https://www.npmjs.com/package/kkrpc)
-[![JSR Version](https://jsr.io/badges/@kunkun/kkrpc)](https://jsr.io/@kunkun/kkrpc)
-![GitHub last commit](https://img.shields.io/github/last-commit/kunkunsh/kkrpc)
+**Seamless bi-directional communication between processes, workers, and contexts**
+
+Call remote functions as if they were local, with full TypeScript type safety and autocompletion support.
+
+**Similar to Comlink but with bidirectional communication** and support for multiple environments - both client and server can expose functions for the other to call across Node.js, Deno, Bun, and browser environments.
+
+[**Quick Start**](#-quick-start) • [**Documentation**](https://kunkunsh.github.io/kkrpc/) • [**Examples**](#-examples) • [**API Reference**](https://jsr.io/@kunkun/kkrpc/doc)
+
+<div align="center">
 
-> A TypeScript-first RPC library that enables seamless bi-directional communication between processes.
-> Call remote functions as if they were local, with full TypeScript type safety and autocompletion support.
+<img src="https://imgur.com/vR3Lmv0.png" style="max-height: 200px; margin: 10px;"/>
+<img src="https://i.imgur.com/zmOHNfu.png" style="max-height: 250px; margin: 10px;"/>
+<img src="https://imgur.com/u728aVv.png" style="max-height: 400px; margin: 10px;"/>
+<img src="https://i.imgur.com/Gu7jH1v.png" style="max-height: 300px; margin: 10px;"/>
 
-- [JSR Package](https://jsr.io/@kunkun/kkrpc)
-- [NPM Package](https://www.npmjs.com/package/kkrpc)
-- [Documentation by JSR](https://jsr.io/@kunkun/kkrpc/doc)
-- [Typedoc Documentation](https://kunkunsh.github.io/kkrpc/)
+</div>
 
-[Excalidraw Diagrams](https://excalidraw.com/#json=xp6GbAJVAx3nU-h3PhaxW,oYBNvYmCRsQ2XR3MQo73Ug)
+---
 
-<img src="https://imgur.com/vR3Lmv0.png" style="max-height: 200px;"/>
-<img src="https://i.imgur.com/zmOHNfu.png" style="max-height: 250px;"/>
-<img src="https://imgur.com/u728aVv.png" style="max-height: 400px;"/>
-<img src="https://i.imgur.com/Gu7jH1v.png" style="max-height: 300px;"/>
+## 🌟 Why kkrpc?
 
-## Features
+kkrpc stands out in the crowded RPC landscape by offering **true cross-runtime compatibility** without sacrificing type safety or developer experience. Unlike tRPC (HTTP-only) or Comlink (browser-only), kkrpc enables seamless communication across Node.js, Deno, Bun, and browser environments.
+
+## ✨ Features
+
+<div align="center">
+
+| Feature | Description |
+|---------|-------------|
+| **🔄 Cross-runtime** | Works seamlessly across Node.js, Deno, Bun, browsers, and more |
+| **🛡️ Type-safe** | Full TypeScript inference and IDE autocompletion support |
+| **↔️ Bidirectional** | Both endpoints can expose and call APIs simultaneously |
+| **🏠 Property Access** | Remote getters/setters with dot notation (`await api.prop`) |
+| **💥 Error Preservation** | Complete error objects across RPC boundaries |
+| **🌐 Multiple Transports** | stdio, HTTP, WebSocket, postMessage, Chrome extensions |
+| **📞 Callback Support** | Remote functions can accept callback functions |
+| **🔗 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 |
+| **🚀 Transferable Objects** | Zero-copy transfers for large data (40-100x faster) |
+
+</div>
+
+## 🌍 Supported Environments
+
+<div align="center">
+
+```mermaid
+graph LR
+    A[kkrpc] --> B[Node.js]
+    A --> C[Deno]
+    A --> D[Bun]
+    A --> E[Browser]
+    A --> F[Chrome Extension]
+    A --> G[Tauri]
+    
+    B -.-> H[stdio]
+    C -.-> H
+    D -.-> H
+    
+    E -.-> I[postMessage]
+    E -.-> J[Web Workers]
+    E -.-> K[iframes]
+    
+    F -.-> L[Chrome Ports]
+    
+    G -.-> M[Shell Plugin]
+    
+    style A fill:#ff6b6b,stroke:#333,stroke-width:2px
+```
 
-- **Cross-runtime compatibility**: Works seamlessly across Node.js, Deno, Bun, browsers, and more
-- **Type-safe remote calls**: Full TypeScript inference and IDE autocompletion support
-- **Bidirectional communication**: Both endpoints can expose and call APIs simultaneously
-- **Property access**: Remote property getters and setters with dot notation (`await api.prop`, `api.prop = value`)
-- **Enhanced error preservation**: Complete error object preservation across RPC boundaries including stack traces, causes, and custom properties
-- **Multiple transport protocols**: stdio, HTTP, WebSocket, postMessage, Chrome extensions
-- **Callback support**: Remote functions can accept callback functions as parameters
-- **Nested object calls**: Deep method chaining like `api.math.operations.calculate()`
-- **Automatic serialization**: Intelligent detection between JSON and superjson formats
-- **Zero configuration**: No schema files or code generation required
+</div>
 
-## Supported Environments
+### 📡 Transport Protocols
 
-- stdio: RPC over stdio between any combinations of Node.js, Deno, Bun processes
-- web: RPC over `postMessage` API and message channel between browser main thread and web workers, or main thread and iframe
-  - Web Worker API (web standard) is also supported in Deno and Bun, the main thread can call functions in worker and vice versa.
-- http: RPC over HTTP like tRPC
-  - supports any HTTP server (e.g. hono, bun, nodejs http, express, fastify, deno, etc.)
-- WebSocket: RPC over WebSocket
+| Transport | Use Case | Supported Runtimes |
+|-----------|----------|-------------------|
+| **stdio** | Process-to-process communication | Node.js ↔ Deno ↔ Bun |
+| **postMessage** | Browser context communication | Browser ↔ Web Workers ↔ iframes |
+| **HTTP** | Web API communication | All runtimes |
+| **WebSocket** | Real-time communication | All runtimes |
+| **Hono WebSocket** | High-performance WebSocket with Hono framework | Node.js, Deno, Bun, Cloudflare Workers |
+| **Socket.IO** | Enhanced real-time with rooms/namespaces | All runtimes |
+| **Elysia WebSocket** | Modern TypeScript framework WebSocket integration | Bun, Node.js, Deno |
+| **Chrome Extension** | Extension component communication | Chrome Extension contexts |
 
 The core of **kkrpc** design is in `RPCChannel` and `IoInterface`.
 
@@ -99,9 +159,64 @@ 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.
 
-## Examples
+## 🚀 Quick Start
+
+### Installation
+
+<div align="center">
+
+```bash
+# npm
+npm install kkrpc
+
+# yarn
+yarn add kkrpc
+
+# pnpm
+pnpm add kkrpc
+
+# deno
+import { RPCChannel } from "jsr:@kunkun/kkrpc"
+```
+
+</div>
+
+### Basic Example
+
+<div align="center">
+
+```typescript
+// server.ts
+import { RPCChannel, NodeIo } from "kkrpc"
+
+const api = {
+  greet: (name: string) => `Hello, ${name}!`,
+  add: (a: number, b: number) => a + b
+}
+
+const rpc = new RPCChannel(new NodeIo(process.stdin, process.stdout), {
+  expose: api
+})
+```
+
+```typescript
+// client.ts
+import { RPCChannel, NodeIo } from "kkrpc"
+import { spawn } from "child_process"
+
+const worker = spawn("deno", ["run", "server.ts"])
+const rpc = new RPCChannel(new NodeIo(worker.stdout, worker.stdin))
+const api = rpc.getAPI<typeof api>()
+
+console.log(await api.greet("World")) // "Hello, World!"
+console.log(await api.add(5, 3))      // 8
+```
 
-Below are simple examples.
+</div>
+
+## 📚 Examples
+
+Below are simple examples to get you started quickly.
 
 ### Stdio Example
 
@@ -223,6 +338,205 @@ const sum = await api.add(1, 2)
 expect(sum).toBe(3)
 ```
 
+### Transferable Objects Example
+
+kkrpc supports zero-copy transfer of large data structures using browser's native transferable objects. This provides 40-100x performance improvement for large binary data transfers.
+
+```ts
+import { RPCChannel, WorkerParentIO, transfer } from "kkrpc/browser"
+
+const worker = new Worker("worker.js")
+const io = new WorkerParentIO(worker)
+const rpc = new RPCChannel(io)
+const api = rpc.getAPI<{
+  processBuffer(buffer: ArrayBuffer): Promise<number>
+  generateData(size: number): Promise<ArrayBuffer>
+}>()
+
+// Create a large buffer (10MB)
+const buffer = new ArrayBuffer(10 * 1024 * 1024)
+console.log("Before transfer:", buffer.byteLength) // 10485760
+
+// Transfer buffer to worker (zero-copy)
+const result = await api.processBuffer(transfer(buffer, [buffer]))
+console.log("Worker processed:", result, "bytes")
+
+// Buffer is now neutered (transferred ownership)
+console.log("After transfer:", buffer.byteLength) // 0
+
+// Get data back from worker (also transferred)
+const newBuffer = await api.generateData(5 * 1024 * 1024)
+console.log("Received from worker:", newBuffer.byteLength) // 5242880
+```
+
+### Hono WebSocket Example
+
+Hono WebSocket adapter provides seamless integration with the Hono framework's high-performance WebSocket support.
+
+#### `server.ts`
+
+```ts
+import { Hono } from 'hono'
+import { upgradeWebSocket, websocket } from 'hono/bun'
+import { createHonoWebSocketHandler } from 'kkrpc'
+import { apiMethods, type API } from './api'
+
+const app = new Hono()
+
+app.get('/ws', upgradeWebSocket(() => {
+  return createHonoWebSocketHandler<API>({
+    expose: apiMethods
+  })
+}))
+
+const server = Bun.serve({
+  port: 3000,
+  fetch: app.fetch,
+  websocket
+})
+
+console.log(`Server running on port ${server.port}`)
+```
+
+#### `client.ts`
+
+```ts
+import { WebSocketClientIO, RPCChannel } from 'kkrpc'
+import { apiMethods, type API } from './api'
+
+const clientIO = new WebSocketClientIO({
+  url: 'ws://localhost:3000/ws'
+})
+
+const clientRPC = new RPCChannel<API, API>(clientIO, {
+  expose: apiMethods
+})
+
+const api = clientRPC.getAPI()
+
+// Test basic RPC calls
+console.log(await api.add(5, 3)) // 8
+console.log(await api.echo("Hello from Hono!")) // "Hello from Hono!"
+
+// Test nested API calls
+console.log(await api.math.grade2.multiply(4, 6)) // 24
+
+// Test property access
+console.log(await api.counter) // 42
+console.log(await api.nested.value) // "hello world"
+
+clientIO.destroy()
+```
+
+**Hono WebSocket Features:**
+- **High Performance**: Built on Hono's ultra-fast WebSocket implementation
+- **Cross-runtime**: Works across Bun, Deno, Node.js, and Cloudflare Workers
+- **Type-safe**: Full TypeScript support with Hono integration
+- **Bidirectional**: Both client and server can expose APIs
+- **Framework Integration**: Seamless integration with Hono's middleware ecosystem
+
+**Learn more:** [Hono WebSocket Documentation](https://hono.dev/docs/helpers/websocket)
+
+### Elysia WebSocket Example
+
+Elysia WebSocket adapter provides seamless integration with the modern TypeScript-first Elysia framework and its uWebSocket-powered WebSocket support.
+
+#### `server.ts`
+
+```ts
+import { Elysia } from 'elysia'
+import { ElysiaWebSocketServerIO, RPCChannel } from 'kkrpc'
+import { apiMethods, type API } from './api'
+
+// Extend API for Elysia-specific features
+interface ElysiaAPI extends API {
+  getConnectionInfo(): Promise<{
+    remoteAddress: string | undefined
+    query: Record<string, string>
+    headers: Record<string, string>
+  }>
+}
+
+const app = new Elysia()
+  .ws('/rpc', {
+    open(ws) {
+      const io = new ElysiaWebSocketServerIO(ws)
+      const elysiaApiMethods: ElysiaAPI = {
+        ...apiMethods,
+        getConnectionInfo: async () => ({
+          remoteAddress: io.getRemoteAddress(),
+          query: io.getQuery(),
+          headers: io.getHeaders()
+        })
+      }
+
+      const rpc = new RPCChannel<ElysiaAPI, ElysiaAPI>(io, {
+        expose: elysiaApiMethods
+      })
+    },
+    message(ws, message) {
+      ElysiaWebSocketServerIO.feedMessage(ws, message)
+    }
+  })
+  .listen(3000)
+
+console.log('Elysia server running on port 3000')
+```
+
+#### `client.ts`
+
+```ts
+import { ElysiaWebSocketClientIO, RPCChannel } from 'kkrpc'
+import { apiMethods, type API } from './api'
+
+const clientIO = new ElysiaWebSocketClientIO('ws://localhost:3000/rpc')
+const clientRPC = new RPCChannel<API, any>(clientIO, {
+  expose: apiMethods
+})
+
+const api = clientRPC.getAPI()
+
+// Test basic RPC calls
+console.log(await api.add(5, 3)) // 8
+console.log(await api.echo("Hello from Elysia!")) // "Hello from Elysia!"
+
+// Test nested API calls
+console.log(await api.math.grade1.add(10, 20)) // 30
+console.log(await api.math.grade3.divide(20, 4)) // 5
+
+// Test Elysia-specific features
+const connInfo = await api.getConnectionInfo()
+console.log('Connected from:', connInfo.remoteAddress)
+console.log('Query params:', connInfo.query)
+console.log('Headers:', connInfo.headers)
+
+clientIO.destroy()
+```
+
+**Elysia WebSocket Features:**
+- **Modern Framework**: Built on Elysia's TypeScript-first design
+- **Ultra-fast**: Powered by uWebSocket for maximum performance
+- **Rich Metadata**: Access to connection info, query params, and headers
+- **Type-safe**: Full TypeScript inference and autocompletion
+- **Runtime Flexible**: Works across Bun, Node.js, and Deno
+- **Developer Experience**: Clean API with factory functions
+
+**Learn more:** [Elysia WebSocket Documentation](https://elysiajs.com/patterns/websocket)
+
+**Key Benefits:**
+- **Zero-copy performance**: No serialization/deserialization overhead
+- **Memory efficient**: Ownership transfers without copying
+- **Automatic fallback**: Graceful degradation for non-transferable transports
+- **Type-safe**: Full TypeScript support
+
+**Supported Transferable Types:**
+- `ArrayBuffer` - Binary data buffers
+- `MessagePort` - Communication channels
+- `ImageBitmap` - Decoded image data
+- `OffscreenCanvas` - Off-screen canvas rendering
+- `ReadableStream`/`WritableStream` - Streaming data
+- And more... [See MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects)
+
 ### HTTP Example
 
 Codesandbox: https://codesandbox.io/p/live/4a349334-0b04-4352-89f9-cf1955553ae7
@@ -419,3 +733,99 @@ async function spawnCmd(runtime: "deno" | "bun" | "node") {
 I provided a sample tauri app in `examples/tauri-demo`.
 
 ![Sample Tauri App](https://i.imgur.com/nkDwRHk.png)
+
+## 🆚 Comparison with Alternatives
+
+<div align="center">
+
+| Feature | kkrpc | tRPC | Comlink |
+|---------|-------|------|---------|
+| **Cross-runtime** | ✅ Node.js, Deno, Bun, Browser | ❌ Node.js/Browser only | ❌ Browser only |
+| **Bidirectional** | ✅ Both sides can call APIs | ❌ Client calls server only | ✅ Both sides can call APIs |
+| **Type Safety** | ✅ Full TypeScript support | ✅ Full TypeScript support | ✅ TypeScript support |
+| **Transport Layers** | ✅ stdio, HTTP, WebSocket, postMessage, Chrome Extension | ❌ HTTP only | ❌ postMessage only |
+| **Error Preservation** | ✅ Complete error objects | ⚠️ Limited error serialization | ⚠️ Limited error serialization |
+| **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 |
+| **Transferable Objects** | ✅ Zero-copy transfers (40-100x faster) | ❌ Not supported | ✅ Basic support |
+
+</div>
+
+### When to choose kkrpc
+
+- **Cross-process communication**: Need to communicate between different runtimes (Node.js ↔ Deno, Browser ↔ Node.js, etc.)
+- **Extension systems**: Building plugin architectures or extension systems
+- **Tauri applications**: Communicating between Tauri frontend and backend processes
+- **Chrome extensions**: Complex communication between content scripts, background pages, and popups
+- **Multi-worker architectures**: Coordinating multiple web workers with different responsibilities
+- **Desktop applications**: Electron/Tauri apps with multiple processes
+
+### When to choose tRPC
+
+- **REST API replacement**: Building type-safe APIs for web applications
+- **HTTP-only communication**: When you only need HTTP-based communication
+- **React/Next.js integration**: When you need tight integration with React ecosystem
+- **Database-driven APIs**: When building traditional client-server applications
+
+### When to choose Comlink
+
+- **Browser-only applications**: Simple web worker communication in browsers
+- **Lightweight needs**: When you only need basic postMessage abstraction
+- **No cross-runtime requirements**: When all your code runs in browsers
+- **Simple worker patterns**: When you don't need advanced features like property access
+
+## 🔍 Keywords & SEO
+
+**Primary Keywords**: RPC, TypeScript, Remote Procedure Call, Type-safe, Bidirectional, Cross-runtime
+
+**Secondary Keywords**: Node.js, Deno, Bun, Browser, Web Worker, Chrome Extension, Tauri, IPC, Inter-process Communication
+
+**Use Cases**: Extension system, Plugin architecture, Microservices, Worker communication, Cross-context communication
+
+## 📦 Package Information
+
+<div align="center">
+
+| Platform | Package | Link |
+|----------|---------|------|
+| **NPM** | `kkrpc` | [![NPM](https://img.shields.io/badge/npm-kkrpc-red?style=flat-square&logo=npm)](https://www.npmjs.com/package/kkrpc) |
+| **JSR** | `@kunkun/kkrpc` | [![JSR](https://img.shields.io/badge/jsr-@kunkun/kkrpc-blue?style=flat-square&logo=deno)](https://jsr.io/@kunkun/kkrpc) |
+| **GitHub** | Repository | [![GitHub](https://img.shields.io/badge/github-kkrpc-black?style=flat-square&logo=github)](https://github.com/kunkunsh/kkrpc) |
+| **Docs** | Typedoc | [![Docs](https://img.shields.io/badge/docs-typedoc-blue?style=flat-square&logo=typescript)](https://kunkunsh.github.io/kkrpc/) |
+| **Examples** | Code Samples | [![Examples](https://img.shields.io/badge/examples-code-green?style=flat-square&logo=github)](https://github.com/kunkunsh/kkrpc/tree/main/examples) |
+
+</div>
+
+## 🤝 Contributing
+
+<div align="center">
+
+**Contributions are welcome!** 🎉
+
+Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+
+[![GitHub issues](https://img.shields.io/github/issues/kunkunsh/kkrpc?style=flat-square&logo=github)](https://github.com/kunkunsh/kkrpc/issues)
+[![GitHub pull requests](https://img.shields.io/github/issues-pr/kunkunsh/kkrpc?style=flat-square&logo=github)](https://github.com/kunkunsh/kkrpc/pulls)
+
+</div>
+
+## 📄 License
+
+<div align="center">
+
+[![License](https://img.shields.io/npm/l/kkrpc?style=flat-square)](https://github.com/kunkunsh/kkrpc/blob/main/LICENSE)
+
+MIT © [kunkunsh](https://github.com/kunkunsh)
+
+</div>
+
+---
+
+<div align="center">
+
+**⭐ Star this repo if it helped you!**
+
+Made with ❤️ by the kkrpc team
+
+</div>