node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



Build Status

This is a JSON-RPC protocol implementation in NodeJS that follows JSON-RPC 2.0 specs. The good and also bad thing about this library is that it enforces method handler modules to have a certain convention/design pattern. However, it allows the server to automatically extract documentation from the handler (Introspection). This library is still under development.


  • Handles GET/POST requests
  • Better error feedback
  • Allows method namespacing (Module.method)
  • Allows exposure of all methods inside a module
  • Authentication can be achieved by giving a preHandle function
  • Introspection (currently planning)


The usual npm install njrpc or if you prefer, you can grab the source/fork it and make changes yourself.


Handlers that can be registered with njrpc should have a name attribute in the instance. A sample handler can be found in handler.js.

The best design pattern to use with this server is the Module design pattern.


List of errors that JSON-RPC server supports.


Map of all the RPC module, in the form of modules[className].methodName


Registers an array of modules/a single module, which should have name as the namespace of the module.


Interceptor capable of pre-processing json request before it get dispatched to Handler modules. This function takes in 2 parameters:

  • jsonRequest: JSON request object
  • next: Function signaling continuation of the process. Passing an Error to this function will force server to return an error response instead of moving on.


Map of custom URL to handler function. Handler function takes in 2 arguments:

  • req: Request object
  • res: Response object to write to

njrpc.output(res, [jsonResponse])

Actually write the JSON response out to the pipe. This can also be overridden to write something else.

njrpc.handle(req, res, [preHandleFn])

Handles a request & response, JSON-RPC style. preHandleFn is used to manipulate the JSON request before it gets pushed down to the Handler level. preHandleFn takes a single JSON request object as the argument (after parsing and whitelisting)


Simple EchoHandler that echoes whatever it receives

var EchoHandler = function () {
        return {
            name : 'EchoHandler',
            echo : function (str) {
                return str;
, jrpcServer = require('njrpc')
, http = require('http');
jrpcServer.register(new EchoHandler());

Authenticated Echo Handler that still echoes, but needs a user & token

var AuthenticatedEchoHandler = function () {
        return {
            name : 'AuthenticatedEchoHandler',
            echo : function(context, str) {
                if (!context.user || !context.token) {
                    throw new Error("This call is unauthenticated");
                return str;
, preHandler = function (jsonReq, next) {
        if (jsonReq.headers) {
            ? jsonReq.params.unshift(jsonReq.headers)
            : jsonReq.params.context = jsonReq.headers;
            return next();
        return next(new Error('User has to be authenticated'));
, jrpcServer = require('njrpc')
, http = require('http');
jrpcServer.register(new AuthenticatedEchoHandler());
jrpcServer.interceptor = preHandler;