CLI Unhandled Rejection Handler

1.1.2 · active · verified Wed Apr 22

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.

Common errors

```
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module
```
cause 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().
```
cause 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.

Warnings

gotcha The 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`.
gotcha As 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).

Install

npm install cli-handle-unhandled npm
yarn add cli-handle-unhandled yarn
pnpm add cli-handle-unhandled pnpm

Imports

unhandledError
wrong:
```
import unhandledError from 'cli-handle-unhandled';
```
correct:
```
const unhandledError = require('cli-handle-unhandled');
```
This package is a CommonJS module. Direct ES Module imports are not supported without a CommonJS wrapper or bundler.
cliHandleUnhandled
wrong:
```
import { cliHandleUnhandled } from 'cli-handle-unhandled';
```
correct:
```
const cliHandleUnhandled = require('cli-handle-unhandled');
cliHandleUnhandled();
```
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.

Quickstart

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);

view raw JSON →