DEFINITIONS.md

Classes

RpcError

Represents the json rpc error base structure, it accepts 3 params: code, message, data as specified by the protocol

RpcServiceBase

Represents the base class from which rpc callable classes can be extended. Extended classes can be wrapped through rpc wrapper and exposed via different transport protocols as json rpc services.

RpcWrapper

Represents the rpc wrapper class that will wrap requests and responses for any object/instance. This class can be used to rpcify the variables and make them callable through json rpc 2.0 protocol. Keep in mind that only functions can be invoked, there's no way to invoke getting/setting properties of object! This instance will act as a proxy to the wrapped object, and can call any function type in object (with callbacks, async functions and simple functions)

Functions

isStringOrNumber(val) ⇒ boolean

Determines if the value is primitive string or primitive number, in case of number NaN and Infinity values are not considered numbers. It returns true in case of it represents one of these two types

isNil(val) ⇒ boolean

Determines if the value is null or undefined, returns true in case of it represents one of these two types

getObjectFunctions(toCheck) ⇒ Array.<string>

Returns the functions/methods that belong to object, it excludes the object prototype methods:

• __defineGetter__,
• __defineSetter__,
• __lookupGetter__,
• __lookupSetter__,
• constructor,
• hasOwnProperty,
• isPrototypeOf,
• propertyIsEnumerable Methods toLocaleString, toString, valueOf are included

Typedefs

JsonRpcErrorFields : Object

Fields that should be exported during serialization

JsonRpcRequest : Object

JsonRpcResponse : Object

RpcError

Represents the json rpc error base structure, it accepts 3 params: code, message, data as specified by the protocol

Kind: global class

• RpcError
  • new RpcError(code, message, [data])
  • instance
    • .code
    • .data
    • .message
    • .toString() ⇒ string
    • .toJSON() ⇒ JsonRpcErrorFields
  • static
    • .PARSE_ERROR : number
    • .INVALID_REQUEST : number
    • .METHOD_NOT_FOUND : number
    • .INVALID_PARAMS : number
    • .INTERNAL_ERROR : number
    • .SERVER_ERROR : number
    • .createError(code, [message], [data]) ⇒ RpcError

new RpcError(code, message, [data])

Param	Type	Default	Description
code	number		json rpc error code
message	string		json rpc error message
[data]	any		json rpc additional error data

Example

RpcError.createError(RpcError.INVALID_REQUEST) // RpcError: { code: -32600, message: 'Invalid request' }
RpcError.createError(RpcError.INVALID_REQUEST, null, new Error('foo')) // RpcError: { code: -32600, message: 'Invalid request', data: 'Error: foo' }
RpcError.createError(RpcError.INVALID_REQUEST, 'INV_REQ', new Error('foo')) // RpcError: { code: -32600, message: 'INV_REQ', data: 'Error: foo' }

rpcError.code

Kind: instance property of RpcError
Properties

Name	Type	Description
code	number	Represents json rpc error code, e.g. -32700. If invalid code range is provided -32000 (Server Error) is used, allowed codes: [-32603, -32600], -32700, [-32099, -32000]

rpcError.data

Kind: instance property of RpcError
Properties

Name	Type	Description
data	any	Represents additional error data specified by protocol

rpcError.message

Kind: instance property of RpcError
Properties

Name	Type	Description
message	string	Represents the json rpc error message, e.g. Parse error

rpcError.toString() ⇒ string

Returns the json representing the error, e.g.: '{"code":-32602,"message":"Invalid params","data":"foo param is required"}'

Kind: instance method of RpcError

rpcError.toJSON() ⇒ JsonRpcErrorFields

Returns the fields that should be exposed on json serialization

Kind: instance method of RpcError

RpcError.PARSE_ERROR : number

-32700

Kind: static constant of RpcError

RpcError.INVALID_REQUEST : number

-32600

Kind: static constant of RpcError

RpcError.METHOD_NOT_FOUND : number

-32601

Kind: static constant of RpcError

RpcError.INVALID_PARAMS : number

-32602

Kind: static constant of RpcError

RpcError.INTERNAL_ERROR : number

-32603

Kind: static constant of RpcError

RpcError.SERVER_ERROR : number

-32000

