PromiseQueue*

*this readme was AI generated

A lightweight concurrency control utility for managing active promises with a fixed limit.

This utility ensures that only a specified number of promises are active at once. Excess promises are queued and activated as earlier ones settle. Designed for high-throughput or rate-limited async environments.

✨ Features

• Limit concurrent promise execution (e.g., max 5 at once)
• Queue additional promises until slots free up
• Adjustable polling interval for smooth async scheduling
• Works with resolved and rejected promises alike
• Simple, dependency-free design

📦 Installation

npm install arc-promise-queue

🧩 Class: PromiseQueue

Constructor

const q = new PromiseQueue();

setAllowedActive(count: number): void

Sets the maximum number of concurrently active promises.

q.setAllowedActive(5); // allow 5 promises at a time

setAddPause(ms: number): void

Sets how often the queue checks for free slots (in milliseconds).

q.setAddPause(10); // check every 10ms

addToQueue(promise: Promise<any>): Promise<void>

Adds a promise to the queue. Resolves once the promise has been accepted into the active pool.

const task = fetch(url);
await q.addToQueue(task);

Note: The queue does not wait for the promise to finish—it only ensures the concurrency limit.

getLengthOfQueue(): number

Returns the number of active promises currently being tracked.

console.log(q.getLengthOfQueue()); // e.g., 3

settleQueued(): Promise<void>

Resolves when all currently queued and active promises have settled.

await q.settleQueued(); // Wait for everything to finish

🧪 Example Usage

import PromiseQueue from 'arc-promisequeue';

const q = new PromiseQueue();
q.setAllowedActive(2);
q.setAddPause(5);

const tasks = Array.from({ length: 5 }, (_, i) =>
  q.addToQueue(
    new Promise((resolve) => {
      console.log('Start', i);
      setTimeout(() => {
        console.log('Finish', i);
        resolve();
      }, 50);
    })
  )
);

await Promise.all(tasks);
await q.settleQueued();
console.log('All done!');

Output:

Start 0
Start 1
Finish 0
Start 2
Finish 1
Start 3
Finish 2
Start 4
Finish 3
Finish 4
All done!

⚙️ Behavior Notes

• The queue monitors completion internally, freeing slots automatically.
• You can enqueue any kind of promise (fetches, I/O, or computations).
• addToQueue() returns as soon as the promise is accepted, not when it finishes.
• Ideal for APIs with rate limits, background tasks, or throttled pipelines.

✅ Testing

Comprehensive Jest tests are included. Run:

npm test

📄 License

This project is released under The Unlicense, placing it in the public domain.