jepc

Fully featured JSON-RPC handler for JavaScript/Node.js. If you need a server, try sepc. If you need a client, try repc. If you need details, read JSON-RPC 2.0 Specification.

Installation

npm i jepc

Usage

Basic:

import jepc from 'jepc';

const add = (a, b) => a + b;
const ping = () => null;

const { handle } = jepc({ add, ping });

const result4 = await handle({ jsonrpc: '2.0', method: 'add', params: [2, 2], id: 1 });
const result8 = await handle('{ "jsonrpc": "2.0", "method": "add", "params": [4, 4], "id": 2 }');
const notificationResult = await handle({ jsonrpc: '2.0', method: 'ping' });
const batchResult = await handle([
    { jsonrpc: '2.0', method: 'add', params: [2, 2], id: 1 },
    { jsonrpc: '2.0', method: 'add', params: [4, 4], id: 2 },
    { jsonrpc: '2.0', method: 'ping' },
]);

console.log(result4); // { jsonrpc: '2.0', result: 4, id: 1 }
console.log(result8); // { jsonrpc: '2.0', result: 8, id: 2 }
console.log(notificationResult); // undefined
console.log(batchResult); // [{ jsonrpc: '2.0', result: 4, id: 1 }, { jsonrpc: '2.0', result: 8, id: 2 }]

Express:

import jepc from 'jepc';
import express from 'express';

const add = (a, b) => a + b;

const { handle } = jepc({ add });

const app = express();

app.use(express.text({ type: '*/*' }));

app.post('/', (req, res) => {
    handle(req.body)
        .then((out) => res.send(out));
});

Accessing params:

// natural (like general js function) 
function add(a, b) {
    return a + b;
}

// using destruction
function createUser({ name, email }) {
    const user = { /* handle user creation */ };

    return user;
}

// using this.params
function createUser() {
    const { name, email } = this.params;

    const user = { /* handle user creation */ };

    return user;
}

// using ...
function sort(...numbers) {
    return numbers.sort();
}

// using "arguments"
// parameter names must be empty here
function sum() {
    const numbers = arguments[0];

    return Object.values(numbers).reduce((s, c) => s + c, 0);
}

Method class:

import jepc, { Method } from 'jepc';

class SumMethod extends Method {
    handle(params) {
        return Object.values(params)
            .reduce((s, c) => s + c, 0);
    }
}

class ReturnId extends Method {
    handle(params, context) {
        return context.request.id;
    }
}

const sum = new SumMethod();

const { handle } = jepc({ sum });

Producing errors:

import jepc, { JsonRpcError } from 'jepc';

function divide(a, b) {
    if (b === 0) {
        throw new JsonRpcError(-32602, 'Cannot divide by zero');
    }

    return a / b;
}

jepc({ divide });

Handling errors:

import jepc from 'jepc';

const add = () => {
    throw new Error('Unsupported!');
}

const { setErrorHandler } = jepc({ divide });

setErrorHandler((error, context, defaultErrorHandler) => {
    console.error(error);

    return defaultErrorHandler(error, context);
});

API

handle

Handle JSON-RPC request. Supports object, array and string as input. If string is passed, it will be parsed as JSON.

• type: function(object | array | string)
• result: Promise<object | array | undefined>
• example:

handle('{}'); // invalid request error
handle('[]'); // invalid request error
handle('a'); // parse error
handle({ "jsonrpc": "2.0", "method": "add", "params": [4, 4], "id": 2 }); // ok
handle('{ "jsonrpc": "2.0", "method": "ping" }'); // ok, undefined returned
handle([{ "jsonrpc": "2.0", "method": "add", "params": [4, 4], "id": 2 }]) // ok, array returned

methods

Available methods.

• type: Record<string, function>

setErrorHandler

Set error handler.

• type: function(function(error, context, defaultErrorHandler))