Naboo's Podracing Misadventure

    error-class-utils
    TypeScript icon, indicating that this package has built-in type declarations

    2.4.0 • Public • Published

    Node Browsers TypeScript Codecov Minified size Twitter Medium

    Properly create error classes.

    Useful utilities when creating custom error classes.

    Features

    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:

    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

    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!

    Install

    npm i error-class-utils

    DownloadsWeekly Downloads

    1,007

    Version

    2.4.0

    License

    MIT

    Unpacked Size

    17.6 kB

    Total Files

    11

    Last publish

    Collaborators

    • ehmicky