[merge] Added errs.merge for merging errors

* Fixes some small JSHint issues
* Added tests
* Added human readable components for effective logging

examples/async-uncaught-exception.js

@@ -0,0 +1,9 @@
+var fs = require('fs'),
+    errs = require('../lib/errs');
+
+process.on('uncaughtException', function(err) {
+  console.log(errs.merge(err, {namespace: 'uncaughtException'}));
+});
+
+var file = fs.createReadStream(__filename, {encoding: 'utf8'});
+file.on('data', function(b) { throw new Error('Oh Noes'); });

examples/handling-streams.js

@@ -0,0 +1,14 @@
+var fs = require('fs'),
+    errs = require('../lib/errs');
+
+function safeReadStream(no_such_file, callback) {
+  try { 
+    return fs.createReadStream(no_such_file, callback);
+  } catch (err) {
+    return errs.handle(err, callback);
+  }
+}
+
+// would throw, now even without a callback it gets picked as a stream
+var file = fs.createReadStream('FileDoesNotExist.here');
+file.on('error', function (err) { console.log(err); });

examples/sync-uncaught-exception.js

@@ -0,0 +1,8 @@
+var fs = require('fs'),
+    errs = require('../lib/errs');
+
+process.on('uncaughtException', function(err) {
+  console.log(errs.merge(err, {namespace: 'uncaughtException'}));
+});
+
+var file = fs.createReadStream('FileDoesNotExist.here');

lib/errs.js

@@ -91,7 +91,7 @@ exports.create = function (type, opts) {
     Error.captureStackTrace(error, arguments.callee);
   }
   else {
-    error.stack = error.stack.split('\n')
+    error.stack = error.stack.split('\n');
     error.stack.splice(1, 1);
     error.stack = error.stack.join('\n');
   }  
@@ -108,6 +108,38 @@ exports.create = function (type, opts) {
   return error;
 };
 
+//
+// ### function merge (err, type, opts)
+// #### @err  {error} The error to merge
+// #### @type {string} **Optional** Registered error type to create
+// #### @opts {string|object|Array|function} Options for creating the error:
+//   * `string`:   Message for the error
+//   * `object`:   Properties to include on the error
+//   * `array`:    Message for the error (' ' joined).
+//   * `function`: Function to return error options.
+//
+// Merges an existing error with a new error instance for with 
+// the specified `type` and `options`.
+//
+exports.merge = function (err, type, opts) {
+  if (!arguments[1] && !exports.registered[type]) {
+    opts = type;
+    type = null;
+  }
+  var merged  = exports.create(type,opts);
+  // optional stuff that might be created by module
+  for (var property in err) { merged[property] = err[property]; }
+  // merging
+  merged.name = merged.name || err.name;
+  merged.message = merged.message || err.message;
+  // override stack
+  merged.stack = err.stack;
+  // add human-readable errors
+  merged.description = err.message;
+  merged.stacktrace = err.stack.split("\n");
+  return merged;
+};
+
 //
 // ### function handle (error, callback)
 // #### @error {string|function|Array|object} Error to handle

package.json

@@ -1,7 +1,7 @@
 {
   "name": "errs",
   "description": "Simple error creation and passing utilities",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "author": "Nodejitsu <info@nodejitsu.com>",
   "contributors": [
     { "name": "Charlie Robbins", "email": "charlie@nodejitsu.com" },

test/errs-test.js

@@ -25,7 +25,7 @@ var opts = [{
   should: true,
   have: 4,
   properties: 'yes'
-}]
+}];
 
 vows.describe('errs').addBatch({
   "Using errs module": {
@@ -66,7 +66,7 @@ vows.describe('errs').addBatch({
           var err = this.err = errs.create('Some emitted error'),
               emitter = errs.handle(err);
 
-          emitter.once('error', this.callback.bind(this, null))
+          emitter.once('error', this.callback.bind(this, null));
         },
         "should invoke the callback with the error": function (_, err) {
           assert.equal(err, this.err);
@@ -83,4 +83,30 @@ vows.describe('errs').addBatch({
       }
     }
   }
-}).export(module);
+}).addBatch({
+  "Using errs module": {
+    "the merge() method": {
+      "should preserve custom properties": function () {
+        var err = new Error('Msg!');
+        err.foo = "bar";
+        err = errs.merge(err, {message: "Override!", ns: "test"});
+        assert.equal(err.foo, "bar");
+      },
+      "should have a stack trace": function () {
+        var err = new Error('Msg!');
+        err = errs.merge(err, {message: "Override!", ns: "test"});
+        assert.isTrue(Array.isArray(err.stacktrace));
+      },
+      "should preserve message specified in create": function () {
+        var err = new Error('Msg!');
+        err = errs.merge(err, {message: "Override!", ns: "test"});
+        assert.equal(err.message, "Override!");
+      },
+      "should preserve properties specified": function () {
+        var err = new Error('Msg!');
+        err = errs.merge(err, {message: "Override!", ns: "test"});
+        assert.equal(err.ns, "test");
+      }
+    }
+  }
+}).export(module);