Async Throttle Queue

Asynchronously execute a queue of functions, limiting the number of concurrent executions.

Inspired and cloned from shaunpersad's "throttled-queue"

Install

Install the module using NPM:

npm install @thanpolas/async-throttle-queue --save

Documentation

Throttles arbitrary code to execute a maximum number of times per interval. Best for making throttled API requests.

For example, making network calls to popular APIs such as Twitter is subject to rate limits. By wrapping all of your API calls in a throttle, it will automatically adjust your requests to be within the acceptable rate limits.

Unlike the throttle functions of popular libraries like lodash and underscore, throttled-queue will not prevent any executions. Instead, every execution is placed into a queue, which will be drained at the desired rate limit.

What is new

With the fork of 2025, the following new features were added:

1. A new dispose() method has been added to the throttle instance, which will clear the queue, delete all pending setTimeout commands and stop any further executions.
2. On each queue instance, three properties were added:
   • length: The total number of running functions.
   • queue: The total number of queued (throttled) functions.
   • total: The total number of running + queued.

Usage

const atq = require('@thanpolas/async-throttle-queue');

// Create an instance of a throttled queue by specifying the maximum number
// of requests as the first parameter, and the interval in milliseconds as the second:
const throttle = atq(5, 1000); // at most 5 requests per second.

// Use the `throttle` instance as a function to enqueue actions:
await throttle(() => {
    // perform some type of async activity in here.
    return Promise.resolve('hello!');
});

// Get the total functions on the throttle instance.
console.log(throttle.total);

Bursts

By specifying a number higher than 1 as the first parameter, you can dequeue multiple actions within the given interval:

const atq = require('@thanpolas/async-throttle-queue');
const throttle = atq(10, 1000); // at most make 10 requests every second.

for (let x = 0; x < 100; x++) {
    await throttle(() => {
        // This will fire at most 10 a second, as rapidly as possible.
        return fetch('https://api.github.com/search/users?q=shaunpersad');
    });
}

Evenly spaced

You can space out your actions by specifying true as the third (optional) parameter:

const atq = require('@thanpolas/async-throttle-queue');
const throttle = atq(10, 1000, true); // at most make 10 requests every second, but evenly spaced.

for (let x = 0; x < 100; x++) {
    async throttle(() => {
        // This will fire at most 10 requests a second, spacing them out instead of in a burst.
        return fetch('https://api.github.com/search/users?q=shaunpersad');
    });
}

Disposing

You can stop the throttle and clear the queue by calling the dispose() method.

Notes:

1. This will not stop any currently executing actions, but will prevent any further actions from being enqueued.
2. After calling dispose(), the internal state of queues is reset, and the already existing throttles should not be used again.
3. Call dispose() when your application is shutting down to prevent uncalled actions from being executed and halting the shutdown process.

const atq = require('@thanpolas/async-throttle-queue');

atq.dispose();

Update Node Version

When a new node version is available you need to updated it in the following:

• /package.json
• /.nvmrc
• /.circleci/config.yml

Releasing

1. Update the changelog bellow ("Release History").
2. Ensure you are on master and your repository is clean.
3. Type: npm run release for patch version jump.
   • npm run release:minor for minor version jump.
   • npm run release:major for major major jump.

Release History

• v1.0.0, 24/Jan/2025
  • Added new properties .length, .queue, .total.
  • Added full test-suite.
• v0.0.4, 16/Jan/2025
  • Fixed bug on dequeue self invoke.
• v0.0.3, 14/Jan/2025
  • Fixed dispose() not properly being exposed.
• v0.0.2, 13/Jan/2025
  • Fix master export.
• v0.0.1, 13/Jan/2025
  • Big Bang

License

Copyright © Thanos Polychronakis and Authors, Licensed under ISC.