Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ehmicky/handle-cli-error
💣 Error handler for CLI applications 💥
https://github.com/ehmicky/handle-cli-error
bash cli console error error-handling error-monitoring errors exit exitcode handler javascript library message monitoring nodejs shell stack terminal timeout typescript
Last synced: 13 days ago
JSON representation
💣 Error handler for CLI applications 💥
- Host: GitHub
- URL: https://github.com/ehmicky/handle-cli-error
- Owner: ehmicky
- License: mit
- Created: 2022-07-23T18:37:56.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-10-24T04:18:37.000Z (16 days ago)
- Last Synced: 2024-10-24T21:42:15.689Z (15 days ago)
- Topics: bash, cli, console, error, error-handling, error-monitoring, errors, exit, exitcode, handler, javascript, library, message, monitoring, nodejs, shell, stack, terminal, timeout, typescript
- Language: JavaScript
- Homepage:
- Size: 7.95 MB
- Stars: 28
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/handle-cli-error)
[](/src/main.d.ts)
[](https://codecov.io/gh/ehmicky/handle-cli-error)
[](https://fosstodon.org/@ehmicky)
[](https://medium.com/@ehmicky)
Error handler for CLI applications.
# Hire me
Please
[reach out](https://www.linkedin.com/feed/update/urn:li:activity:7117265228068716545/)
if you're looking for a Node.js API or CLI engineer (11 years of experience).
Most recently I have been [Netlify Build](https://github.com/netlify/build)'s
and [Netlify Plugins](https://www.netlify.com/products/build/plugins/)'
technical lead for 2.5 years. I am available for full-time remote positions.
# Features
- 🖍️ Pretty [colors](#%EF%B8%8F-colors), [icons](#-icon) and [header](#-header)
- 💣 [Error class-specific](#-classes) handling
- 🚒 [Graceful exit](#-timeout)
- ⛑️ [Normalize](https://github.com/ehmicky/normalize-exception) invalid errors
- 🔕 Log verbosity: [message](#-silent), [stack](#-stack), [properties](#-props)
- 🚨 Custom [exit code](#-exitcode)
- 💥 Exception-safe
# Screenshot
# Example
## General
```js
#!/usr/bin/env node
import handleCliError from 'handle-cli-error'
const cliMain = () => {
try {
// ...
} catch (error) {
handleCliError(error) // Logs `error` then exit the process
}
}
cliMain()
```
## Error class-specific
```js
handleCliError(error, {
classes: {
InputError: { exitCode: 1, stack: false },
DatabaseError: { exitCode: 2, stack: false },
default: { exitCode: 3 },
},
})
```
# Install
```bash
npm install handle-cli-error
```
This package works in Node.js >=18.18.0.
This is an ES module. It must be loaded using
[an `import` or `import()` statement](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c),
not `require()`. If TypeScript is used, it must be configured to
[output ES modules](https://www.typescriptlang.org/docs/handbook/esm-node.html),
not CommonJS.
# API
## handleCliError(error, options?)
`error` `any`\
`options` [`Options?`](#options)\
_Return value_: `undefined`
Logs `error` on the console (`stderr`) then exits the process.
This never throws. Invalid errors are silently
[normalized](https://github.com/ehmicky/normalize-exception).
### Options
#### 🚨 exitCode
_Type_: `integer`\
_Default_: `1`
Process [exit code](https://en.wikipedia.org/wiki/Exit_status).
Note: when passing invalid [`options`](#options), the exit code is always `125`.
#### 📕 stack
_Type_: `boolean`\
_Default_: `true`
Whether to log the error's stack trace.
#### 📢 props
_Type_: `boolean`\
_Default_: `true`
Whether to log the error's additional properties.
#### 🔕 silent
_Type_: `boolean`\
_Default_: `false`
Exits the process without logging anything on the console.
#### 🖍️ colors
_Type_: `boolean`\
_Default_: `true` in terminals, `false` otherwise
Whether to colorize the error's message, stack trace and additional properties.
Quoted strings in the error's message are printed in bold (for `"..."` and
`'...'`) and in italic (for `` `...` ``).
#### ❌ icon
_Type_: `string`\
_Default_: `'cross'`
Icon prepended to the error's name. The available values are listed
[here](https://github.com/sindresorhus/figures/blob/main/readme.md#figures-1).
Can be disabled by passing an empty string.
#### 💄 header
_Type_: `string`\
_Default_: `'red bold'`
Color/style of the error's [icon](#-icon) and name. The available values are
listed [here](https://github.com/ehmicky/chalk-string#available-styles). Several
styles can be specified by using spaces. Can be disabled by passing an empty
string.
#### 🚒 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](#error-class-specific). The object:
- Keys are either the
[`error.name`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/name),
or `"default"` (used if no `error.name` matches)
- Values are [options](#options) objects
# Related projects
- [`modern-errors`](https://github.com/ehmicky/modern-errors): Handle errors in
a simple, stable, consistent way
- [`modern-errors-cli`](https://github.com/ehmicky/modern-errors-cli): Handle
errors in CLI modules
- [`error-custom-class`](https://github.com/ehmicky/error-custom-class): Create
one error class
- [`error-class-utils`](https://github.com/ehmicky/error-class-utils): Utilities
to properly create error classes
- [`error-serializer`](https://github.com/ehmicky/error-serializer): Convert
errors to/from plain objects
- [`normalize-exception`](https://github.com/ehmicky/normalize-exception):
Normalize exceptions/errors
- [`is-error-instance`](https://github.com/ehmicky/is-error-instance): Check if
a value is an `Error` instance
- [`merge-error-cause`](https://github.com/ehmicky/merge-error-cause): Merge an
error with its `cause`
- [`set-error-class`](https://github.com/ehmicky/set-error-class): Properly
update an error's class
- [`set-error-message`](https://github.com/ehmicky/set-error-message): Properly
update an error's message
- [`wrap-error-message`](https://github.com/ehmicky/wrap-error-message):
Properly wrap an error's message
- [`set-error-props`](https://github.com/ehmicky/set-error-props): Properly
update an error's properties
- [`set-error-stack`](https://github.com/ehmicky/set-error-stack): Properly
update an error's stack
- [`error-cause-polyfill`](https://github.com/ehmicky/error-cause-polyfill):
Polyfill `error.cause`
- [`log-process-errors`](https://github.com/ehmicky/log-process-errors): Show
some ❤ to Node.js process errors
- [`error-http-response`](https://github.com/ehmicky/error-http-response):
Create HTTP error responses
- [`winston-error-format`](https://github.com/ehmicky/winston-error-format): Log
errors with Winston
# Credits
The logo background was created by
[dgim-studio](https://www.freepik.com/free-vector/comic-dynamic-elements-set_7997347.htm).
# Support
For any question, _don't hesitate_ to [submit an issue on GitHub](../../issues).
Everyone is welcome regardless of personal background. We enforce a
[Code of conduct](CODE_OF_CONDUCT.md) 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](CONTRIBUTING.md). Pull requests are welcome!