Small library for controlling parallelism at scale
npm install arc-promise-queue_*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.
---
- 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
---
``bash`
npm install arc-promise-queue
---
js
const q = new PromiseQueue();
`---
$3
Sets the maximum number of concurrently active promises.js
q.setAllowedActive(5); // allow 5 promises at a time
`---
$3
Sets how often the queue checks for free slots (in milliseconds).js
q.setAddPause(10); // check every 10ms
`---
$3
Adds a promise to the queue. Resolves once the promise has been accepted into the active pool.js
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.
---
$3
Returns the number of active promises currently being tracked.js
console.log(q.getLengthOfQueue()); // e.g., 3
`---
$3
Resolves when all currently queued and active promises have settled.js
await q.settleQueued(); // Wait for everything to finish
`---
🧪 Example Usage
js
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).
-
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:
`bash
npm test
``---
This project is released under The Unlicense, placing it in the public domain.