Properly create error classes.
Useful utilities when creating custom error classes.
Hire me
Please reach out if you're looking for a Node.js API or CLI engineer (11 years of experience). Most recently I have been Netlify Build's and Netlify Plugins' technical lead for 2.5 years. I am available for full-time remote positions.
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 >=18.18.0 and browsers.
This is an ES module. It must be loaded using
an import
or import()
statement,
not require()
. If TypeScript is used, it must be configured to
output ES modules,
not CommonJS.
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 anError
instance -
merge-error-cause
: Merge an error with itscause
-
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
: Polyfillerror.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!