{"_id":"error-causes","_rev":"4245017","name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","dist-tags":{"latest":"3.0.2"},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"time":{"modified":"2026-03-29T21:29:21.000Z","created":"2022-10-06T03:39:13.801Z","3.0.2":"2023-03-16T17:31:40.209Z","3.0.1":"2023-03-16T17:28:07.019Z","3.0.0":"2022-11-05T18:53:48.958Z","2.0.1":"2022-11-04T00:43:07.041Z","2.0.0":"2022-11-04T00:19:07.245Z","1.1.0":"2022-10-14T00:50:19.980Z","1.0.2":"2022-10-06T03:39:13.801Z"},"users":{},"author":{"name":"Eric Elliott"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"versions":{"3.0.2":{"name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","version":"3.0.2","main":"index.js","scripts":{"lint":"eslint --fix src","test":"NODE_ENV=test node src/index-test.js | tap-nirvana","watch":"watch 'npm run -s test && npm run -s lint' src","update":"updtr","release":"release-it"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"author":{"name":"Eric Elliott"},"license":"MIT","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"homepage":"https://github.com/paralleldrive/error-causes#readme","devDependencies":{"eslint":"8.27.0","eslint-config-prettier":"8.5.0","eslint-plugin-prettier":"4.2.1","esm":"3.2.25","prettier":"2.7.1","release-it":"15.5.0","riteway":"7.0.0","tap-nirvana":"1.1.0","updtr":"4.0.0","watch":"1.0.2"},"gitHead":"83ece39413be623833db259b5fe0379bdcd16843","_id":"error-causes@3.0.2","_nodeVersion":"16.17.1","_npmVersion":"8.19.2","dist":{"shasum":"0d657671293d806f0b2008a4cf85518b762865c2","size":6310,"noattachment":false,"key":"/error-causes/-/error-causes-3.0.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/error-causes/download/error-causes-3.0.2.tgz"},"_npmUser":{"name":"brunomoutinho","email":"bcit_mordell@simplelogin.com"},"directories":{},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/error-causes_3.0.2_1678987900044_0.6830554649245484"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2023-03-16T17:31:40.209Z","publish_time":1678987900209,"_cnpm_publish_time":1678987900209},"3.0.1":{"name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","version":"3.0.1","main":"index.js","scripts":{"lint":"eslint --fix src","test":"NODE_ENV=test node src/index-test.js | tap-nirvana","watch":"watch 'npm run -s test && npm run -s lint' src","update":"updtr","release":"release-it"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"author":{"name":"Eric Elliott"},"license":"MIT","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"homepage":"https://github.com/paralleldrive/error-causes#readme","devDependencies":{"eslint":"8.27.0","eslint-config-prettier":"8.5.0","eslint-plugin-prettier":"4.2.1","esm":"3.2.25","prettier":"2.7.1","release-it":"15.5.0","riteway":"7.0.0","tap-nirvana":"1.1.0","updtr":"4.0.0","watch":"1.0.2"},"gitHead":"bc6166ac2ff5c5f0c3c47ef44d43cf0f90ae3941","_id":"error-causes@3.0.1","_nodeVersion":"16.17.1","_npmVersion":"8.19.2","dist":{"shasum":"6bb1f6196cada69939a141352f4b9f73f7a056ce","size":6311,"noattachment":false,"key":"/error-causes/-/error-causes-3.0.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/error-causes/download/error-causes-3.0.1.tgz"},"_npmUser":{"name":"brunomoutinho","email":"bcit_mordell@simplelogin.com"},"directories":{},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/error-causes_3.0.1_1678987686864_0.17131820448175117"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2023-03-16T17:28:07.019Z","publish_time":1678987687019,"_cnpm_publish_time":1678987687019},"3.0.0":{"name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","version":"3.0.0","main":"index.js","scripts":{"lint":"eslint --fix src","test":"NODE_ENV=test node src/index-test.js | tap-nirvana","watch":"watch 'npm run -s test && npm run -s lint' src","update":"updtr","release":"release-it"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"author":{"name":"Eric Elliott"},"license":"MIT","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"homepage":"https://github.com/paralleldrive/error-causes#readme","devDependencies":{"eslint":"8.26.0","eslint-config-prettier":"8.5.0","eslint-plugin-prettier":"4.2.1","esm":"3.2.25","prettier":"2.7.1","release-it":"15.5.0","riteway":"7.0.0","tap-nirvana":"1.1.0","updtr":"4.0.0","watch":"1.0.2"},"gitHead":"bc4b80761b4c3db64e3b15993711efd08e6c842a","_id":"error-causes@3.0.0","_nodeVersion":"16.13.0","_npmVersion":"8.19.2","dist":{"shasum":"ba806006287bd47888ae18480286eeef49aa6c06","size":6260,"noattachment":false,"key":"/error-causes/-/error-causes-3.0.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/error-causes/download/error-causes-3.0.0.tgz"},"_npmUser":{"name":"ericelliott","email":"nospam@paralleldrive.com"},"directories":{},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/error-causes_3.0.0_1667674428794_0.6196740782798658"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-11-05T18:53:54.802Z","publish_time":1667674428958,"_cnpm_publish_time":1667674428958},"2.0.1":{"name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","version":"2.0.1","main":"index.js","scripts":{"lint":"eslint --fix src","test":"NODE_ENV=test node src/index-test.js | tap-nirvana","watch":"watch 'npm run -s test && npm run -s lint' src","release":"release-it"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"author":{"name":"Eric Elliott"},"license":"MIT","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"homepage":"https://github.com/paralleldrive/error-causes#readme","devDependencies":{"eslint":"8.24.0","eslint-config-prettier":"8.5.0","eslint-plugin-prettier":"4.2.1","prettier":"2.7.1","release-it":"15.5.0","riteway":"7.0.0","tap-nirvana":"1.1.0","watch":"1.0.2"},"dependencies":{"esm":"3.2.25"},"gitHead":"c0d173c86d1f606ddab90930c33bbaabf008c77c","_id":"error-causes@2.0.1","_nodeVersion":"16.13.0","_npmVersion":"8.19.2","dist":{"shasum":"98bd5a2133e97cbed8cd7f431b12b658064389cc","size":6254,"noattachment":false,"key":"/error-causes/-/error-causes-2.0.1.tgz","tarball":"http://registry.cnpm.dingdandao.com/error-causes/download/error-causes-2.0.1.tgz"},"_npmUser":{"name":"ericelliott","email":"nospam@paralleldrive.com"},"directories":{},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/error-causes_2.0.1_1667522586884_0.6830497216484244"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-11-04T00:43:15.270Z","publish_time":1667522587041,"_cnpm_publish_time":1667522587041},"2.0.0":{"name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","version":"2.0.0","main":"index.js","type":"module","scripts":{"lint":"eslint --fix src","test":"NODE_ENV=test node src/test | tap-nirvana","watch":"watch 'npm run -s test && npm run -s lint' src","release":"release-it"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"author":{"name":"Eric Elliott"},"license":"MIT","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"homepage":"https://github.com/paralleldrive/error-causes#readme","devDependencies":{"eslint":"8.24.0","eslint-config-prettier":"8.5.0","eslint-plugin-prettier":"4.2.1","prettier":"2.7.1","release-it":"15.5.0","riteway":"7.0.0","tap-nirvana":"1.1.0","watch":"1.0.2"},"dependencies":{"esm":"3.2.25"},"gitHead":"c6cac5d2bcb5ac6eff88a7f89b73e1da040d6c1a","_id":"error-causes@2.0.0","_nodeVersion":"16.13.0","_npmVersion":"8.19.2","dist":{"shasum":"86f6df5c839bca53209227151ba5174de942d863","size":6184,"noattachment":false,"key":"/error-causes/-/error-causes-2.0.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/error-causes/download/error-causes-2.0.0.tgz"},"_npmUser":{"name":"ericelliott","email":"nospam@paralleldrive.com"},"directories":{},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/error-causes_2.0.0_1667521147049_0.23000117085501515"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-11-04T00:19:30.463Z","publish_time":1667521147245,"_cnpm_publish_time":1667521147245},"1.1.0":{"name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","version":"1.1.0","main":"index.js","type":"module","scripts":{"lint":"eslint --fix src","test":"NODE_ENV=test node src/test | tap-nirvana","watch":"watch 'npm run -s test && npm run -s lint' src","release":"release-it"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"author":{"name":"Eric Elliott"},"license":"MIT","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"homepage":"https://github.com/paralleldrive/error-causes#readme","devDependencies":{"eslint":"8.24.0","eslint-config-prettier":"8.5.0","eslint-plugin-prettier":"4.2.1","prettier":"2.7.1","release-it":"15.5.0","riteway":"7.0.0","tap-nirvana":"1.1.0","watch":"1.0.2"},"gitHead":"984afd4cc21550a8cb3d951a4bc6e8c202741fb9","_id":"error-causes@1.1.0","_nodeVersion":"16.13.0","_npmVersion":"8.8.0","dist":{"shasum":"cc14b6eced96cc05c979d6745abff66339e44b39","size":5997,"noattachment":false,"key":"/error-causes/-/error-causes-1.1.0.tgz","tarball":"http://registry.cnpm.dingdandao.com/error-causes/download/error-causes-1.1.0.tgz"},"_npmUser":{"name":"ericelliott","email":"nospam@paralleldrive.com"},"directories":{},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/error-causes_1.1.0_1665708619804_0.44246811604038605"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-10-14T00:55:04.105Z","publish_time":1665708619980,"_cnpm_publish_time":1665708619980},"1.0.2":{"name":"error-causes","description":"Simple error handling based on standard JavaScript error cause.","version":"1.0.2","main":"index.js","type":"module","scripts":{"lint":"eslint --fix src","test":"NODE_ENV=test node src/test | tap-nirvana","watch":"watch 'npm run -s test && npm run -s lint' src","release":"release-it"},"repository":{"type":"git","url":"git+https://github.com/paralleldrive/error-causes.git"},"author":{"name":"Eric Elliott"},"license":"MIT","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"homepage":"https://github.com/paralleldrive/error-causes#readme","devDependencies":{"eslint":"8.24.0","eslint-config-prettier":"8.5.0","eslint-plugin-prettier":"4.2.1","prettier":"2.7.1","release-it":"15.5.0","riteway":"7.0.0","tap-nirvana":"1.1.0","watch":"1.0.2"},"gitHead":"8d8dac20cc0516bde711e4dc95e8a02ed2909568","_id":"error-causes@1.0.2","_nodeVersion":"16.13.0","_npmVersion":"8.8.0","dist":{"shasum":"6d0ab110909d5a927725a68c79b2526506bef8cb","size":5177,"noattachment":false,"key":"/error-causes/-/error-causes-1.0.2.tgz","tarball":"http://registry.cnpm.dingdandao.com/error-causes/download/error-causes-1.0.2.tgz"},"_npmUser":{"name":"ericelliott","email":"nospam@paralleldrive.com"},"directories":{},"maintainers":[{"name":"brunomoutinho","email":""},{"name":"ericelliott","email":"eric@ericleads.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/error-causes_1.0.2_1665027553589_0.7112719784243637"},"_hasShrinkwrap":false,"_cnpmcore_publish_time":"2022-10-06T03:39:17.000Z","publish_time":1665027553801,"_cnpm_publish_time":1665027553801}},"readme":"# Error Causes\n\nSimple error handling based on standard JavaScript error cause.\n\nHandling errors should be easier. Imagine if you could do this:\n\n```js\nconst [fetchErrors, handleFetchErrors] = errorCauses({\n  NotFound: {\n    code: 404,\n    message: \"The requested resource was not found\",\n  },\n  MissingURI: {\n    code: 400,\n    message: \"URI is required\",\n  },\n});\n\nfetch(uri).then(handleSuccess).catch(handleFetchErrors({\n  NotFound: ({ name, code, message }) =>\n    // 404 NotFound: The requested resource was not found\n    console.log(`${ code } ${ name }: ${ message }`),\n  MissingURI: ({ message }) => console.log(message), // URI is required\n}));\n```\n\nWith Error Causes, you can. When you build an API or SDK, you can define the errors that can occur and export both the possible error causes, and a function to handle them that users can pass their own handlers to. It's a nice way to document your API with live code and make it easy for users to handle errors.\n\nError Causes also makes it easy to throw errors with a named cause:\n\n```js\nconst { NotFound, MissingURI } = fetchErrors;\n\nif (!uri) throw createError(MissingURI);\n```\n\n## Getting Started\n\nInstall with npm:\n\n```js\nnpm install error-causes\n```\n\nOr install with yarn:\n\n```\nyarn add error-causes\n```\n\nImport:\n\n```js\nimport { errorCauses, createError, noop } from \"error-causes\";\n```\n\n\n## Why Error Causes?\n\nFor every asynchronous API, it's a good idea to define and document the various error causes that might arise. How can a caller distinguish an error caused by bad input from an error caused by a network failure?\n\nOne common solution in JavaScript is to use custom error types and the `instanceof` operator to distinguish between different error causes in calling code. That is a bad idea because JavaScript uses isolated memory realms for security, and `instanceof` always fails across memory realms (e.g., it will always fail when testing an instance in a child iframe against a constructor in the parent frame, or vice versa). It's also a bad idea because errors can be serialized, deserialized, and rethrown, which could break the `instanceof` lookup. In other words, the `instanceof` approach works most of the time, but when it doesn't it can cause a lot of wasted debugging time.\n\nAnother common solution is to branch based on the text of the error message. That's a bad idea because error messages are likely to change, and may even be localized, making them an inapropriate basis for conditional branching.\n\nTraditionally in both hardware and software engineering, conditional branching for error handling is done using error codes instead of types. For example, the ubiquitous [HTTP status codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).\n\nUnfortunately, JavaScript never standardized the inclusion of an error code. Adding your own involves subclassing or extending the error object in non-standard ways, and there was never a way to pass a cause or structured metadata to the Error constructor - only a message. Until ECMAScript 2022 added the [error cause](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause#providing_structured_data_as_the_error_cause) parameter to the `Error` constructor.\n\nThat helps a little, but handlers still have to manually destructure causes.\n\nUnder the hood, `error-causes` constructs a structured `cause` property for thrown errors that it can then use to automatically match in the error handler:\n\n```js\ntype Cause = {\n  name: String,\n  message: String\n  code: Any,\n  stack: String,\n  cause: Cause, // You can use this to reference the original error\n}\n```\n\n## API\n\n### errorCauses\n\n```js\n(options: ErrorCausesOptions) => [\n  ErrorCausesOptions,\n  handleErrors(CausedError) => Void\n]\n```\n\nTakes options and returns an object containing error causes keyed by error name, and an error handling function.\n\nThe returned cause objects can be passed to the `createError` factory to create the corresponding `CausedError`, or used to manually switch over an error if you prefer not to use the error matcher.\n\n```js\n// Can include any number of ErrorName: Cause pairs\ntype ErrorCausesOptions = {\n  [ErrorName]: Cause // See above\n}\n```\n\n#### handleErrors Throws\n\nIf you pass an error handlers object which is missing an error cause, it will throw an error. You must supply handlers for all error causes. This is to ensure that you don't accidentally forget to handle an error.\n\n```js\nconst MissingHandler = {\n  name: \"MissingHandler\",\n  message: \"Missing error handler\",\n};\n```\n\n`handleErrors` returns a function that takes an error and returns nothing. It will throw if the error is not a `CausedError` or if the error cause is not handled.\n\n```js\nconst UnexpectedError = {\n  name: \"UnexpectedError\",\n  message: \"An unexpected error was thrown\",\n};\n```\n\n\n### createError\n\n```js\n(errorOptions: ErrorOptions) => CausedError\n```\n\nIn order to be handled by the automatically generated handler, errors must have a cause property. The built-in syntax to create a caused error looks like this:\n\n```js\nconst notFoundError = new Error('The requested resource was not found', {\n  cause: {\n    name: 'NotFound',\n    code: 404\n  }\n);\n```\n\nThat's not too bad, but we think this is much nicer:\n\n```js\nconst notFoundError = createError({\n  name: 'NotFound',\n  code: 404,\n  message: 'The requested resource was not found,\n});\n```\n\nOptions:\n\n```js\ntype errorOptions = {\n  name: String,\n  code: Any,\n  message: String,\n  cause: Any,\n  stack: String,\n  ...rest: * // Mixed types allowed\n}\n```\n\n### noop\n\nA no-op function which can be used as a default handler for errors that you don't care about.\n\n```js\n() => Void\n```\n\n## Sponsors\n\nThis project is made possible by [EricElliottJS.com](https://ericelliottjs.com) and [DevAnywhere.io](https://devanywhere.io). If you would like to sponsor this project, [reach out via DevAnywhere](https://devanywhere.io/help?subject=Sponsor+Error+Causes).\n\n\n## License\n\nMIT\n","_attachments":{},"homepage":"https://github.com/paralleldrive/error-causes#readme","bugs":{"url":"https://github.com/paralleldrive/error-causes/issues"},"license":"MIT"}