Package Exports

handle-cli-error

Readme

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

modern-errors: Handle errors like it's 2022 🔮
error-custom-class: Create one error class
error-class-utils: Utilities to properly create error classes
error-serializer: Convert errors to/from plain objects
normalize-exception: Normalize exceptions/errors
merge-error-cause: Merge an error with its cause
set-error-class: Properly update an error's class
set-error-message: Properly update an error's message
set-error-props: Properly update an error's properties
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!

handle-cli-error