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): Promise<string> => {
    console.log(`Running iteration ${iteration} after delay of ${delay}ms`);
    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
Running iteration 2 after delay of 500ms
Running iteration 3 after delay of 500ms
Running iteration 4 after delay of 500ms
Running iteration 5 after delay of 500ms
Running iteration 6 after delay of 500ms
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): Promise<string> => {
    console.log(`Running iteration ${iteration} after delay of ${delay}ms`);
    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
Running iteration 2 after delay of 100ms
Running iteration 3 after delay of 200ms
Running iteration 4 after delay of 400ms
Running iteration 5 after delay of 800ms
Running iteration 6 after delay of 1600ms
Finished after 3111ms (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): Promise<string> => {
    console.log(`Running iteration ${iteration} after delay of ${delay}ms`);
    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 78ms
Running iteration 2 after delay of 154ms
Running iteration 3 after delay of 228ms
Running iteration 4 after delay of 605ms
Running iteration 5 after delay of 136ms
Running iteration 6 after delay of 1652ms
Finished after 2863ms (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. The function can either:

• return a non promised value (in which case, a failed check should throw an error)
• return 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.