Noosphere Possibilities Maximized

    seven-boom

    1.0.3 • Public • Published

    seven-boom

    A decorator around Boom (HTTP-friendly error objects) to empower it

    This library is fully tested with 100% coverage

    CircleCI Coverage Status Donate

    Table of contents generated with markdown-toc

    Why do I need this

    The reason beyond this library is to have more cusomize errors. Boom provide very cool interface and functions to create new errors, yet most of the errors are only get message(String) and data(Object) as arguments. Then boom will add some more keys to the error object like isServer, isBoom and so on. Most of the hard work are done by Boom guys, so they should get a proper credit.

    In a lot of apps the errors contain more data on the root level. some common examples are:

    • guid of the error (as id in database or for better look for it in the db / log)
    • a name / code of the error (usually for client usage, because checking the error type by the message is very wrong)
    • timeThrown for analytical purposes

    What do i get with this library

    SevenBoom give you an ability to init the SevenBoom object with your desired error format.

    • You can add new root fields which from now will be an args for any of your error.
    • You can add functions which will called any time you create new error (pass a guid generator / or time (now) generator is great example for this feature.

    What include out of the box

    • A guid generator (by uuid.v4) which will add guid field for any of your errors
    • timeThrown generator (date.isoString) which will add timeThrown for any of your errors

    Boom compatability

    In order to make the transition from Boom easier, the SevenBoom args will be in the same order as the default Boom args. So you can simply replace all of your Boom.XXX with SevenBoom.XXX and everything should work just fine. Then you can start change your usage every place you want (if you added more args).

    How does it work

    Under the hood, SevenBoom is pretty simple, it just going over all Boom function and wrap them with new functions with the same name. Then when you call the SevenBoom function it will internally call Boom then add your new args, and run your functions

    Configure

    you should import the SevenBoom class by

    import SevenBoom from 'seven-boom';

    Then you should create an args definitions array:

    const argsDefs = [
      {
        name : 'errorName',
        order: 1
      }, {
        name : 'timeThrown',
        order: 2,
        default: null
      }, {
        name : 'guid',
        order: 3,
        default: null
      }
    ];

    finally you should call init

    SevenBoom.init(argsDefs);

    Arg definition contains the following keys:

    • name - the name will be the key inside the result.output.payload
    • order - the order of the arg in the new function (i just sort by this order before pass the args on, so you can make skip for example order 1 then order 5 then order 10)
    • default - default can be either a value like 'myDefaultVal' or a function which return a value for example
    function _defaultTimeThrown() {
      return (new Date()).toISOString();
    }

    The default will be used only in case you didn't pass an actual value. so you can always override it when calling the function. If you want to use the default value for an arg which is not the last one you can just pass undefined and the default will be used.

    There is special case for the timeThrown and guid defaults. If you specify them as an args with a falsy default (null, undefined etc), it will create a default default uses those functions:

    function _defaultTimeThrown() {
      return (new Date()).toISOString();
    }
     
    function _defaultGenerateGuid() {
      return uuid.v4();
    }

    If you don't specify them as an args at all they won't be used.

    Usage

    You should start by reading Boom docs, it's very easy and intuitive. For more examples you can just look on the sevenBoom.spec.js file.

    Before

    Code

    function getUserById(userId) {
     const errorMessage = `User with id: ${userId} not found`;
     const errorData = { userId };
     throw Boom.notFound(errorMessage, errorData);
    }

    Error result

    {
      isBoom: true,
      isServer: false,
      message: 'User with id: 123 not found.',
      data: {userId: '123'},
      output: {
        statusCode: '404',
        payload: {
          statusCode: '404',
          error: 'Not Found',
          message: 'User with id: 123 not found.',
          data: {userId: '123'}
        }
      }
    }

    After

    Code

    import SevenBoom from 'seven-boom';
    const argsDefs = [
      {
        name : 'errorName',
        order: 1
      }, {
        name : 'timeThrown',
        order: 2,
        default: null
      }, {
        name : 'guid',
        order: 3,
        default: null
      }
    ];
    SevenBoom.init(argsDefs);
     
    function getUserById(userId) {
     const errorMessage = `User with id: ${userId} not found`;
     const errorData = { userId };
     const errorName = 'USER_NOT_FOUND';
     throw SevenBoom.notFound(errorMessage, errorData, errorName);
     }

    Error result

    {
      isBoom: true,
      isServer: false,
      message: 'User with id: 123 not found.',
      data: {userId: '123'},
      output: {
        statusCode: '404',
        payload: {
          statusCode: '404',
          error: 'Not Found',
          message: 'User with id: 123 not found.',
          errorName: 'USER_NOT_FOUND',
          timeThrown: "2017-01-16T21:25:58.536Z",
          guid: 'b6c44655-0aae-486a-8d28-533db6c6c343',
          data: {userId: '123'}
        }
      }
    }

    Real example

    The best way to understand is always look on some real code. Therefore you can take a look on graphql-apollo-errors which use SevenBoom internally to handle graphql / apollo errors in a better way. Or you can look at the spec files.

    Source of the name

    The name seven-boom is a wordplay - it's a combination of the boom (as the base library) and seven boom which is a simple game. See more about seven-boom game here

    License

    MIT - Do what ever you want

    Contribute

    I'm open to hear any feedback - new ideas, bugs, needs. Feel free to open issues / PR

    Support on Paypal

    Hey dude! Help me out for a couple of 🍻!

    Donate

    Keywords

    Install

    npm i seven-boom

    DownloadsWeekly Downloads

    2,022

    Version

    1.0.3

    License

    MIT

    Last publish

    Collaborators

    • shohamgilad