Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ehmicky/error-class-utils

Properly create error classes.
https://github.com/ehmicky/error-class-utils

browser cause code-quality create custom error error-classes error-handler error-handling error-monitoring error-reporting errors javascript library message monitoring nodejs properties stacktrace typescript

Last synced: 3 months ago
JSON representation

Properly create error classes.

Awesome Lists containing this project

README 

        
[![Node](https://img.shields.io/badge/-Node.js-808080?logo=node.js&colorA=404040&logoColor=66cc33)](https://www.npmjs.com/package/error-class-utils)

[![Browsers](https://img.shields.io/badge/-Browsers-808080?logo=firefox&colorA=404040)](https://unpkg.com/error-class-utils?module)

[![TypeScript](https://img.shields.io/badge/-Typed-808080?logo=typescript&colorA=404040&logoColor=0096ff)](/src/main.d.ts)

[![Codecov](https://img.shields.io/badge/-Tested%20100%25-808080?logo=codecov&colorA=404040)](https://codecov.io/gh/ehmicky/error-class-utils)

[![Minified size](https://img.shields.io/bundlephobia/minzip/error-class-utils?label&colorA=404040&colorB=808080&logo=webpack)](https://bundlephobia.com/package/error-class-utils)

[![Mastodon](https://img.shields.io/badge/-Mastodon-808080.svg?logo=mastodon&colorA=404040&logoColor=9590F9)](https://fosstodon.org/@ehmicky)

[![Medium](https://img.shields.io/badge/-Medium-808080.svg?logo=medium&colorA=404040)](https://medium.com/@ehmicky)



Properly create error classes.



Useful utilities when creating custom error classes.



# Hire me



Please

[reach out](https://www.linkedin.com/feed/update/urn:li:activity:7117265228068716545/)

if you're looking for a Node.js API or CLI engineer (11 years of experience).

Most recently I have been [Netlify Build](https://github.com/netlify/build)'s

and [Netlify Plugins](https://www.netlify.com/products/build/plugins/)'

technical lead for 2.5 years. I am available for full-time remote positions.



# Features



- Ponyfill

  [`error.cause`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)

  on

  [older Node.js and browsers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause#browser_compatibility)

- Properly [set `error.name`](#seterrornameerrorclass-name)

- Fix [issues](#ensurecorrectclasserror-newtarget) when `Error` has been

  polyfilled



# Example



```js

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')

```



```js

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



```bash

npm install error-class-utils

```



This package works in both Node.js >=18.18.0 and

[browsers](https://raw.githubusercontent.com/ehmicky/dev-tasks/main/src/browserslist).



This is an ES module. It must be loaded using

[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),

not `require()`. If TypeScript is used, it must be configured to

[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),

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`](https://github.com/es-shims/error-cause)) prevent

extending from it. This fixes it.



The second argument must be

[`new.target`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/new.target).

This must be called directly inside a class constructor, after

[`super(message, parameters)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/super).



```js

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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause)

on

[older Node.js and browsers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause#browser_compatibility).



This must be called inside a class constructor, after

[`super(message, parameters)`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/super).



```js

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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/name)

- Is

  [inherited](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties)

- Is

  [non-enumerable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Enumerability_and_ownership_of_properties)



```js

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`](https://github.com/ehmicky/modern-errors): Handle errors in

  a simple, stable, consistent way

- [`error-custom-class`](https://github.com/ehmicky/error-custom-class): Create

  one error class

- [`error-serializer`](https://github.com/ehmicky/error-serializer): Convert

  errors to/from plain objects

- [`normalize-exception`](https://github.com/ehmicky/normalize-exception):

  Normalize exceptions/errors

- [`is-error-instance`](https://github.com/ehmicky/is-error-instance): Check if

  a value is an `Error` instance

- [`merge-error-cause`](https://github.com/ehmicky/merge-error-cause): Merge an

  error with its `cause`

- [`set-error-class`](https://github.com/ehmicky/set-error-class): Properly

  update an error's class

- [`set-error-message`](https://github.com/ehmicky/set-error-message): Properly

  update an error's message

- [`wrap-error-message`](https://github.com/ehmicky/wrap-error-message):

  Properly wrap an error's message

- [`set-error-props`](https://github.com/ehmicky/set-error-props): Properly

  update an error's properties

- [`set-error-stack`](https://github.com/ehmicky/set-error-stack): Properly

  update an error's stack

- [`error-cause-polyfill`](https://github.com/ehmicky/error-cause-polyfill):

  Polyfill `error.cause`

- [`handle-cli-error`](https://github.com/ehmicky/handle-cli-error): 💣 Error

  handler for CLI applications 💥

- [`log-process-errors`](https://github.com/ehmicky/log-process-errors): Show

  some ❤ to Node.js process errors

- [`error-http-response`](https://github.com/ehmicky/error-http-response):

  Create HTTP error responses

- [`winston-error-format`](https://github.com/ehmicky/winston-error-format): Log

  errors with Winston



# Support



For any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).



Everyone is welcome regardless of personal background. We enforce a

[Code of conduct](CODE_OF_CONDUCT.md) 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](CONTRIBUTING.md). Pull requests are welcome!