@gnana997/node-jsonrpc

Transport-agnostic JSON-RPC 2.0 client and server for TypeScript/Node.js

Features

• ✅ Transport Agnostic - Works with IPC, stdio, HTTP, WebSocket, or any custom transport
• ✅ Full JSON-RPC 2.0 - Complete spec compliance for client and server
• ✅ TypeScript First - Fully typed with excellent IntelliSense support
• ✅ Zero Dependencies - Only uses Node.js standard library
• ✅ Middleware Support - Intercept and modify requests/responses
• ✅ Batch Requests - Send multiple requests in a single round-trip
• ✅ Request Cancellation - AbortSignal support for cancelling requests
• ✅ Debug Logging - Built-in logger with configurable levels
• ✅ Bidirectional - Server can send notifications to clients
• ✅ Multi-Client - Server handles multiple concurrent connections
• ✅ Well Tested - Comprehensive test suite with 80%+ coverage

Installation

npm install @gnana997/node-jsonrpc

Quick Start

Client

import { JSONRPCClient } from '@gnana997/node-jsonrpc';
import { MyTransport } from './my-transport'; // Your transport implementation

const client = new JSONRPCClient({
  transport: new MyTransport(),
});

await client.connect();

// Make a request
const result = await client.request('subtract', { minuend: 42, subtrahend: 23 });
console.log(result); // 19

// Send a notification (no response)
client.notify('update', { status: 'ready' });

// Listen for server notifications
client.on('notification', (method, params) => {
  console.log(`Server sent ${method}:`, params);
});

Server

import { JSONRPCServer } from '@gnana997/node-jsonrpc';
import { MyTransportServer } from './my-transport'; // Your transport implementation

const server = new JSONRPCServer({
  transportServer: new MyTransportServer(),
});

// Register method handlers
server.registerMethod('subtract', async (params) => {
  return params.minuend - params.subtrahend;
});

server.registerMethod('sum', async (params) => {
  return params.reduce((a: number, b: number) => a + b, 0);
});

await server.listen();

// Send notification to all connected clients
server.broadcast('serverStatus', { status: 'ready' });

Examples

The examples/ directory contains complete, runnable examples demonstrating various features:

Client Examples

• basic-client.ts - Basic request/response and notifications
• batch-client.ts - Parallel and sequential batch requests
• middleware-client.ts - Logging, metrics, auth, and custom middleware
• error-handling-client.ts - Timeout, cancellation, and error recovery

Server Examples

• basic-server.ts - Method registration and request handling
• notification-server.ts - Broadcasting and pub/sub patterns
• middleware-server.ts - Auth, validation, and rate limiting
• multi-client-server.ts - Managing multiple clients and client-to-client messaging

Testing Examples

• test-client.ts - Unit testing client functionality
• test-server.ts - Unit testing server functionality
• test-integration.ts - Integration testing patterns
• mock-transport.ts - Mock transport for testing

Transport Abstraction

This package is transport-agnostic. You need to provide a Transport implementation for the client and a TransportServer implementation for the server.

See TRANSPORT.md for details on implementing custom transports.

Available Transports

• node-ipc-jsonrpc - IPC transport (Unix sockets, Windows named pipes)
• More coming soon...

Documentation

• API Reference - Complete API documentation
• Transport Guide - How to implement custom transports
• Examples - Usage examples and patterns

API Overview

JSONRPCClient

class JSONRPCClient extends EventEmitter {
  constructor(config: JSONRPCClientConfig);

  connect(): Promise<void>;
  disconnect(): Promise<void>;
  isConnected(): boolean;

  request<T>(method: string, params?: any, options?: RequestOptions): Promise<T>;
  notify(method: string, params?: any): void;
  batch(): BatchRequest;

  use(middleware: Middleware): void;

  // Events: 'connected', 'disconnected', 'notification', 'error'
}

JSONRPCServer

class JSONRPCServer extends EventEmitter {
  constructor(config: JSONRPCServerConfig);

  listen(): Promise<void>;
  close(): Promise<void>;

  registerMethod(name: string, handler: Handler): void;
  use(middleware: Middleware): void;

  notify(transport: Transport, method: string, params?: any): void;
  broadcast(method: string, params?: any): number;

  // Events: 'notification', 'error'
}

License

MIT © gnana997