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.

``js
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.

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

Install

`bash
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[]](#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

`js
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

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

Wrap error options

`js
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

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

Multiple effects

`js
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

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

Boolean condition

`js
// 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

`js
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

`js
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

`js
// 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!