jsonrpc-lite

What is jsonrpc-lite?

The jsonrpc-lite package is a lightweight implementation of the JSON-RPC 2.0 protocol. It allows developers to easily create and parse JSON-RPC 2.0 requests and responses, making it suitable for building APIs and services that communicate using this protocol.

What are jsonrpc-lite's main functionalities?

Creating JSON-RPC Requests

This feature allows you to create a JSON-RPC request object. The code sample demonstrates how to create a request for a method named 'add' with parameters 'a' and 'b'.

const jsonrpc = require('jsonrpc-lite');
const request = jsonrpc.request(1, 'add', { a: 5, b: 3 });
console.log(request);

Parsing JSON-RPC Messages

This feature allows you to parse a JSON-RPC message string into a JSON-RPC object. The code sample shows how to parse a JSON-RPC request message.

const jsonrpc = require('jsonrpc-lite');
const message = '{"jsonrpc":"2.0","method":"add","params":{"a":5,"b":3},"id":1}';
const parsed = jsonrpc.parse(message);
console.log(parsed);

Creating JSON-RPC Responses

This feature allows you to create a JSON-RPC response object. The code sample demonstrates how to create a successful response with a result.

const jsonrpc = require('jsonrpc-lite');
const response = jsonrpc.success(1, { result: 8 });
console.log(response);

Creating JSON-RPC Errors

This feature allows you to create a JSON-RPC error response. The code sample shows how to create an error response for a method not found.

const jsonrpc = require('jsonrpc-lite');
const error = jsonrpc.error(1, jsonrpc.JsonRpcError.methodNotFound());
console.log(error);

Other packages similar to jsonrpc-lite

jayson

Jayson is a full-featured JSON-RPC 2.0/1.0 server and client for Node.js. It provides more comprehensive server and client implementations compared to jsonrpc-lite, which is more focused on message creation and parsing.

node-json-rpc

Node-json-rpc is a simple JSON-RPC 2.0 server and client library for Node.js. It offers similar functionalities to jsonrpc-lite but includes server and client capabilities, making it suitable for building complete JSON-RPC services.

json-rpc-ws

Json-rpc-ws is a library for JSON-RPC 2.0 over WebSockets. It extends the JSON-RPC protocol to work over WebSockets, providing real-time communication capabilities, which jsonrpc-lite does not natively support.

README

JSON-RPC lite

Parse and Serialize JSON-RPC2 messages in node.js or browser.

Inspired by https://github.com/soggie/jsonrpc-serializer

A implementation of JSON-RPC 2.0 specifications

Install

npm install jsonrpc-lite

API

const jsonrpc = require('jsonrpc-lite')

jsonrpc.request(id, method[, params])

Creates a JSON-RPC 2.0 request object, return JsonRpc object.

• id: {String|Integer}
• method: {String}
• params: {Object|Array}, optional

const requestObj = jsonrpc.request('123', 'update', {list: [1, 2, 3]})
// {
//   jsonrpc: '2.0',
//   id: '123',
//   method: 'update',
//   params: {list: [1, 2, 3]}
// }

jsonrpc.notification(method[, params])

Creates a JSON-RPC 2.0 notification object, return JsonRpc object.

• method: {String}
• params: {Object|Array}, optional

const notificationObj = jsonrpc.notification('update', {list: [1, 2, 3]})
// {
//   jsonrpc: '2.0',
//   method: 'update',
//   params: {list: [1, 2, 3]}
// }

jsonrpc.success(id, result)

Creates a JSON-RPC 2.0 success response object, return JsonRpc object.

• id: {String|Integer}
• result: {Mixed}

const successObj = jsonrpc.success('123', 'OK')
// {
//   jsonrpc: '2.0',
//   id: '123',
//   result: 'OK',
// }

jsonrpc.error(id, error)

Creates a JSON-RPC 2.0 error response object, return JsonRpc object.

• id: {String|Integer}
• error: {JsonRpcError}

const errorObj = jsonrpc.error('123', new jsonrpc.JsonRpcError('some error', 99))
// {
//   jsonrpc: '2.0',
//   id: '123',
//   error: {code: 99, 'message': 'some error'},
// }

jsonrpc.parse(message)

Takes a JSON-RPC 2.0 payload (string) and tries to parse it into a JSON. If successful, determine what object is it (response, notification, success, error, or invalid), and return it's type and properly formatted object.

• message: {String}

return an array, or an object of this format:

single parsed request:

{
  type: 'request',
  payload: {
    jsonrpc: '2.0',
    id: 123,
    method: 'update',
    params: {}
  }
}

batch parsed result:

[{
  type: 'request',
  payload: {
    jsonrpc: '2.0',
    id: '123',
    method: 'update',
    params: [1, 2, 3]
  }
}, {
  type: 'notification',
  payload: {
    jsonrpc: '2.0',
    method: 'update',
    params: {_id: 'xxx'}
  }
}, {
  type: 'success',
  payload: {
    jsonrpc: '2.0',
    id: '123',
    result: 'OK'
  }
}, {
  type: 'error',
  payload: {
    jsonrpc: '2.0',
    id: '123',
    error: [jsonrpc.JsonRpcError object]
  }
}, {
  type: 'invalid',
  payload: [jsonrpc.JsonRpcError object]
}]

jsonrpc.parseObject(message)

Takes a JSON-RPC 2.0 payload (Object) and tries to parse it into a JSON. If successful, determine what object is it (response, notification, success, error, or invalid), and return it's type and properly formatted object.

• message: {Object}

return an JsonRpcParsed object with type and payload.

Class: jsonrpc.JsonRpc()

Class: jsonrpc.JsonRpcError(message, code[, data])

Create a JsonRpcError instance.

• message: {String}
• code: {Integer}
• data: {Mixed} optional

const error = new jsonrpc.JsonRpcError('some error', 999)

Class Method: jsonrpc.JsonRpcError.invalidRequest([data])

Class Method: jsonrpc.JsonRpcError.methodNotFound([data])

Class Method: jsonrpc.JsonRpcError.invalidParams([data])

Class Method: jsonrpc.JsonRpcError.internalError([data])

Class Method: jsonrpc.JsonRpcError.parseError([data])