kkrpc 0.2.2 → 0.5.0

package/README.md

@@ -1,36 +1,107 @@
-# 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's potential can be used in other types of apps, so I open sourced it as a standalone package.
+> It can potentially be used in other types of apps, so I open sourced it as a standalone package.
+
+**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">
+
+<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;"/>
+
+</div>
+
+---
+
+## 🌟 Why kkrpc?
+
+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.
 
-[![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)
+## ✨ Features
 
-> 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.
+<div align="center">
 
-- [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/)
+| 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) |
 
-[Excalidraw Diagrams](https://excalidraw.com/#json=xp6GbAJVAx3nU-h3PhaxW,oYBNvYmCRsQ2XR3MQo73Ug)
+</div>
 
-<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;"/>
+## 🌍 Supported Environments
 
-## Supported Environments
+<div align="center">
 
-- 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
+```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
+```
+
+</div>
+
+### 📡 Transport Protocols
+
+| 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 |
+| **Socket.IO** | Enhanced real-time with rooms/namespaces | All runtimes |
+| **Chrome Extension** | Extension component communication | Chrome Extension contexts |
 
 The core of **kkrpc** design is in `RPCChannel` and `IoInterface`.
 
@@ -86,9 +157,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"
 
-Below are simple examples.
+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
+```
+
+</div>
+
+## 📚 Examples
+
+Below are simple examples to get you started quickly.
 
 ### Stdio Example
 
@@ -111,6 +237,81 @@ const api = parent.getAPI()
 expect(await api.add(1, 2)).toBe(3)
 ```
 
+### Property Access Example
+
+kkrpc supports direct property access and mutation across RPC boundaries:
+
+```ts
+// Define API with properties
+interface API {
+	add(a: number, b: number): Promise<number>
+	counter: number
+	settings: {
+		theme: string
+		notifications: {
+			enabled: boolean
+		}
+	}
+}
+
+const api = rpc.getAPI<API>()
+
+// Property getters (using await for remote access)
+const currentCount = await api.counter
+const theme = await api.settings.theme
+const notificationsEnabled = await api.settings.notifications.enabled
+
+// Property setters (direct assignment)
+api.counter = 42
+api.settings.theme = "dark"
+api.settings.notifications.enabled = true
+
+// Verify changes
+console.log(await api.counter) // 42
+console.log(await api.settings.theme) // "dark"
+```
+
+### Enhanced Error Preservation
+
+kkrpc preserves complete error information across RPC boundaries:
+
+```ts
+// Custom error class
+class DatabaseError extends Error {
+	constructor(message: string, public code: number, public query: string) {
+		super(message)
+		this.name = 'DatabaseError'
+	}
+}
+
+// API with error-throwing method
+const apiImplementation = {
+	async getUserById(id: string) {
+		if (!id) {
+			const error = new DatabaseError("Invalid user ID", 400, "SELECT * FROM users WHERE id = ?")
+			error.timestamp = new Date().toISOString()
+			error.requestId = generateRequestId()
+			throw error
+		}
+		// ... normal logic
+	}
+}
+
+// Error handling on client side
+try {
+	await api.getUserById("")
+} catch (error) {
+	// All error properties are preserved:
+	console.log(error.name)      // "DatabaseError"
+	console.log(error.message)   // "Invalid user ID"
+	console.log(error.code)      // 400
+	console.log(error.query)     // "SELECT * FROM users WHERE id = ?"
+	console.log(error.stack)     // Full stack trace
+	console.log(error.timestamp) // ISO timestamp
+	console.log(error.requestId) // Request ID
+}
+```
+
 ### Web Worker Example
 
 ```ts
@@ -135,6 +336,51 @@ 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
+```
+
+**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
@@ -208,52 +454,60 @@ console.log("Sum: ", sum)
 
 ### Chrome Extension Example
 
+For Chrome extensions, use the dedicated `ChromePortIO` adapter for reliable, port-based communication.
+
 #### `background.ts`
 
 ```ts
-import { ChromeBackgroundIO, RPCChannel } from "kkrpc"
-import type { API } from "./api"
+import { ChromePortIO, RPCChannel } from "kkrpc/chrome-extension";
+import type { BackgroundAPI, ContentAPI } from "./types";
 
-// Store RPC channels for each tab
-const rpcChannels = new Map<number, RPCChannel<API, {}>>()
+const backgroundAPI: BackgroundAPI = {
+  async getExtensionVersion() {
+    return chrome.runtime.getManifest().version;
+  },
+};
 
-// Listen for tab connections
 chrome.runtime.onConnect.addListener((port) => {
-	if (port.sender?.tab?.id) {
-		const tabId = port.sender.tab.id
-		const io = new ChromeBackgroundIO(tabId)
-		const rpc = new RPCChannel(io, { expose: backgroundAPI })
-		rpcChannels.set(tabId, rpc)
-
-		port.onDisconnect.addListener(() => {
-			rpcChannels.delete(tabId)
-		})
-	}
-})
+  if (port.name === "content-to-background") {
+    const io = new ChromePortIO(port);
+    const rpc = new RPCChannel(io, { expose: backgroundAPI });
+    // Handle disconnect
+    port.onDisconnect.addListener(() => io.destroy());
+  }
+});
 ```
 
 #### `content.ts`
 
 ```ts
-import { ChromeContentIO, RPCChannel } from "kkrpc"
-import type { API } from "./api"
-
-const io = new ChromeContentIO()
-const rpc = new RPCChannel<API, API>(io, {
-	expose: {
-		updateUI: async (data) => {
-			document.body.innerHTML = data.message
-			return true
-		}
-	}
-})
+import { ChromePortIO, RPCChannel } from "kkrpc/chrome-extension";
+import type { BackgroundAPI, ContentAPI } from "./types";
 
-// Get API from background script
-const api = rpc.getAPI()
-const data = await api.getData()
-console.log(data) // { message: "Hello from background!" }
+const contentAPI: ContentAPI = {
+  async getPageTitle() {
+    return document.title;
+  },
+};
+
+const port = chrome.runtime.connect({ name: "content-to-background" });
+const io = new ChromePortIO(port);
+const rpc = new RPCChannel<ContentAPI, BackgroundAPI>(io, { expose: contentAPI });
+
+const backgroundAPI = rpc.getAPI();
+
+// Example call
+backgroundAPI.getExtensionVersion().then(version => {
+  console.log("Extension version:", version);
+});
 ```
 
+**Chrome Extension Features:**
+- **Port-based**: Uses `chrome.runtime.Port` for stable, long-lived connections.
+- **Bidirectional**: Both sides can expose and call APIs.
+- **Type-safe**: Full TypeScript support for your APIs.
+- **Reliable**: Handles connection lifecycle and cleanup.
+
 ### Tauri Example
 
 Call functions in bun/node/deno processes from Tauri app with JS/TS.
@@ -323,3 +577,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>