TypeScripttypescriptasyncconcurrencypromiseproduction-ready

Promise Pool with Concurrency Control

Execute async tasks with bounded concurrency, progress tracking, and error collection without overwhelming downstream services.

interface PoolOptions {
  concurrency: number;
  stopOnError?: boolean;
  onProgress?: (completed: number, total: number) => void;
}

interface PoolResult<T> {
  results: T[];
  errors: { index: number; error: unknown }[];
  duration: number;
}

export async function promisePool<TInput, TOutput>(
  items: TInput[],
  fn: (item: TInput, index: number) => Promise<TOutput>,
  options: PoolOptions
): Promise<PoolResult<TOutput>> {
  const { concurrency, stopOnError = false, onProgress } = options;
  const results: TOutput[] = new Array(items.length);
  const errors: { index: number; error: unknown }[] = [];
  const startTime = Date.now();

  let currentIndex = 0;
  let completed = 0;
  let aborted = false;

  async function worker(): Promise<void> {
    while (currentIndex < items.length && !aborted) {
      const index = currentIndex++;
      try {
        results[index] = await fn(items[index], index);
      } catch (error) {
        errors.push({ index, error });
        if (stopOnError) {
          aborted = true;
          return;
        }
      }
      completed++;
      onProgress?.(completed, items.length);
    }
  }

  // Spawn workers up to concurrency limit
  const workers = Array.from(
    { length: Math.min(concurrency, items.length) },
    () => worker()
  );

  await Promise.all(workers);

  return {
    results: results.filter((_, i) => !errors.some((e) => e.index === i)),
    errors,
    duration: Date.now() - startTime,
  };
}

// Variant: async generator for streaming results
export async function* promisePoolStream<TInput, TOutput>(
  items: TInput[],
  fn: (item: TInput) => Promise<TOutput>,
  concurrency: number
): AsyncGenerator<{ index: number; result: TOutput } | { index: number; error: unknown }> {
  const executing = new Map<number, Promise<{ index: number; result?: TOutput; error?: unknown }>>();
  let nextIndex = 0;

  while (nextIndex < items.length || executing.size > 0) {
    while (executing.size < concurrency && nextIndex < items.length) {
      const index = nextIndex++;
      const promise = fn(items[index])
        .then((result) => ({ index, result }))
        .catch((error) => ({ index, error }));
      executing.set(index, promise);
    }

    if (executing.size > 0) {
      const settled = await Promise.race(executing.values());
      executing.delete(settled.index);
      if ("error" in settled) {
        yield { index: settled.index, error: settled.error };
      } else {
        yield { index: settled.index, result: settled.result! };
      }
    }
  }
}

title: "Promise Pool with Concurrency Control" description: "Execute async tasks with bounded concurrency, progress tracking, and error collection without overwhelming downstream services." category: "TypeScript" language: "typescript" tags: ["typescript", "async", "concurrency", "promise", "production-ready"] createdAt: "2025-03-05" updatedAt: "2025-03-25"

Overview

A bounded concurrency pool for executing async tasks in parallel without overwhelming downstream services. Unlike Promise.all() which runs everything at once, this limits concurrent executions while maintaining order and collecting both successes and failures.

Code

const { results, errors, duration } = await promisePool(
  items,
  async (item) => processItem(item),
  { concurrency: 10, stopOnError: false }
);

Notes

  • Results array preserves the original input order regardless of completion order
  • The stopOnError option provides fail-fast behavior for critical batch operations
  • The streaming variant (promisePoolStream) yields results as they complete, useful for pipelines
  • Concurrency of 10-20 is typical for HTTP requests; use lower values for database writes
  • Memory usage stays bounded since only concurrency promises execute simultaneously