@cutticat/shutdown

Library for registering graceful shutdown handlers in CuttiCat Node.js applications.

Contents

• Overview
• Installation
• Quick start
• API
• Documentation
• Important
• Requirements

Overview

The library registers handlers for:

• Process signals (SIGINT, SIGTERM, SIGHUP by default)
• Uncaught exceptions (uncaughtException)
• Unhandled promise rejections (unhandledRejection)

When a signal or error is received, registered callbacks are invoked, their completion is awaited (with a timeout), and then the process exits with the appropriate exit code.

Installation

pnpm i @cutticat/shutdown

Quick start

import { registerShutdown } from "@cutticat/shutdown"

const shutdown = registerShutdown({
  onShutdown: async (options) => {
    console.log("Shutting down...", options)
    await closeDatabase()
    await closeRedis()
  },
  logger: console,
  timeout: 5000,
})

// Add additional handlers later
shutdown.onShutdown(async () => {
  await flushLogs()
})

API

registerShutdown(options)

Registers graceful shutdown handlers. Returns a RegisteredShutdown object.

Options:

• onShutdown — callback invoked on shutdown (may be async)
• register — callback for registering additional handlers (e.g. for an HTTP server)
• logger — logger or logger factory
• signals — list of signals (default ["SIGINT", "SIGTERM", "SIGHUP"])
• timeout — timeout in ms (default 10000)
• uncaughtException — handle uncaughtException (default true)
• unhandledRejection — handle unhandledRejection (default true)

RegisteredShutdown

• status — current status (waiting | disposed | shuttingDown)
• dispose() — unregisters handlers without performing shutdown
• shutdown(options) — initiates shutdown
• onShutdown(callback) — adds a callback
• register(callback) — registers a handler (receives the shutdown function)

shutdownDefaults

Default option values.

Documentation

Further documentation:

• Project structure
• Scripts
• Style guide
• Contributing

Full API documentation is available in JSDoc comments.

Important

It is recommended to call registerShutdown() once per process. Multiple calls create several sets of handlers for the same events; repeated shutdowns are ignored, but listeners remain until dispose() is called.

onShutdown callbacks are invoked in reverse registration order (LIFO): last registered first (e.g. closing the HTTP server), then earlier ones (DB pool, etc.). Unregister functions from register() on dispose() / shutdown completion also run in reverse order.

Requirements

• Node.js >= 22.0.0
• pnpm >= 10.17.0
• TypeScript >= 5.9.0