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, {
types: {
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 error
s 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 tasksNumber.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 noerror.name
matches) - Values are options objects
Related projects
modern-errors
: Handle errors like it's 2022🔮 error-type
: Create custom error typesnormalize-exception
: Normalize exceptions/errorsmerge-error-cause
: Merge an error with itscause
error-cause-polyfill
: Polyfillerror.cause
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
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!