kkrpc

name: kkrpc description: Build bidirectional RPC systems in TypeScript with kkrpc. Create RPC channels, expose APIs, use multiple transports (stdio, WebSocket, HTTP), handle callbacks, property access, and errors across Node.js, Deno, Bun, and browsers. version: 1.0.0 license: MIT metadata: author: kkrpc domain: typescript-rpc tags: - rpc - typescript - bidirectional - ipc - websocket - stdio - cross-runtime

compatibility: Works in Node.js, Deno, Bun, and browsers with appropriate entry points

kkrpc - TypeScript RPC Library

Build bidirectional RPC systems in TypeScript with full type safety and multiple transport options.

Installation

# npm
npm install kkrpc

# pnpm
pnpm add kkrpc

# Deno
import { RPCChannel } from "jsr:@kunkun/kkrpc"

Quick Start

Basic RPC Setup

Server (expose API):

import { NodeIo, RPCChannel } from "kkrpc"

const api = {
    greet: (name: string) => `Hello, ${name}!`,
    add: (a: number, b: number) => a + b,
    counter: 42
}

const rpc = new RPCChannel(new NodeIo(process.stdin, process.stdout), { expose: api })

Client (consume API):

import { spawn } from "child_process"
import { NodeIo, RPCChannel } from "kkrpc"

