Nonchalantly Perusing Magazines

    TypeScript icon, indicating that this package has built-in type declarations

    3.0.1 • Public • Published


    build status code style styled with prettier made with lass license

    Gracefully exit HTTP servers (Express/Koa/Fastify/etc), databases (Mongo/Mongoose), Redis clients, Bree job schedulers, and custom handlers.

    Table of Contents



    npm install @ladjs/graceful


    See the Express, Koa, Fastify, or Other code snippet examples and Instance Options below.

    You can pass Instance Options to customize your graceful handler (e.g. if you have more than one server, or wish to close both a Redis connection and a server at the same time).

    const Graceful = require('@ladjs/graceful');
    // ...
    // see Instance Options in the README below and examples for different projects (e.g. Koa or Express)
    const graceful = new Graceful({
      // http or net servers
      // (this supports Express/Koa/Fastify/etc)
      // (basically anything created with http.createServer or net.createServer)
      // <>
      // <>
      // <>
      servers: [],
      // bree clients
      // <>
      brees: [],
      // redis clients
      // <>
      // <>
      redisClients: [],
      // mongoose clients
      // <>
      mongooses: [],
      // custom handlers to invoke upon shutdown
      customHandlers: [],
      // logger
      logger: console,
      // how long to wait in ms for exit to finish
      timeoutMs: 5000,
      // options to pass to `lil-http-terminator` to override defaults
      lilHttpTerminator: {}
    // NOTE: YOU MUST INVOKE `graceful.listen()` IN ORDER FOR THIS TO WORK!

    Using this package will bind process event listeners when graceful.listen() is called:

    • process.on('warning') - will output via config.logger.warn
    • process.on('unhandledRejection') - bubbles up to uncaughtException (will output via config.logger.error and process.exit(1) (does not exit gracefully)
    • process.once('uncaughtException') - will output via config.logger.error and process.exit(1) (does not exit gracefully)
    • process.on('message') - support Windows (e.g. signals not available) and listen for message of shutdown and then exit gracefully
    • process.once('SIGTERM') - will exit gracefully
    • process.once('SIGHUP') - will exit gracefully
    • process.once('SIGINT') - will exit gracefully
    • process.once('SIGUSR2') - will exit gracefully (nodemon support)

    This package also prevents multiple process/SIG events from triggering multiple graceful exits. Only one graceful exit can occur at a time.

    For servers passed, we use lil-http-terminator under the hood. Default configuration options can be overridden by passing a lilHttpTerminator configuration object. See index.js for more insight.


    const express = require('express');
    const Graceful = require('@ladjs/graceful');
    const app = express();
    const server = app.listen();
    const graceful = new Graceful({ servers: [server] });


    const Koa = require('koa');
    const Graceful = require('@ladjs/graceful');
    const app = new Koa();
    const server = app.listen();
    const graceful = new Graceful({ servers: [server] });


    const fastify = require('fastify');
    const Graceful = require('@ladjs/graceful');
    const app = fastify();
    // NOTE: @ladjs/graceful is smart and detects `app.server` automatically
    const graceful = new Graceful({ servers: [app] });


    This package works with any server created with http.createServer or net.createServer (Node's internal HTTP and Net packages).

    Please defer to the test folder files for example usage.

    Instance Options

    Here is the full list of options and their defaults. See index.js for more insight if necessary.

    Property Type Default Value Description
    servers Array [] An array of HTTP or NET servers to gracefully close on exit
    brees Array [] An array of Bree instances to gracefully exit
    redisClients Array [] An array of Redis client instances to gracefully exit
    mongooses Array [] An array of Mongoose connections to gracefully exit
    customHandlers Array [] An array of functions (custom handlers) to invoke upon graceful exit
    logger Object console This is the default logger. We recommend using Cabin instead of using console as your default logger. Set this value to false to disable logging entirely (uses noop function)
    timeoutMs Number 5000 A number in milliseconds for how long to wait to gracefully exit
    lilHttpTerminator Object {} An object of options to pass to lil-http-terminator to override default options provided


    You can refer Forward Email for more complex usage:

    Additionally you can also refer to Lad usage:

    You can also read more about Bree at


    Name Website
    Nick Baugh
    Felix Mosheev
    Nicholai Nissen
    Spencer Snyder


    MIT © Nick Baugh


    npm i @ladjs/graceful

    DownloadsWeekly Downloads






    Unpacked Size

    20.2 kB

    Total Files


    Last publish


    • titanism
    • shadowgate15
    • niftylettuce
    • shaunwarman
    • spence-s