Overview

medhira-concurrency-utils helps you pick the right parallelism level at runtime — based on CPU cores, system load, and memory pressure — so worker pools, batch jobs, and parallel pipelines stay fast without overloading the machine.

import { getDynamicConcurrency } from 'medhira-concurrency-utils';

const concurrency = getDynamicConcurrency();
console.log(concurrency); // e.g. 8

Features

| | | |---|---| | Dynamic | Adjusts concurrency based on real-time system metrics | | Memory-aware | Reduces workers when memory usage exceeds your threshold | | Load-aware | Responds to OS load average on Linux/macOS | | Zero dependencies | Uses only Node.js built-in os module | | TypeScript-first | Full type definitions included | | Configurable | Tune memory, load, and per-worker memory assumptions |

Installation

npm install medhira-concurrency-utils

yarn add medhira-concurrency-utils

Quick Start

import { getDynamicConcurrency } from 'medhira-concurrency-utils';

async function processAll(items, processItem) {
  const concurrency = getDynamicConcurrency();
  const results = [];

  for (let i = 0; i < items.length; i += concurrency) {
    const chunk = items.slice(i, i + concurrency);
    const chunkResults = await Promise.all(chunk.map(processItem));
    results.push(...chunkResults);
  }

  return results;
}

API

getDynamicConcurrency(options?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | memoryLimitThreshold | number | 0.8 | Memory usage ratio (0, 1] above which concurrency is reduced | | loadThreshold | number | 0.7 | Load average ratio (0, 1] relative to CPU count | | memoryPerWorkerMB | number | 512 | Estimated memory per worker (MB) for capacity calculation |

Returns: number — optimal concurrent operations (always ≥ 1)

TypeScript

import {
  getDynamicConcurrency,
  type GetDynamicConcurrencyOptions,
} from 'medhira-concurrency-utils';

const options: GetDynamicConcurrencyOptions = {
  memoryLimitThreshold: 0.7,
  loadThreshold: 0.6,
  memoryPerWorkerMB: 256,
};

const concurrency: number = getDynamicConcurrency(options);

How It Works

flowchart TD
    A([getDynamicConcurrency]) --> B[Read CPU count, load average, memory]
    B --> C{Memory above threshold<br/>OR load above threshold?}
    C -->|Yes| D["Return max(1, floor(cpuCount / 2))"]
    C -->|No| E["Return min(cpuCount × 2,<br/>floor(memoryLimit / memoryPerWorker))"]
    D --> F([Result ≥ 1])
    E --> F

Platform note: On Windows, os.loadavg() returns zeros — load-based reduction is skipped and only memory metrics are used.

Use Cases

• Parallel processing — chunk arrays and run Promise.all per batch
• Worker threads — size pools dynamically with worker_threads
• Batch pipelines — throttle DB inserts, file I/O, or API calls

See the full documentation for detailed examples.

Documentation

| Resource | Link | |----------|------| | Full docs | medhira-concurrency-utils.readthedocs.io | | API reference | getDynamicConcurrency | | GitHub | HELLOMEDHIRA/medhira-concurrency-utils |

Contributing

Contributions are welcome! See Contributing Guide for setup and PR guidelines.

Support

For sponsorship, private support, or customization: [email protected]

License

Apache-2.0 — Copyright © 2026 MEDHIRA