Whoops

It makes simple throw qualified errors. Inspired in errno and create-error-class.

Why

• An easy way to create qualified errors.
• Using the standard Error interface in browser and NodeJS.
• Attach extra information, depending of your case of use.

Basically turns:

var error = Error('ENOFILE, Something is wrong')
error.name = 'DAMNError'
error.code = 'ENOFILE'

throw error // => 'DAMNError: ENOFILE, Something is wrong'

into one line error declaration:

var Whoops = require('Whoops');
var error = Whoops('DAMError', 'ENOFILE', 'Something is wrong');

throw error // => 'DAMNError: ENOFILE, Something is wrong'

Also you can create custom class errors for avoid write the name of the error all the time:

var DAMError = Whoops.create('DAMError')

Now you can avoid the first parameter in the inline declaration:

var error = DAMError('ENOFILE', 'Something is wrong');
throw error // => 'DAMNError: ENOFILE, Something is wrong'

Constructor also can be executed in object mode for the cases where you need to setup more properties associated with the error:

var error = Whoops({
  name: 'DAMError', , ''
  code: 'ENOFILE'
  message: 'Something is wrong'
  path: 'filepath'
});

In this mode you can pass a generator function as message:

var error = Whoops({
  name: 'DAMError', , ''
  code: 'ENOFILE',
  file: 'damnfile'
  message: function() {
    return "Something is wrong with the file '" + this.file "'."
  }
});

throw error // => "DAMNError: ENOFILE, Something is wrong with the file 'damnfile'"

Install

npm install whoops --save

If you want to use in the browser (powered by Browserify):

bower install whoops --save

and later link in your HTML:

<script src="bower_components/whoops/dist/whoops.js"></script>

API

.constructor([String|Object])

Create a new Error. You can use it using two different interfaces.

String Constructor

Following the schema .constructor([name], [code], {message})

Object Constructor

Whatever property that you pass in an object will be associated with the Error.

If you pass a function as message property will be executed in the context of the Error.

For both constructor modes, if the code of the error is provided will be concatenated and the begin of the message.

.create({String})

Create a new qualified Error. All is the same than the normal constructor, but in this case you don't have to provide the name of the error.

Extra: Always throw/return an Error!

If you code implementation is

• synchronous, throws Error. If you just return the Error nothings happens!.
• asynchronous, returns Error in the first argument of the callback (or using promises).

About asynchronous code, is correct return a Object that is not a Error in the first argument of the callback to express unexpected behavior, but the Object doesn't have a type and definitely can't follow a error interface for determinate a special behavior:

callback('LOL something was wrong') // poor
callback({message: 'LOL something was wrong' } // poor, but better
callback(Whoops('LOL, something was wrong') // BEST!

Passing always an Error you can can associated different type of error with different behavior:

switch (err.name) {
  case 'JSONError':
    console.log('your error logic here');
    break;
  default:
    console.log('undefined code');
    break;
};

License

MIT © Kiko Beats