handle-cli-error

Error handler for CLI applications.

Features

• 💣 Error class-specific handling
• 🚒 Graceful exit
• ⛑️ Normalize invalid errors
• 📕 Log verbosity: full, short or silent
• 🚨 Custom exit code
• 💥 Exception-safe

Example

General

#!/usr/bin/env node
import handleCliError from 'handle-cli-error'

const cliMain = function () {
  try {
    // ...
  } catch (error) {
    handleCliError(error) // Print `error` then exit the process
  }
}

cliMain()

Error class-specific

handleCliError(error, {
  classes: {
    InputError: { exitCode: 1, short: true },
    DatabaseError: { exitCode: 2, short: true },
    default: { exitCode: 3 },
  },
})

Install

npm install handle-cli-error

This package is an ES module and must be loaded using an import or import() statement, not require().

API

handleCliError(error, options?)

error any
options Options?
Return value: undefined

Prints error on the console (stderr) then exits the process.

This never throws. Invalid errors are silently normalized.

Options

🚨 exitCode

Type: integer
Default: 1

Process exit code.

Note: when passing invalid options, the exit code is always 125.

📕 short

Type: boolean
Default: false

When true, only the error message is logged, not its stack trace.

This is useful when the error was caused by the user (as opposed to being an internal bug), in which cause the stack trace is not relevant to the user.

🔕 silent

Type: boolean
Default: false

When true, the error is not logged. The process still exits with a specific exit code.

🚒 timeout

Type: integer (in milliseconds)
Default: 5000 (5 seconds)

The process exits gracefully: it waits for any ongoing tasks (callbacks, promises, etc.) to complete, up to a specific timeout.

Special values:

• 0: Exits right away, without waiting for ongoing tasks
• Number.POSITIVE_INFINITY: Waits for ongoing tasks forever, without timing out

💣 classes

Type: object
Default: {}

Specify different options per error class. The object:

• Keys are either the error.name, or "default" (used if no error.name matches)
• Values are options objects

Related projects

• modern-errors: Handle errors like it's 2022 🔮
• create-error-types: Create multiple error classes
• error-type: Create one error class
• error-serializer: Convert errors to/from plain objects
• normalize-exception: Normalize exceptions/errors
• merge-error-cause: Merge an error with its cause
• error-cause-polyfill: Polyfill error.cause
• log-process-errors: Show some ❤ to Node.js process errors

Credits

The logo background was created by dgim-studio.

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!

Changelog

2.0.0

Breaking changes

• Rename types option to classes