Skip to content

codeofnode/response-builder

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

35 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

About

Building nodejs response with ease.

Resources

Stars

Watchers

Forks

Packages

No packages published