modern-errors plugin to execute class-specific logic.

This adds BaseError.switch() to wrap an error according to its class.

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.

Example

Adding the plugin to modern-errors.

import ModernError from 'modern-errors'

import modernErrorsSwitch from 'modern-errors-switch'

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsSwitch],
})
// ...

Wrapping an error's message according to its class.

try {
  // ...
} catch (error) {
  throw BaseError.switch(error)
    .case(InputError, 'The input was invalid.')
    .case(DatabaseError, 'Bug at the database layer.')
    .default('Unknown error.')
}

Install

npm install modern-errors-switch

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

modernErrorsSwitch

Type: Plugin

Plugin object to pass to the plugins option of ErrorClass.subclass().

BaseError.switch(error)

error: unknown
Return value: Switch

Apply logic according to error's class. This must be chained with .case() and end with .default().

Although error should be an Error instance most of the times, it can be of any type. However, the final value returned by .default() is always an instance of BaseError or a subclass of it.

Switch.case(condition, ...effects)

condition: Condition
effect: Effect
Return value: Switch

If error matches the condition, apply the effects. 0, 1 or multiple effects can be applied.

Switch.default(...effects)

effect: Effect
Return value: BaseError

If none of the .case() statements matched, apply those default effects.

Condition

The condition can be:

• An error class, matched with instanceof
• An error name string
• A filtering function taking the error as argument and returning a boolean

Effect

Each effect can be:

• A new error class. It must be a subclass of BaseError. It is ignored if error's class is already a subclass.
• A message string to append or (if it ends with : or :\n) prepend
• An options object to merge
• A mapping function taking the error as argument and returning it

Usage

Wrap error message

BaseError.switch(error)
  // If `InputError`, then appends the following message
  .case(InputError, 'The input was invalid.')
  // If the message ends with `:` or `:\n`, it is prepended instead
  .case(DatabaseError, 'Bug at the database layer:')
  // Empty error messages are ignored
  .default('')

Convert error classes

// Convert `TypeError` class to `InputError`, etc. or default to `UnknownError`
BaseError.switch(error)
  .case(TypeError, InputError)
  .case(URIError, ClientError)
  .default(UnknownError)

Wrap error options

BaseError.switch(error)
  // If `DatabaseError`, add options for other plugins like `modern-errors-bugs`
  .case(DatabaseError, { bugs: 'https://github.com/my-name/my-project/issues' })
  .default()

Map error

BaseError.switch(error)
  // If `DatabaseError`, adds `error.databaseUrl`
  .case(DatabaseError, (error) => {
    error.databaseUrl = databaseUrl
    return error
  })
  .default()

Multiple effects

BaseError.switch(error)
  // 0 effects
  .case(TypeError)
  // Multiple effects
  .case(URIError, ClientError, 'Invalid URI.', {
    bugs: 'https://github.com/my-name/my-project/issues',
  })
  .default(UnknownError)

Custom condition

BaseError.switch(error)
  // If `error.type` is `database`, append the following message
  .case((error) => error.type === 'database', 'Bug at the database layer.')
  .default()

Unknown errors

// Any `error` can be wrapped, even if it is not an `Error` instance
try {
  throw null
} catch (error) {
  // Therefore the filtering and mapping functions' argument might be anything
  throw BaseError.switch(error)
    .case(
      (error) => error instanceof Error && error.type === 'database',
      'Bug at the database layer.',
    )
    .default((error) => {
      if (error instanceof Error) {
        error.type = 'other'
      }

      return error
    })
}

Related projects

• log-process-errors: Show some ❤ to Node.js process errors
• modern-errors: Handle errors in a simple, stable, consistent way
• modern-errors-cli: Handle errors in CLI modules
• modern-errors-process: Handle process errors
• modern-errors-bugs: Print where to report bugs
• modern-errors-serialize: Serialize/parse errors
• modern-errors-clean: Clean stack traces
• modern-errors-http: Create HTTP error responses
• modern-errors-winston: 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!