The `json-rpc-2.0` package provides a robust, protocol-agnostic implementation of the JSON-RPC 2.0 specification for both client and server applications. It is designed to work seamlessly in Node.js and browser environments, offering first-class TypeScript support through its strongly typed interfaces. The current stable version is 1.7.1, with releases occurring periodically, often driven by new feature additions or minor bug fixes, as seen in the recent 1.7.x releases. A key differentiator is its zero-dependency philosophy, keeping the package lean and avoiding 'dependency hell'. It focuses purely on the JSON-RPC protocol, allowing developers to choose their preferred underlying transport (HTTP, WebSocket, TCP, etc.) without library constraints, making protocol migrations straightforward. It offers features like middleware for request/response interception and custom parameter injection for concerns like authentication.
npm install json-rpc-2.0Verified import paths — ran on the pinned version, not inferred.
This quickstart sets up a basic JSON-RPC 2.0 server using Express and a corresponding client. It demonstrates adding methods, applying middleware for request logging, handling both requests and notifications, and making typed calls from the client. It uses `node-fetch` for HTTP communication, illustrating the protocol-agnostic nature of the library.
Ensure that any errors thrown within JSON-RPC methods are instances of `Error` or `JSONRPCErrorException`. For custom error information, use `JSONRPCErrorException` which provides `code`, `message`, and `data` properties.
Always check `if (jsonRPCResponse)` before attempting to send the response. If `jsonRPCResponse` is `null`, it indicates a notification, and you should respond with `res.sendStatus(204)` (for HTTP) or similar 'no content' mechanism for your protocol.
Carefully implement the `sender` function for `JSONRPCClient` and the `receive` call on `JSONRPCServer` to correctly send and receive raw JSON-RPC payloads over your chosen transport. Consider message framing for stream-based protocols like WebSockets or TCP.
Always `await` the result of `server.receive()` and ensure that any methods added via `server.addMethod()` correctly return the final result or a `Promise` that resolves to the result. Use `try...catch` blocks within your methods to gracefully handle synchronous and asynchronous errors.
For ES Modules (modern Node.js and TypeScript), use `import { JSONRPCServer } from 'json-rpc-2.0';`. If forced to use CommonJS `require`, ensure you destructure correctly: `const { JSONRPCServer } = require('json-rpc-2.0');`.Ensure `server.receive(jsonRPCRequest).then(...)` or `await server.receive(jsonRPCRequest)` is used. Also, make sure that errors thrown by your RPC methods are either `Error` objects or instances of `JSONRPCErrorException` (v1.4.0+) to allow the server to correctly format them.
On the server, ensure that for any JSON-RPC *request* (payload has an `id`), a `jsonRPCResponse` is always generated and sent back to the client. Only send 204 No Content for JSON-RPC *notifications* (payload lacks an `id`). Check server logs for errors during request processing.
No dependency data recorded yet.