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

Examples

Custom error classes

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
}

Error properties

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

Error cause

// `error.cause` can be used even in older Node.js or browsers
try {
  doSomething()
} catch (cause) {
  throw new UserError('message', { cause })
}

Parent class

const ParentError = errorCustomClass('ParentError')
const ChildError = errorCustomClass('ChildError', onCreate, ParentError)
const childError = new ChildError('message')
console.log(childError instanceof ChildError) // true
console.log(childError instanceof ParentError) // true

Custom initialization logic

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

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, onCreate?, ParentClass?)

errorName string
onCreate (error, params) => void
ParentClass typeof Error
Return value: CustomError

Custom initialization logic

onCreate(error, params) is optional and is called on new CustomError('message', params).

By default, it sets any params.props as error properties. However, you can override it with any custom logic to validate, normalize params, etc.

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!