smart-shutdown

A lightweight and easy-to-use Node.js package to handle graceful shutdowns for your application. Compatible with both CommonJS (CJS) and ECMAScript Modules (MJS).

Features

• Graceful shutdown of your Node.js applications.
• Easy to integrate with existing codebases.
• Works seamlessly with both CJS and MJS module systems.

Installation

Install the package via npm:

npm install smart-shutdown

Or with yarn:

yarn add smart-shutdown

Usage

Import the Package

For ECMAScript Modules (MJS)

import { ShutdownHelper } from 'smart-shutdown';

const shutdown = new ShutdownHelper();

shutdown.shutdown(); //this need to be define once at application level

For CommonJS (CJS)

const { ShutdownHelper } = require('smart-shutdown');

const shutdown = new ShutdownHelper();

shutdown.shutdown(); //this need to be define once at application level

API

ShutdownHelper

The ShutdownHelper class provides a mechanism to handle graceful shutdowns. It listens to system signals (e.g., SIGINT, SIGTERM) and executes cleanup operations before exiting the application.

Methods

• shutdown(options): Initiates the graceful shutdown process. Accepts an options object.
• shutdownHandlerFn(callback): A callback function executed before the application shuts down. This function should handle cleanup tasks and execute before the timeout expires.

shutdown method Options

| Option | Default | Description | |--------------|------------------|----------------------------------------------------------------------------------------------------------------------------| | server | - | An HTTP server. If provided, it will close the server during shutdown, serving all pending requests but not accepting new ones. | | timeout | 30000 | Timeout in milliseconds before forced shutdown. | | development| false | If set to true, skips graceful shutdown to speed up the development process. | | finally | - | A small, non-time-consuming function to execute at the end of the shutdown process (not executed in development mode). | | log | - | A function to provide logs during the shutdown process. |

Example

Here is an example of using smart-shutdown in a typical Node.js application:

import { ShutdownHelper, shutdownHandlerFn } from 'smart-shutdown';

const shutdown = new ShutdownHelper();

// `app` can be an HTTP, HTTPS, Express, Koa, or Fastify server, etc.
const server = app.listen(...);

//this need to be define once at application level
shutdown.shutdown({
    server: server,
    timeout: 20000, // Custom timeout in milliseconds
    log: (level, message) => console.log(message),
    finally: () => console.log('Application has shut down gracefully.')
});

shutdownHandlerFn(() => {
    console.log('Executing cleanup tasks...');
    // Close database connections
    closeDatabaseConnection();
    // Close Redis connections
    closeRedisConnection();
    console.log('Cleanup completed.');
});

async function closeDatabaseConnection() {
    // Simulate database connection closure
    return new Promise((resolve) => setTimeout(resolve, 1000));
}

async function closeRedisConnection() {
    // Simulate Redis connection closure
    return new Promise((resolve) => setTimeout(resolve, 500));
}