json-rpiecy

📫 rpiecy - JSON-RPC

Rpiecy is a lightweighted lib for managing JSON-RPC objects and comunication.

Features

• ✔︎ Easy
• ✔︎ Customizable
• ✔︎ Liteweighted

Table Of Content

• Installing
• Usage
  • Require
  • ES6 Import
• Api
  • Methods
    • rpiecy.createRequest()
    • rpiecy.createResponse()
    • rpiecy.parse()
    • rpiecy.listen(callback)
    • rpiecy.listenFor(method, callback)
    • rpiecy.output(rpcEnt)
    • rpiecy.sendAndAwait(req)
    • rpiecy.validate
      • isRpc(str)
  • Classes
    • rpiecy.Request
    • rpiecy.Notification
    • rpiecy.Response
    • rpiecy.RpcError
• Examples

Installing

The easiest way of installing is using npm:

$ npm i json-rpiecy -s

Or using yarn:

$ yarn add json-rpiecy

Usage

Require

Using node require:

const rpiecy = require('json-rpiecy');

ES6 Import

Using es6 imports:

import * as rpiecy from 'json-rpiecy';

Api

Methods

rpiecy.createRequest()

Accepts a set of arguments, and returns a rpiecy.Request instance.
Signatures:

• rpiecy.createRequest(method, params?, id?)
  • method - string
  • params? - object | array
  • id? - string | number | null
• rpiecy.createRequest(object)
  • object - object
  • object.method? - string
  • object.params? - object | array
  • object.id? - string | number | null

rpiecy.createResponse()

Accepts a set of arguments, and returns a rpiecy.Response instance.
Signatures:

• rpiecy.createResponse(id, result?, error?)
  • id - string | number
  • result? - string
    • result may be omitted if error is passed
  • error? - rpiecy.Error
    • will be omitted if result is valid
    • required if no result passed
• rpiecy.createResponse(object)
  • object - object

rpiecy.parse()

Parses a json string into a Request a Notification a Response or an Error.
Signature:

• rpiecy.parse(str)

rpiecy.listen(callback)

Listens for requests on specified server/input, check this for more info.
By default it uses stdio for listening and outputing

Signature:

• rpiecy.listen(callback)

rpiecy.listenFor(method, callback)

Listens for method to be passed

Signature:

• rpiecy.listenFor(method, callback): void

rpiecy.output(rpcEnt)

Outputs a rpc entity via defined output channel

Signature:

• rpiecy.output(rpcEnt): void

rpiecy.sendAndAwait(req)

Outputs an rpc Request via defined output channel, and awaits the response, it returns a Promise<RpcResponse>

Signature:

• rpiecy.sendAndAwait(req): Promise<rpiecy.Response>

rpiecy.validate

Namespace containing a set of utility methods for rpc validation.

isRpc(str)

Check if string or object is valid rpc

Signature:

• rpiecy.validate.isRpc(value: string | object): boolean

Classes

rpiecy.Request

A rpc call is represented by a Request object.

Signature:

• rpiecy.Request(method, params?, id?)
  • method - string
  • params? - object | array
  • id? - string | number | null
• rpiecy.Request(object)
  • object - object
  • object.method? - string
  • object.params? - object | array
  • object.id? - string | number | null

Methods:

• .response(result: object): Response<result> - creates a Response object for this request
• .error(message: string, code: number, data?:any): Response<error> - creates an Response with error for this request
• .error(error?: object): Response<error> - overload for accepting an object as first argument
• .matches(method: string): boolean - Check if request matches method
• .sendAndAwait(): Promise<Response> - Sends a request to set output channel, and awaits the response

rpiecy.Notification

A Notification is a Request object without an "id" member. A Request object that is a Notification signifies the Client's lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

rpiecy.Response

When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications.

Signature:

• rpiecy.Response(id, result?, error?)
  • id - string | number
  • result? - string
    • result may be omitted if error is passed
  • error? - rpiecy.Error
    • will be omitted if result is valid
    • required if no result passed
• rpiecy.Response(object)
  • object - object
  • object.result? - object | array
  • object.error? - object | array
  • object.id? - string | number | null

rpiecy.RpcError

When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a RpcError:

Signature:

• rpiecy.RpcError(message, code, data?)
  • message - string
  • code - number
  • data - object | array
• rpiecy.RpcError(object)
  • object - object
  • object.message - string
  • object.code - number
  • object.data? - object | array

Static Constants:

• Error.INTERNAL_ERROR = -32603
• Error.INVALID_PARAMS = -32602
• Error.METHOD_NOT_FOUND = -32601
• Error.INVALID_REQUEST = -32600
• Error.PARSE_ERROR = -32700
• Error.TIMED_OUT = -32001

Examples

const rpiecy = require('rpiecy');

const request = rpiecy.createRequest({ method: 'method', params: {}, id: 'id' });
request.print();
request.output();


const response = rpiecy.createResponse('id', { /* result */ });
response.print();
response.output();

rpiecy.sendAndAwait(request)
  .then(response => {
    console.log(`Response for ${request.id}: `, response);
  })

rpiecy.listen((request) => {
  console.log(`Received request ${request.id}: `, request);
  request.response({ data: SOME_DATA }).output();
});

const method = rpiecy.createMethod('test-method', {});
rpiecy.listenFor(method, (request) => {
  console.log(`Received request ${request.id}: `, request);
  request.response({ data: SOME_DATA }).output();
});