@darkobits/adeiu

Adeiu is a POSIX signal handler designed to for applications with asynchronous cleanup / shutdown requirements, such as gracefully shutting-down an HTTP server or closing a database connection.

Features

• Zero dependencies.
• Ensures provided handlers are called before any other event listeners and are run concurrently, minimizing shutdown time.
• Works with any combination of synchronous and asynchronous handlers.
• Automatically exits with code 0 once all handlers resolve/return, or 1 if any reject/throw.
• Supports edge cases related to the Node debugger being attached to a process. (See this issue)

Install

npm i @darkobits/adeiu

Use

adeiu(handler: AdeiuHandler, options?: AdeiuOptions): () => void

Adeiu accepts an asynchronous or synchronous handler function and returns an unregister function. By default, the handler will be registered to respond to the following signals:

• SIGINT
• SIGQUIT
• SIGTERM
• SIGUSR2

import adeiu from '@darkobits/adeiu'

const unregister = adeiu(async signal => {
  console.log(`Received signal ${signal}; shutting down...`)
  await asyncCleanup()
  console.log('Done.')
})

If multiple handlers are registered, they will be invoked in parallel.

Customizing Signals

Usually, responding to signals dynamically can be accomplished by inspecting the signal argument passed to your handler. However, if it is important that handlers are only installed for a particular signal, or if you'd like to respond to signals other than the defaults, you may optionally provide an array of signals:

import adeiu from '@darkobits/adeiu'

// Register handler that will _only_ be invoked on SIGINT:
adeiu(() => {
  // ...
}, { signals: ['SIGINT'] })

import adeiu, { DEFAULT_SIGNALS } from '@darkobits/adeiu'

// Register handler with the default signals _and_ SIGUSR1:
adeiu(() => {
  // ...
}, { signals: [...DEFAULT_SIGNALS, 'SIGUSR1'] })

Specifying a Timeout

By default, handlers will have no timeout imposed. If, however, you wish to only wait a specific amount of time for a handler to run, the timeout option may be used:

import adeiu from '@darkobits/adeiu'

// Register a handler that will have 5 seconds to execute.
adeiu(() => {
  // ...
}, { timeout: 5000 })

Changelog

0.5.0 (2025-02-24)

⚠ BREAKING CHANGES

• adeiu.SIGNALS has been moved to a named export, DEFAULT_SIGNALS.

Before:

import adeiu from '@darkobits/adeiu'

// Default signals.
adeiu.SIGNALS

After:

import adeiu, { DEFAULT_SIGNALS } from '@darkobits/adeiu'

// Default signals.
DEFAULT_SIGNALS

• Export default signals. (ecbf785)