Piscina

Piscina is a Node.js worker thread pool library that makes it straightforward to offload CPU-intensive or blocking work onto a pool of worker_threads, with fast structured-clone-based communication, flexible pool sizing, task cancellation, and backpressure support. It handles both fixed-task and variable-task workloads, tracks run/wait-time statistics, and supports optional memory resource limits per worker.

Written in TypeScript and maintained by contributors close to Node.js core (including a former Node.js TSC member), it targets modern Node.js versions and supports CommonJS, ESM, and TypeScript consumers out of the box.

What You Get

• A Piscina pool class with configurable minThreads/maxThreads and idle timeout
• Promise-based task dispatch with cancellation via AbortSignal
• Backpressure signaling (drain/needsDrain events) for high-throughput producers
• Per-worker memory resource limits and CPU scheduling priority (Linux)
• Built-in run/wait-time statistics via a histogram for pool performance monitoring

Common Use Cases

• Offloading CPU-bound computation (image processing, parsing, hashing) from the Node.js event loop
• Running a fixed pool of worker threads to parallelize batch or queue-processing jobs
• Isolating untrusted or memory-heavy work behind per-worker memory limits
• Building throughput-sensitive services that need backpressure-aware task dispatch

Under The Hood

Architecture Piscina’s core (src/main.ts, src/worker_pool) manages a pool of worker_threads workers, each running a shared src/worker.ts bootstrap that loads the user’s task file and executes it on message. The main-thread Piscina class (src/index.ts/main.ts) queues incoming run() calls (src/task_queue), assigns them to idle workers, and resolves the caller’s promise when the worker posts a result back; src/histogram.ts tracks run/wait-time statistics and src/abort.ts wires AbortSignal-based cancellation through to in-flight tasks.

Tech Stack Pure TypeScript targeting modern Node.js (engines.node >= 22.x in the current line), built with tsc and distributed as both CommonJS and an ESM wrapper (gen-esm-wrapper) from dist/. Test and benchmark tooling includes a custom test runner (scripts/run-tests.js), Jest for a subset of tests, and a dedicated benchmark suite comparing pool configurations.

Code Quality The repo maintains a real benchmark suite (benchmark/index.js) alongside its test suite and a test:coverage script, plus strict linting (eslint + tsc --noEmit across both source and test tsconfigs). Active maintenance from Node.js-core-adjacent maintainers (jasnell, metcoder95, addaleax) and 50 contributors signals sustained code review rigor.

API Design The API surface is intentionally small — construct a Piscina with pool options, call run(task, options), listen for a few events (error, drain, needsDrain, message) — which keeps the learning curve low despite the underlying complexity of thread-pool management; documented readonly properties (completed, duration, options) give visibility into pool health without extra instrumentation.