JSON-RPC 2.0

For full-duplex communication (like WebSockets), use JSONRPCServerAndClient. This class combines a server and a client into a single entity.

1. Initialize it with a JSONRPCServer and a JSONRPCClient.
2. Use serverAndClient.receiveAndSend(parsedMessage) inside your transport's message handler (e.g., ws.onmessage) to process incoming messages and automatically send responses.
3. Use serverAndClient.rejectAllPendingRequests(reason) when the connection closes to prevent client-side requests from hanging.

const serverAndClient = new JSONRPCServerAndClient(
  new JSONRPCServer(),
  new JSONRPCClient((request) => {
    webSocket.send(JSON.stringify(request));
    return Promise.resolve();
  })
);

webSocket.onmessage = (event) => {
  serverAndClient.receiveAndSend(JSON.parse(event.data.toString()));
};

webSocket.onclose = (event) => {
  serverAndClient.rejectAllPendingRequests(`Connection closed: ${event.reason}`);
};

Use JSONRPCServer to create a server that handles JSON-RPC requests. You can register methods using addMethod(methodName, handler). The handler receives the request parameters as its first argument and can optionally receive custom injected parameters as its second argument.

To process incoming requests, use server.receive(jsonRPCRequest) or server.receiveJSON(jsonString). If the request is a notification (no id), receive returns undefined (or a falsy value), allowing you to respond with a 204 No Content status in your transport layer (e.g., Express).

const { JSONRPCServer } = require("json-rpc-2.0");

const server = new JSONRPCServer();

// Basic method
server.addMethod("echo", ({ text }) => text);

// Method with custom injected parameters (e.g., for authentication)
server.addMethod("echo", ({ text }, { userID }) => `${userID} said ${text}`);

// Processing a request
server.receive(jsonRPCRequest, { userID }).then((jsonRPCResponse) => {
  if (jsonRPCResponse) {
    res.json(jsonRPCResponse);
  } else {
    res.sendStatus(204);
  }
});

Server-side Error Handling

• Standard Errors: Rejecting a method with a standard JavaScript Error will result in a JSON-RPC error response with the error's message.
• Custom JSON-RPC Errors: Use JSONRPCErrorException to return specific error codes and data.
• Error Mapping: Implement server.mapErrorToJSONRPCErrorResponse to globally transform any thrown error into a specific JSONRPCErrorResponse format.

Client-side Error Handling

When a server returns an error, the client.request promise will reject with an Error object containing the message from the server.

import { JSONRPCErrorException } from "json-rpc-2.0";

// Throwing a structured error on the server
server.addMethod("throws", () => {
  throw new JSONRPCErrorException("Invalid input", 123, { foo: "bar" });
});

// Catching error on the client
client.request("throws").catch((error) => {
  console.error(error.message); 
});

Use JSONRPCClient to make requests to a JSON-RPC server. The constructor requires a transport function that takes a jsonRPCRequest and returns a Promise. This function is responsible for sending the request and, upon receiving a response, calling client.receive(jsonRPCResponse) to resolve the client's internal request promise.

• client.request(method, params, [customParams]): Returns a promise that resolves to the result of the method call.
• client.notify(method, params, [customParams]): Sends a notification (no response expected).

import { JSONRPCClient } from "json-rpc-2.0";

const client = new JSONRPCClient((jsonRPCRequest) =>
  fetch("http://localhost/json-rpc", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify(jsonRPCRequest),
  }).then((response) => {
    if (response.status === 200) {
      return response.json().then((jsonRPCResponse) => client.receive(jsonRPCResponse));
    }
    // Handle error cases...
  })
);

// Making a request
client.request("echo", { text: "Hello" }).then(console.log);

// Making a notification
client.notify("log", { message: "Hello" });

Use TypedJSONRPCServer<T> and TypedJSONRPCClient<T> to provide strong type safety for your JSON-RPC methods.

1. Define a type (not an interface) representing your methods, where each key is a method name and the value is a function signature defining params and the return type.
2. Pass this type to the constructor of the server and client.

This enables compile-time checking for method names, parameter shapes, and return types for both addMethod on the server and request/notify on the client.

type Methods = {
  echo(params: { message: string }): string;
  sum(params: { x: number; y: number }): number;
};

const server: TypedJSONRPCServer<Methods> = new JSONRPCServer();
const client: TypedJSONRPCClient<Methods> = new JSONRPCClient(/* ... */);

// Type-safe usage
server.addMethod("echo", ({ message }) => message); // OK
// server.addMethod("echo", ({ message }) => 123); // Error: return type must be string

client.request("sum", { x: 1, y: 2 }).then(result => {
  // result is inferred as number
});

If you need full control over the JSON-RPC wire format, use the Advanced API methods:

Server

server.addMethodAdvanced(methodName, handler) allows you to handle the raw JSONRPCRequest object and return a raw JSONRPCResponse object directly. This is useful for custom validation or complex response structures.

Client

client.requestAdvanced(jsonRPCRequest) allows you to send a manually constructed JSONRPCRequest and receive a JSONRPCResponse. You can also provide a custom ID factory function to the JSONRPCClient constructor to avoid ID conflicts between basic and advanced calls.

// Server Advanced Method
server.addMethodAdvanced("doSomething", (jsonRPCRequest: JSONRPCRequest): PromiseLike<JSONRPCResponse> => {
  return {
    jsonrpc: JSONRPC,
    id: jsonRPCRequest.id,
    result: "Success",
  };
});

// Client Advanced Request
client.requestAdvanced(jsonRPCRequest).then((response) => {
  if (response.error) {
    console.log(response.error.message);
  } else {
    console.log(response.result);
  }
});