error-ninja

Error-Ninja

Backend 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.

const 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.

const 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.

const err = new ErrorNinja('ATTACHMENT_TOO_BIG', { fileSize: 17483, maxSize: 1024, name: 'crash.log' });
throw err;

/*
  Outputs...
  Error [ATTACHMENT_TOO_BIG]: You cannot upload an attachment that big!
  ----------
  {"fileSize":17483,"maxSize":1024,"name":"crash.log"}
  ----------
     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:

const 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:

const 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.

const err = new ErrorNinja('ATTACHMENT_TOO_BIG', { fileSize: 17483, maxSize: 1024, name: 'crash.log' });

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, name: 'crash.log' }
              // data defaults to {}

Convert an existing error to an ErrorNinja

You can convert ordinary errors created by the Node core or other modules to ErrorNinja errors without throwing them:

  doSomethingAsync((err, result) => {
    err = ErrorNinja.convert(err, 'MY_ERROR_ID'/* , data, outputData */);

    ErrorNinja.isNinja(err);  // true.
  });

Or you can convert and throw them immediately. The ErrorNinja.throw() function returns a converter function which will convert the err passed to the catch block.

  doSomethingAsync()
    .then(result => {
      // Do something else here...
    })
    .catch(err => ErrorNinja.throw('MY_ERROR_ID'));

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.
  const err1 = new Error();
  if (ErrorNinja.isError(err1)) { ... }

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