@-xun/error

This tiny library provides so-called "named errors," which are normal Error classes (compatible with all JS runtimes) with some slight tweaks to improve overall handling safety, improve DX for the developers that work with these classes, and improve UX for the users that might encounter them.

More specifically, this library returns a factory function (makeNamedError) capable of creating custom Error subclasses with powerful cross-package cross-realm instanceof checks and human-readable names that both survive transpilation/minification and show up in stack traces.

• Features
• Install
• Usage
• Appendix
  • Published Package Details
  • License
• Contributing and Support
  • Contributors

Features

Works via a simple wrapper function using normal ES6 class syntax

makeNamedError(
  // Anonymous classes will be transformed into a named class by makeNamedError
  class extends Error {
    // ...
  },
  'MyCustomError'
);

makeNamedError(
  // However, for improved DX in TypeScript, give your class definitions names
  class MyCustomSubclassError extends MyCustomError {
    // ...
  },
  'MyCustomSubclassError'
);

Makes error name available via prototypical instance and as a static class property

const { MyCustomError } = makeNamedError(/* ... */, 'MyCustomError');

console.log(MyCustomError.name) // MyCustomError
console.log((new MyCustomError()).name) // MyCustomError

Ensures error class names in error messages and other outputs survive minification

const { MyCoolError } = makeNamedError(/* ... */, 'MyCoolError');

console.log(MyCoolError.name) // MyCoolError (every time!)

Provides built-in type guards that are safer and more powerful than instanceof

const { BigError, isBigError } = makeNamedError(/* ... */, 'BigError');

console.log(isBigError(new BigError())) // true
console.log(isBigError(new SomeOtherError())) // false
console.log(isBigError(new Error())) // false

Each class's .isX() function is additionally provided as a static class property:

const { BigError } = makeNamedError(/* ... */, 'BigError');

console.log(BigError.isError(new BigError())); // true
console.log(BigError.isError(new SomeOtherError())); // false
console.log(BigError.isError(new Error())); // false

All instanceof checks still work as expected (but can be avoided):

const { BigError } = makeNamedError(/* ... */, 'BigError');
const { BiggestError } = makeNamedError(/* ... */, 'BiggestError');

console.log(new BigError() instanceof BigError); // true
console.log(new BigError() instanceof Error); // true
console.log(new BiggestError() instanceof BiggestError); // true
console.log(new BiggestError() instanceof Error); // true

console.log(new Error() instanceof BigError); // false

Unlike instanceof, the .isX()/.isError() function is both cross-realm safe and safe to use in situations where multiple distinct copies of your error classes might exist in the dependency tree (e.g. dual package hazard).

In case of the latter, where two different libraries might import two different versions of your error classes (a surprisingly common occurrence!), this package takes away the pain:

import lib1 from 'some-lib-exports-your-error';
import lib2 from 'unrelated-lib-also-exports-same-error-but-not-strictly-equal';

console.log(new lib1.YourError() instanceof lib2.YourError); // false
console.log(lib2.YourError.isError(new lib1.YourError())); // true

Supports inheritance (both ES6 "extends" and pre-ES6 prototypical)

const { AppError } = makeNamedError(
  class AppError extends Error {
    panic() {
      console.log('oh no!');
      process.exit(123);
    }
  },
  'AppError'
);

const { ValidationError } = makeNamedError(
  // Note how ValidationError extends AppError
  class ValidationError extends AppError {
    #validationErrors: string[];

    constructor(issues: string[]) {
      super();
      this.#validationErrors = issues;
    }

    getValidationErrors() {
      return this.#validationErrors;
    }
  },
  'ValidationError'
);

const error = new ValidationError(['validation error 1', 'validation error 2']);

if (ValidationError.isError(error)) {
  console.log('validation errors:', error.getValidationErrors().join(', '));
  // validation errors: validation error 1, validation error 2
}

// Other logic...

if (AppError.isError(error)) {
  error.panic(); // This will run thanks to polymorphism and inheritance rules
}

