Remote Procedure Call (RPC)

A transport-agnostic, bidirectional RPC library for Node.js, Bun, and modern browsers.

Features

• Transport-Agnostic - Websockets, HTTP, RabbitMQ, etc.
• Bidirectional transactions and responses
• JSON-RPC 2.0 codec with optional 1.0 compatibility
• MessagePack codec support
• Ready-to-use websocket adapters
• ESM and CommonJS project support

Installation

This module is available through the npm registry.

npm install @tekuconcept/rpc

For NodeJS WebSocket support, also install:

npm install ws

Library Structure

┌──────────────────────────┐
│        RpcPeer           │  ← protocol semantics (req, res,
│                          │     correlation, timeouts, handlers)
└──────────▲───────────────┘
           │ normalized messages
┌──────────┴───────────────┐
│        RpcCodec          │  ← envelope (JSON-RPC 1.0 / 2.0)
│                          │     (or user-defined)
└──────────▲───────────────┘
           │ bytes / frames
┌──────────┴───────────────┐
│      RpcTransport        │  ← WebSockets, MessagePort, etc.
└──────────────────────────┘

Quick Start

Websocket Server

const wss = new WebSocketServer({ port: 8080 })

wss.on('connection', async (ws) => {
    const peer = new RpcPeer({
        connection: ws,
        // These are already the default config.
        transport: 'websockets',
        codec: { name: 'json-rpc 2.0', strict: true },
    })

    peer.add('ready', (params: string, ctx) => {
        return { ok: true, echoed: params }
    })

    await peer.call('ping')
})

Websocket Client

const ws = new WebSocket('ws://localhost:8080')

// Wait for connection to open

const peer = new RpcPeer({ connection: ws })
peer.add('ping', () => ({ pong: true }))

await peer.notify('ready', { key: 'fun days' })

Advanced Usage

RpcPeer tries to keep the entire setup process as simple as possible. That said, it simultaneously maximizes on customizability and control.

class CustomTransport implements RpcTransport { ... }
class CustomCodec implements RpcCodec { ... }


// Add custom transport and codec for quick construction
// -----------------------------------------------------

RpcPeer.defaults.registerTransport(
    'Example Transport', CustomTransport
)
RpcPeer.defaults.registerCodec(
    'Example Codec', CustomCodec
)

const peer1 = new RpcPeer({
    connection,
    transport: {
        name: 'Example Transport',
        param1: 42,
        param2: 'best transport'
    },
    codec: 'Example Codec'
})


// Configure the global defaults for simplified setup
// -----------------------------------------------------

RpcPeer.defaults.transport = 'Example Transport'
RpcPeer.defaults.codec = 'Example Codec'
RpcPeer.defaults.forTransport(
    'Example Transport',
    { param1: 42, param2: 'best transport' }
)

const peer2 = new RpcPeer({ connection }) // same as peer1


// Skip all defaults and go bare metal
// -----------------------------------------------------

const transport = new CustomTransport(
    connection,
    { param1: 42, param2: 'best transport' }
)
const codec = new CustomerCodec()
const peer3 = new RpcPeer(transport, codec) // same as peer1

To report an issue or suggest a feature, visit the GitHub repo.