close-with-grace

close-with-grace

Exit your process, gracefully (if possible) - for Node.js

Install

npm i close-with-grace

Usage

const closeWithGrace = require('close-with-grace')

// delay is the number of milliseconds for the graceful close to
// finish.
closeWithGrace({ delay: 500 }, async function ({ signal, err, manual }) {
  if (err) {
    console.error(err)
  }
  await closeYourServer()
})

// default delay is 10000
// to disable delay feature at all, pass falsy value to delay option.
closeWithGrace({ delay: false }, () => await somethingUseful())

Injecting custom logger

const closeWithGrace = require('close-with-grace')

// delay is the number of milliseconds for the graceful close to
// finish.
closeWithGrace(
  {
    delay: 500,
    logger: { error: (m) => console.error(`[close-with-grace] ${m}`) }
  },
  async function ({ signal, err, manual }) {
  if (err) {
    console.error(err)
  }
  await closeYourServer()
})

// default logger is console
// to disable logging at all, pass falsy value to logger option.
closeWithGrace({ logger: false }, () => await somethingUseful())

Example with Fastify

import fastify from 'fastify'
import closeWithGrace from 'close-with-grace'

const app = fastify()

closeWithGrace(async function ({ signal, err, manual }) {
  if (err) {
    app.log.error({ err }, 'server closing with error')
  } else {
    app.log.info(`${signal} received, server closing`)
  }
  await app.close()
})

await app.listen()

Skipping specific events

Skip specific events from triggering the graceful close. Note: You are responsible for handling skipped events yourself.

import closeWithGrace from 'close-with-grace'

// Handle errors separately
process.on('unhandledRejection', (err) => {
  // Your custom error handling
})

closeWithGrace(
  { skip: ['unhandledRejection', 'uncaughtException'] },
  async function ({ signal, err, manual }) {
    await cleanupResources()
  }
)

API

closeWithGrace([opts], fn({ err, signal, manual }))

closeWithGrace adds a global listeners to the events:

• process.once('SIGHUP')
• process.once('SIGINT')
• process.once('SIGQUIT')
• process.once('SIGILL')
• process.once('SIGTRAP')
• process.once('SIGABRT')
• process.once('SIGBUS')
• process.once('SIGFPE')
• process.once('SIGSEGV')
• process.once('SIGUSR2')
• process.once('SIGTERM')
• process.once('uncaughtException')
• process.once('unhandledRejection')
• process.once('beforeExit')

In case one of them is emitted, it will call the given function. If it is emitted again, it will terminate the process abruptly.

opts

• delay: the numbers of milliseconds before abruptly close the process. Default: 10000.

  • Pass false, null or undefined to disable this feature.

• logger: instance of logger which will be used internally. Default: console.

  • Pass false, null or undefined to disable this feature.

• skip: an array of event names to skip from triggering the graceful close callback. Default: [].

  • Example: skip: ['unhandledRejection', 'uncaughtException', 'SIGTERM']
  • Note: You must handle skipped events yourself, otherwise they may cause the process to crash or exit unexpectedly.

• onSecondError(error): A callback to execute if the process throws an uncaughtException or an unhandledRejection while fn is executing.

• onSecondSignal(signal): A callback to execute if the process receives another signal while fn is executing.

• onTimeout(delay): A callback to execute if fn failed to completed after delay milliseconds.

Both onSecondError, onSecondSignal or onTimeout can be used to perform custom logic, but process.exit(1) will be immediately be invoked after they exit so no asynchronous operations are possible.

fn({ err, signal, manual } [, cb])

Execute the given function to perform a graceful close. The function can either return a Promise or call the callback. If this function does not error, the process will be closed with exit code 0. If the function rejects with an Error, or call the callback with an Error as first argument, the process will be closed with exit code 1.

return values

Calling closeWithGrace() will return an object as formed:

• close(): close the process, the manual argument will be set to true.
• uninstall(): remove all global listeners.

License

MIT

Similar packages

Other packages similar to close-with-grace

graceful-shutdown

The 'graceful-shutdown' package provides similar functionality for handling graceful shutdowns in Node.js applications. It allows you to register shutdown handlers and ensures that cleanup tasks are completed before the application exits. Compared to 'close-with-grace', 'graceful-shutdown' offers a more straightforward API but may lack some advanced features.

node-graceful-shutdown

The 'node-graceful-shutdown' package helps manage graceful shutdowns by providing a mechanism to handle termination signals and perform cleanup tasks. It is similar to 'close-with-grace' in terms of functionality but offers a different API design. 'node-graceful-shutdown' focuses on simplicity and ease of use.

http-terminator

The 'http-terminator' package is designed to facilitate graceful shutdowns of HTTP servers in Node.js. It ensures that all ongoing requests are completed before the server shuts down. While 'http-terminator' is more specialized for HTTP servers, 'close-with-grace' offers a more general-purpose solution for handling various types of cleanup tasks.