// The program will die before reaching this point thanks to error.panic()

Comes with kickass TypeScript types out of the box

import {
  makeNamedError,
  isANamedErrorClass,
  isANamedErrorInstance
} from '@-xun/error';

const { SmallError, isSmallError } = makeNamedError(
  /* ... */, // All class methods and properties are preserved as expected
  'SmallError'
);

console.log(isANamedErrorClass(Error)); // false
console.log(isANamedErrorInstance(new Error())); // false
console.log(SmallError.isError(new Error())); // false
console.log(isSmallError(new Error())); // false

// All isX type guard functions will narrow unknown types properly!

console.log(isANamedErrorClass(SmallError)); // true
console.log(isANamedErrorInstance(new SmallError())); // true
console.log(SmallError.isError(new SmallError())); // true
console.log(isSmallError(new SmallError())); // true

Install

To install:

npm install @-xun/error

Usage

Start using @-xun/error in four quick and easy steps.

1. Import:

import { makeNamedError } from '@-xun/error';

2. Optionally create a "root" error class from which the rest of your custom Error subclasses will descend:

export const { AppError } = makeNamedError(
  class AppError extends Error {},
  'AppError'
);

3. Create and export the rest of your custom Error subclasses as you normally would:

export const { ValidationError } = makeNamedError(
  class ValidationError extends AppError {},
  'ValidationError'
);

export const { AuthError } = makeNamedError(
  class AuthError extends AppError {},
  'AuthError'
);

export const { NotFoundError } = makeNamedError(
  class NotFoundError extends AppError {},
  'NotFoundError'
);

// Improve TypeScript DX by exporting the literal class types too, if you want:

/**
 * Helpful comment for users of your Error subclass goes here.
 */
export type ValidationError = InstanceType<typeof ValidationError>;

/**
 * Helpful comment for users of your Error subclass goes here.
 */
export type AuthError = InstanceType<typeof AuthError>;

/**
 * Helpful comment for users of your Error subclass goes here.
 */
export type NotFoundError = InstanceType<typeof NotFoundError>;

4. Use your custom errors like any other Error subclass (because they are):

import { ValidationError } from './shared/errors.ts';

// ...

if (somethingBadHappened) {
  throw new ValidationError();
}

// ...

Neat! 📸

Appendix

Further documentation can be found under docs/.

Published Package Details

This is a CJS2 package with statically-analyzable exports built by Babel for use in Node.js versions that are not end-of-life. For TypeScript users, this package supports both "Node10" and "Node16" module resolution strategies.

That means both CJS2 (via require(...)) and ESM (via import { ... } from ... or await import(...)) source will load this package from the same entry points when using Node. This has several benefits, the foremost being: less code shipped/smaller package size, avoiding dual package hazard entirely, distributables are not packed/bundled/uglified, a drastically less complex build process, and CJS consumers aren't shafted.

Each entry point (i.e. ENTRY) in package.json's exports[ENTRY] object includes one or more export conditions. These entries may or may not include: an exports[ENTRY].types condition pointing to a type declaration file for TypeScript and IDEs, a exports[ENTRY].module condition pointing to (usually ESM) source for Webpack/Rollup, a exports[ENTRY].node and/or exports[ENTRY].default condition pointing to (usually CJS2) source for Node.js require/import and for browsers and other environments, and other conditions not enumerated here. Check the package.json file to see which export conditions are supported.

Note that, regardless of the { "type": "..." } specified in package.json, any JavaScript files written in ESM syntax (including distributables) will always have the .mjs extension. Note also that package.json may include the sideEffects key, which is almost always false for optimal tree shaking where appropriate.

License

See LICENSE.

Contributing and Support

New issues and pull requests are always welcome and greatly appreciated! 🤩 Just as well, you can star 🌟 this project to let me know you found it useful! ✊🏿 Or buy me a beer, I'd appreciate it. Thank you!

See CONTRIBUTING.md and SUPPORT.md for more information.

Contributors

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!