kunkunsh/kkrpc/kkrpc-migration

kkrpc 1.0 Migration

Use this skill to migrate applications from kkrpc 0.7.x or temporary kkrpc/next APIs to the stable 1.0 API.

The 1.0 public API is native Transport<RPCMessage> based. Do not preserve the classic IoInterface adapter model, public *IO classes, classic-compat, next/io, browser-lite, browser-mini, or electron-ipc imports.

Canonical user documentation: docs/src/content/docs/guides/migration-1-0.md. For the slim-core feature split, also check docs/src/content/docs/guides/migration-0-1-to-0-2.md.

Migration Workflow

1. Inspect package versions and imports.
2. Search for old API usage.
3. Replace package entries and transport imports.
4. Replace channel setup with wrap(), expose(), or native RPCChannel.
5. Replace classic IO adapters with native transport factories.
6. Replace validation and middleware options with plugins.
7. Move SuperJSON to explicit codec composition.
8. Run type checks, tests, and old-API searches.

Search Patterns

Run these searches before editing and again before finishing:

rg 'kkrpc/next|next/io|classic-compat|IoInterface|IoMessage|RPCValidators|kkrpc/browser-lite|kkrpc/browser-mini|kkrpc/electron-ipc'
rg '[A-Za-z0-9_]+IO\b'
rg 'validators\s*:|interceptors\s*:'

The *IO search may find application names. Review matches manually and only migrate kkrpc classic adapter usage.

Entry Mapping

Runtime transports must not be imported from the main kkrpc entry. Use explicit subpaths.

Async iterable streaming and request/response remote references must also use explicit subpaths. The default kkrpc entry is the slim request/response core.

Core API Patterns

Client-only proxy

Use wrap() when this side only calls a remote API.

import { wrap } from "kkrpc"
import { webSocketClientTransport } from "kkrpc/ws"
const api = wrap<RemoteAPI>(webSocketClientTransport({ url: "ws://localhost:3000" }))

If the proxy has a bounded lifetime, dispose it explicitly:

import { dispose } from "kkrpc"
dispose(api)

Server-only API

Use expose() when this side only publishes a local API.

import { expose } from "kkrpc"
const controller = expose(localAPI, transport)
controller.dispose()

Bidirectional endpoint

Use native RPCChannel when both sides expose APIs.

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

The generic order is local API first, remote API second.

Transport Mapping

HTTP Guardrail

HTTP is unary request/response in 1.0. Do not migrate callback-heavy, subscription, streaming-progress, remote-reference, raw-function, or server-push code to kkrpc/http. Use WebSocket or another evented transport for those boundaries.

When migrating remote references to RabbitMQ, Kafka, Redis Streams, or NATS, configure remotePeerId. Broadcast bus mode is for fan-out messages and does not advertise remote-reference support.

Remote proxies decoded from one channel are not portable across another channel. Replace implicit proxy forwarding with an explicit bridge method if an old design depended on that behavior.

Validation Migration

Replace classic validators options with validationPlugin().

import { expose } from "kkrpc"
import { validationPlugin } from "kkrpc/validation"
const validators = {
	"math.add": {
		input: argsSchema,
		output: resultSchema
	}
}
expose(api, transport, {
	plugins: [validationPlugin(validators)]
})

If preserving an existing validator map is simpler, pass that map to validationPlugin() instead of rewriting the API around defineMethod().

Middleware Migration

Replace classic interceptors options with middlewarePlugin().

import { middlewarePlugin, type RPCInterceptor } from "kkrpc/middleware"
const logger: RPCInterceptor = async (ctx, next) => {
	console.log(ctx.method)
	return next()
}
const plugins = [middlewarePlugin([logger])]

Install the plugin through wrap(), expose(), or RPCChannel options.

SuperJSON Migration

SuperJSON is not a core import. Use kkrpc/superjson only where a transport needs richer value encoding.

import { superJsonCodec } from "kkrpc/superjson"
import { createTransport } from "kkrpc/transport"
const transport = createTransport({ platform, codec: superJsonCodec() })

Transferables

Use transfer() from kkrpc only for transports that support transferable ownership, such as Web Workers.

import { transfer } from "kkrpc"
await api.process(transfer(buffer, [buffer]))

Do not assume transfer support for HTTP, stdio, or message-bus transports.

Guardrails

• Do not add backward compatibility aliases for removed public APIs.
• Do not reintroduce IoInterface, IoMessage, or public *IO classes.
• Do not import runtime-specific transports from kkrpc.
• Do not pull optional peers into browser-safe entries.
• Do not claim HTTP supports callbacks or bidirectional calls.
• Do not leave async iterable APIs on the default kkrpc entry; use kkrpc/streaming.
• Do not leave callback-return or object-handle APIs on the default kkrpc entry; use kkrpc/remote-refs and explicit proxy(value) markers.
• Do not rely on unmarked nested functions crossing by raw identity; kkrpc/remote-refs rejects them.
• Do not edit generated dist or Typedoc output while migrating this repository.

Verification

For this repository, run:

pnpm --filter kkrpc check-types
pnpm --filter kkrpc test
pnpm --filter "./examples/*" check-types

For downstream projects, run the project type check, unit tests, and at least one integration test for each migrated transport boundary.

Before declaring migration complete, re-run the old API searches and verify that remaining matches are documentation, intentional compatibility notes, or unrelated false positives.