Package Exports

handle-cli-error

Readme

💥 Error handler for CLI applications.

Features

Error type-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 type-specific

handleCliError(error, {
  InputError: { exitCode: 1, short: true },
  DatabaseError: { exitCode: 2, short: true },
  InternalError: { 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

types

Type: object
Default: {}

Specify different options per error type. 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-type: Create custom error types
normalize-exception: Normalize exceptions/errors
merge-error-cause: Merge an error with its cause
error-cause-polyfill: Polyfill error.cause

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