\n\n \n\n# @-xun/error\n\n\n\nThis tiny library provides so-called \"named errors,\" which are normal [Error][1]\nclasses (compatible with all JS runtimes) with some slight tweaks to improve\noverall handling safety, improve DX for the developers that work with these\nclasses, and improve UX for the users that might encounter them.\n\nMore specifically, this library returns a factory function\n([`makeNamedError`][6]) capable of creating custom [Error][1] subclasses with\npowerful [cross][4]-[package][5] [cross-realm instanceof checks][3] and\nhuman-readable names that both survive transpilation/minification and show up in\nstack traces.\n\n\n\n---\n\n\n\n\n\n\n- [Features](#features)\n- [Install](#install)\n- [Usage](#usage)\n- [Appendix](#appendix)\n - [Published Package Details](#published-package-details)\n - [License](#license)\n- [Contributing and Support](#contributing-and-support)\n - [Contributors](#contributors)\n\n\n\n\n\n \n\n## Features\n\n**Works via a [simple wrapper function][2] using normal ES6 class syntax**\n\n```typescript\nmakeNamedError(\n // Anonymous classes will be transformed into a named class by makeNamedError\n class extends Error {\n // ...\n },\n 'MyCustomError'\n);\n\nmakeNamedError(\n // However, for improved DX in TypeScript, give your class definitions names\n class MyCustomSubclassError extends MyCustomError {\n // ...\n },\n 'MyCustomSubclassError'\n);\n```\n\n**Makes error name available via prototypical instance and as a static class\nproperty**\n\n```typescript\nconst { MyCustomError } = makeNamedError(/* ... */, 'MyCustomError');\n\nconsole.log(MyCustomError.name) // MyCustomError\nconsole.log((new MyCustomError()).name) // MyCustomError\n```\n\n**Ensures error class names in error messages and other outputs survive\nminification**\n\n```typescript\nconst { MyCoolError } = makeNamedError(/* ... */, 'MyCoolError');\n\nconsole.log(MyCoolError.name) // MyCoolError (every time!)\n```\n\n**Provides built-in type guards that are safer and more powerful than\n`instanceof`**\n\n```typescript\nconst { BigError, isBigError } = makeNamedError(/* ... */, 'BigError');\n\nconsole.log(isBigError(new BigError())) // true\nconsole.log(isBigError(new SomeOtherError())) // false\nconsole.log(isBigError(new Error())) // false\n```\n\nEach class's `.isX()` function is additionally provided as a static class\nproperty:\n\n```typescript\nconst { BigError } = makeNamedError(/* ... */, 'BigError');\n\nconsole.log(BigError.isError(new BigError())); // true\nconsole.log(BigError.isError(new SomeOtherError())); // false\nconsole.log(BigError.isError(new Error())); // false\n```\n\nAll instanceof checks still work as expected (but can be avoided):\n\n```typescript\nconst { BigError } = makeNamedError(/* ... */, 'BigError');\nconst { BiggestError } = makeNamedError(/* ... */, 'BiggestError');\n\nconsole.log(new BigError() instanceof BigError); // true\nconsole.log(new BigError() instanceof Error); // true\nconsole.log(new BiggestError() instanceof BiggestError); // true\nconsole.log(new BiggestError() instanceof Error); // true\n\nconsole.log(new Error() instanceof BigError); // false\n```\n\nUnlike instanceof, the `.isX()`/`.isError()` function is both [cross-realm\nsafe][3] and safe to use in situations where multiple _distinct_ copies of your\nerror classes might exist in the dependency tree (e.g. [dual package\nhazard][4]).\n\nIn case of the latter, where [two different libraries might import two different\nversions of your error classes][5] (a surprisingly common occurrence!), this\npackage takes away the pain:\n\n```typescript\nimport lib1 from 'some-lib-exports-your-error';\nimport lib2 from 'unrelated-lib-also-exports-same-error-but-not-strictly-equal';\n\nconsole.log(new lib1.YourError() instanceof lib2.YourError); // false\nconsole.log(lib2.YourError.isError(new lib1.YourError())); // true\n```\n\n**Supports inheritance** (both ES6 \"extends\" and pre-ES6 prototypical)\n\n```typescript\nconst { AppError } = makeNamedError(\n class AppError extends Error {\n panic() {\n console.log('oh no!');\n process.exit(123);\n }\n },\n 'AppError'\n);\n\nconst { ValidationError } = makeNamedError(\n // Note how ValidationError extends AppError\n class ValidationError extends AppError {\n #validationErrors: string[];\n\n constructor(issues: string[]) {\n super();\n this.#validationErrors = issues;\n }\n\n getValidationErrors() {\n return this.#validationErrors;\n }\n },\n 'ValidationError'\n);\n\nconst error = new ValidationError(['validation error 1', 'validation error 2']);\n\nif (ValidationError.isError(error)) {\n console.log('validation errors:', error.getValidationErrors().join(', '));\n // validation errors: validation error 1, validation error 2\n}\n\n// Other logic...\n\nif (AppError.isError(error)) {\n error.panic(); // This will run thanks to polymorphism and inheritance rules\n}\n\n// The program will die before reaching this point thanks to error.panic()\n```\n\n**Comes with kickass TypeScript types out of the box**\n\n```typescript\nimport {\n makeNamedError,\n isANamedErrorClass,\n isANamedErrorInstance\n} from '@-xun/error';\n\nconst { SmallError, isSmallError } = makeNamedError(\n /* ... */, // All class methods and properties are preserved as expected\n 'SmallError'\n);\n\nconsole.log(isANamedErrorClass(Error)); // false\nconsole.log(isANamedErrorInstance(new Error())); // false\nconsole.log(SmallError.isError(new Error())); // false\nconsole.log(isSmallError(new Error())); // false\n\n// All isX type guard functions will narrow unknown types properly!\n\nconsole.log(isANamedErrorClass(SmallError)); // true\nconsole.log(isANamedErrorInstance(new SmallError())); // true\nconsole.log(SmallError.isError(new SmallError())); // true\nconsole.log(isSmallError(new SmallError())); // true\n```\n\n## Install\n\n\n\nTo install:\n\n```shell\nnpm install @-xun/error\n```\n\n## Usage\n\nStart using `@-xun/error` in four quick and easy steps.\n\n1. Import:\n\n```typescript\nimport { makeNamedError } from '@-xun/error';\n```\n\n2. Optionally create a \"root\" error class from which the rest of your custom\n Error subclasses will descend:\n\n```typescript\nexport const { AppError } = makeNamedError(\n class AppError extends Error {},\n 'AppError'\n);\n```\n\n3. Create and export the rest of your custom Error subclasses as you normally\n would:\n\n```typescript\nexport const { ValidationError } = makeNamedError(\n class ValidationError extends AppError {},\n 'ValidationError'\n);\n\nexport const { AuthError } = makeNamedError(\n class AuthError extends AppError {},\n 'AuthError'\n);\n\nexport const { NotFoundError } = makeNamedError(\n class NotFoundError extends AppError {},\n 'NotFoundError'\n);\n\n// Improve TypeScript DX by exporting the literal class types too, if you want:\n\n/**\n * Helpful comment for users of your Error subclass goes here.\n */\nexport type ValidationError = InstanceType;\n\n/**\n * Helpful comment for users of your Error subclass goes here.\n */\nexport type AuthError = InstanceType;\n\n/**\n * Helpful comment for users of your Error subclass goes here.\n */\nexport type NotFoundError = InstanceType;\n```\n\n4. Use your custom errors like any other `Error` subclass (because they are):\n\n```typescript\nimport { ValidationError } from './shared/errors.ts';\n\n// ...\n\nif (somethingBadHappened) {\n throw new ValidationError();\n}\n\n// ...\n```\n\nNeat! 📸\n\n\n\n## Appendix\n\n\n\nFurther documentation can be found under [`docs/`][x-repo-docs].\n\n\n\n\n### Published Package Details\n\nThis is a [CJS2 package][x-pkg-cjs-mojito] with statically-analyzable exports\nbuilt by Babel for use in Node.js versions that are not end-of-life. For\nTypeScript users, this package supports both `\"Node10\"` and `\"Node16\"` module\nresolution strategies.\n\n\n\n\n\nExpand details\n\nThat means both CJS2 (via `require(...)`) and ESM (via `import { ... } from ...`\nor `await import(...)`) source will load this package from the same entry points\nwhen using Node. This has several benefits, the foremost being: less code\nshipped/smaller package size, avoiding [dual package\nhazard][x-pkg-dual-package-hazard] entirely, distributables are not\npacked/bundled/uglified, a drastically less complex build process, and CJS\nconsumers aren't shafted.\n\nEach entry point (i.e. `ENTRY`) in [`package.json`'s\n`exports[ENTRY]`][x-repo-package-json] object includes one or more [export\nconditions][x-pkg-exports-conditions]. These entries may or may not include: an\n[`exports[ENTRY].types`][x-pkg-exports-types-key] condition pointing to a type\ndeclaration file for TypeScript and IDEs, a\n[`exports[ENTRY].module`][x-pkg-exports-module-key] condition pointing to\n(usually ESM) source for Webpack/Rollup, a `exports[ENTRY].node` and/or\n`exports[ENTRY].default` condition pointing to (usually CJS2) source for Node.js\n`require`/`import` and for browsers and other environments, and [other\nconditions][x-pkg-exports-conditions] not enumerated here. Check the\n[package.json][x-repo-package-json] file to see which export conditions are\nsupported.\n\nNote that, regardless of the [`{ \"type\": \"...\" }`][x-pkg-type] specified in\n[`package.json`][x-repo-package-json], any JavaScript files written in ESM\nsyntax (including distributables) will always have the `.mjs` extension. Note\nalso that [`package.json`][x-repo-package-json] may include the\n[`sideEffects`][x-pkg-side-effects-key] key, which is almost always `false` for\noptimal [tree shaking][x-pkg-tree-shaking] where appropriate.\n\n\n\n\n\n\n\n### License\n\n\n\nSee [LICENSE][x-repo-license].\n\n\n\n\n## Contributing and Support\n\n**[New issues][x-repo-choose-new-issue] and [pull requests][x-repo-pr-compare]\nare always welcome and greatly appreciated! 🤩** Just as well, you can [star 🌟\nthis project][x-badge-repo-link] to let me know you found it useful! ✊🏿 Or [buy\nme a beer][x-repo-sponsor], I'd appreciate it. Thank you!\n\nSee [CONTRIBUTING.md][x-repo-contributing] and [SUPPORT.md][x-repo-support] for\nmore information.\n\n\n\n\n\n### Contributors\n\n\n\n\n\n\n[](#contributors-)\n\n\n\n\nThanks goes to these wonderful people ([emoji\nkey][x-repo-all-contributors-emojis]):\n\n\n\n\n\n\n
![](\"https://raw.githubusercontent.com/Xunnamius/error-utils/refs/heads/main/logo.png\"){kind=logo}
\n![\"Bernard\"/](\"https://avatars.githubusercontent.com/u/656017?v=4?s=100\")
![](\"https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg\"){kind=logo}
\n Add your contributions\n \n