kkrpc

name: kkrpc description: Use when building TypeScript RPC with kkrpc stable APIs, choosing native Transport adapters, or integrating validation, middleware, transferables, streaming, remote references, relay, or inspector tooling. version: 2.0.0 license: MIT metadata: author: kkrpc domain: typescript-rpc tags: - rpc - typescript - bidirectional - ipc - websocket - http - workers - electron - tauri - chrome-extension

compatibility: Works in Node.js, Deno, Bun, browsers, Electron, Tauri, Chrome extensions, and queue-backed runtimes with the correct stable entry point and transport.

kkrpc - TypeScript RPC Library

Use kkrpc to expose a local TypeScript object and call the remote side as a typed proxy. The stable API is native Transport<RPCMessage> based. Start with the small default kkrpc entry, then opt into kkrpc/streaming or kkrpc/remote-refs only when the API needs those features.

import { expose, wrap } from "kkrpc"

const controller = expose(localAPI, serverTransport)
const remote = wrap<RemoteAPI>(clientTransport)

controller.dispose()

Use low-level RPCChannel when both sides expose APIs or when you need explicit channel ownership:

import { RPCChannel } from "kkrpc"

const channel = new RPCChannel<LocalAPI, RemoteAPI>(transport, { expose: localAPI })
const remote = channel.getAPI()

First Decisions

1. Pick the stable entry point.
2. Pick the native transport factory.
3. Decide whether one side or both sides expose APIs.
4. Add plugins only when validation, middleware, logging, or custom behavior is required.

Entry Points

Core API Pattern

Prefer explicit local and remote API types. In bidirectional RPC, each side can expose its own API and call the other side.

type ServerAPI = {
    math: {
        add(a: number, b: number): Promise<number>
    }
    version(): Promise<string>
}

type ClientAPI = {
    notify(message: string): Promise<void>
}

const clientAPI: ClientAPI = {
    async notify(message) {
        console.log(message)
    }
}

const channel = new RPCChannel<ClientAPI, ServerAPI>(transport, { expose: clientAPI })
const server = channel.getAPI()

console.log(await server.math.add(1, 2))

Remote property access is supported:

const counter = await api.counter
const nested = await api.nested.deepObj.prop

Top-level callbacks can be passed as arguments for fire-and-forget progress notifications:

await api.process("input", (progress) => {
    console.log("progress", progress)
})

Default callbacks do not propagate return values or thrown errors. Use kkrpc/remote-refs and proxy(callback) when the remote side must await the callback result.

kkrpc/remote-refs is explicit: unmarked function values are rejected rather than passed by raw object identity. Wrap each callback, returned function leaf, or object handle that should remain remote with proxy(value).

Remote proxies are channel-scoped. Do not pass a remote proxy decoded from one RPCChannel through a different channel; expose an explicit bridge method if that is truly required.

Streaming Example

import { expose, wrap } from "kkrpc/streaming"

type LogAPI = {
    tail(service: string): AsyncIterable<string>
}

for await (const line of wrap<LogAPI>(transport).tail("api")) {
    console.log(line)
}

Remote References Example

import { proxy, releaseProxy, wrap } from "kkrpc/remote-refs"

const result = await wrap<RemoteAPI>(transport).useCallback(
    proxy(async (value) => `callback:${value}`)
)

const counter = await wrap<RemoteAPI>(transport).createCounter()
await releaseProxy(counter)

Worker Example

Parent side:

import { wrap } from "kkrpc"
import { workerTransport } from "kkrpc/worker"

const worker = new Worker(new URL("./worker.ts", import.meta.url), { type: "module" })
const api = wrap<WorkerAPI>(workerTransport(worker))

console.log(await api.ping())

Worker side:

import { expose } from "kkrpc"
import { workerSelfTransport } from "kkrpc/worker"

expose(
    {
        async ping() {
            return "pong"
        }
    },
    workerSelfTransport()
)

WebSocket Example

import { wrap } from "kkrpc"
import { webSocketClientTransport } from "kkrpc/ws"

const api = wrap<RemoteAPI>(webSocketClientTransport("ws://localhost:3000/rpc"))

Validation Example

import { expose, wrap } from "kkrpc"
import { validationPlugin } from "kkrpc/validation"

const plugins = [validationPlugin(validators)]
const controller = expose(localAPI, serverTransport, { plugins })
const remote = wrap<RemoteAPI>(clientTransport, { plugins })

Middleware Example

import { middlewarePlugin } from "kkrpc/middleware"

const plugins = [
    middlewarePlugin([
        async (ctx, next) => {
            console.log(ctx.method)
            return next()
        }
    ])
]

SuperJSON Example

Use kkrpc/superjson only when the application needs SuperJSON value support. Do not import it from the main kkrpc entry.

import { createTransport } from "kkrpc/transport"
import { superJsonCodec } from "kkrpc/superjson"

const transport = createTransport({ platform, codec: superJsonCodec() })

Inspector Example

import { createInspector, MemoryBackend } from "kkrpc/inspector"

const memory = new MemoryBackend()
const inspector = createInspector({ backends: [memory], options: { trackLatency: true } })
const channel = new RPCChannel<LocalAPI, RemoteAPI>(transport, {
    expose: localAPI,
    plugins: [inspector.plugin("server")]
})

Relay Example

import { relayTransport } from "kkrpc/relay"

const relay = relayTransport(leftTransport, rightTransport)
relay.dispose()

Migration Rules

1. Use kkrpc instead of old experimental native entry paths.
2. Use native transport factories instead of blocking IO classes.
3. Keep optional peers behind their stable subpaths.
4. Do not import runtime-specific transports from the main kkrpc entry.
5. Do not use removed compatibility entries or browser-lite/browser-mini entries in new code.

Common Pitfalls