modern-errors-process

modern-errors plugin to handle process errors.

This improves process errors: uncaught exceptions, unhandled promises, promises handled too late and warnings.

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.

Features

• Stack traces for warnings and rejectionHandled
• Single event handler for all process errors
• Set any process error's class to UnknownError
• Ignore duplicate process errors
• Normalize invalid errors
• Process exit is graceful and can be prevented

Example

Adding the plugin to modern-errors.

import ModernError from 'modern-errors'

import modernErrorsProcess from 'modern-errors-process'

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

Initializing the process error handler.

UnknownError.logProcess()

Install

Production code (e.g. a server) can install this either as a production or as a development dependency.

npm install modern-errors-process

However, libraries should install this as a development dependency.

npm install -D modern-errors-process

This is because logging is modified globally and libraries users might not expect this side-effect. Also, this might lead to conflicts between libraries.

This package requires Node.js >=18.18.0.

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

modernErrorsProcess

Type: Plugin

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

ErrorClass.logProcess()

Return value: () => void

Start handling process errors.

The return value restores Node.js default behavior.

const restore = UnknownError.logProcess()
restore()

Options

Type: object

exit

Type: boolean

Whether to exit the process on uncaught exceptions or unhandled promises.

This is false by default if other libraries are listening to those events, so they can perform the exit instead. Otherwise, this is true.

If some tasks are still ongoing, the exit waits for them to complete up to 3 seconds.

onError

Type: (error, event) => Promise<void> | void
Default: console.error(error)

Function called once per process error. Duplicate process errors are ignored.

error

Type: UnknownError

The process error. This is guaranteed to be a normalized UnknownError instance. A short description of the event is also appended to its message.

event

Type: Event

Process event name among: 'uncaughtException', 'unhandledRejection', 'rejectionHandled', 'warning'.

Configuration

Options must be passed either to ModernError.subclass().

export const BaseError = ModernError.subclass('BaseError', {
  plugins: [modernErrorsProcess],
  process: options,
})

To UnknownError.subclass().

export const UnknownError = BaseError.subclass('UnknownError', {
  process: options,
})

Or to UnknownError.logProcess().

UnknownError.logProcess(options)

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-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
• modern-errors-switch: Execute class-specific logic

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!