Registry / devops / cli-handle-unhandled

cli-handle-unhandled

JSON →
library1.1.2jsnpmunverified

cli-handle-unhandled is a specialized Node.js utility package designed for command-line interfaces (CLIs) to ensure graceful, yet explicit, termination upon encountering unhandled promise rejections. Currently stable at version 1.1.2, the package has a mature and focused scope, with infrequent but consistent maintenance releases since its initial launch. Its key differentiator lies in its opinionated approach: rather than merely logging an unhandled rejection and allowing the process to continue in an indeterminate state, it registers a handler that explicitly crashes the Node.js process, providing immediate feedback essential for robust CLI tooling. This prevents silent failures that can occur when asynchronous operations reject without a `.catch()` block, making errors transparent to the user or calling environment. It is primarily a CommonJS module, targeting Node.js environments.

devops
npm install cli-handle-unhandled
github ↗package ↗
INSTALL
IMPORT
SIG · CLI-HANDLE-UNHANDL
C
cli-handle-unhandled
devopsjavascriptv1.1.2
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

unhandledError
✓ const unhandledError = require('cli-handle-unhandled');
✗ import unhandledError from 'cli-handle-unhandled';
This package is a CommonJS module. Direct ES Module imports are not supported without a CommonJS wrapper or bundler.
cliHandleUnhandled
✓ const cliHandleUnhandled = require('cli-handle-unhandled'); cliHandleUnhandled();
✗ import { cliHandleUnhandled } from 'cli-handle-unhandled';
The package exports a function directly. It's typically invoked immediately to register the handler. Named imports are not applicable for its default (and only) export.

Demonstrates how to initialize cli-handle-unhandled and triggers an unhandled promise rejection to show its intended behavior of crashing the process.

const cliHandleUnhandled = require('cli-handle-unhandled'); // Initialize the unhandled rejection handler cliHandleUnhandled(); console.log('Application started. An unhandled promise rejection will occur in 1 second.'); async function simulateUnhandledRejection() { return new Promise((resolve, reject) => { setTimeout(() => { console.log('Simulating an unhandled rejection...'); reject(new Error('This is an intentional unhandled rejection!')); // This will trigger cli-handle-unhandled }, 1000); }); } // Call an async function without a .catch() to trigger an unhandled rejection simulateUnhandledRejection(); // Keep the process alive briefly to allow the promise to reject setTimeout(() => { console.log('This message should not appear if cli-handle-unhandled works.'); }, 2000);
Debug
Known issues
gotchaThe primary function of `cli-handle-unhandled` is to cause the Node.js process to exit (crash) gracefully when an unhandled promise rejection occurs. It does not 'prevent' crashes but rather ensures that unhandled rejections lead to an explicit, observable failure state, which is often desired in CLI tools to avoid silent errors.
fix
Understand that this package is meant to terminate the process on unhandled rejections. If you want to *prevent* crashes and handle rejections gracefully without exiting, use `process.on('unhandledRejection', (reason, promise) => { /* custom logging & recovery */ });` without `cli-handle-unhandled`.
affects: >=1.0.0
gotchaAs a CommonJS module, `cli-handle-unhandled` must be imported using `require()`. Attempting to use ES Module `import` syntax in a pure ESM project without proper transpilation or wrapper might result in `ERR_REQUIRE_ESM`.
fix
Ensure your project or file uses CommonJS `require()` to import this package, or configure your build system to handle CJS imports within an ESM context. For Node.js versions 12+, consider dynamic `import()` for CJS modules if absolutely necessary: `const cliHandleUnhandled = await import('cli-handle-unhandled'); cliHandleUnhandled.default();` (assuming a default export when dynamically imported).
affects: >=1.0.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module
Attempting to `require()` an ES Module or using `import` for this CommonJS package in a project configured for ESM.
fix
Use `const cliHandleUnhandled = require('cli-handle-unhandled');` in CommonJS files, or configure your build system to properly handle CommonJS modules within an ES Module environment.
(node:XXXX) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch().
This is typically the warning that `cli-handle-unhandled` is designed to intercept. If you see this warning without a subsequent process exit, it means the handler might not be properly installed or another global unhandled rejection handler is overriding it.
fix
Ensure `cliHandleUnhandled()` is called early in your application's lifecycle. Check for other global `process.on('unhandledRejection', ...)` handlers that might be installed after `cli-handle-unhandled` and are preventing the intended crash.
Upgrade
Version history
1.1.2latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
4
Resources
githubhttps://github.com/ahmadawais/cli-handle-unhandled ↗
packagehttps://www.npmjs.com/package/cli-handle-unhandled ↗
cli-handle-unhandled — npm install cli-handle-unhandled · libregistry