Polyfill error.cause.

error.cause
is a recent JavaScript feature to wrap errors.

``js
try {
doSomething()
} catch (cause) {
throw new Error('message', { cause })
}
`

Unfortunately, it is
not supported
in Node <16.9.0, Opera nor Safari <15. This library adds support for it in those
environments.

Differences with other polyfills

Unlike error-cause:

- The package size is small (~50kB vs ~2000kB)
- Error child classes still work
- Error.stackTraceLimit
still works
- error.stack does not include the polyfill's internal code (in Node.js and
Chrome)

Unlike
core-js/Babel,
this does not require adding core-js as a production dependency (~1000kB).

Install

`bash
npm install error-cause-polyfill
`

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

polyfill()

_Return value_: () => void

Modifies the global error classes (Error, TypeError, etc.) so they support
error.cause. If error.cause is already supported, this is a noop.

`js
import 'error-cause-polyfill/auto'

try {
doSomething()
} catch (cause) {
throw new Error('message', { cause })
}
`

Or alternatively:

`js
import { polyfill } from 'error-cause-polyfill'

polyfill()

try {
doSomething()
} catch (cause) {
throw new Error('message', { cause })
}
`

This returns a function to undo everything.

`js
import { polyfill } from 'error-cause-polyfill'

const undoPolyfill = polyfill()
undoPolyfill()
`

getErrors()

_Return value_: object

Returns an object with each error class (Error, TypeError, etc.) but with
error.cause support. If error.cause is already supported, this returns the
global error classes as is.

Unlike polyfill(), this does not modify the global error classes.

`js
import { getErrors } from 'error-cause-polyfill'

const Errors = getErrors()

try {
doSomething()
} catch (cause) {
throw new Errors.Error('message', { cause })
}
`

hasSupport()

_Return value_: boolean

Returns whether the global error classes currently support error.cause.

`js
import { hasSupport, polyfill } from 'error-cause-polyfill'

console.log(hasSupport()) // false
polyfill()
console.log(hasSupport()) // true
`

Related projects

- modern-errors: Handle errors in
a simple, stable, consistent way
- error-custom-class: Create
one error class
- error-class-utils: Utilities
to properly create error classes
- 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
- 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!