{"id":17398473,"url":"https://github.com/vweevers/module-error","last_synced_at":"2025-04-30T06:44:48.213Z","repository":{"id":40574650,"uuid":"420031876","full_name":"vweevers/module-error","owner":"vweevers","description":"Create errors with code and cause properties.","archived":false,"fork":false,"pushed_at":"2023-06-01T16:00:22.000Z","size":23,"stargazers_count":6,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-30T06:44:42.595Z","etag":null,"topics":["error","javascript","nodejs","npm-package"],"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/vweevers.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2021-10-22T09:00:52.000Z","updated_at":"2024-09-04T02:08:13.000Z","dependencies_parsed_at":"2024-10-23T05:19:48.490Z","dependency_job_id":null,"html_url":"https://github.com/vweevers/module-error","commit_stats":{"total_commits":13,"total_committers":2,"mean_commits":6.5,"dds":"0.46153846153846156","last_synced_commit":"2be472a97328ddf04ad8ce9b8fb7e5cfa6eafd16"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fmodule-error","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fmodule-error/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fmodule-error/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fmodule-error/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vweevers","download_url":"https://codeload.github.com/vweevers/module-error/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251658196,"owners_count":21622819,"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":["error","javascript","nodejs","npm-package"],"created_at":"2024-10-16T14:57:06.148Z","updated_at":"2025-04-30T06:44:48.193Z","avatar_url":"https://github.com/vweevers.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# module-error\n\n**Create errors with `code` and `cause` properties. Simple and extensible.**\n\n[![npm status](http://img.shields.io/npm/v/module-error.svg)](https://www.npmjs.org/package/module-error)\n[![node](https://img.shields.io/node/v/module-error.svg)](https://www.npmjs.org/package/module-error)\n[![Test](https://img.shields.io/github/workflow/status/vweevers/module-error/Test?label=test)](https://github.com/vweevers/module-error/actions/workflows/test.yml)\n[![Standard](https://img.shields.io/badge/standard-informational?logo=javascript\u0026logoColor=fff)](https://standardjs.com)\n[![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org)\n\n## Usage\n\nWorks like a regular `Error` constructor but adds an options argument (as [`proposal-error-cause`](https://github.com/tc39/proposal-error-cause) does).\n\n```js\nconst ModuleError = require('module-error')\n\nthrow new ModuleError('Message goes here', {\n  code: 'EXAMPLE_NOT_FOUND'\n})\n```\n\nThe primary purpose of `ModuleError` is to define a `code` property on the error object following Node.js conventions. It should be set to an uppercase string that uniquely identifies a situation, prefixed with the name of your module (or a collection of modules) to prevent conflicts.\n\nThe output looks like this in Node.js (some stack frames omitted for brevity):\n\n```\nModuleError: Message goes here\n    at Object.\u003canonymous\u003e (/home/app/example.js:5:7)\n    at node:internal/main/run_main_module:17:47 {\n  code: 'EXAMPLE_NOT_FOUND'\n}\n```\n\nThe benefit of error codes is that messages can be changed without a semver-major release because your [semver](https://semver.org) contract will be on the codes. Codes can be reused across related modules while allowing individual modules to customize messages. I also prefer it over `instanceof MyError` logic because codes work cross-realm and when a tree of `node_modules` contains multiple versions of a module.\n\nTo wrap another error:\n\n```js\ntry {\n  JSON.parse(await fs.readFile('state.json'))\n} catch (err) {\n  throw new ModuleError('Could not load state', {\n    code: 'EXAMPLE_INVALID_STATE',\n    cause: err\n  })\n}\n```\n\nIf for convenience you want to create subclasses with prepared codes:\n\n```js\nclass NotFoundError extends ModuleError {\n  constructor(message, options) {\n    super(message, { ...options, code: 'EXAMPLE_NOT_FOUND' })\n  }\n}\n```\n\nThen you can do:\n\n```js\nthrow new NotFoundError('Message goes here')\n```\n\nUnder Node.js the stack trace will be adjusted accordingly, to skip the frame containing your error constructor.\n\n## API\n\n### `ModuleError(message, [options])`\n\nConstructor to create an error with the provided `message` string. Options:\n\n- `code` (string): if provided, define a `code` property with this value.\n- `cause` (Error): if provided, define a `cause` property with this value. Unlike the spec of [`proposal-error-cause`](https://github.com/tc39/proposal-error-cause) the property is enumerable so that Node.js (v16 at the time of writing) will print it. Firefox prints it regardless, Chromium doesn't yet.\n- `expected`: if truthy, define a `expected` property with value `true`. This is useful for command line interfaces to differentiate unexpected errors from e.g. invalid user input. A pattern I like to follow is to print only an error message if `err.expected` is true and no `--verbose` flag was provided. Otherwise print the full stack.\n- `transient`: if truthy, define a `transient` property with value `true`. This communicates to users that the operation that caused the error may be retried. See also [`transient-error`](https://github.com/vweevers/transient-error) to mark existing errors as transient.\n\n## Install\n\nWith [npm](https://npmjs.org) do:\n\n```\nnpm install module-error\n```\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvweevers%2Fmodule-error","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvweevers%2Fmodule-error","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvweevers%2Fmodule-error/lists"}