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

    3.1.0 • Public • Published

    node-graceful

    Build Status npm npm bundle size (version)

    node-graceful is a small helper module without dependencies that aims to ease graceful exit of complex node programs including async waiting on multiple independent modules.

    Installation:

    npm i -S node-graceful
    
    yarn add node-graceful

    Had any problem? open an issue

    Quick example

    Typescript

    import Graceful from 'node-graceful';
    Graceful.captureExceptions = true;
    
    Graceful.on('exit', async () => {
      await server.close();
    });

    Plain JS

    const Graceful = require('node-graceful');
    Graceful.captureExceptions = true;
    
    Graceful.on('exit', async () => {
        console.log(`Received ${signal} - Exiting gracefully`);
        await webServer.close(); 
    });
    
    //  Graceful will wait until all listeners had finished
    Graceful.on('exit', (signal) => {
        return new Promise((resolve) => {
            console.log("Another independent listener!");
            setTimeout(() => resolve(), 1000);    
        });
    });

    Quick Docs

    interface Graceful {
        // add exit listener
        on(signal: 'exit', listener: GracefulListener): GracefulSubscription;
        // remove exit listener
        off(signal: 'exit', listener: GracefulListener): void;
        // remove all exit listeners
        clear(): void;
        // trigger graceful process exit with or without exit code and signal
        exit(): void;
        exit(exitCode: number): void;
        exit(exitSignal: string): void;
        exit(exitCode: number, exitSignal: string): void;
    
        // whether to exit immediately when a second kill signal is received
        exitOnDouble: boolean; // default: true
        // maximum time to wait before hard-killing the process
        timeout: number; // default: 30000
        // whether to treat uncaught exceptions as process terminating events
        captureExceptions: boolean; // default: false
        // whether to treat unhandled promise rejections as process terminating events
        captureRejections: boolean; // default: false
    }
    
    type GracefulListener = (signal: string, details?: object) => (void | any | Promise<any> | Promise<Error>);
    type GracefulSubscription = () => void;

    Read bellow for full API reference.

    API Reference

    Graceful.on('exit', {Function} listener)

    Add exit listener to be called when process exit is triggered. Graceful listens on all terminating signals and triggers exit accordingly.

    Terminating events: SIGTERM SIGINT SIGBREAK SIGHUP

    Options

    • listener(signal, details?) - listener function
      • signal - the signal that triggered the exit. example: 'SIGTERM'
      • details - optional details provided by the trigger. for example in case of unhandledException this will be an error object. on external signal it will be undefined.

    Examples

    The listener function can return a promise that will delay the process exit until it's fulfilment.

    Graceful.on('exit', () => Promise.resolve('I Am A Promise!'));
    Graceful.on('exit', async () => {
      // async function always returns promise so shutdown will be delayed until this functions ends
      await webServer.close();
    
      return Promise.all([
        controller.close(),
        dbClient.close()
      ]);
    });

    if old style callback is needed, wrap the logic with a promise

    const server = require('http').createServer(function (req, res) {
        res.write('ok');
        res.end()
    })
    Graceful.on('exit', () => {
      return new Promise((resolve, reject) => {
        server.close((err) => {
          if (err) return reject(err);
          resolve();
        });
      });
    });

    Return value

    the method returns a function that when invoked, removes the listener subscription. the function is a shorthand for .off method

    example
    // use the return value to remove listener
    const removeListener = Graceful.on('exit', () => {});
    removeListener(); // listener was removed and will not be triggered

    Graceful.off('exit', {Function} listener)

    Remove a previously subscribed listener.

    example
    const gracefulExit = () => {
        console.log("exiting!");
    };
    
    // add listener
    let removeListener = Graceful.on('SIGTERM', gracefulExit);
    
    // remove listener
    Graceful.off('SIGTERM', gracefulExit);
    // same as invoking the return value
    // removeListener();

    Graceful.clear()

    Unsubscribe all exit listeners.

    example
    // add listener
    Graceful.on('exit', () => {
       console.log("Received some exit signal!");
       return Promise.resolve("A promise to be waited on before dying");
    });
    
    Graceful.on('exit', (done) => {
       console.log("Another listener");
       done();
    });
    
    // remove all listener
    Graceful.clear();

    Graceful.exit({Number} [code], {String} [signal])

    Trigger graceful process exit. This method is meant to be a substitute command for process.exit() to allow other modules to exit gracefully in case of error.

    • code - (optional) exit code to be used. default - process.exitCode
    • signal - (optional) signal to be simulating for listeners. default - SIGTERM
    example
    server.listen(3333)
            .on('listening', function () {
                console.log('Yay!')
            })
            .on('error', function (err) {
                if (err.code === 'EADDRINUSE') {
                    console.error("Damn, Port is already in use...");
                    Graceful.exit();
                }
            });
    
    // exit code and signal can be specified
    // Graceful.exit(1);
    // Graceful.exit(1, 'SIGINT');
    // Graceful.exit('SIGINT');

    Options

    Options are global and shared, any change will override previous values.

    Graceful.exitOnDouble = true {boolean}

    Whether to exit immediately when a second deadly event is received, For example when Ctrl-C is pressed twice etc.. When exiting due to double event, exit code will be process.exitCode or 1 (necessarily a non-zero)

    Graceful.timeout = 30000 {number}

    Maximum time to wait for exit listeners in ms. After exceeding the time, the process will force exit and the exit code will be process.exitCode or 1 (necessarily a non-zero)

    Setting the timeout to 0 will disable timeout functionality (will wait indefinitely)

    Graceful.captureExceptions = false {boolean}

    Whether to treat uncaughtException event as a terminating event and trigger graceful shutdown.

    Graceful.captureExceptions = true;
    
    throw new Error('DANG!'); // this will now trigger graceful shutdown 

    Graceful.captureRejections = false {boolean}

    Whether to treat unhandledRejection event as a terminating event and trigger graceful shutdown. On newer node versions unhandledRejection is in-fact a terminating event

    Graceful.captureRejections = true;
    
    Promise.reject(new Error('DANG!')); // this will now trigger graceful shutdown 

    exitCode

    Graceful will obey process.exitCode property value when exiting unless the exit is forced (double signal, timeout) in which case the exit code must be non-zero.

    Install

    npm i node-graceful

    DownloadsWeekly Downloads

    6,219

    Version

    3.1.0

    License

    MIT

    Unpacked Size

    17.3 kB

    Total Files

    5

    Last publish

    Collaborators

    • mrbar42