Minimal ESM-only Node.js process-level handler for uncaught exceptions, unhandled rejections, and warnings.
- Features
- Requirements
- Installation
- Usage
- TypeScript
- Errors / Troubleshooting
- Development
- Security
- Support
- License
- Links
- Handles uncaught exceptions, unhandled rejections, and warnings
- Pluggable logger (defaults to @eliware/log)
- Idempotent registration with safe, repeatable cleanup
- Selectable events, one-shot handlers, and AbortSignal cleanup
- Easy to add/remove handlers for testability
- ESM-only package with TypeScript declarations
- Node.js 26 or newer
npm install @eliware/errorsimport { registerHandlers } from '@eliware/errors';
registerHandlers();
// Or with options:
// registerHandlers({ processObj: process, log: customLogger });
const registration = registerHandlers();
console.log('Handlers registered.');
registration.removeHandlers();Registers process-level exception handlers. Returns an object with a removeHandlers function to detach all handlers (useful for testing).
options(optional):processObj: Process-like event target (default:process)log: Logger witherror,warn, anddebugmethods (default: @eliware/log)events: Supported event names to register (default: all three)once: Use one-shot listeners when supportedsignal: AbortSignal that automatically removes handlers
- Returns:
{ removeHandlers: () => void }; call it to detach all three handlers.
Registration is idempotent per process-like object; repeated calls return the existing registration. Cleanup is safe to call repeatedly and removes the registration from the internal registry. Existing listeners are preserved. For production use, remember that handling uncaughtException can leave the process in an unsafe state; log it and shut down gracefully when appropriate.
Type definitions are included:
export declare function registerHandlers(
options?: {
processObj?: NodeJS.Process;
log?: typeof import('@eliware/log')
}
): { removeHandlers: () => void };
export default registerHandlers;The package only registers handlers; it does not terminate or restart the process. After an uncaught exception, log the failure and shut down gracefully when appropriate. Use a process-like object and custom logger in tests.
npm test
npm run test:gaps
npm run lint
npm run typecheck
npm run packDo not expose sensitive exception or rejection data through custom loggers. Review logger configuration and redact secrets before logging process errors.
For help, questions, or to chat with the author and community, visit:
