valeronlol / express-json-rpc-router

JSON RPC express router

JSON-RPC node.js implementation

JSON-RPC official spec.

Extremely fast and simple Node.js JSON-RPCv2 router middleware. Handle incoming request and apply to controller functions. Validation available.

Note As Router require body-parser which must be used before router.

Installation

$ npm install express express-json-rpc-router

or

$ yarn add express express-json-rpc-router

Examples

Simple

const express = require('express')
const jsonRouter = require('express-json-rpc-router')
const app = express()

const controller = {
    testMethod({ username }) {
        console.log('username: ', username)
        return ['example data 1', 'example data 2']
    }
}

app.use(express.json())
app.use(jsonRouter({ methods: controller }))
app.listen(3000, () => console.log('Example app listening on port 3000'))

and

curl -X POST \
  http://localhost:3000 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "testMethod",
    "params": {
        "username": "valeron"
    },
    "id": 1
 }'

will return:

{
  "jsonrpc": "2.0",
  "result": [
    "example data 1",
    "example data 2"
  ],
  "id": 1
}

With Validation, after hooks and onError callback

const controller = {
    // You have access to raw express req/res object as raw.res and raw.req 
    testMethod({ username }, raw) {
        console.log('username: ', username)
        return ['example data 1', 'example data 2']
    }
}

const beforeController = {
    // You have access to raw express req/res object as raw.res and raw.req
    testMethod(params, _, raw) {
        if (Math.random() >= 0.5) { // Random error
            const error = new Error('Something going wrong')
            error.data = { hello: 'world' } // its optional
            throw error
        }
    }
}

const afterController = {
    testMethod: [
      // You have access to result and to raw express req/res object as raw.res and raw.req.
      (params, result, raw) => console.log('testMethod executed 1!'), () => console.log('testMethod executed 2!')
    ]
}

app.use(bodyParser.json())
app.use(jsonRouter({
    methods: controller,
    beforeMethods: beforeController,
    afterMethods: afterController,
    onError(err) {
        console.log(err) // send report
    }
}))
app.listen(3000, () => console.log('Example app listening on port 3000'))

and

curl -X POST \
  http://localhost:3000 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "testMethod",
    "params": {
        "username": "valeron"
    },
    "id": 1
 }'

will return:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Something going wrong",
    "data": { "hello": "world" }
  },
  "id": 1
}

Changelog:

- v1.2.0
* Added raw { req, res } native express object to controller and hooks as last argument.
* Passed next arguments: `params, null, raw` to beforeController actions and `params, result, raw` to afterController
* Passed additional second argument `params, raw` to controller actions
- v1.3.0
* Added optional err.data payload to comply with JSON RPC specification: "5.1 Error object".

Options

The express-json-rpc-router function takes an optional options object that may contain any of the following keys:

methods type: Object<function(params, raw)>

You can pass the object of your methods that will be called when a match is made via JSON-RPC method field.

beforeMethods type: Object<function(params, _, raw)|Array<function(params, params, _, raw)>>

You can provide function or array of functions, which will be called before main method with same name are called. This is the best place for validation. beforeMethods names should be the same as methods names. Request params will be passed as first argument.

afterMethods type: Object<function(params, execResult, raw)|Array<function(params, execResult, raw)>>

You can provide function or array of functions, which will be called after main method with same name are called. This is the best place to write logs. afterMethods names should be the same as methods names. Method execution result will be passed as second argument. Request params will be passed as first argument.

onError type: function(err, params)

callback(err, params) {} Optionally you can pass onError callback which will be called when json-rpc middleware error occurred.

License

MIT

express-json-rpc-router's Issues

Multiple usage

Hi! Handy module, but doesn't allow to create multiple RPC endpoints due to global config.
Can you please put config inside module.exports?

Add Typescript typings

Cannot destructure property 'stores' of 'undefined' as it is undefined."

If the params property is omitted from the request, then destructuring fails. For example:

{
    "jsonrpc": "2.0",
    "method": "addStore",
    "id": 1
}

The response is:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32603,
        "message": "Cannot destructure property 'store' of 'undefined' as it is undefined."
    },
    "id": 1
}

if the function is defined as:

async addStore ({ store }, raw) {

}

A workaround

async addStore (data = {},  raw) {
   const { store } = data;
}

Would it be possible to provide an empty JSON to the functions, even when params is missing, to allow function parameter level destructuring?

Cannot destructure property 'store' of 'undefined' as it is undefined."

If the params property is omitted from the request, then destructuring fails. For example:

{
    "jsonrpc": "2.0",
    "method": "addStore",
    "id": 1
}

The response is:

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32603,
        "message": "Cannot destructure property 'store' of 'undefined' as it is undefined."
    },
    "id": 1
}

if the function is defined as:

async addStore ({ store }, raw) {

}

A workaround

async addStore (data = {},  raw) {
   const { store } = data;
}

Would it be possible to provide an empty JSON to the functions, even when params is missing, to allow function parameter level destructuring?