kkrpc RPC Framework

kkrpc is a high-performance RPC framework designed with the following capabilities:

• Cross-Runtime Support: Works seamlessly across Node.js, Deno, Bun, and the Browser.
• Full Type-Safety: Provides complete TypeScript inference and autocomplete.
• Bidirectional Communication: Unlike traditional RPCs (like tRPC), both the client and server can expose and call APIs on each other.
• Nested API Organization: Supports organizing APIs using nested object structures (e.g., api.math.grade1.add()).
• Error Preservation: Maintains complete error objects as they cross runtime boundaries.
• Function Callbacks: Allows passing functions as parameters across the RPC boundary.
• Transferable Objects: Supports zero-copy transfers for large data, providing 40-100x performance improvements for large binary payloads.
• Zero Configuration: Requires no code generation or complex setup; simply install and use.

kkrpc uses JavaScript Proxy objects to allow direct property access and mutation across RPC boundaries. This makes remote objects behave like local ones with full TypeScript support.

Key Mechanics

• Property Getters: Accessing a property (e.g., api.counter) returns a proxy. To retrieve the actual value, you must use await (e.g., await api.counter). This triggers a "get" type RPC message.
• Property Setters: Assigning a value (e.g., api.counter = 42) triggers the proxy's set trap, sending a "set" type RPC message.
• Nested Properties: Deep access is supported via dot notation (e.g., api.nested.deep.property).
• Fire-and-Forget Setters: Property assignments (api.counter = 42) are non-blocking and return immediately. They do not wait for the remote operation to complete.

Error Handling for Setters

Because setters are fire-and-forget, a failed assignment will not throw at the site of the assignment. To catch errors from failed sets (kind: "set") or remote-callback failures (kind: "callback"), you must pass an onUncaughtError handler to the channel.

// Getter (requires await)
const val = await api.property

// Setter (fire-and-forget)
api.property = newValue

The stable architecture of kkrpc is built around two primary abstractions: RPCChannel and Transport.

• RPCChannel<LocalAPI, RemoteAPI>: Manages the RPC state machine. It handles:
  • pending: Outbound requests waiting for a response.
  • callbacks: Local callback arguments provided for remote execution.
  • destroyed: State to prevent calls after disposal and reject pending requests.
  • timeout: Single call timeout (defaults to 30_000 ms; non-positive values disable it).
  • plugins: Hooks for request, handler, response, and error to implement validation, middleware, or inspection.
• Transport<T>: A message-oriented interface that decouples IO details from RPC message encoding. It uses createTransport() to combine a Platform<Wire> with a Codec<Message, Wire>.

When a RPCChannel receives a message, it dispatches it based on the compact field t (type).

The benchmark measures the incremental cost of adding specific features to the kkrpc core. Use these configurations to decide which features to include in your project based on your bundle size constraints:

• kkrpc core: The base package including the generic Transport<RPCMessage> channel, proxy creation, top-level callback arguments, and transfer descriptors.
• kkrpc + json codec: Core plus createTransport() and jsonCodec() for plain JSON serialization.
• kkrpc + superjson: Core plus createTransport() and superJsonCodec() for richer JS value serialization.
• kkrpc/worker: Core plus workerTransport() for Web Worker support.
• kkrpc/streaming: Core plus opt-in async iterable argument/result streaming with pull-based backpressure.
• kkrpc/remote-refs: Core plus explicit proxy(value) remote references with nested marked refs and identity behavior.