Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Simple error creation and passing utilities

tree: 8651ce96d0

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

errs Build Status

Simple error creation and passing utilities focused on:

Creating Errors

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'
  });

Reusing Custom Error Types

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)' ]

Optional Callback Invocation

Node.js handles asynchronous IO through the elegant EventEmitter API. In many scenarios the callback may be optional because you are returning an EventEmitter for piping or other event multiplexing. This complicates code with a lot of boilerplate:

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

        throw err;
      }
    });
  }

errs it presents a common API for both emitting error events and invoking continuations (i.e. callbacks) with errors;

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

If a callback is supplied to errs.handle() it will be invoked with the error. It no callback is provided then an EventEmitter is returned which emits an error event on the next tick.

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

Something went wrong with that request. Please try again.