ees

Error Enhancement Suite

This little gem makes tracking errors in node.js more sane.

Consider the following contrived example:

var fs = require('fs')

getJsonFile('package.jsonn', function(err, data) {
  if (err) return console.log(err.stack);
  console.log(data);
});

function getJsonFile(filename, cb) {
  getFile(filename, function(err, data) {
    if (err) return cb(err);
    var json = JSON.parse(data);
    cb(null, json);
  });
}

function _getFile(filename, cb) {
  getFile(filename, cb);
}

function getFile(filename, cb) {
  fs.readFile(filename, function(err, data) {
    if (err) return cb(err);
    cb(null, data);
  });
}

Notice we spelled package.jsonn wrong, so when this code runs, we get the following output:

Error: ENOENT, open 'package.jsonn'

If this were a large application running in production, that error would be absolutely worthless.

Enter EES.

We can modify the previous example and just add some tagging and inspections:

var fs = require('fs')

require('ees')

// define a custom category
Error.category('caffeine');

getJsonFile('package.jsonn', function(err, data) {
  if (err) return console.log(err.location('calling getJsonFile').report());
  console.log(data);
});

function getJsonFile(filename, cb) {
  _getFile(filename, function(err, data) {
    if (err) return cb(err.location('getJsonFile'));
    var json = JSON.parse(data);
    cb(null, json);
  });
}

function _getFile(filename, cb) {
  getFile(filename, function(err, data) {
    if (err) return cb(err
      .location('_getFile')
      .author('adam')
      .caffeine(4)
      .updated('2 Dec 2012')
    );
    cb(null, data);
  });
}

function getFile(filename, cb) {
  fs.readFile(filename, function(err, data) {
    if (err) return cb(err
      .location('calling fs.readFile')
      .location('getFile')
      .inspect('filename', filename)
      .caffeine(7)
    );
    cb(null, data);
  });
}

This generates a reverse stack trace and gives a report that looks like this:

location: calling fs.readFile
location: getFile
  inspect: filename (string): 'package.jsonn'
  caffeine: 7
location: _getFile
  author: adam
  caffeine: 4
  updated: 2 Dec 2012
location: getJsonFile
location: calling getJsonFile
stack trace:
Error: ENOENT, open 'package.jsonn'

We can now tell what we were doing and the path that we took to get to the erroneous code.

Magic.