concurrent-pool

A lightweight LIFO concurrent pool with retry queue support.

Features

• LIFO scheduling based on a stack
• Keeps the pool as full as possible up to the configured concurrency
• Failed tasks move into a retry queue and return to the stack after a delay
• Promise-based API with TypeScript types

Installation

npm install concurrent-pool

Usage

import { ConcurrentPool, RetryLimitExceededError } from "concurrent-pool";

const pool = new ConcurrentPool<string>({
  concurrency: 3,
  defaultMaxRetries: 2,
  defaultRetryDelay: (attempt) => attempt * 500
});

const tasks = pool.addMany([
  {
    id: "task-1",
    run: async () => {
      return "done-1";
    }
  },
  {
    id: "task-2",
    run: async () => {
      throw new Error("temporary failure");
    }
  }
]);

const results = await Promise.allSettled(tasks);
await pool.onIdle();

for (const result of results) {
  if (result.status === "rejected" && result.reason instanceof RetryLimitExceededError) {
    console.error(result.reason.taskId, result.reason.attempts);
  }
}

API

new ConcurrentPool(options)

Creates a pool instance.

options:

• concurrency: maximum number of running tasks
• defaultMaxRetries: default retry count after the first failure
• defaultRetryDelay: retry delay in milliseconds or a resolver function

pool.add(task)

Adds a single task and returns its promise.

task:

• id: optional task id used in error reporting
• run: async task executor
• maxRetries: retry count after the first failed attempt
• retryDelay: delay before the failed task returns to the pending stack

pool.addMany(tasks)

Adds multiple tasks and returns an array of promises.

pool.stats()

Returns the current pool snapshot:

• pending
• running
• failedWaitingRetry

pool.onIdle()

Resolves when there are no pending, running, or retry-waiting tasks left.

RetryLimitExceededError

Thrown when a task still fails after all retries.

Properties:

• taskId
• attempts
• cause

Publish

npm run check
npm run build
npm publish

If the package name is already taken on npm, update the name field in package.json before publishing.

Build Tool

This package uses tsdown to generate the publishable output in dist/.