bottleneck

What is bottleneck?

The bottleneck npm package is a rate limiter that allows you to control the rate at which tasks are executed. It is useful for managing resource usage and ensuring that your application does not exceed the rate limits imposed by APIs or other systems. It can be used to throttle function calls, manage task execution concurrency, and queue tasks.

What are bottleneck's main functionalities?

Task Scheduling

This feature allows you to schedule tasks to be executed with a minimum time interval between them and a maximum number of concurrent tasks. The code sample demonstrates how to create a limiter that only allows one task to run at a time with a minimum of 1 second between task starts.

const Bottleneck = require('bottleneck');
const limiter = new Bottleneck({ maxConcurrent: 1, minTime: 1000 });

async function myFunction(id) {
  console.log(`Working on task ${id}`);
}

for (let i = 0; i < 5; i++) {
  limiter.schedule(() => myFunction(i));
}

Priority Queueing

This feature allows you to assign priorities to tasks. Tasks with higher priority (lower priority number) will be executed before those with lower priority. The code sample shows how to schedule tasks with different priorities.

const Bottleneck = require('bottleneck');
const limiter = new Bottleneck({ maxConcurrent: 2 });

async function myFunction(priority, id) {
  console.log(`Working on task ${id} with priority ${priority}`);
}

limiter.schedule({ priority: 1 }, myFunction, 1, 'A');
limiter.schedule({ priority: 5 }, myFunction, 5, 'B');
limiter.schedule({ priority: 3 }, myFunction, 3, 'C');

Rate Limiting

This feature allows you to limit the rate at which functions are executed. It can be used to avoid hitting rate limits of external APIs. The code sample demonstrates how to set up a limiter with a reservoir that refreshes over time, and how to handle the 'depleted' event when the rate limit is exceeded.

const Bottleneck = require('bottleneck');
const limiter = new Bottleneck({ reservoir: 100, // initial value
  reservoirRefreshAmount: 100,
  reservoirRefreshInterval: 60 * 1000 // must be divisible by 250
});

limiter.on('depleted', () => console.log('Rate limit exceeded'));

// Function to be rate-limited
async function myFunction() {
  console.log('Doing something.');
}

setInterval(() => {
  limiter.submit(myFunction);
}, 10);

Other packages similar to bottleneck

p-throttle

p-throttle is a package that allows you to throttle function calls. It is similar to bottleneck in that it helps to control the rate of function execution, but it is built on top of Promises and does not provide the same level of detailed configuration as bottleneck, such as priority queueing or reservoir-based limiting.

async-ratelimiter

async-ratelimiter is a rate limiting library that uses Redis for storage. It is designed for more distributed use cases where you need to maintain rate limits across multiple processes or servers. Unlike bottleneck, which is more focused on in-process rate limiting, async-ratelimiter is suitable for scenarios where you need a shared rate limit state.

leaky-bucket

leaky-bucket is another rate limiting library that implements the leaky bucket algorithm. It is similar to bottleneck in providing rate limiting capabilities, but it has a different algorithmic approach. While bottleneck uses a more general approach with configurable reservoirs, leaky-bucket strictly adheres to the leaky bucket algorithm, which may be more suitable for certain use cases.

README

bottleneck

Bottleneck is a simple and efficient Asynchronous Rate Limiter for Node.JS and the browser. When dealing with services with limited resources, it's important to ensure that they don't become overloaded. Bottleneck is the easiest solution as it doesn't add any complexity to the code.

Databases, file systems, network access, APIs, etc. are all services that can easily be overwhelmed.

#Install

Node

npm install bottleneck

Browser

<script type="text/javascript" src="bottleneck.min.js"></script>

#Usage

Most APIs have a rate limit. For example, the Reddit.com API limits programs to 1 request every 2 seconds.

var Bottleneck = require("bottleneck"); //Node.JS only

// Wait at least 2000ms between each request.
// Never more than 1 request running at a time.
var limiter = new Bottleneck(1, 2000);

new Bottleneck(maxNb, minTime);

• maxNb : How many requests can be running at the same time. 0 for unlimited.
• minTime : Optional. How long to wait after launching a request before launching another one.

Instead of doing

someAsyncCall(arg1, arg2, argN, callback);

You do

limiter.submit(someAsyncCall, arg1, arg2, argN, callback);

And now you can be assured that someAsyncCall will follow the rate guidelines!

If a callback isn't necessary, pass null instead.

###stopAll

limiter.stopAll();

Cancels all queued up requests and prevents additonal requests from being submitted.

###changeSettings

limiter.changeSettings(maxNb, minTime)

Same parameters as the constructor, pass null to skip a parameter.