@eliware/signals 
Graceful shutdown signal handler utility for Node.js
Table of Contents
- Features
- Requirements
- Setup
- Usage
- Development
- Testing
- Troubleshooting
- Security
- API
- Packaging
- Examples
- Support
- Links
- License
Features
The package starts cleanup for SIGTERM, SIGINT, and SIGHUP.
Run ordered cleanup functions during shutdown.
Set the exit code or prevent process exit.
Requirements
Use Node.js 26 or later. Use native ESM.
Setup
Run this command in your project:
npm install @eliware/signals
Usage
Import registerSignals from @eliware/signals.
Pass a cleanup function as shutdownHook.
Set exit: false when your application controls process exit.
Call shutdown() to run cleanup and wait for all cleanup functions to complete.
Call removeHandlers() when you no longer require the registration.
import registerSignals from "@eliware/signals";
registerSignals({
shutdownHook: async () => {
process.stdout.write("Cleanup complete\n");
},
});
This example requires Node.js 26 or later and native ESM.
Run it in a project that has this package installed.
Send SIGTERM, SIGINT, or SIGHUP to run the cleanup function.
The process exits with code 0 after the cleanup function completes.
Read the release notes for user-visible changes. Read the user guides for full usage details.
Development
Run npm ci to install the locked development dependencies.
Read AGENTS.md for repository validation commands and the specification index for repository requirements.
Testing
Run npm test to validate the package.
Troubleshooting
Set exit: false when your application controls process exit.
Call and await shutdown() when your application must wait for cleanup.
Read the troubleshooting guide for more help.
Security
Keep secrets and sensitive shutdown data out of logs.
Do not rely on asynchronous cleanup during Node.js exit events.
API
Call registerSignals(options?) to receive a registration object.
Options include processObj, log, signals, shutdownHook, exitCode, exit, and signal.
Each cleanup function runs in registration order.
If a cleanup function fails, the package logs a fixed notice without error details and continues.
Read the API reference and type declarations for details.
Packaging
Use numeric MAJOR.MINOR.PATCH versions and matching v<version> release tags.
The npm workflow validates the matching tag and package version before publication.
Run npm run pack to check package contents. Publish only after approved release steps.
Examples
Read the example index and run node examples/example.mjs.
Support
For help, questions, or to chat with the author and community, visit:
