error-ninja

Error-Ninja

Error handling can be a pain, it's tempting to just pass strings to callbacks so it's easier to handle, but using a proper Error object is a better way and Error Ninja can help with this.

What's the Point?

1. Outputs a human-readable error message in the console.
2. Lets you set an error ID to make it easy to create and identify the error.
3. Makes it easier to debug errors by outputting additional data.
4. Makes it easier to handle errors by adding extra properties to the error.
5. Throws just like a plain old JavaScript Error.
6. Allows you to detect if a variable is a JavaScript error or an ErrorNinja error.

Define Your Error Messages

First, define a hash of error IDs and error messages.

var ErrorNinja = require('error-ninja').define({
  'invalid-blog-id':    'The given blog ID does not exist!',
  'attachment-too-big': 'You cannot upload an attachment that big!',
  'some-error':         'Woah, this code is buggy!'
});

Create and Throw Errors

Now you can create an error. You can throw this error just like any other.

var err = new ErrorNinja('invalid-blog-id');
throw err;

/*
  Outputs...
  Error [invalid-blog-id]: The given blog ID does not exist!
     at new ErrorNinja (/path/to/Error-Ninja/errorNinja.js:36:19)
     at Object.<anonymous> (/path/to/myScript.js:59:13)
     at Module._compile (module.js:456:26)
     at Object.Module._extensions..js (module.js:474:10)
     at Module.load (module.js:356:32)
     at Function.Module._load (module.js:312:12)
     at Function.Module.runMain (module.js:497:10)
     at startup (node.js:119:16)
     at node.js:906:3
 */

Include Data in the Error

If you need to include some extra properties in the error you can specify the second parameter. By default this data will be output to the console if the error is thrown, and you'll also be able to access it when handling your error.

var err = new ErrorNinja('attachment-too-big', { fileSize: 17483, maxSize: 1024 });
throw err;

/*
  Outputs...
  Error [attachment-too-big]: You cannot upload an attachment that big!
  ----------
  {"fileSize":17483,"maxSize":1024}
  ----------
     at new ErrorNinja (/path/to/Error-Ninja/errorNinja.js:36:19)
     at Object.<anonymous> (/path/to/myScript.js:59:13)
     at Module._compile (module.js:456:26)
     at Object.Module._extensions..js (module.js:474:10)
     at Module.load (module.js:356:32)
     at Function.Module._load (module.js:312:12)
     at Function.Module.runMain (module.js:497:10)
     at startup (node.js:119:16)
     at node.js:906:3
 */

Turn Off Data Console Output

To prevent the extra error data being output in the console you can do one of two things:

1. Pass false as the 3rd argument when creating an error:

var err = new ErrorNinja('some-error', { abc: 'do-not-output' }, false);

1. Or you can turn off data output for all errors created by this instance of Error Ninja:

var ErrorNinja = require('error-ninja').define({ ... }, { outputData: false });

Access Useful Properties in the Error

Apart from the usual error properties you can also access the following additional properties that should help with handling your errors.

var err = new ErrorNinja('attachment-too-big', { fileSize: 17483, maxSize: 1024 });

err.id;       // "attachment-too-big"
err.isError;  // True
err.isNinja;  // True
err.human;    // "You cannot upload an attachment that big!"
err.data;     // (mixed) e.g. { fileSize: 17483, maxSize: 1024 }
              // data defaults to {}

How to Tell if a Variable is an Error?

ErrorNinja provides two methods to detect if a variable is an error, or more specifically an ErrorNinja error.

  // Ordinary JavaScript errors.
  var err1 = new Error();
  if (ErrorNinja.isError(err1)) { ... }

  // ErrorNinja errors.
  var err2 = new ErrorNinja('...');
  if (ErrorNinja.isNinja(err2)) { ... }