Kind: static constant of RpcError

RpcError.createError(code, [message], [data]) ⇒ RpcError

Kind: static method of RpcError

Param	Type	Default	Description
code	number		json rpc error code, if invalid code range is provided -32000 (Server Error) is used, allowed codes: [-32603, -32600], -32700, [-32099, -32000]
[message]	string	null	json rpc error message, if omitted it will be generated based on error code
[data]	any		json rpc additional error data

RpcServiceBase

Represents the base class from which rpc callable classes can be extended. Extended classes can be wrapped through rpc wrapper and exposed via different transport protocols as json rpc services.

Kind: global abstract class

• RpcServiceBase
  • .methods
  • .validateMethod(method) ⇒ Promise.<void> | void
  • .validateParams(method, params) ⇒ Promise.<void> | void
  • .areParamsValid(method, params) ⇒ Promise.<boolean> | boolean

rpcServiceBase.methods

Kind: instance property of RpcServiceBase
Access: protected
Properties

Name	Type	Description
methods	Array.<string>	Represents the list of methods that are exposed through rpc calls, each method here should be implemented with the same name

rpcServiceBase.validateMethod(method) ⇒ Promise.<void> | void

Checks if the method is available in service and can be called externally, if not it throws the appropriate rpc error It should not be overridden in extended classes!

Kind: instance method of RpcServiceBase
Throws:

• RpcError

Param	Type	Description
method	string	The method that will be checked if it exists and it's available

rpcServiceBase.validateParams(method, params) ⇒ Promise.<void> | void

Checks if the params for the called method through rpc are valid, if not it throws the appropriate rpc error. It should not be overridden in extended classes!

Kind: instance method of RpcServiceBase
Throws:

• RpcError

Param	Type	Description
method	string	The method that will be called externally
params	Object | Array.<any>	The params that will be passed to the method

rpcServiceBase.areParamsValid(method, params) ⇒ Promise.<boolean> | boolean

The abstract that will verify if the provided params for the method are valid, it should be implemented in all extended classes

Kind: instance abstract method of RpcServiceBase

Param	Type	Description
method	string	The method that will be called externally
params	Object | Array.<any>	The params that will be passed to the method

RpcWrapper

Represents the rpc wrapper class that will wrap requests and responses for any object/instance. This class can be used to rpcify the variables and make them callable through json rpc 2.0 protocol. Keep in mind that only functions can be invoked, there's no way to invoke getting/setting properties of object! This instance will act as a proxy to the wrapped object, and can call any function type in object (with callbacks, async functions and simple functions)

Kind: global class

• RpcWrapper
  • new RpcWrapper(service, [cbMethods])
  • .service
  • .proxy
  • .cbMethods
  • .callReq(payload) ⇒ Promise.<(JsonRpcResponse|Array.<JsonRpcResponse>|void)>
  • ._procReq(req) ⇒ Promise.<(JsonRpcResponse|void)>
  • ._createRes([id], [err], [res]) ⇒ JsonRpcResponse
  • ._execFunc(func, params) ⇒ any

new RpcWrapper(service, [cbMethods])

Param	Type	Default	Description
service	RpcServiceBase | Object		The object/instance that will be wrapped. It can be any object type but if it's extension of RpcServiceBase it will validate also params passed to method during the call. In case if it's a simple object then it should be responsibility of the method itself to validate the passed arguments. In case it's instance of RpcServiceBase then the service will be stored into service property, otherwise it will be stored in proxy property
[cbMethods]	Array.<string>	[]	Optional methods that use callbacks. Here we should specify all methods that use callbacks to pass the responses. Each method that has callbacks should support this callback structure: (err?: Error, res?: any) => void

Example

// RpcServiceBase extended class
const myService = new ProductService([ { id: 1, name: 'Product 1' }, { id: 2, name: 'Product 2' } ])
const rpcProxy = new RpcWrapper(myService)
const payload = '{"jsonrpc":"2.0","method":"find","params":[1],"id":"3"}'
const rpcRes = await rpcProxy.callReq(payload) // '{"jsonrpc":"2.0","id":"3","result":{"id":1,"name":"Product 1"}}'

Example

