calibrate

Calibrate

Micro library for providing uniform json output for RESTful APIs, with error handling.

Feel free to raise an issue or contact me on twitter if you have any questions @johnbrett_. Beginners, feature requests and bug reports are welcomed.

Please star if you using this module so I know where to focus my time spent on open source work.

Usage:

const Calibrate = require('calibrate')

/**
* Checks whether data is an error, calls either Calibrate.error or Calibrate.reponse
**/
Calibrate(data [, meta])

// Valid response structure:
{
    "statusCode": ...,
    "data":       ...,
    "meta":       ...
}

// Error response structure:
{
    "statusCode": ...,
    "error":      ...,
    "message":    ...
}

/**
* If data is non-null and defined:
*  -  wraps value in object with statusCode and meta properties
* If null or undefined
*  -  returns a Boom notFound error object
**/
Calibrate.response(data [, meta])

/**
* If is a Boom Error object
*  - returns object as is
* If is a non Boom Error Object
*  - returns a Boom badImplementaion Error Object
**/
Calibrate.error(data)

/**
* **For use with Hapi.js framework (http://hapijs.com)**
* Decorates the reply interface with the calibrate method
**/
Calibrate.decorate // register as a hapijs plugin

/**
 * If decorating your server using a Glue (https://github.com/hapijs/glue) manifest,
 * you can use `calibrate/decorate` as the plugin name. 
 * Background: https://github.com/johnbrett/calibrate/issues/55
 **/

Example in Hapijs:

'use strict';

const Hapi = require('hapi');
const Calibrate = require('calibrate');
const server = new Hapi.Server({ port: 3000 });

(async () => await server.register({ plugin: Calibrate.hapi, options: { onResponse: false } }))();    // 

server.route([
    {
        method: 'GET',
        path: '/user/{id}',
        handler: function (request, h) {                // Using Promises
            
            const promise = User.findById(request.params.id)
                .then(Calibrate.response)               // Formats Response
                .catch(Calibrate.error);                // Errors caught and wrapped
            return h.response(promise);                 // Return Calibrated Response
        }
    },
        {
            method: 'GET',
            path: '/team/{id}',
            handler: function (request, h) {            // Using Callbacks

                Team.findById(request.params.id, (err, team) => {
                    
                    if (err) {                                      // Catch any errors
                        return h.response(Calibrate.error(err));    // Errors caught and wrapped
                    }
                    
                    return h.response(Calibrate.response(team));    // Return Calibrate Response
                });
            }
        },
        {
            method: 'GET',
            path: '/team/{id}',
            handler: function (request, h) {            // Using new decorator function

                Team.findById(request.params.id, (err, team) => {
                    
                    if(err) {                           // Catch any errors
                        return h.calibrate(err);        // Using decorator function
                    }
                    
                    return h.calibrate(team);           // Using decorator function
                });
            }
        }
    ]);

    (async () => await server.start())();
});

License MIT @ John Brett