rb

ResponseBuilder

Build the success and error responses in nodejs application and manage what to be sent to client.

Features

• Automatically logging all the errors, if found, whether on terminal/file
• Setting up status code for error and success automatically
• Automatically detect 404 cases and sent 404 response in those cases.
• Attaching a unique requestId each time a response a sent. With which client can report some unknown error to the API service provider, referencing that requestId.
• Sending your custom errorCode of your app, which can help client to see and identify why an error encountered and what is the remedy.
• Adding extra fields like message, status or any other field while sending response
• If provided, automatically sends the API version information with each response sent to client. That can have many advantages like handling client side code based on the API version and many others if we think.
• Every feature can be set/unset as options, that is customizable globally(throught the app), run-time(within a route function/block) or on-fly(at time of calling handler)
• Reduced, clean and manageable code for your nodejs server.

Install

npm install rb

How to use

Before without RB :

    MongooseModel.find({ _id : some_id }, function(err, docs) {
        if (err) {
            console.error(err);
            res.status(400);
            return res.json({
              error : err
            });
        }
 
        if (!doc) {
            res.status(404);
            return res.json({
              error : 'Document not found'
            });
        }
 
        res.json(docs);
    });

After with RB :

    MongooseModel.find({ _id : some_id }, RB.build(res).all);  // where RB = require('rb')

Builder and Handlers

Builder as : RB.build(res) and handler as .all

Builder with only response

var Builder = RB.build(res [,<options>]);

Widely used. As sending response does not require any request parameter. Options are used to provide run time parameters, explained in detail below.

Builder with request as well as response

RB.build(req,res [,<options>])

Sometimes you may want to use generate some fields for response that depends up request properties, in those cases you should provide req,res [,<options>] as per above format

and now the handlers

Handler for all

.all([<error>],[<successResult>],[<extraSuccessData>]);

Widely used. Handles both error and success case callbacks. This in turn calls .error handler or .success handler based on the values found of parameters.

Error handler

.error([<error>],[<onTheFlyStatusCode>],[<onTheFlyErrorCode>])

Sometime you may want to send error back to client without having a callback. If called without any parameter, default error message will be sent with status 400.

Success handler

.success([<successResult>],[<extraSuccessData>])

Sometime you may want to send success object without having a callback. If called without any parameter, default success message will be sent with status 200. If 2nd parameter is a function, then it will be used as returning success callback instead of sending response to client.

Callback handler

.callIfSuccess(<callBackAsParameter>)

In many cases, you only want to handle only success cases to make further callbacks before sending response to client. Calling this with a function (callback) as parameter that is called with the success result after processing. If in case an error found, then this callback will not be called, and error will directly sent to client

Build once and handle at multiple places

function(req,res){
    var Builder = RB.build(req,res[,<runTimeOptions>]);
    //...
    someFunctionCallingWithCallBack(Builder.all);
    //...
    return Builder.error('You deserve 401..!',401); //Forcely sending 401 error in certain case
    //..
    someOtherFunctionCallingWithCallBack(Builder.all);
};

In some cases we want to handle response for many places that deal with same request/response. In such cases we can build the builder once and use throught the that route function.

Best Practice

In a express like application, we can setup a middleware where we can build the responseBuilder and associate it with res. eg.

  // example of setup middleware, (considering express.io being used)
  app.use(function(req,res,next){
    // you can setup any logic to build the builder based on parameter/url/method you find in request.
    // for example, here i am setting extraKey, valid only for GET request otherwise false, that will auto put total no of records fetched in case of GET requests.
    // You can build the builder the way you want, passing other valid options from table below.
    res.RB = RB.build(req,res,{ extraKey : (req.method === 'GET' ? 'total' : false) });
    // or if you want very simple, you can even do like this `res.RB = RB.build(res);` see builder section above.
  });
 

Now we have response builder as res.RB. Now use res.RB.<anyOfAboveHandlers> wherever you want in your controllers. See handlers above

Options

There are options which configures and handle responses. Every option can either be false or as of corresponding type.

