{"_id":"errs","_rev":"162633","name":"errs","description":"Simple error creation and passing utilities","dist-tags":{"latest":"0.3.2"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"time":{"modified":"2021-06-03T11:42:06.000Z","created":"2012-02-24T14:06:28.241Z","0.3.2":"2014-11-26T05:10:10.066Z","0.3.1":"2014-11-26T05:09:11.652Z","0.3.0":"2014-01-11T17:04:05.345Z","0.2.4":"2013-03-07T00:33:05.657Z","0.2.3":"2012-08-17T03:55:20.279Z","0.2.2":"2012-06-28T12:00:05.950Z","0.2.0":"2012-03-03T07:31:44.305Z","0.1.1":"2012-02-24T14:06:28.241Z"},"users":{"jupiter":true,"ghkddbguse":true},"author":{"name":"Charlie Robbins","email":"charlie.robbins@gmail.com"},"repository":{"type":"git","url":"http://github.com/indexzero/errs.git"},"versions":{"0.3.2":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.3.2","author":{"name":"Charlie Robbins","email":"charlie.robbins@gmail.com"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"repository":{"type":"git","url":"http://github.com/indexzero/errs.git"},"keywords":["errors","error","utilities"],"devDependencies":{"vows":"0.8.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"gitHead":"a0b8f3beeb97ee041750f617fca12e7a0fc6bcfb","bugs":{"url":"https://github.com/indexzero/errs/issues"},"homepage":"https://github.com/indexzero/errs","_id":"errs@0.3.2","_shasum":"798099b2dbd37ca2bc749e538a7c1307d0b50499","_from":".","_npmVersion":"2.1.9","_nodeVersion":"0.10.33","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"dist":{"shasum":"798099b2dbd37ca2bc749e538a7c1307d0b50499","size":8266,"noattachment":false,"key":"/errs/-/errs-0.3.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.3.2.tgz"},"directories":{},"publish_time":1416978610066,"_cnpm_publish_time":1416978610066,"_hasShrinkwrap":false},"0.3.1":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.3.1","author":{"name":"Charlie Robbins","email":"charlie.robbins@gmail.com"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"repository":{"type":"git","url":"http://github.com/indexzero/errs.git"},"keywords":["errors","error","utilities"],"devDependencies":{"vows":"0.8.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"gitHead":"e6020091c5ec836f6f09a9af775f37c4d6dee729","bugs":{"url":"https://github.com/indexzero/errs/issues"},"homepage":"https://github.com/indexzero/errs","_id":"errs@0.3.1","_shasum":"edea03b43fed0e5ab07e537bbb4d96e2beea41bf","_from":".","_npmVersion":"2.1.9","_nodeVersion":"0.10.33","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"dist":{"shasum":"edea03b43fed0e5ab07e537bbb4d96e2beea41bf","size":8282,"noattachment":false,"key":"/errs/-/errs-0.3.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.3.1.tgz"},"directories":{},"publish_time":1416978551652,"_cnpm_publish_time":1416978551652,"_hasShrinkwrap":false},"0.3.0":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.3.0","author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"repository":{"type":"git","url":"http://github.com/flatiron/errs.git"},"keywords":["errors","utilities"],"devDependencies":{"vows":"0.7.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"readmeFilename":"README.md","bugs":{"url":"https://github.com/flatiron/errs/issues"},"homepage":"https://github.com/flatiron/errs","_id":"errs@0.3.0","dist":{"shasum":"e58aee1974618067d9e7a8ad885f6d6aad0ac9ca","size":8205,"noattachment":false,"key":"/errs/-/errs-0.3.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.3.0.tgz"},"_from":".","_npmVersion":"1.3.22","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"directories":{},"publish_time":1389459845345,"_cnpm_publish_time":1389459845345,"_hasShrinkwrap":false},"0.2.4":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.2.4","author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"repository":{"type":"git","url":"http://github.com/flatiron/errs.git"},"keywords":["errors","utilities"],"devDependencies":{"vows":"0.6.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"readmeFilename":"README.md","_id":"errs@0.2.4","dist":{"shasum":"48ccefec94fd3e613d6469840dd1c038937983f6","size":8073,"noattachment":false,"key":"/errs/-/errs-0.2.4.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.2.4.tgz"},"_npmVersion":"1.1.66","_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"directories":{},"publish_time":1362616385657,"_cnpm_publish_time":1362616385657,"_hasShrinkwrap":false},"0.2.3":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.2.3","author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"repository":{"type":"git","url":"git://github.com/flatiron/errs.git"},"keywords":["errors","utilities"],"devDependencies":{"vows":"0.6.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"_id":"errs@0.2.3","dependencies":{},"optionalDependencies":{},"_engineSupported":true,"_npmVersion":"1.1.2","_nodeVersion":"v0.8.6","_defaultsLoaded":true,"dist":{"shasum":"3e990af8dd01c958ea4a23ac487d3e748813a381","size":8068,"noattachment":false,"key":"/errs/-/errs-0.2.3.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.2.3.tgz"},"directories":{},"publish_time":1345175720279,"_cnpm_publish_time":1345175720279,"_hasShrinkwrap":false},"0.2.2":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.2.2","author":{"name":"Nodejitsu Inc.","email":"info@nodejitsu.com"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"repository":{"type":"git","url":"git://github.com/flatiron/errs.git"},"keywords":["errors","utilities"],"devDependencies":{"vows":"0.6.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"_id":"errs@0.2.2","dependencies":{},"optionalDependencies":{},"_engineSupported":true,"_npmVersion":"1.1.2","_nodeVersion":"v0.6.18","_defaultsLoaded":true,"dist":{"shasum":"e28a8235b91058ebba81b5d57e13c1b153eb6d4c","size":7993,"noattachment":false,"key":"/errs/-/errs-0.2.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.2.2.tgz"},"directories":{},"publish_time":1340884805950,"_cnpm_publish_time":1340884805950,"_hasShrinkwrap":false},"0.2.0":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.2.0","author":{"name":"Nodejitsu","email":"info@nodejitsu.com"},"contributors":[{"name":"Charlie Robbins","email":"charlie@nodejitsu.com"},{"name":"Nuno Job","email":"nuno@nodejitsu.com"}],"repository":{"type":"git","url":"git://github.com/flatiron/errs.git"},"keywords":["errors","utilities"],"devDependencies":{"vows":"0.6.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"_id":"errs@0.2.0","dependencies":{},"optionalDependencies":{},"_engineSupported":true,"_npmVersion":"1.1.2","_nodeVersion":"v0.6.10","_defaultsLoaded":true,"dist":{"shasum":"627a0958869fefe952e7033decf05b323ecb9a67","size":7352,"noattachment":false,"key":"/errs/-/errs-0.2.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.2.0.tgz"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"directories":{},"publish_time":1330759904305,"_cnpm_publish_time":1330759904305,"_hasShrinkwrap":false},"0.1.1":{"name":"errs","description":"Simple error creation and passing utilities","version":"0.1.1","author":{"name":"Nodejitsu","email":"info@nodejitsu.com"},"contributors":[{"name":"Charlie Robbins","email":"charlie@nodejitsu.com"},{"name":"Nuno Job","email":"nuno@nodejitsu.com"}],"repository":{"type":"git","url":"git://github.com/flatiron/errs.git"},"keywords":["errors","utilities"],"devDependencies":{"vows":"0.6.x"},"main":"./lib/errs","scripts":{"test":"vows test/*-test.js --spec"},"engines":{"node":">= 0.4.0"},"_npmUser":{"name":"indexzero","email":"charlie.robbins@gmail.com"},"_id":"errs@0.1.1","dependencies":{},"optionalDependencies":{},"_engineSupported":true,"_npmVersion":"1.1.1","_nodeVersion":"v0.6.10","_defaultsLoaded":true,"dist":{"shasum":"d4493dcccf0848ed75ee4e3205f606058841baf2","size":5753,"noattachment":false,"key":"/errs/-/errs-0.1.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/errs/download/errs-0.1.1.tgz"},"maintainers":[{"name":"indexzero","email":"charlie.robbins@gmail.com"}],"directories":{},"publish_time":1330092388241,"_cnpm_publish_time":1330092388241,"_hasShrinkwrap":false}},"readme":"# errs [![Build Status](https://secure.travis-ci.org/flatiron/errs.png)](http://travis-ci.org/flatiron/errs)\n\nSimple error creation and passing utilities focused on:\n\n* [Creating Errors](#creating-errors)\n* [Reusing Error Types](#reusing-types)\n* [Merging with Existing Errors](#merging-errors)\n* [Optional Callback Invocation](#optional-invocation)\n* [Piping Error Events](#piping-errors)\n\n<a name=\"creating-errors\" />\n## Creating Errors\n\nYou should know by now that [a String is not an Error][0]. Unfortunately the `Error` constructor in Javascript isn't all that convenient either. How often do you find yourself in this situation?\n\n``` js\n  var err = new Error('This is an error. There are many like it.');\n  err.someProperty = 'more syntax';\n  err.someOtherProperty = 'it wont stop.';\n  err.notEven = 'for the mayor';\n\n  throw err;\n```\n\nRest your fingers, `errs` is here to help. The following is equivalent to the above:\n\n``` js\n  var errs = require('errs');\n\n  throw errs.create({\n    message: 'This is an error. There are many like it.',\n    someProperty: 'more syntax',\n    someOtherProperty: 'it wont stop.',\n    notEven: 'for the mayor'\n  });\n```\n\n<a name=\"reusing-types\" />\n## Reusing Custom Error Types\n\n`errs` also exposes an [inversion of control][1] 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:\n\n``` js\n  /*\n   * file-a.js: Create and register your error type.\n   *\n   */\n\n  var util = require('util'),\n      errs = require('errs');\n\n  function MyError() {\n    this.message = 'This is my error; I made it myself. It has a transparent stack trace.';\n  }\n\n  //\n  // Alternatively `MyError.prototype.__proto__ = Error;`\n  //\n  util.inherits(MyError, Error);\n\n  //\n  // Register the error type\n  //\n  errs.register('myerror', MyError);\n\n\n\n  /*\n   * file-b.js: Use your error type.\n   *\n   */\n\n  var errs = require('errs');\n\n  console.log(\n    errs.create('myerror')\n      .stack\n      .split('\\n')\n  );\n```\n\nThe output from the two files above is shown below. Notice how it contains no references to `errs.js`:\n\n```\n[ 'MyError: This is my error; I made it myself. It has a transparent stack trace.',\n  '    at Object.<anonymous> (/file-b.js:19:8)',\n  '    at Module._compile (module.js:441:26)',\n  '    at Object..js (module.js:459:10)',\n  '    at Module.load (module.js:348:31)',\n  '    at Function._load (module.js:308:12)',\n  '    at Array.0 (module.js:479:10)',\n  '    at EventEmitter._tickCallback (node.js:192:40)' ]\n```\n\n<a name=\"merging-errors\" />\n## Merging with Existing Errors\n\nWhen working with errors you catch or are returned in a callback you can extend those errors with properties by using the `errs.merge` method. This will also create a human readable error message and stack-trace:\n\n``` js\nprocess.on('uncaughtException', function(err) {\n  console.log(errs.merge(err, {namespace: 'uncaughtException'}));\n});\n\nvar file = fs.createReadStream('FileDoesNotExist.here');\n```\n\n``` js\n{ [Error: Unspecified error]\n  name: 'Error',\n  namespace: 'uncaughtException',\n  errno: 34,\n  code: 'ENOENT',\n  path: 'FileDoesNotExist.here',\n  description: 'ENOENT, no such file or directory \\'FileDoesNotExist.here\\'',\n  stacktrace: [ 'Error: ENOENT, no such file or directory \\'FileDoesNotExist.here\\'' ] }\n```\n\n<a name=\"optional-invocation\" />\n## Optional Callback Invocation\n\nNode.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:\n\n``` js\n  function importantFeature(callback) {\n    return someAsyncFn(function (err) {\n      if (err) {\n        if (callback) {\n          return callback(err);\n        }\n\n        throw err;\n      }\n    });\n  }\n```\n\n`errs` it presents a common API for both emitting `error` events and invoking continuations (i.e. callbacks) with errors. 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:\n\n``` js\n  function importantFeature(callback) {\n    return someAsyncFn(function (err) {\n      if (err) {\n        return errs.handle(err, callback);\n      }\n    });\n  }\n```\n\n<a name=\"piping-errors\" />\n## Piping Errors\n\nOften when working with streams (especially when buffering for whatever reason), you may have already returned an `EventEmitter` or `Stream` instance by the time an error is handled.\n\n``` js\n  function pipeSomething(callback) {\n    //\n    // You have a stream (e.g. http.ResponseStream) and you\n    // have an optional `callback`.\n    //\n    var stream = new require('stream').Stream;\n\n    //\n    // You need to do something async which may respond with an\n    // error\n    //\n    getAnotherStream(function (err, source) {\n      if (err) {\n        if (callback)\n          callback(err);\n        }\n\n        stream.emit('error', err);\n        return;\n      }\n\n      source.pipe(stream);\n    })\n\n    return stream;\n  }\n```\n\nYou may pass either a `function` or `EventEmitter` instance to `errs.handle`.\n\n``` js\n  function pipeSomething(callback) {\n    //\n    // You have a stream (e.g. http.ResponseStream) and you\n    // have an optional `callback`.\n    //\n    var stream = new require('stream').Stream;\n\n    //\n    // You need to do something async which may respond with an\n    // error\n    //\n    getAnotherStream(function (err, source) {\n      if (err) {\n        //\n        // Invoke the callback if it exists otherwise the stream.\n        //\n        return errs.handle(err, callback || stream);\n      }\n\n      source.pipe(stream);\n    })\n\n    return stream;\n  }\n```\n\nIf you wish to invoke both a `callback` function and an `error` event simply pass both:\n\n``` js\n  errs.handle(err, callback, stream);\n```\n\n## Methods\nThe `errs` modules exposes some simple utility methods:\n\n* `.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.\n* `.register(type, proto)`: Registers the specified `proto` to `type` for future calls to `errors.create(type, opts)`.\n* `.unregister(type)`: Unregisters the specified `type` for future calls to `errors.create(type, opts)`.\n* `.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.\n* `.merge(err, type, opts)`: Merges an existing error with a new error instance for with the specified `type` and `opts`.\n\n## Installation\n\n### Installing npm (node package manager)\n\n``` bash\n  $ curl http://npmjs.org/install.sh | sh\n```\n\n### Installing errs\n\n``` bash\n  $ [sudo] npm install errs\n```\n\n## Tests\nAll tests are written with [vows][2] and should be run with [npm][3]:\n\n``` bash\n  $ npm test\n```\n\n#### Author: [Charlie Robbins](http://github.com/indexzero)\n#### Contributors: [Nuno Job](http://github.com/dscape)\n#### License: MIT\n\n[0]: http://www.devthought.com/2011/12/22/a-string-is-not-an-error/\n[1]: http://martinfowler.com/articles/injection.html\n[2]: https://vowsjs.org\n[3]: https://npmjs.org\n","_attachments":{},"homepage":"https://github.com/indexzero/errs","bugs":{"url":"https://github.com/indexzero/errs/issues"}}