Neptune's Potato Monsters

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

    3.1.2 • Public • Published

    Npm Version node Build status Test Coverage Maintainability Known Vulnerabilities

    busywait.js

    Simple Async busy wait module for Node.JS

    Main features

    • Simple api to busy wait for a desired outcome
    • Exponential backoff (with optional full jitter) support
    • Slim library (single file, 100 lines of code, no dependencies)
    • Full typescript support

    Quick example

    import {busywait} from 'busywait';
    
    const waitUntil = Date.now() + 2500;
    
    const checkFn = async (iteration: number, delay: number, totalDelay: number): Promise<string> => {
        console.log(`Running iteration ${iteration} after delay of ${delay}ms and total delay of ${totalDelay}`);
        if (Date.now() > waitUntil) {
            return `success`;
        }
        throw new Error('custom error');
    };
    
    (async () => {
        const result = await busywait(checkFn, {
            sleepTime: 500,
            maxChecks: 20,
        })
        console.log(`Finished after ${result.backoff.time}ms (${result.backoff.iterations} iterations) with result ${result.result}`);
    })();

    Will result in:

    Running iteration 1 after delay of 0ms and total delay of 1
    Running iteration 2 after delay of 500ms and total delay of 504
    Running iteration 3 after delay of 500ms and total delay of 1007
    Running iteration 4 after delay of 500ms and total delay of 1508
    Running iteration 5 after delay of 500ms and total delay of 2010
    Running iteration 6 after delay of 500ms and total delay of 2511
    Finished after 2511ms (6 iterations) with result success

    Exponential backoff

    import {busywait} from 'busywait';
    
    const waitUntil = Date.now() + 2500;
    
    const checkFn = async (iteration: number, delay: number, totalDelay: number): Promise<string> => {
        console.log(`Running iteration ${iteration} after delay of ${delay}ms and total delay of ${totalDelay}`);
        if (Date.now() > waitUntil) {
            return `success`;
        }
        throw new Error('custom error');
    };
    
    (async () => {
        const result = await busywait(checkFn, {
            sleepTime: 100,
            jitter: 'none',
            multiplier: 2,
        })
        console.log(`Finished after ${result.backoff.time}ms (${result.backoff.iterations} iterations) with result ${result.result}`);
    })();

    Will result in:

    Running iteration 1 after delay of 0ms and total delay of 1
    Running iteration 2 after delay of 100ms and total delay of 104
    Running iteration 3 after delay of 200ms and total delay of 306
    Running iteration 4 after delay of 400ms and total delay of 707
    Running iteration 5 after delay of 800ms and total delay of 1509
    Running iteration 6 after delay of 1600ms and total delay of 3110
    Finished after 3110ms (6 iterations) with result success

    Exponential backoff with full jitter

    import {busywait} from 'busywait';
    
    const waitUntil = Date.now() + 2500;
    
    const checkFn = async (iteration: number, delay: number, totalDelay: number): Promise<string> => {
        console.log(`Running iteration ${iteration} after delay of ${delay}ms and total delay of ${totalDelay}`);
        if (Date.now() > waitUntil) {
            return `success`;
        }
        throw new Error('custom error');
    };
    
    (async () => {
        const result = await busywait(checkFn, {
            sleepTime: 100,
            jitter: 'full',
            multiplier: 2,
            waitFirst: true,
        })
        console.log(`Finished after ${result.backoff.time}ms (${result.backoff.iterations} iterations) with result ${result.result}`);
    })();

    Will result in:

    Running iteration 1 after delay of 31ms and total delay of 31
    Running iteration 2 after delay of 165ms and total delay of 199
    Running iteration 3 after delay of 217ms and total delay of 417
    Running iteration 4 after delay of 378ms and total delay of 796
    Running iteration 5 after delay of 1397ms and total delay of 2195
    Running iteration 6 after delay of 1656ms and total delay of 3853
    Finished after 3853ms (6 iterations) with result success

    Install

    npm install busywait

    Parameters

    checkFn

    A function that takes a single optional argument, which is the current iteration number.

    Args
    • iteration - The current iteration number (starting from 1)
    • delay - The last delay (in ms) that was applied
    • totalDelay - The total delay (in ms) applied so far
    Return

    Either:

    • a non promised value (in which case, a failed check should throw an error)
    • a promised value (in which case, a failed check should return a rejected promise)

    options

    mandatory
    • sleepTime - Time in ms to wait between checks. In the exponential mode, will be the base sleep time.
    optional
    • multiplier - The exponential multiplier. Set to 2 or higher to achieve exponential backoff (default: 1 - i.e. linear backoff)
    • maxDelay - The max delay value between checks in ms (default: infinity)
    • maxChecks - The max number of checks to perform before failing (default: infinity)
    • waitFirst - Should we wait the sleepTime before performing the first check (default: false)
    • jitter - ('none' | 'full') The jitter mode to use (default: none)
    • failMsg - Custom error message to reject the promise with

    Return value

    Return value is a promise.

    • The promise will be resolved if the checkFn was resolved within a legal number of checks.
    • The promise will be rejected if the checkFn rejected (or threw an error) maxChecks times.

    Promise resolved value:

    • backoff.iterations - The number of iterations it took to finish
    • backoff.time - The number of time it took to finish
    • result - The resolved value of checkFn

    Contributing

    All contributions are happily welcomed!
    Please make all pull requests to the master branch from your fork and ensure tests pass locally.

    Install

    npm i busywait

    DownloadsWeekly Downloads

    138

    Version

    3.1.2

    License

    ISC

    Unpacked Size

    33.5 kB

    Total Files

    6

    Last publish

    Collaborators

    • regevbr