{"id":16208459,"url":"https://github.com/ehmicky/merge-error-cause","last_synced_at":"2025-03-16T11:30:36.565Z","repository":{"id":40602734,"uuid":"501756836","full_name":"ehmicky/merge-error-cause","owner":"ehmicky","description":"Merge an error with its `cause`","archived":false,"fork":false,"pushed_at":"2025-02-04T20:38:19.000Z","size":10593,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-01T08:45:24.335Z","etag":null,"topics":["browser","cause","code-quality","error","error-classes","error-handler","error-handling","error-monitoring","error-reporting","errors","exceptions","javascript","library","merge","message","monitoring","nodejs","properties","stacktrace","typescript"],"latest_commit_sha":null,"homepage":"","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/ehmicky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-09T17:56:45.000Z","updated_at":"2025-02-04T20:38:22.000Z","dependencies_parsed_at":"2023-02-07T12:16:26.214Z","dependency_job_id":"c746e34f-56c1-41fe-a280-acc7a1826cb1","html_url":"https://github.com/ehmicky/merge-error-cause","commit_stats":{"total_commits":604,"total_committers":2,"mean_commits":302.0,"dds":"0.013245033112582738","last_synced_commit":"5b565ff9b46a8e453044341a7f26255d6cbb25aa"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fmerge-error-cause","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fmerge-error-cause/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fmerge-error-cause/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fmerge-error-cause/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmicky","download_url":"https://codeload.github.com/ehmicky/merge-error-cause/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243814907,"owners_count":20352037,"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":["browser","cause","code-quality","error","error-classes","error-handler","error-handling","error-monitoring","error-reporting","errors","exceptions","javascript","library","merge","message","monitoring","nodejs","properties","stacktrace","typescript"],"created_at":"2024-10-10T10:17:03.044Z","updated_at":"2025-03-16T11:30:36.060Z","avatar_url":"https://github.com/ehmicky.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js\u0026colorA=404040\u0026logoColor=66cc33)](https://www.npmjs.com/package/merge-error-cause)\n[![Browsers](https://img.shields.io/badge/-Browsers-808080?logo=firefox\u0026colorA=404040)](https://unpkg.com/merge-error-cause?module)\n[![TypeScript](https://img.shields.io/badge/-Typed-808080?logo=typescript\u0026colorA=404040\u0026logoColor=0096ff)](/src/main.d.ts)\n[![Codecov](https://img.shields.io/badge/-Tested%20100%25-808080?logo=codecov\u0026colorA=404040)](https://codecov.io/gh/ehmicky/merge-error-cause)\n[![Minified size](https://img.shields.io/bundlephobia/minzip/merge-error-cause?label\u0026colorA=404040\u0026colorB=808080\u0026logo=webpack)](https://bundlephobia.com/package/merge-error-cause)\n[![Mastodon](https://img.shields.io/badge/-Mastodon-808080.svg?logo=mastodon\u0026colorA=404040\u0026logoColor=9590F9)](https://fosstodon.org/@ehmicky)\n[![Medium](https://img.shields.io/badge/-Medium-808080.svg?logo=medium\u0026colorA=404040)](https://medium.com/@ehmicky)\n\nMerge an error with its `cause`.\n\nThis merges\n[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)\nrecursively with its parent `error`, including its\n[`message`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/message),\n[`stack`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/stack),\n[`name`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name)\nand\n[`errors`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError).\n\n# Hire me\n\nPlease\n[reach out](https://www.linkedin.com/feed/update/urn:li:activity:7117265228068716545/)\nif you're looking for a Node.js API or CLI engineer (11 years of experience).\nMost recently I have been [Netlify Build](https://github.com/netlify/build)'s\nand [Netlify Plugins](https://www.netlify.com/products/build/plugins/)'\ntechnical lead for 2.5 years. I am available for full-time remote positions.\n\n# Example\n\n```js\nimport mergeErrorCause from 'merge-error-cause'\n\nconst main = (userId) =\u003e {\n  try {\n    return createUser(userId)\n  } catch (error) {\n    throw mergeErrorCause(error)\n    // Printed as:\n    //   TypeError: Invalid user id: false\n    //   Could not create user.\n  }\n}\n\nconst createUser = (userId) =\u003e {\n  try {\n    validateUserId(userId)\n    return sendDatabaseRequest('create', userId)\n  } catch (cause) {\n    throw new Error('Could not create user.', { cause })\n  }\n}\n\nconst validateUserId = (userId) =\u003e {\n  if (typeof userId !== 'string') {\n    throw new TypeError(`Invalid user id: ${userId}.`)\n  }\n}\n\nmain(false)\n```\n\n# Install\n\n```bash\nnpm install merge-error-cause\n```\n\nThis package works in both Node.js \u003e=18.18.0 and\n[browsers](https://raw.githubusercontent.com/ehmicky/dev-tasks/main/src/browserslist).\n\nThis is an ES module. It must be loaded using\n[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),\nnot `require()`. If TypeScript is used, it must be configured to\n[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),\nnot CommonJS.\n\n# API\n\n## mergeErrorCause(error)\n\n`error` `Error | any`\\\n_Return value_: `Error`\n\n`error` is modified and returned.\n\nIf `error`'s class is `Error` or if [`error.wrap`](#error-class) is `true`,\n[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)\nis modified and returned instead.\n\nIf `error` is not a valid `Error`, a new `error` is created and returned\ninstead.\n\nThis never throws.\n\n# Background\n\n[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)\nis a\n[recent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause#browser_compatibility)\nJavaScript feature to wrap error messages and properties.\n\n```js\ntry {\n  validateUserId(userId)\n  sendDatabaseRequest('create', userId)\n} catch (cause) {\n  throw new Error('Could not create user.', { cause })\n}\n```\n\nHowever, it comes with a few issues.\n\n## Traversing `error.cause`\n\n### Problem\n\nConsumers need to traverse `error.cause`.\n\n\u003c!-- eslint-disable max-depth --\u003e\n\n```js\ntry {\n  createUser(userId)\n} catch (error) {\n  if (error.code === 'E101' || (error.cause \u0026\u0026 error.cause.code === 'E101')) {\n    // Checking for properties requires traversing `error.cause`\n  }\n\n  if (\n    error.name === 'UserError' ||\n    (error.cause \u0026\u0026 error.cause.name === 'UserError')\n  ) {\n    // So does checking for error class\n  }\n}\n```\n\nThis is tricky to get right. For example:\n\n- `error.cause.cause` might also exist (and so on)\n- If `error` is not an `Error` instance, `error.name` might throw\n- Recursing over `error.cause` might be an infinite cycle\n\n### Solution\n\nThis library merges `error.cause` recursively. It also\n[ensures `error` is an `Error` instance](#normalization). Consumers can then\nhandle errors without checking its `cause`.\n\n\u003c!-- eslint-disable max-depth --\u003e\n\n```js\ntry {\n  createUser(userId)\n} catch (error) {\n  if (error.code === 'E101') {\n    /* ... */\n  }\n\n  if (error.name === 'UserError') {\n    /* ... */\n  }\n}\n```\n\n## Verbose stack trace\n\n### Problem\n\nStack traces with multiple `error.cause` can be quite verbose.\n\n```\nError: Could not create user group.\n    at createUserGroup (/home/user/app/user_group.js:19:9)\n    at createGroups (/home/user/app/user_group.js:101:10)\n    at startApp (/home/user/app/app.js:35:20)\n    at main (/home/user/app/app.js:3:4) {\n  [cause]: Error: Could not create user.\n      at newUser (/home/user/app/user.js:52:7)\n      at createUser (/home/user/app/user.js:43:5)\n      at createUserGroup (/home/user/app/user_group.js:17:11)\n      at createGroups (/home/user/app/user_group.js:101:10)\n      at startApp (/home/user/app/app.js:35:20)\n      at main (/home/user/app/app.js:3:4) {\n    [cause]: Error: Invalid user.\n        at validateUser (/home/user/app/user.js:159:8)\n        at userInstance (/home/user/app/user.js:20:4)\n        at newUser (/home/user/app/user.js:50:7)\n        at createUser (/home/user/app/user.js:43:5)\n        at createUserGroup (/home/user/app/user_group.js:17:11)\n        at createGroups (/home/user/app/user_group.js:101:10)\n        at startApp (/home/user/app/app.js:35:20)\n        at main (/home/user/app/app.js:3:4) {\n      [cause]: UserError: User \"15\" does not exist.\n          at checkUserId (/home/user/app/user.js:195:3)\n          at checkUserExist (/home/user/app/user.js:170:10)\n          at validateUser (/home/user/app/user.js:157:23)\n          at userInstance (/home/user/app/user.js:20:4)\n          at newUser (/home/user/app/user.js:50:7)\n          at createUser (/home/user/app/user.js:43:5)\n          at createUserGroup (/home/user/app/user_group.js:17:11)\n          at createGroups (/home/user/app/user_group.js:101:10)\n          at startApp (/home/user/app/app.js:35:20)\n          at main (/home/user/app/app.js:3:4)\n    }\n  }\n}\n```\n\nEach error cause is indented and printed separately.\n\n- The stack traces mostly repeat each other since the function calls are part of\n  the same line execution\n- The most relevant message (innermost) is harder to find since it is shown last\n\n### Solution\n\nThis library only keeps the innermost stack trace. Error messages are\nconcatenated by default from innermost to outermost. This results in much\nsimpler stack traces without losing any information.\n\n```\nTypeError: User \"15\" does not exist.\nInvalid user.\nCould not create user.\nCould not create user group.\n    at checkUserId (/home/user/app/user.js:195:3)\n    at checkUserExist (/home/user/app/user.js:170:10)\n    at validateUser (/home/user/app/user.js:157:23)\n    at userInstance (/home/user/app/user.js:20:4)\n    at newUser (/home/user/app/user.js:50:7)\n    at createUser (/home/user/app/user.js:43:5)\n    at createUserGroup (/home/user/app/user_group.js:17:11)\n    at createGroups (/home/user/app/user_group.js:101:10)\n    at startApp (/home/user/app/app.js:35:20)\n    at main (/home/user/app/app.js:3:4)\n```\n\n# Features\n\n## Stack traces\n\nOnly the innermost stack trace is kept.\n\nPlease make sure you use `async`/`await` instead of `new Promise()` or callbacks\nto prevent truncated stack traces.\n\n## Messages\n\nInner error messages are printed first.\n\n```js\ntry {\n  throw new Error('Invalid user id.')\n} catch (cause) {\n  throw new Error('Could not create user.', { cause })\n  // Printed as:\n  //   Error: Invalid user id.\n  //   Could not create user.\n}\n```\n\nIf the outer error message ends with `:`, it is prepended instead.\n\n```js\ntry {\n  throw new Error('Invalid user id.')\n} catch (cause) {\n  throw new Error('Could not create user:', { cause })\n  // Printed as:\n  //   Error: Could not create user: Invalid user id.\n}\n```\n\n`:` can optionally be followed by a newline.\n\n```js\ntry {\n  throw new Error('Invalid user id.')\n} catch (cause) {\n  throw new Error('Could not create user:\\n', { cause })\n  // Printed as:\n  //   Error: Could not create user:\n  //   Invalid user id.\n}\n```\n\n## Error class\n\nThe outer error class is used.\n\n```js\ntry {\n  throw new TypeError('User id is not a string.')\n} catch (cause) {\n  const error = new UserError('Could not create user.', { cause })\n  const mergedError = mergeErrorCause(error)\n  console.log(mergedError instanceof UserError) // true\n  console.log(mergedError.name) // 'UserError'\n}\n```\n\nIf the parent error class is `Error`, the child class is used instead. This\nallows wrapping the error message or properties while keeping its class.\n\n```js\ntry {\n  throw new TypeError('User id is not a string.')\n} catch (cause) {\n  const error = new Error('Could not create user.', { cause })\n  console.log(mergeErrorCause(error) instanceof TypeError) // true\n}\n```\n\n`error.wrap: true` has the same effect, but works with any parent error class.\n\n```js\ntry {\n  throw new TypeError('User id is not a string.')\n} catch (cause) {\n  const error = new UserError('Could not create user.', { cause })\n  error.wrap = true\n  console.log(mergeErrorCause(error) instanceof TypeError) // true\n}\n```\n\n## Error properties\n\nError properties are shallowly merged.\n\n\u003c!-- eslint-disable fp/no-mutating-assign --\u003e\n\n```js\n// Both `userId` and `invalidUser` are kept\ntry {\n  throw Object.assign(new Error('Invalid user id.'), { userId: '5' })\n} catch (cause) {\n  throw Object.assign(new Error('Could not create user.', { cause }), {\n    invalidUser: true,\n  })\n}\n```\n\nEmpty error messages are ignored. This is useful when wrapping error properties.\n\n\u003c!-- eslint-disable fp/no-mutating-assign, unicorn/error-message --\u003e\n\n```js\ntry {\n  throw new Error('Invalid user id.')\n} catch (cause) {\n  throw Object.assign(new Error('', { cause }), { invalidUser: true })\n}\n```\n\n## Aggregate errors\n\nAny\n[`aggregateError.errors[*].cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError)\nis processed recursively. However, `aggregateError.errors` are not merged with\neach other since those are different from each other.\n\nIf both `error.errors` and `error.cause.errors` exist, they are concatenated.\n\n## Normalization\n\nInvalid errors [are normalized](https://github.com/ehmicky/normalize-exception)\nto proper `Error` instances.\n\n\u003c!-- eslint-disable no-throw-literal --\u003e\n\n```js\ntry {\n  throw 'Invalid user id.'\n} catch (error) {\n  console.log(mergeErrorCause(error)) // Error: Invalid user id.\n}\n```\n\n# Related projects\n\n- [`modern-errors`](https://github.com/ehmicky/modern-errors): Handle errors in\n  a simple, stable, consistent way\n- [`error-custom-class`](https://github.com/ehmicky/error-custom-class): Create\n  one error class\n- [`error-class-utils`](https://github.com/ehmicky/error-class-utils): Utilities\n  to properly create error classes\n- [`error-serializer`](https://github.com/ehmicky/error-serializer): Convert\n  errors to/from plain objects\n- [`normalize-exception`](https://github.com/ehmicky/normalize-exception):\n  Normalize exceptions/errors\n- [`is-error-instance`](https://github.com/ehmicky/is-error-instance): Check if\n  a value is an `Error` instance\n- [`set-error-class`](https://github.com/ehmicky/set-error-class): Properly\n  update an error's class\n- [`set-error-message`](https://github.com/ehmicky/set-error-message): Properly\n  update an error's message\n- [`wrap-error-message`](https://github.com/ehmicky/wrap-error-message):\n  Properly wrap an error's message\n- [`set-error-props`](https://github.com/ehmicky/set-error-props): Properly\n  update an error's properties\n- [`set-error-stack`](https://github.com/ehmicky/set-error-stack): Properly\n  update an error's stack\n- [`error-cause-polyfill`](https://github.com/ehmicky/error-cause-polyfill):\n  Polyfill `error.cause`\n- [`handle-cli-error`](https://github.com/ehmicky/handle-cli-error): 💣 Error\n  handler for CLI applications 💥\n- [`log-process-errors`](https://github.com/ehmicky/log-process-errors): Show\n  some ❤ to Node.js process errors\n- [`error-http-response`](https://github.com/ehmicky/error-http-response):\n  Create HTTP error responses\n- [`winston-error-format`](https://github.com/ehmicky/winston-error-format): Log\n  errors with Winston\n\n# Support\n\nFor any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).\n\nEveryone is welcome regardless of personal background. We enforce a\n[Code of conduct](CODE_OF_CONDUCT.md) in order to promote a positive and\ninclusive environment.\n\n# Contributing\n\nThis project was made with ❤️. The simplest way to give back is by starring and\nsharing it online.\n\nIf the documentation is unclear or has a typo, please click on the page's `Edit`\nbutton (pencil icon) and suggest a correction.\n\nIf you would like to help us fix a bug or add a new feature, please check our\n[guidelines](CONTRIBUTING.md). Pull requests are welcome!\n\n\u003c!-- Thanks go to our wonderful contributors: --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START --\u003e\n\u003c!-- prettier-ignore --\u003e\n\u003c!--\n\u003ctable\u003e\u003ctr\u003e\u003ctd align=\"center\"\u003e\u003ca href=\"https://fosstodon.org/@ehmicky\"\u003e\u003cimg src=\"https://avatars2.githubusercontent.com/u/8136211?v=4\" width=\"100px;\" alt=\"ehmicky\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eehmicky\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/ehmicky/merge-error-cause/commits?author=ehmicky\" title=\"Code\"\u003e💻\u003c/a\u003e \u003ca href=\"#design-ehmicky\" title=\"Design\"\u003e🎨\u003c/a\u003e \u003ca href=\"#ideas-ehmicky\" title=\"Ideas, Planning, \u0026 Feedback\"\u003e🤔\u003c/a\u003e \u003ca href=\"https://github.com/ehmicky/merge-error-cause/commits?author=ehmicky\" title=\"Documentation\"\u003e📖\u003c/a\u003e\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n --\u003e\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fmerge-error-cause","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmicky%2Fmerge-error-cause","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fmerge-error-cause/lists"}