{"id":16244585,"url":"https://github.com/indexzero/errs","last_synced_at":"2025-04-09T18:18:15.804Z","repository":{"id":2556373,"uuid":"3535192","full_name":"indexzero/errs","owner":"indexzero","description":"Simple error creation and passing utilities","archived":false,"fork":false,"pushed_at":"2016-01-26T12:46:45.000Z","size":49,"stargazers_count":75,"open_issues_count":2,"forks_count":11,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-09T18:18:09.176Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://github.com/indexzero/errs","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/indexzero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-02-24T11:31:14.000Z","updated_at":"2024-07-03T09:11:39.000Z","dependencies_parsed_at":"2022-08-19T18:31:46.778Z","dependency_job_id":null,"html_url":"https://github.com/indexzero/errs","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Ferrs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Ferrs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Ferrs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/indexzero%2Ferrs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/indexzero","download_url":"https://codeload.github.com/indexzero/errs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085326,"owners_count":21045139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T14:19:47.442Z","updated_at":"2025-04-09T18:18:15.788Z","avatar_url":"https://github.com/indexzero.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# errs [![Build Status](https://secure.travis-ci.org/indexzero/errs.png)](http://travis-ci.org/indexzero/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\u003ca name=\"creating-errors\" /\u003e\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\u003ca name=\"reusing-types\" /\u003e\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.\u003canonymous\u003e (/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\u003ca name=\"merging-errors\" /\u003e\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\u003ca name=\"optional-invocation\" /\u003e\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\u003ca name=\"piping-errors\" /\u003e\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexzero%2Ferrs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Findexzero%2Ferrs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Findexzero%2Ferrs/lists"}