// Object with callback methods
const service1 = {
  storeContent: (content, cb) => {
    fs.writeFile('test.log', content + '\n', { flag: 'a' }, cb)
  }
}
const proxy1 = new RpcWrapper(service1, ['storeContent'])

Example

// Simple object
const myService = {
  ping: async () => Date.now(),
  echo: (params) => params,
}
const rpcProxy = new RpcWrapper(myService)

rpcWrapper.service

The service that will be proxied

Kind: instance property of RpcWrapper
Access: protected
Properties

Name	Type
[service]	RpcServiceBase

rpcWrapper.proxy

The object that will be proxied

Kind: instance property of RpcWrapper
Access: protected
Properties

Name	Type
[proxy]	Object

rpcWrapper.cbMethods

Methods of the object that uses callbacks

Kind: instance property of RpcWrapper
Access: protected
Properties

Name	Type
cbMethods	Array.<string>

rpcWrapper.callReq(payload) ⇒ Promise.<(JsonRpcResponse|Array.<JsonRpcResponse>|void)>

This method invokes the json rpc requests against the wrapped object/instance. The response can be an array, single item or void depending on request.

Kind: instance method of RpcWrapper
Returns: Promise.<(JsonRpcResponse|Array.<JsonRpcResponse>|void)> - e.g. {"jsonrpc": "2.0", "result": 7, "id": "1"}
Access: public

Param	Type	Description
payload	string	JSON payload that is received through transport layer, e.g. {"jsonrpc": "2.0", "method": "sum", "params": [1,2,4], "id": "1"}

rpcWrapper._procReq(req) ⇒ Promise.<(JsonRpcResponse|void)>

Validates the received request and invokes the method on proxied object, and in case of id param returns the response.

Kind: instance method of RpcWrapper
Returns: Promise.<(JsonRpcResponse|void)> - e.g. {"jsonrpc": "2.0", "result": 7, "id": "1"}
Access: protected

Param	Type	Description
req	JsonRpcRequest	Request object received through the proxy call

rpcWrapper._createRes([id], [err], [res]) ⇒ JsonRpcResponse

Crafts the json rpc response based on input

Kind: instance method of RpcWrapper
Access: protected

Param	Type	Description
[id]	string | number	Optional request id
[err]	RpcError	Optional error object
[res]	any	Optional response object, ignored in case when err is present

rpcWrapper._execFunc(func, params) ⇒ any

Calls the function inside the proxied object with specified arguments

Kind: instance method of RpcWrapper
Access: protected

Param	Type	Description
func	function	The function of the proxied object that will be invoked
params	any	The params that will be passed, in case if rpc request is array params are passed in order, otherwise single object is passed

isStringOrNumber(val) ⇒ boolean

Determines if the value is primitive string or primitive number, in case of number NaN and Infinity values are not considered numbers. It returns true in case of it represents one of these two types

Kind: global function

Param	Type	Description
val	any	Value that will be checked

isNil(val) ⇒ boolean

Determines if the value is null or undefined, returns true in case of it represents one of these two types

Kind: global function

Param	Type	Description
val	any	Value that will be checked

getObjectFunctions(toCheck) ⇒ Array.<string>

Returns the functions/methods that belong to object, it excludes the object prototype methods:

• __defineGetter__,
• __defineSetter__,
• __lookupGetter__,
• __lookupSetter__,
• constructor,
• hasOwnProperty,
• isPrototypeOf,
• propertyIsEnumerable Methods toLocaleString, toString, valueOf are included

Kind: global function

Param	Type	Description
toCheck	Object	The object from which the function names will be extracted

JsonRpcErrorFields : Object

Fields that should be exported during serialization

Kind: global typedef
Properties

Name	Type	Description
code	number	RpcError code field
message	string	Error message field
[data]	any	RpcError data field, present only if not nil

JsonRpcRequest : Object

Kind: global typedef
Properties

Name	Type
jsonrpc	'2.0'
method	string
[params]	Object | Array
[id]	string | number

JsonRpcResponse : Object

Kind: global typedef
Properties

Name	Type	Description
jsonrpc	'2.0'
[error]	Object
error.code	number	RpcError code field
error.message	string	Error message field
[error.data]	any	RpcError data field, present only if not nil
[result]	any
[id]	string | number