const worker = spawn("bun", ["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
console.log(await api.counter) // 42

Core Concepts

RPCChannel

The main class that manages bidirectional communication:

class RPCChannel<LocalAPI extends Record<string, any>, RemoteAPI extends Record<string, any>> {
    constructor(
        io: IoInterface,
        options?: {
            expose?: LocalAPI
            serialization?: { version: "json" | "superjson" }
            validators?: RPCValidators<LocalAPI>
        }
    )

    getAPI(): RemoteAPI // Get proxy to remote API
    expose(api: LocalAPI): void // Expose local API
}

IoInterface (Transports)

Transport adapters for different environments:

API Definition Patterns

Pattern 1: Inline API (Simple)

const api = {
    greet: (name: string) => `Hello, ${name}!`,
    add: (a: number, b: number) => a + b
}

type API = typeof api

const rpc = new RPCChannel<API, API>(io, { expose: api })
const remote = rpc.getAPI()

Pattern 2: Interface-First (Recommended)

interface MathAPI {
    add(a: number, b: number): Promise<number>
    multiply(a: number, b: number): Promise<number>
}

interface MyAPI {
    math: MathAPI
    greet(name: string): Promise<string>
}

const api: MyAPI = {
    math: {
        add: async (a, b) => a + b,
        multiply: async (a, b) => a * b
    },
    greet: async (name) => `Hello, ${name}!`
}

const rpc = new RPCChannel<MyAPI, MyAPI>(io, { expose: api })

Pattern 3: Nested APIs

interface API {
    math: {
        basic: {
            add(a: number, b: number): Promise<number>
            subtract(a: number, b: number): Promise<number>
        }
        advanced: {
            pow(base: number, exp: number): Promise<number>
            sqrt(n: number): Promise<number>
        }
    }
}

// Usage
const result = await api.math.advanced.pow(2, 10) // 1024

Transport Examples

Stdio (Process Communication)

import { spawn } from "child_process"
import { NodeIo, RPCChannel } from "kkrpc"

// Spawn child process
const child = spawn("bun", ["worker.ts"])

// Create channel
const io = new NodeIo(child.stdout, child.stdin)
const rpc = new RPCChannel<LocalAPI, RemoteAPI>(io, { expose: localApi })

// Get remote API
const api = rpc.getAPI()

WebSocket

import { RPCChannel, WebSocketClientIO, WebSocketServerIO } from "kkrpc"

// Server
wss.on("connection", (ws) => {
    const io = new WebSocketServerIO(ws)
    const rpc = new RPCChannel<API, API>(io, { expose: api })
})

// Client
const ws = new WebSocket("ws://localhost:3000")
const io = new WebSocketClientIO({ ws })
const rpc = new RPCChannel<{}, API>(io)
const api = rpc.getAPI()

Web Worker

import { WorkerParentIO, WorkerChildIO, RPCChannel } from "kkrpc/browser"

// Main thread
const worker = new Worker("./worker.ts", { type: "module" })
const io = new WorkerParentIO(worker)
const rpc = new RPCChannel<LocalAPI, RemoteAPI>(io, { expose: localApi })

// Worker thread
const io = new WorkerChildIO()
const rpc = new RPCChannel<RemoteAPI, LocalAPI>(io, { expose: api })

HTTP

import { HTTPClientIO, HTTPServerIO, RPCChannel } from "kkrpc"

// Server
const serverIO = new HTTPServerIO()
const serverRPC = new RPCChannel<API, API>(serverIO, { expose: api })

Bun.serve({
    async fetch(req) {
        if (new URL(req.url).pathname === "/rpc") {
            const response = await serverIO.handleRequest(await req.text())
            return new Response(response, {
                headers: { "Content-Type": "application/json" }
            })
        }
        return new Response("Not found", { status: 404 })
    }
})

// Client
const clientIO = new HTTPClientIO({ url: "http://localhost:3000/rpc" })
const clientRPC = new RPCChannel<{}, API>(clientIO)

Advanced Features

Callback Functions

Send functions as arguments that can be invoked remotely:

interface API {
    processData(data: string, onProgress: (percent: number) => void): Promise<string>
}

// Server
const api: API = {
    processData: async (data, onProgress) => {
        for (let i = 0; i <= 100; i += 10) {
            onProgress(i)
            await sleep(100)
        }
        return `Processed: ${data}`
    }
}

// Client
const result = await api.processData("my-data", (progress) => {
    console.log(`Progress: ${progress}%`)
})

Property Access

Access and mutate remote properties:

interface API {
    counter: number
    settings: {
        theme: string
        notifications: { enabled: boolean }
    }
}

// Get values
const count = await api.counter
const theme = await api.settings.theme

// Set values
api.counter = 100
api.settings.theme = "dark"

Enhanced Error Handling

Errors preserve name, message, stack, and custom properties:

class ValidationError extends Error {
    constructor(
        message: string,
        public field: string,
        public code: number
    ) {
        super(message)
        this.name = "ValidationError"
    }
}

// Thrown on server
type API = {
    validateUser(data: unknown): Promise<void>
}

// Caught on client
try {
    await api.validateUser({})
} catch (error) {
    console.log(error.name) // "ValidationError"
    console.log(error.message) // "Name is required"
    console.log(error.field) // "name"
    console.log(error.code) // 400
}

Validation (Optional)

Use Standard Schema (Zod, Valibot, ArkType) for runtime validation:

import { RPCChannel, type RPCValidators } from "kkrpc"
import { z } from "zod"

type MathAPI = {
    add(a: number, b: number): Promise<number>
}

const api: MathAPI = {
    add: async (a, b) => a + b
}

const validators: RPCValidators<MathAPI> = {
    add: {
        input: z.tuple([z.number(), z.number()]),
        output: z.number()
    }
}

const rpc = new RPCChannel(io, { expose: api, validators })

Transferable Objects (Browser)

Zero-copy transfer of large binary data:

import { RPCChannel, transfer, WorkerParentIO } from "kkrpc/browser"

interface API {
    processBuffer(buffer: ArrayBuffer): Promise<number>
}

const worker = new Worker("worker.js")
const io = new WorkerParentIO(worker)
const rpc = new RPCChannel<{}, API>(io)
const api = rpc.getAPI()

// Create large buffer
const buffer = new ArrayBuffer(10 * 1024 * 1024)

// Transfer (zero-copy) to worker
const result = await api.processBuffer(transfer(buffer, [buffer]))
// Note: buffer is now detached (length 0)

Serialization Options

JSON (Default for Interop)

const rpc = new RPCChannel(io, {
    expose: api,
    serialization: { version: "json" }
})

• Standard JSON
• Works with all interop languages
• No Date, Map, Set, BigInt support

SuperJSON (Default, TypeScript-only)

const rpc = new RPCChannel(io, {
    expose: api,
    serialization: { version: "superjson" }
})

• Supports Date, Map, Set, BigInt, Uint8Array
• TypeScript-to-TypeScript only
• Auto-detected by receiver

Common Patterns

Bidirectional Communication

Both sides expose APIs:

// Side A
interface API_A {
    compute(data: number[]): Promise<number>
}

interface API_B {
    notify(message: string): Promise<void>
}

const apiA: API_A = {
    compute: async (data) => data.reduce((a, b) => a + b, 0)
}

const rpc = new RPCChannel<API_A, API_B>(io, { expose: apiA })
const apiB = rpc.getAPI()

// Call B from A
await apiB.notify("Computation complete")

Dynamic API Exposure

Change exposed API at runtime:

const rpc = new RPCChannel(io)

// Later...
rpc.expose(newApi)

Cleanup

Destroy connections when done:

// For transports that support it
io.destroy()

Environment-Specific Entry Points

// Browser (excludes stdio)
import { RPCChannel, WorkerParentIO } from "kkrpc/browser"

// Deno
import { RPCChannel, DenoIo } from "kkrpc/deno"

// Chrome Extension
import { RPCChannel, ChromePortIO } from "kkrpc/chrome-extension"

Error Reference

Testing

Test with Reference Implementation

// interop/node/server.ts provides a test server
const api = {
    math: { add: (a: number, b: number) => a + b },
    echo: <T>(v: T) => v,
    counter: 42
}

Unit Test Pattern

import { expect, test } from "bun:test"
import { NodeIo, RPCChannel } from "kkrpc"

test("basic RPC call", async () => {
    const api = { add: (a: number, b: number) => a + b }

    // Create connected pair
    const { port1, port2 } = new MessageChannel()

    const serverIO = new NodeIo(port1)
    const clientIO = new NodeIo(port2)

    new RPCChannel<typeof api, {}>(serverIO, { expose: api })
    const client = new RPCChannel<{}, typeof api>(clientIO)

    const result = await client.getAPI().add(2, 3)
    expect(result).toBe(5)
})

Best Practices

1. Use Interface-First: Define interfaces before implementations for type safety
2. Handle Errors: Always wrap RPC calls in try-catch
3. Clean Up: Destroy transports when components unmount
4. Validate Inputs: Use validators for public APIs
5. Choose Serialization: Use JSON for interop, superjson for TS-only
6. Transfer Large Data: Use transfer() for ArrayBuffers in browsers
7. Namespace APIs: Use nested objects to organize methods

References

• Package: packages/kkrpc/
• Core source: packages/kkrpc/src/
• Serialization: packages/kkrpc/src/serialization.ts
• Adapters: packages/kkrpc/src/adapters/
• Interop guide: skills/interop/SKILL.md