errs

Simple error creation and passing utilities focused on:

• Creating Errors
• Reusing Error Types
• Optional Callback Invocation

You should know by now that a String is not an Error. Unfortunately the Error constructor in Javascript isn't all that convenient either. How often do you find yourself in this situation?

  var err = new Error('This is an error. There are many like it.');
  err.someProperty = 'more syntax';
  err.someOtherProperty = 'it wont stop.';
  err.notEven = 'for the mayor';
  
  throw err;

Rest your fingers, errs is here to help. The following is equivalent to the above:

  var errs = require('errs');
  
  throw errs.create({
    message: 'This is an error. There are many like it.',
    someProperty: 'more syntax',
    someOtherProperty: 'it wont stop.',
    notEven: 'for the mayor'
  });

errs also exposes an inversion of control interface for easily reusing custom error types across your application. Custom Error Types registered with errs will transparently invoke Error constructor and Error.captureStackTrace to attach transparent stack traces:

  /*
   * file-a.js: Create and register your error type.
   *
   */
   
  var util = require('util'),
      errs = require('errs');

  function MyError() {
    this.message = 'This is my error; I made it myself. It has a transparent stack trace.';
  }

  //
  // Alternatively `MyError.prototype.__proto__ = Error;`
  //
  util.inherits(MyError, Error);

  //
  // Register the error type
  //
  errs.register('myerror', MyError);



  /*
   * file-b.js: Use your error type.
   *
   */
   
  var errs = require('errs');
  
  console.log(
    errs.create('myerror')
      .stack
      .split('\n')
  );

The output from the two files above is shown below. Notice how it contains no references to errs.js:

[ 'MyError: This is my error; I made it myself. It has a transparent stack trace.',
  '    at Object.<anonymous> (/file-b.js:19:8)',
  '    at Module._compile (module.js:441:26)',
  '    at Object..js (module.js:459:10)',
  '    at Module.load (module.js:348:31)',
  '    at Function._load (module.js:308:12)',
  '    at Array.0 (module.js:479:10)',
  '    at EventEmitter._tickCallback (node.js:192:40)' ]

  function importantFeature(callback) {
    return someAsyncFn(function (err) {
      if (err) {
        if (callback) {
          return callback(err);
        }
        
        throw err;
      }
    });
  }

  function importantFeature(callback) {
    return someAsyncFn(function (err) {
      if (err) {
        return errs.handle(err, callback);
      }
    });
  }

Methods

The errs modules exposes some simple utility methods:

• .create(type, opts): Creates a new error instance for with the specified type and opts. If the type is not registered then a new Error instance will be created.
• .register(type, proto): Registers the specified proto to type for future calls to errors.create(type, opts).
• .unregister(type): Unregisters the specified type for future calls to errors.create(type, opts).
• .handle(err, callback): Attempts to instantiate the given error. If the error is already a properly formed error object (with a stack property) it will not be modified.

Installation

Installing npm (node package manager)

  $ curl http://npmjs.org/install.sh | sh

Installing errs

  $ [sudo] npm install errs

Tests

All tests are written with vows and should be run with npm:

  $ npm test

Author: Nodejitsu Inc.

Contributors: Charlie Robbins, Nuno Job

License: MIT