error-custom-class

Create custom error classes.

Features

• Simple API: errorCustomClass('errorName')
• Follows best practices
• Error properties can be set on initialization: new CustomError('message', { props: { example: true } })
• Polyfills error.cause on older Node.js and browsers
• Optional parent class or custom initialization logic

Example

import errorCustomClass from 'error-custom-class'

const UserError = errorCustomClass('UserError')
const DatabaseError = errorCustomClass('DatabaseError')

try {
  throw new UserError('message')
} catch (error) {
  console.log(error.name) // 'UserError'
  console.log(error instanceof UserError) // true
}

Install

npm install error-custom-class

This package is an ES module and must be loaded using an import or import() statement, not require().

API

errorCustomClass(errorName, options?)

errorName string
options Options?
Return value: CustomError

Creates a custom error class.

Options

Options are an optional object with the following members.

onCreate

Type: (error, params) => void

Called on new CustomError('message', params).

const DatabaseError = errorCustomClass('DatabaseError', {
  onCreate(error, { props }) {
    error.dbId = props.databaseId
  },
})
const databaseError = new DatabaseError('message', { props: { databaseId: 2 } })
console.log(databaseError.dbId) // 2
console.log(databaseError.databaseId) // undefined

Error properties

By default, onCreate() sets any params.props as error properties.

const userError = new UserError('message', { props: { userId: 56 } })
console.log(userError.userId) // 56

ParentClass

Type: typeof Error
Default: Error

Parent error class.

const ParentError = errorCustomClass('ParentError')
const ChildError = errorCustomClass('ChildError', { ParentClass: ParentError })
const childError = new ChildError('message')
console.log(childError instanceof ChildError) // true
console.log(childError instanceof ParentError) // true

Best practices

Constructor

A common pattern for custom error classes is:

class CustomError extends Error {
  constructor(message) {
    super(message)
    this.name = 'CustomError'
  }
}

However, this has several issues (which error-custom-class handles):

• error.cause is not set
• Unlike native error classes, error.name is:
  • Enumerable, although it should not. For example, for (const key in error) will iterate over name, which is unexpected.
  • Set on the error instance instead of its prototype. In Node.js, this sometimes results in the error name being printed as Error [CustomError] instead of CustomError.

Polyfills

Some Error polyfills (such as es-shims/error-cause) prevent extending from it. This library includes some logic to fix this.

Related projects

• modern-errors: Handle errors like it's 2022 🔮
• error-custom-classes: Create multiple error classes
• error-serializer: Convert errors to/from plain objects
• normalize-exception: Normalize exceptions/errors
• merge-error-cause: Merge an error with its cause
• set-error-class: Properly update an error's class
• set-error-message: Properly update an error's message
• set-error-props: Properly update an error's properties
• error-cause-polyfill: Polyfill error.cause
• handle-cli-error: 💣 Error handler for CLI applications 💥
• log-process-errors: Show some ❤ to Node.js process errors

Support

For any question, don't hesitate to submit an issue on GitHub.

Everyone is welcome regardless of personal background. We enforce a Code of conduct in order to promote a positive and inclusive environment.

Contributing

This project was made with ❤️. The simplest way to give back is by starring and sharing it online.

If the documentation is unclear or has a typo, please click on the page's Edit button (pencil icon) and suggest a correction.

If you would like to help us fix a bug or add a new feature, please check our guidelines. Pull requests are welcome!