A pool library. Not that kind.

A small task pool for async work that needs throughput, ordering, and cancellation.

Install · Example · Model · Usage · API

Install

npm install billiards@alpha

Example

import { createPool } from "billiards"

const pool = createPool({
  concurrency: 50,
  perKeyConcurrency: 1,
})

await pool.map(events, processEvent, {
  key: event => event.accountId,
})

This runs up to 50 tasks at once, while allowing only one running task for each accountId.

Model

Most task pools expose one limit.

createPool({
  concurrency: 50,
})

billiards also supports a per-key limit.

createPool({
  concurrency: 50,
  perKeyConcurrency: 1,
})

Use it when work can run concurrently across a system, but must remain serialized for the same account, tenant, customer, file, user, webhook, or external resource.

Features

bounded global concurrency
keyed concurrency
input-order mapping
completion-order streaming
retries
timeouts
cancellation
producer backpressure
runtime resizing
zero runtime dependencies

Usage

See USAGE.md for examples and API.md for exact signatures, exported types, and edge-case contracts.