README
ShutdownCleanup">
Module to handle applications' graceful shutdowns.
This super simple module helps shutting down servers, database handles, etc. in NodeJS applications. It allows to register handlers for certain shutdown signals/events in order to attempt a graceful shutdown (clean-ups etc.)
NOTE: it removes any previous registered listeners for the given signals!
By default it listens to:
SIGTERM
SIGHUP
SIGINT
It also listens to process.exit
but keep in mind that exit
does
not allow asynchrounous listeners' operations to complete (see process.exit on NodeJS.org)
It is also possible to add (or remove) other shutdown signals/events.
Table of Contents
- Node compatibility
- Install
- Usage
- TypeScript
- Uncaught Exceptions & other similar events
- Exit codes
- Changelog
- Contributing
- License
Node compatibility
Tested in nodejs version:
- 12
- 14
- 16 (see Exit codes)
- 17
Version 4.0.0
drops compatibility with node <= 10.
Install
npm i -S @hypercliq/shutdown-cleanup
Usage
Register a handler
import { ShutdownCleanup } from 'shutdown-cleanup'
// const ShutdownCleanup = require('shutdown-cleanup').ShutdownCleanup
ShutdownCleanup.registerHandler(() => console.log('This is printed on exit :)'))
Add a signal or event to listen to
ShutdownCleanup.addSignal('uncaughtException')
Remove a signal or an event
ShutdownCleanup.removeSignal('SIGHUP')
List signals and events listened to
ShutdownCleanup.listSignals()
TypeScript
TypeScript types are included.
Uncaught Exceptions & other similar events
It is possible to listen to the uncaughtException
event, but no error message will be displayed if the handle function does not explicitly ask for it or we don't enable debug
(this is also true for other events such as unhandledRejection
.)
Handle parameter
ShutdownCleanup.registerHandler((codeOrError) =>
console.log('This what we got back:', codeOrError)
)
By accepting a parameter (in this case codeOrError
) we can get back from the module either a code/signal or an error.
Debug
Another way to see what's going on is to turn debug
on:
DEBUG=shutdown-cleanup npm start
or Windows
set DEBUG=shutdown-cleanup & npm start
shutdown-cleanup does not depend on debug while being fully compatible with it. This means that it works with or without debug
as a dependency.
# compatible with debug
DEBUG=* npm start
Exit codes
In previous versions, shutdown-cleanup
returned an exit code of 1
whenever an exit code (error number) was undefined
or was 0
. This behaviour has changed from v3.1.13
.
Now, shutdown-cleanup
relays the code number associated with the signal that caused node
to terminate.
In some cases (when signal is an Error
), the code number (errno
) might be undefined
. In those cases, shutdown-cleanup
sets the exit code to 1.
For node versions *less than v15*, shutdown-cleanup
reports unhandledRejection
exit code as 0
. This is in line with what node is actually returning. In fact, unhandledRejection
produces this deprecation warning:
DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.
Changelog
see CHANGELOG
Contributing
PRs welcome!
License
Shutdown-Cleanup is licensed under the MIT. See LICENSE for more details.