{"id":16208476,"url":"https://github.com/ehmicky/normalize-exception","last_synced_at":"2025-03-16T11:30:37.195Z","repository":{"id":40602306,"uuid":"501354039","full_name":"ehmicky/normalize-exception","owner":"ehmicky","description":"Normalize exceptions/errors","archived":false,"fork":false,"pushed_at":"2025-03-13T05:04:08.000Z","size":8566,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-13T06:19:08.507Z","etag":null,"topics":["browser","cause","code-quality","error","error-classes","error-handler","error-handling","error-monitoring","error-reporting","errors","exceptions","javascript","library","message","monitoring","nodejs","normalization","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-08T17:46:53.000Z","updated_at":"2025-03-13T05:04:12.000Z","dependencies_parsed_at":"2024-04-22T20:27:44.178Z","dependency_job_id":"924299f3-333a-4ce0-b1d2-b5c03ec220f1","html_url":"https://github.com/ehmicky/normalize-exception","commit_stats":{"total_commits":409,"total_committers":2,"mean_commits":204.5,"dds":0.009779951100244544,"last_synced_commit":"dd96430c89d61625cb6e40d2d7a938f3a3149de1"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fnormalize-exception","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fnormalize-exception/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fnormalize-exception/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ehmicky%2Fnormalize-exception/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ehmicky","download_url":"https://codeload.github.com/ehmicky/normalize-exception/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243814864,"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","message","monitoring","nodejs","normalization","properties","stacktrace","typescript"],"created_at":"2024-10-10T10:17:10.966Z","updated_at":"2025-03-16T11:30:36.847Z","avatar_url":"https://github.com/ehmicky.png","language":"JavaScript","readme":"[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js\u0026colorA=404040\u0026logoColor=66cc33)](https://www.npmjs.com/package/normalize-exception)\n[![Browsers](https://img.shields.io/badge/-Browsers-808080?logo=firefox\u0026colorA=404040)](https://unpkg.com/normalize-exception?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/normalize-exception)\n[![Minified size](https://img.shields.io/bundlephobia/minzip/normalize-exception?label\u0026colorA=404040\u0026colorB=808080\u0026logo=webpack)](https://bundlephobia.com/package/normalize-exception)\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\nNormalize:\n\n- Exceptions that are [not `Error` instances](#invalid-type)\n- Error properties (`name`, `message`, `stack`, `constructor`) that are\n  [missing](#missing-properties), [invalid](#invalid-properties),\n  [enumerable](#enumerable-properties), [readonly](#readonly-properties),\n  [non-writable](#non-writable-properties),\n  [non-configurable](#non-configurable-properties),\n  [non-extensible](#non-extensible-error), [proxied](#proxies) or\n  [throwing](#throwing-properties)\n- [`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)\n  and\n  [`error.errors`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError)\n  [recursively](#recursion), when present\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\u003c!-- eslint-disable no-throw-literal --\u003e\n\n```js\nimport normalizeException from 'normalize-exception'\n\ntry {\n  throw 'message'\n} catch (error) {\n  console.log(error) // 'message'\n  console.log(normalizeException(error)) // Error: message\n  console.log(normalizeException(error) instanceof Error) // true\n}\n```\n\n# Install\n\n```bash\nnpm install normalize-exception\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## normalizeException(error, options?)\n\n`error` `any`\\\n`options` [`Options`](#options)\\\n_Return value_: `Error`\n\n`normalizeException()` never throws.\n\nIf `error` is an `Error` instance, it is returned. Any missing or invalid error\nproperty is directly modified.\n\nIf it is not an `Error` instance, a new one is created and returned.\n\n### Options\n\nOptions are an optional object with the following properties.\n\n#### shallow\n\n_Type_: `boolean`\\\n_Default_: `false`\n\nUnless `true`,\n[`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)\nand\n[`error.errors`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError)\nare normalized [recursively](#recursion), when present.\n\n# Features\n\n## Invalid type\n\n### Strings\n\n\u003c!-- eslint-disable no-throw-literal --\u003e\n\n```js\ntry {\n  throw 'message'\n} catch (error) {\n  console.log(error) // 'message'\n  console.log(normalizeException(error)) // Error: message\n  console.log(normalizeException(error) instanceof Error) // true\n}\n```\n\n### Plain objects\n\n\u003c!-- eslint-disable no-throw-literal --\u003e\n\n```js\ntry {\n  throw { name: 'TypeError', message: 'message' }\n} catch (error) {\n  console.log(normalizeException(error)) // TypeError: message\n}\n```\n\n### Others\n\n\u003c!-- eslint-disable unicorn/no-null, no-throw-literal --\u003e\n\n```js\ntry {\n  throw null\n} catch (error) {\n  console.log(error.message) // Throws\n  console.log(normalizeException(error).message) // 'null'\n}\n```\n\n## Missing properties\n\n```js\ntry {\n  const error = new TypeError('message')\n  error.name = undefined\n  throw error\n} catch (error) {\n  console.log(error.name) // undefined\n  console.log(normalizeException(error).name) // 'TypeError'\n}\n```\n\n## Mismatched constructor\n\n\u003c!-- eslint-disable fp/no-delete --\u003e\n\n```js\ntry {\n  const error = new TypeError('message')\n  error.constructor = RangeError\n  throw error\n} catch (error) {\n  console.log(error.constructor) // RangeError\n  console.log(normalizeException(error).constructor) // TypeError\n}\n```\n\n## Missing stack\n\n```js\ntry {\n  const error = new Error('message')\n  error.stack = undefined\n  throw error\n} catch (error) {\n  console.log(error.stack) // undefined\n  console.log(normalizeException(error).stack) // 'Error: message ...'\n}\n```\n\n## Invalid properties\n\n```js\ntry {\n  const error = new Error('message')\n  error.message = true\n  throw error\n} catch (error) {\n  console.log(typeof error.message) // 'boolean'\n  console.log(typeof normalizeException(error).message) // 'string'\n}\n```\n\n## Enumerable properties\n\n\u003c!-- eslint-disable fp/no-class, fp/no-this, fp/no-mutation --\u003e\n\n```js\nclass ExampleError extends Error {\n  constructor(...args) {\n    super(...args)\n    // Common mistake: this makes `error.name` enumerable\n    this.name = 'ExampleError'\n  }\n}\n\ntry {\n  throw new ExampleError('message')\n} catch (error) {\n  console.log({ ...error }) // { name: 'ExampleError' }\n  console.log({ ...normalizeException(error) }) // {}\n}\n```\n\n## Readonly properties\n\n\u003c!-- eslint-disable fp/no-mutating-methods, fp/no-get-set, fp/no-mutation --\u003e\n\n```js\ntry {\n  const error = new Error('message')\n  Object.defineProperty(error, 'message', { get: () =\u003e 'message' })\n  throw error\n} catch (error) {\n  error.message = 'other' // Throws\n  normalizeException(error).message = 'other' // Does not throw\n}\n```\n\n## Non-writable properties\n\n\u003c!-- eslint-disable fp/no-mutating-methods, fp/no-mutation --\u003e\n\n```js\ntry {\n  const error = new Error('message')\n  Object.defineProperty(error, 'message', { value: '', writable: false })\n  throw error\n} catch (error) {\n  error.message = 'other' // Throws\n  normalizeException(error).message = 'other' // Does not throw\n}\n```\n\n## Non-configurable properties\n\n\u003c!-- eslint-disable fp/no-mutating-methods, fp/no-delete --\u003e\n\n```js\ntry {\n  const error = new Error('message')\n  Object.defineProperty(error, 'message', { value: '', configurable: false })\n  throw error\n} catch (error) {\n  delete error.message // Throws\n  delete normalizeException(error).message // Does not throw\n}\n```\n\n## Non-extensible error\n\n\u003c!-- eslint-disable fp/no-mutation --\u003e\n\n```js\ntry {\n  const error = new Error('message')\n  Object.preventExtensions(error)\n  throw error\n} catch (error) {\n  error.prop = true // Throws\n  normalizeException(error).prop = true // Does not throw\n}\n```\n\n## Proxies\n\n\u003c!-- eslint-disable fp/no-proxy, no-shadow --\u003e\n\n```js\ntry {\n  throw new Proxy(new Error('message'), {})\n} catch (error) {\n  const { toString } = Object.prototype\n  console.log(toString.call(error)) // '[object Object]'\n  console.log(toString.call(normalizeException(error))) // '[object Error]'\n}\n```\n\n## Throwing properties\n\n### Proxies\n\n\u003c!-- eslint-disable fp/no-proxy, no-shadow --\u003e\n\n```js\ntry {\n  throw new Proxy(new Error('message'), {\n    get: () =\u003e {\n      throw new Error('example')\n    },\n  })\n} catch (error) {\n  console.log(error.message) // Throws\n  console.log(normalizeException(error).message) // Does not throw\n}\n```\n\n### Getters\n\n\u003c!-- eslint-disable fp/no-mutating-methods, fp/no-get-set --\u003e\n\n```js\ntry {\n  const error = new Error('message')\n  Object.defineProperty(error, 'message', {\n    get: () =\u003e {\n      throw new Error('example')\n    },\n  })\n  throw error\n} catch (error) {\n  console.log(error.message) // Throws\n  console.log(normalizeException(error).message) // Does not throw\n}\n```\n\n## Recursion\n\n### `error.cause`\n\n```js\ntry {\n  throw new Error('message', { cause: 'innerError' })\n} catch (error) {\n  console.log(error.cause instanceof Error) // false\n  console.log(normalizeException(error).cause instanceof Error) // true\n}\n```\n\n### `error.errors`\n\n```js\ntry {\n  throw new AggregateError(['innerError'], 'message')\n} catch (error) {\n  console.log(error.errors[0] instanceof Error) // false\n  console.log(normalizeException(error).errors[0] instanceof Error) // true\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- [`merge-error-cause`](https://github.com/ehmicky/merge-error-cause): Merge an\n  error with its `cause`\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/normalize-exception/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/normalize-exception/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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fnormalize-exception","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fehmicky%2Fnormalize-exception","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fehmicky%2Fnormalize-exception/lists"}