Graceful Process Termination and Cleanup in Node.js

When building Node.js applications, especially servers or long-running scripts, handling process termination correctly is critical. You need to close database connections, flush logs, and release resources before the process dies. The packages death, exit-hook, and node-cleanup all aim to solve this, but they approach the problem with different levels of control and maintenance maturity. Let's break down how they work.

🛑 Handling Exit Signals and Events

All three packages hook into Node.js process events, but they expose different levels of abstraction.

death listens for SIGINT, SIGTERM, and uncaught exceptions. It wraps the cleanup logic in a simple async function.

// death: Simple async callback
const death = require('death');

death(async ({ signal, err }) => {
  console.log(`Process died with signal: ${signal}`);
  await db.close();
  process.exit(1);
});

exit-hook registers callbacks that run when the process exits. It handles both sync and async functions automatically.

// exit-hook: Registering hooks
const exitHook = require('exit-hook');

exitHook(() => {
  console.log('Exiting');
});

exitHook(async () => {
  await db.close();
});

node-cleanup separates cleanup logic from the exit event itself. You register handlers, and the library manages the exit flow, allowing you to override the exit code.

// node-cleanup: Registration with exit code control
const nodeCleanup = require('node-cleanup');

nodeCleanup((exitCode, signal) => {
  console.log(`Cleanup triggered: ${signal}`);
  db.close();
  // Return true to prevent default exit, false to allow it
  return false; 
});

🧹 Asynchronous Cleanup Support

Modern Node.js applications often rely on async resources (database pools, network sockets). How each package handles async cleanup varies significantly.

death was one of the early adopters of async cleanup. It awaits the callback before exiting.

// death: Native async support
const death = require('death');

death(async () => {
  await logger.flush();
  await cache.disconnect();
  // Process exits after promise resolves
});

exit-hook also supports async functions out of the box. It waits for all registered hooks to complete before allowing the process to terminate.

// exit-hook: Multiple async hooks
const exitHook = require('exit-hook');

exitHook(async () => {
  await serviceA.stop();
});

exitHook(async () => {
  await serviceB.stop();
});
// Both run before exit

node-cleanup requires you to manage the exit flow manually if you have async operations. The callback is synchronous by default, so you must handle promises explicitly or delay the exit.

// node-cleanup: Manual async handling
const nodeCleanup = require('node-cleanup');

nodeCleanup((exitCode, signal) => {
  cleanupPromise = db.close().then(() => {
    process.exit(exitCode);
  });
  // Prevent default immediate exit
  return true; 
});

⚠️ Maintenance and Stability Status

This is the most critical factor for architectural decisions. Using unmaintained packages for core infrastructure like process lifecycle is risky.

death is deprecated. The repository is archived, and it is no longer receiving updates. It may not handle newer Node.js edge cases correctly.

// death: DEPRECATED
// Do not use in new projects.
// npm install death (Not recommended)

exit-hook is actively maintained. It is part of Sindre Sorhus's ecosystem of high-quality utilities. It receives updates for compatibility with newer Node versions.

// exit-hook: MAINTAINED
// Safe for production use.
// npm install exit-hook

node-cleanup is maintained but has a smaller community footprint compared to exit-hook. It is stable but sees fewer updates.

// node-cleanup: STABLE
// Safe for production use.
// npm install node-cleanup

🎯 Controlling Exit Codes

Sometimes you need to ensure the process exits with a specific code depending on how cleanup went.

death allows you to call process.exit() manually inside the callback, giving you full control.

// death: Manual exit code
const death = require('death');

death(async ({ err }) => {
  if (err) {
    await logError(err);
    process.exit(1);
  }
  process.exit(0);
});

exit-hook does not inherently manage exit codes. It runs hooks and then lets the process exit naturally. You must call process.exit() inside the hook if you want to override.

// exit-hook: Override exit code manually
const exitHook = require('exit-hook');

exitHook(() => {
  if (somethingWrong) {
    process.exit(1);
  }
});

node-cleanup provides the exit code as an argument to the handler, allowing you to inspect it before the process dies.

// node-cleanup: Inspect exit code
const nodeCleanup = require('node-cleanup');

nodeCleanup((exitCode, signal) => {
  if (exitCode !== 0) {
    console.error('Exiting with error code:', exitCode);
  }
  return false; // Proceed with exit
});

🌐 Real-World Scenarios

Scenario 1: CLI Tool Cleanup

You are building a CLI that creates temporary files. You need to delete them on exit.

• ✅ Best choice: exit-hook
• Why? Simple API, actively maintained, handles async file deletion easily.

const exitHook = require('exit-hook');
const fs = require('fs');

exitHook(() => {
  fs.unlinkSync('/tmp/temp-file');
});

Scenario 2: Database Server Shutdown

You run a server that needs to close DB connections gracefully on SIGTERM.

• ✅ Best choice: node-cleanup
• Why? Allows inspection of the signal and exit code, useful for logging why the server stopped.

const nodeCleanup = require('node-cleanup');

nodeCleanup((exitCode, signal) => {
  console.log(`Shutting down: ${signal}`);
  db.close();
  return false;
});

Scenario 3: Legacy Script Maintenance

You are maintaining an old script that already uses death.

• ✅ Best choice: Keep death (temporarily)
• Why? Refactoring might introduce bugs. Plan to migrate to exit-hook later.

// Legacy code
const death = require('death');
death(() => { /* ... */ });

📌 Summary Table

💡 Final Recommendation

For new projects, always choose exit-hook. It is actively maintained, has a clean API, and handles async cleanup reliably without forcing you to manage exit flows manually unless you need to.

Use node-cleanup if you specifically need to inspect the exit code or signal within the cleanup handler before the process terminates, as it exposes these arguments directly.

Avoid death in any new architecture. It is deprecated and unmaintained, posing a risk for long-term stability. If you encounter it in legacy code, plan a migration to exit-hook during your next refactor cycle.

Final Thought: Process cleanup is infrastructure code. It needs to be reliable. Prioritize maintenance status and community support over minor API differences when choosing between these utilities.