Option	Description	If found unset(false)	Type	Default	ValidOnlyIf
errorKey	Name of the key with which main error is associated in response.	Response body will only contain the error after preprocessing.	String	'error'	Error Handler called
successKey	Name of the key with which main success result is associated in response.	Response body will only contain the success object after preprocessing.	String	false	Success Handler called
extraKey	The key in success response with which contains extra success data. (came with 3rd parmeter in .all or with 2nd parameter in .success).	Extra information will not get associated with response object	String	false	Success handler called
getRequestId	This will link every response with unique requestId for future references. This is the function that return the requestId for a request. You just need to setup this function once globaly with setOptions function of RB, and will be called throughout the application whenever a RB being used. req can be found as first parameter if builder having property req	requestId will not be linked	Function	Current TimeStamp in MS	(errorKey OR successKey) AND addRequestIdWhen
addRequestIdWhen	addRequestId constraints. 0 : never, 1 : only on success, 2 : only on error, 3 : always	requestId will not be linked	Integer[0-3]	0	errorKey or OR successKey
addToError	Object which will get merged with the error response object	Nothing additional will be merged	Object	false	errorKey
addToSuccess	Object which will get merged with the success response object	Nothing additional will be merged	Object	false	successKey
defaultSuccess	In case of falsy value in successResult, this will will be the raw error.	Raw input will be used	String	'SUCCESS'	successKey
defaultError	In case of falsy value in error, this will will be the raw error.	Raw input will be used	String	'SOME_UNKNOWN_ERROR'	errorKey
responseType	RB first try to find if req and its Accept header found. If not so, this one determines what default Content-Type header to be sent.	will not set any Content-Type	String	'application/json'	Either req not found or its Accept is not amongs xml, html or plain
successStatus	Success status sode to be sent	304	Integer(100-600)	200	Success Handler Called
errorStatus	Error status sode to be sent	304	Integer(100-600)	400	Error Handler Called
errorCode	These are the custom/application error code. So that if end user find this error code in response, one may refer some error code ref page and find reason and how to get rid of that error.	No error code will be set	String without space	false	errorKey and Error handler called
errorCodeKey	with which key errorCode to be associated in error object	String	'errorCode'	false	errorCode is set and error handler called
noResultStatus	What status code to be sent if none of error and successResult found	304	Integer(100-600)	404	none of error or successResult found
noResultError	What Error message to be sent if none of error and successResult found	if noResultStatus found and noResultError not found, response will be send without body	String	'RECORD_NOT_FOUND'	noResultStatus
successCallback	Builder will build the successObject and then handler will call this function instead of sending to client. Usefull in cases when you want to perform nested database operations before sending final response	Response will be sent to client	Function that get successResult as first parameter	false	success handler called
filterProperties	To remove the fields in response that are critical when known to client eg password, some private key etc.	No fields will be removed	String containing space separated keys	false	success handler called
preProcessError	If you want to modify/customize error object before sending to client. You get errorObject as first parameter and you should return modified errrorObject in function	Raw error will be sent	Function that returns modified error	MongoDB Unique entry preprocessor. If you are not using mongoDB, rest assured. In 99% cases it wont affect your error.	error handler called
preProcessSuccess	same as preProcessError but for success cases.	Raw success data will be sent	Function returning modified success data	false	success handler called
attachFile	this gives filename of file that needed to be sent as attachement in the response.	Normal response will be sent	String or Function returning name of file as string	false	success handler called
noResponseBody	to send no response body, only status required to be sent	normal response will be sent	Boolean	false	always valid
version	you may like to send version information of the api client is using. You just need to set version globaly with setOptions function of RB, and will be saved throughout the application. This field represents the version information.	no version field will be sent	String	false	errorKey or successKey is set
versionKey	the key with which version info to be associated	No version info will be send	String	'version'	version option is set
logger	Used to log the error/success responses so as to debug easily in development environment, or customize it so that error/response will be saved in file. (you may integerate winston easily for prod)	no loggin will take place	Function	console.log(requestId, info)	logLevel is set
logLevel	in which cases logger should call. // 0 : never, 1 : only on success, 2 : only on error, 3 : always	logger will not be called	integer[0-3]	2	always valid
headers	additional header to be sent with response. Common headers like *-powered-by to be set once and will be used automatically whenever RB is used.	no additional header will be sent	Object, key value pairs of (headerName : headervalue)	false	always valid

How to set options

Globally

require('rb').setOptions(optionsObject)
// optionsObject may be something like
// {version : '1.4.3', noResultStatus : false, successKey : 'result', addToError: { ok : false }, addToSuccess : { ok : true }, //otherValidOptions }

You can set global options like version ,getRequestId, and everything that are application specific. This should be called after RB is loaded and before the main application starts.

At builder

RB.build(res, optionsObject);
OR
RB.build(req, res, optionsObject); //if req is also used further
// optionsObject may be something like
// {errorCode : 'OUT_OF_SERVICE', attachement : 'file_name', addToError : { message : 'Credentials are not valid.!' } //otherValidOptions }

You can set request/response specific options at build time.

At error handler

Builder.error('some_error', statusCodeOnTheFly, ErrorCodeOnTheFly)

Applicable only for error handler. These will be used when you are calling handler yourself without a handler. You may set the properties like statusCode or ErrorCode.

Roadmap

Raise a feature request by logging an issue, and that will fill this place

Any hurdles?

Found anything difficult to understand? or some bug or some improvement?. Create an issue issue for the same.

License

ResponseBuilder is released under the MIT license:

http://www.opensource.org/licenses/MIT