hypercliq/shutdown-cleanup

Module to handle graceful shutdowns

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
  • Register a handler
    • Handler function
  • Add a signal or event to listen to
  • Remove a signal or an event
  • List signals and events listened to
• TypeScript
• Uncaught Exceptions & other similar events
  • Debug
• Exit codes
• Contributing
• License

Node compatibility

Tested in nodejs version:

• 14
• 16 (see Exit codes)
• 18

Version 4.0.0 drops compatibility with node <= 10.

Version 5.0.0 drops compatibility with node <= 12.

Install

npm i -S @hypercliq/shutdown-cleanup

Usage

Register a handler

import {
  registerHandler,
  addSignal,
  removeSignal,
  listSignals,
} from 'shutdown-cleanup'

registerHandler(() => console.log('This is printed on exit :)'))

Handler function

type HandlerFunction = (
  signal?: SignalsEvents | Error | number
) => void | Promise<void>

The optional parameter signal will be set to what caused the program to exit (see exit codes).

registerHandler((signal) => console.log('This is what we got back:', signal))

Add a signal or event to listen to

addSignal('uncaughtException')

Remove a signal or an event

removeSignal('SIGHUP')

List signals and events listened to

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

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 (e.g. when signal is an Error), the code number (errno) might be undefined. In those cases, shutdown-cleanup sets the exit code to 0x99

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.

Contributing

PRs welcome!

License

Shutdown-Cleanup is licensed under the MIT. See LICENSE for more details.