Concurrentie

A tiny, zero‑dependency concurrency limiter for TypeScript & Node.js. Safely run a fixed number of async jobs in parallel without ever oversubscribing.

Installation

npm install concurrentie

Quick‑start

import createConcurrentie from 'concurrentie';

// Allow at most 3 async jobs to run at the same time
const limiter = createConcurrentie({ concurrency: 3 });

// Wrap any promise‑returning function with .run()
async function fetchWithLimit(url: string) {
  return limiter.run(() => fetch(url).then(r => r.json()));
}

// Kick off a bunch of requests in parallel
await Promise.all([
  fetchWithLimit('https://…/1'),
  fetchWithLimit('https://…/2'),
  fetchWithLimit('https://…/3'),
  fetchWithLimit('https://…/4'),
]);
// Only three fetches were in flight at any given moment 🎉

If you need finer‑grained control you can claim & release slots manually:

const claim = await limiter.claim();
try {
  // do your critical async work here
} finally {
  limiter.release(claim); // always release in a finally‑block!
}

API

| Method | Description | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | run<T>(fn: () => Promise<T>) | Executes fn when a slot is available and resolves with its result. Automatically releases the slot afterwards. | | claim() | Returns a promise that resolves to a claim token when a slot is available. Useful when you want to hold the slot across multiple awaits. | | release(claim) | Releases a previously claimed slot. Throws if the claim was not active. | | getActiveCount() | Returns the number of currently active claims. |

createConcurrentie(config)

• concurrency number (required) – Maximum number of concurrent claims. Must be a positive integer.

concurrency is snapshotted at construction time. Even if you mutate the original config object later, the limiter will continue to enforce the initial value.

Why another limiter?

• Minimal – ~1 KB minified, zero dependencies.
• Predictable – No clever prioritisation; simple FIFO queue semantics.
• TypeScript‑first – Ships with full type definitions.

Contributing

We ❤️ contributions! Bug reports, feature requests and pull‑requests are welcome.

1. Fork the repo
2. npm i
3. Run the tests with npm test
4. Submit a PR describing your change

See CONTRIBUTING.md for full guidelines.

License

MIT © 2025  Ralusek