bottleneck

The Group feature manages multiple limiters automatically by creating them dynamically based on a key. This is ideal for scenarios like rate-limiting per origin IP, where you want to apply the same rate-limiting rules to many different entities independently without manually managing thousands of limiter instances.

When you call .key(str) on a Group, it returns a limiter instance. If a limiter for that specific key doesn't exist, it is created using the options provided to the Group constructor. To prevent memory leaks, idle limiters are automatically deleted after a certain period (default is 5 minutes, configurable via the timeout option in milliseconds).

const group = new Bottleneck.Group(options);

// Use a key (e.g., an IP address) to route to a specific limiter
group.key("77.66.54.32").schedule(() => {
  /* process the request */
});

To contribute to the project:

1. Clone the repository.
2. Make changes only to files in src/.
3. Build and test: ./scripts/build.sh && npm test.
4. For faster development compilation, use: ./scripts/build.sh dev.

Testing Requirements:

• Tests must pass in Clustering mode and using the ES5 bundle.
• Requires a local Redis server. If using non-default host/port, configure them in the .env file.
• Run full tests with: ./scripts/build.sh && npm run test-all.

Always ensure you build and test without the dev flag before submitting a Pull Request.

The Batcher feature allows you to group multiple requests into a single batch, which is useful for APIs that support bulk operations.

Note: Batching does not perform throttling; it only optimizes request grouping based on time and size constraints.

To use it:

1. Create a new Bottleneck.Batcher(options).
2. Listen for the "batch" event to receive the grouped items.
3. Use .add(item) to add items to the batch. This returns a Promise that resolves once the batch has been flushed.

const batcher = new Bottleneck.Batcher({
  maxTime: 1000,
  maxSize: 10
});

batcher.on("batch", (batch) => {
  console.log(batch); // e.g., ["some-data", "some-other-data"]
  // Handle batch here
});

batcher.add("some-data");
batcherer.add("some-other-data");

The recommended way to configure a newly created limiter within a Group is to listen for the "created" event. This event handler is executed before .key(str) returns the new limiter, allowing you to attach event listeners (like "error") or other configurations to the specific limiter instance.

group.on("created", (limiter, key) => {
  console.log("A new limiter was created for key: " + key)

  // Prepare the limiter, for example we'll want to listen to its "error" events!
  limiter.on("error", (err) => {
    // Handle errors here
  })
});

Debugging complex scheduling logic (priorities, weights, latency) can be difficult. Use the following strategies to troubleshoot:

1. Catch Errors: Listen for the "error" event emitted by limiters and Groups. These are often uncaught exceptions from your application code.
2. Real-time Monitoring: Listen to the "debug" event to see detailed information about how the limiter is executing code. For better readability, include job IDs in your jobs.
3. Identify Bottleneck Errors: Bottleneck uses BottleneckError objects to signal when it has to fail a job. You can distinguish these from your own application errors using instanceof.

Always review the 'Gotchas' section if behavior is unexpected.

limiter.schedule(fn)
.then((result) => { /* ... */ } )
.catch((error) => {
  if (error instanceof Bottleneck.BottleneckError) {
    /* ... */
  }
});

Install Bottleneck via npm for Node.js or the browser.

npm install --save bottleneck

If you need to support older browsers or Node versions earlier than 6.0, use the ES5 bundle:

var Bottleneck = require("bottleneck/es5");

To implement basic rate limiting, use the Bottleneck constructor with minTime and/or maxConcurrent options.

• minTime: The minimum amount of time (in milliseconds) between the start of each task. For example, 333 ms allows approximately 3 requests per second.
• maxConcurrent: The maximum number of tasks that can run at the same time. Setting this to 1 ensures that only one request is active at any given moment, preventing overlapping requests if they take longer than the minTime interval.

// Execute 3 requests per second
const limiter = new Bottleneck({
  minTime: 333
});

// Execute 3 requests per second, but ensure only 1 runs at a time
const limiter = new Bottleneck({
  maxConcurrent: 1,
  minTime: 333
});

When the limiter reaches its highWater (High Water Mark) limit, it uses a strategy to decide what to do with new jobs. These strategies are available via Bottleneck.strategy:

• LEAK (1): Drops the oldest job in the queue to make room for the new one.
• OVERFLOW (2): Drops the new job being submitted.
• OVERFLOW_PRIORITY (4): Drops the job with the lowest priority in the queue to make room for the new one.
• BLOCK (3): (Note: Implementation details for BLOCK may vary, but it is a defined strategy constant).