Promise Concurrency Manager

A lightweight utility to control and limit concurrent promises in your application.

Unlike typical wrappers, this library gives you explicit control over when tasks start, making it ideal for advanced flow control.

✨ Features

• Limit number of concurrently running promises
• Simple and explicit control flow
• Wait until a slot is available before executing
• Wait for all promises to complete
• Lightweight with zero dependencies

📦 Installation

npm install promise-concurrency-manager

🚀 Usage

import PromiseConcurrency from 'promise-concurrency-manager';

const concurrency = new PromiseConcurrency({ concurrencyLimit: 2 });

async function runTasks() {
  for (let i = 0; i < 5; i++) {
    await concurrency.waitIfConcurrencyLimitReached();

    concurrency.addPromise(
      new Promise((resolve) => {
        console.log(`Starting task ${i}`);
        setTimeout(() => {
          console.log(`Finished task ${i}`);
          resolve(true);
        }, 1000);
      })
    );
  }

  await concurrency.waitUntilAllPromisesAreResolved();
  console.log('All tasks completed');
}

runTasks();

🧠 How it works

1. Before starting a task, call:

await concurrency.waitIfConcurrencyLimitReached();

👉 This ensures you don’t exceed the concurrency limit.

2. Add your promise:

concurrency.addPromise(promise);

3. Optionally wait for all tasks:

await concurrency.waitUntilAllPromisesAreResolved();

⚙️ API

new PromiseConcurrency(options)

Create a new concurrency manager.

type Options = {
  concurrencyLimit: number;
};

| Option | Description | Default | |--------|------------|--------| | concurrencyLimit | Maximum concurrent promises | 1 |

addPromise(promise: Promise<any>): void

Adds a promise to the active pool.

• Automatically removed when resolved

waitIfConcurrencyLimitReached(): Promise<void>

Waits until at least one active promise resolves if limit is reached.

waitUntilAllPromisesAreResolved(): Promise<void>

Waits for all active promises to complete.

🔁 Typical Pattern

await concurrency.waitIfConcurrencyLimitReached();
concurrency.addPromise(task());

📌 Use Cases

• Rate-limiting API calls
• Controlling parallel processing
• Batch processing jobs
• Preventing resource exhaustion

⚠️ Notes

• You must call waitIfConcurrencyLimitReached() manually before adding promises
• This library does not wrap your functions — it gives you control instead

📄 License

MIT