Skip to content

mahsumurebe/jrpc-client

Repository files navigation

JRPC Client

JSONRPC 2.0 Client package for Nodejs. Fully tested to comply with the official JSON-RPC 2.0 specification

GitHub package.json version GitHub release (latest by date) GitHub tag (latest by date) npm

Libraries.io SourceRank, scoped npm package minzipped-size minfied-size

issues-open issues-closed license

Quick Overview

It is used to quickly create JSONRPC Client. Method call is very simple.

To Create a Server

You can use the @mahsumurebe/jrpc-server package to create a server.

Install

For installation, you can run the following command in the directory of your project.

npm install @mahsumurebe/jrpc-client  

Usage

It should not create a JRPCClient instance.

import { JRPCClient, HttpAdapter } from '@mahsumurebe/jrpc-client';

// Create instance
const clientInstance = new JRPCClient(new HttpAdapter('http://localhost:3000'));
// Call start method for connection
await clientInstance.start();

Call Method

Method calls are made after the JRPCClient instance is created.

// Call foo method with "bar" and "baz" parameters
const response = await clientInstance.call({
  id: 1,
  jsonrpc: "2.0",
  method: "foo",
  params: ["bar", "baz"],
});
console.log(response);
// Response Object
// { id: 1, jsonrpc: "2.0", response: "foo response" }

The call method returns the JSONRPC response. Returns the ErrorResponse class instance if the request response is an error.

Batch Call Method

Call method can be used to call requests. You can review the usage example below.

const batchResponse = await clientInstance.call([
  { id: 1, jsonrpc: "2.0", method: "foo", params: ["bar", "baz"] },
  { id: 2, jsonrpc: "2.0", method: "bar", params: ["bar", "baz"] },
  { jsonrpc: "2.0", method: "notification", params: ["bar", "baz"] }, // Notification request does not return value
]);
console.log(batchResponse);
// [
//   { id: 1, jsonrpc: "2.0", response: "foo response" },
//   { id: 2, jsonrpc: "2.0", response: "bar response" },
// ]

Notification Method

Check out the sample code below to make a method notification.

// Notification foo method with "bar" and "baz" parameters
await clientInstance.notification({
  jsonrpc: "2.0",
  method: "foo",
  params: ["bar", "baz"],
});

Note: The notification method does not return any response. The request is sent to the server. No response is expected from the server.

Batch Notification Method

Check out the example below for sending batch notifications.

await clientInstance.notification([
  { jsonrpc: "2.0", method: "foo", params: ["bar", "baz"] },
  { jsonrpc: "2.0", method: "bar", params: ["bar", "baz"] },
  { jsonrpc: "2.0", method: "baz", params: ["bar", "baz"] }, 
]);

Adapters

There are HTTP and Websocket adapters available.

HTTP

HTTP Adapter is used to connect to JRPC Servers served over HTTP Protocol.

// Adapter Instance
import {JRPCClient, HttpAdapter} from '@mahsumurebe/jrpc-client';

const adapter = new HttpAdapter('http://localhost:3000');

// Client Instance
const clientInstance = new JRPCClient(adapter);

Configuration List

Configurations are defined in the object in the first parameter of the construction method when creating the HttpAdapter.

KEY DEFAULT DESCRIPTION Type
parser null Response parser Function
headers null HTTP Headers object
timeout 10_000 Timeout number

Websocket

Websocket Adapter is used to connect to JRPC Servers served over Websocket Protocol.

// Adapter Instance
import { JRPCClient, WebsocketAdapter } from '@mahsumurebe/jrpc-client';

const adapter = new WebsocketAdapter('ws:/localhost:3000');

// Client Instance
const clientInstance = new JRPCClient(adapter);

Configuration List

Configurations are defined in the object in the first parameter of the construction method when creating the WebsocketAdapter.

KEY DEFAULT DESCRIPTION Type
parser null Response parser Function
headers null HTTP Headers object
timeout 10_000 Timeout number

Custom Adapters

For custom adapters, you need to extend the adapter class with the AdapterAbstract abstract class. You have to create the abstract functions request, connect and destroy inside the class.

connect: A piece of code that provides the protocol connection should be added to this method.

destroy: A piece of code that breaks the protocol connection should be added to this method.

request: A piece of code that sends the body to the server and parses the output should be added to this method. When there is a response from the server, the response object should be sent to the adapter.config.parse function.

Resources