modern-errors plugin to execute class-specific logic.

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

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(conditions, ...effects)

conditions: Condition | Condition[]
effect: Effect
Return value: Switch

If error matches the conditions, 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 conditions can be:

• An error class, matched with instanceof
• An error name string
• An object containing of subset of error properties
• A filtering function taking the error as argument and returning a boolean
• A boolean
• An array of the above types, checking if any condition in the array matches

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)

Check error properties

BaseError.switch(error)
  // If `error.isDatabase` is `true`, append the following message
  .case({ isDatabase: true }, 'Bug at the database layer.')
  .default()

Boolean condition

// Performs the condition in global scope
const IS_PRODUCTION = process.env.NODE_ENV === 'production'

BaseError.switch(error)
  .case(IS_PRODUCTION, 'Bug at the database layer.')
  .default()

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

Alternative conditions

BaseError.switch(error)
  // If `error` is either a `DatabaseError` or has `isDatabase: true`,
  // append the following message
  .case([DatabaseError, { isDatabase: true }], '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

• switch-functional: Functional switch statement
• 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-beautiful: Prettify errors messages and stacks
• 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!