error-class-utils

Properly create error classes.

Useful utilities when creating custom error classes.

Features

• Ponyfill error.cause on older Node.js and browsers
• Properly set error.name
• Fix issues when Error has been polyfilled

Example

import {
  ensureCorrectClass,
  ponyfillCause,
  setErrorName,
} from 'error-class-utils'

export class CustomError extends Error {
  constructor(message, parameters) {
    super(message, parameters)

    // Fix some issues when `Error` has been polyfilled
    ensureCorrectClass(this, new.target)

    // Ponyfill `error.cause` on old Node.js/browsers
    ponyfillCause(this, parameters)
  }
}

// Properly set `error.name` as a non-enumerable and inherited property
setErrorName(CustomError, 'CustomError')

import { CustomError } from './errors.js'

const cause = new Error('innerMessage')
const error = new CustomError('message', { cause })
console.log(error instanceof CustomError) // true
console.log(error.name) // 'CustomError'
console.log(error.cause) // Error: innerMessage ...

Install

npm install error-class-utils

This package works in both Node.js >=14.18.0 and browsers. It is an ES module and must be loaded using an import or import() statement, not require().

API

ensureCorrectClass(error, new.target)

error Error
new.target typeof Error
Return value: void

Some Error polyfills (such as es-shims/error-cause) prevent extending from it. This fixes it.

The second argument must be new.target. This must be called directly inside a class constructor, after super(message, parameters).

import { ensureCorrectClass } from 'error-class-utils'

class CustomError extends Error {
  constructor(message, parameters) {
    super(message, parameters)
    ensureCorrectClass(this, new.target)
  }
}

// Thanks to `ensureCorrectClass()`, this is now always true even when
// `Error` has been polyfilled
console.log(new CustomError('message') instanceof CustomError) // true

ponyfillCause(error, parameters?)

error Error
parameters ErrorParams?
Return value: void

Ponyfills error.cause on older Node.js and browsers.

This must be called inside a class constructor, after super(message, parameters).

import { ponyfillCause } from 'error-class-utils'

class CustomError extends Error {
  constructor(message, parameters) {
    super(message, parameters)
    ponyfillCause(this, parameters)
  }
}

try {
  throw new Error('innerMessage')
} catch (cause) {
  // Works on any platforms thanks to ponyfill
  const error = new CustomError('message', { cause })
  console.log(error.cause.message) // 'innerMessage'
}

setErrorName(ErrorClass, name)

ErrorClass typeof Error
name string
Return value: void

Set an ErrorClass's name.

This must be performed on an error class, not instance. Unlike setting this.name = '...' inside an error's constructor, this follows the native Error classes' pattern where error.name:

• Ends with the Error suffix
• Matches the constructor's name
• Is inherited
• Is non-enumerable

import { setErrorName } from 'error-class-utils'

class CustomError extends Error {}
setErrorName(CustomError, 'CustomError')

console.log(CustomError.name) // 'CustomError'
console.log(CustomError.prototype.name) // 'CustomError'

const error = new CustomError('message')
console.log(error.name) // 'CustomError'
console.log(Object.keys(error).includes('name')) // false

Related projects

• modern-errors: Handle errors in a simple, stable, consistent way
• error-custom-class: Create one error class
• error-serializer: Convert errors to/from plain objects
• normalize-exception: Normalize exceptions/errors
• is-error-instance: Check if a value is an Error instance
• 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
• wrap-error-message: Properly wrap an error's message
• set-error-props: Properly update an error's properties
• set-error-stack: Properly update an error's stack
• error-cause-polyfill: Polyfill error.cause
• handle-cli-error: 💣 Error handler for CLI applications 💥
• log-process-errors: Show some ❤ to Node.js process errors
• error-http-response: Create HTTP error responses
• winston-error-format: Log errors with Winston

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!