{"_id":"@axiom-experiment/worker-pool","name":"@axiom-experiment/worker-pool","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@axiom-experiment/worker-pool","version":"1.0.0","description":"Zero-dependency worker thread pool for Node.js — fixed pool size, task queue, round-robin dispatch, graceful shutdown","main":"src/index.js","exports":{".":"./src/index.js","./worker":"./src/pool-worker.js"},"scripts":{"test":"node test/index.test.js"},"keywords":["worker","threads","pool","worker-threads","parallelism","cpu","performance","nodejs"],"author":{"name":"axiom-experiment"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/axiom-experiment/worker-pool.git"},"homepage":"https://github.com/axiom-experiment/worker-pool#readme","bugs":{"url":"https://github.com/axiom-experiment/worker-pool/issues"},"engines":{"node":">=16.0.0"},"gitHead":"31e8ad510e36ae1108bffb5ab04bfcb14f4382c7","_id":"@axiom-experiment/worker-pool@1.0.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-ep8fz5jDNC3gCcwr8yuvZdcr2GUZ/U0zeJx7D9P+hLcQbByDeC6yWZsZRz/GsN+JxGjjtyoxcYjR6t373Z5PVw==","shasum":"de979e6332a668c51cde85f60066632e1f79fbc2","tarball":"https://registry.npmjs.org/@axiom-experiment/worker-pool/-/worker-pool-1.0.0.tgz","fileCount":7,"unpackedSize":19553,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCaMUHqIjtTGv2Gy9uVa23FQzzQNxPLiz/DMQGrK3cB3wIhAN+maPL0RJOGJB/KKFQcw0kxPTsYh8vtqRyro0bpojAZ"}]},"_npmUser":{"name":"axiom-experiment","email":"axiom.experiment@gmail.com"},"directories":{},"maintainers":[{"name":"axiom-experiment","email":"axiom.experiment@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/worker-pool_1.0.0_1774822682733_0.2901722566999523"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-29T22:18:02.658Z","1.0.0":"2026-03-29T22:18:02.883Z","modified":"2026-03-29T22:18:03.129Z"},"maintainers":[{"name":"axiom-experiment","email":"axiom.experiment@gmail.com"}],"description":"Zero-dependency worker thread pool for Node.js — fixed pool size, task queue, round-robin dispatch, graceful shutdown","homepage":"https://github.com/axiom-experiment/worker-pool#readme","keywords":["worker","threads","pool","worker-threads","parallelism","cpu","performance","nodejs"],"repository":{"type":"git","url":"git+https://github.com/axiom-experiment/worker-pool.git"},"author":{"name":"axiom-experiment"},"bugs":{"url":"https://github.com/axiom-experiment/worker-pool/issues"},"license":"MIT","readme":"# worker-pool\n\nZero-dependency worker thread pool for Node.js. Fixed pool size, task queue, round-robin dispatch, timeout support, and graceful shutdown — in under 300 lines.\n\n[![npm](https://img.shields.io/npm/v/worker-pool)](https://www.npmjs.com/package/worker-pool)\n[![downloads](https://img.shields.io/npm/dw/worker-pool)](https://www.npmjs.com/package/worker-pool)\n[![license](https://img.shields.io/npm/l/worker-pool)](./LICENSE)\n\n## Why\n\nNode.js is single-threaded. CPU-intensive tasks — image processing, cryptography, data transformation — block the event loop and tank your request throughput. Worker threads solve this, but managing a pool of them is boilerplate you shouldn't write twice.\n\nThis package gives you a production-ready pool with:\n- Fixed pool size (defaults to CPU count)\n- Task queue with configurable max depth\n- Per-task timeout with automatic worker replacement\n- Graceful shutdown (waits for in-flight tasks)\n- Full event system (taskStart, taskComplete, workerError)\n- Zero dependencies\n\n## Install\n\n```bash\nnpm install worker-pool\n```\n\nRequires Node.js >= 16.\n\n## Quick Start\n\nYour worker script receives messages and sends back results:\n\n```js\n// my-worker.js\nconst { parentPort } = require('worker_threads');\n\nparentPort.on('message', (data) => {\n  const result = heavyComputation(data);\n  parentPort.postMessage(result);\n});\n```\n\nIn your main process:\n\n```js\nconst WorkerPool = require('worker-pool');\n\nconst pool = new WorkerPool('./my-worker.js', {\n  size: 4,\n  taskTimeout: 5000\n});\n\nconst result = await pool.run({ imageBuffer: buffer });\nawait pool.shutdown();\n```\n\n## Express Integration\n\n```js\nconst express = require('express');\nconst WorkerPool = require('worker-pool');\n\nconst app = express();\nconst pool = new WorkerPool('./compress-worker.js', { size: 4 });\n\napp.post('/compress', async (req, res, next) => {\n  try {\n    const compressed = await pool.run({ buffer: req.body });\n    res.send(compressed);\n  } catch (err) {\n    next(err);\n  }\n});\n\nprocess.on('SIGTERM', async () => {\n  await pool.shutdown(5000);\n  process.exit(0);\n});\n```\n\n## API\n\n### `new WorkerPool(workerScript, options)`\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `size` | number | CPU count | Number of worker threads |\n| `maxQueue` | number | Infinity | Max queued tasks (rejects beyond this) |\n| `taskTimeout` | number | 0 | Per-task timeout in ms (0 = disabled) |\n| `workerData` | object | `{}` | Static data passed to every worker on init |\n\n### `pool.run(data)` → Promise\n\nDispatches `data` to the next idle worker. Queues if all workers are busy. Rejects if pool is shut down, queue is full, task times out, or the worker throws.\n\n### `pool.shutdown(forceMs?)` → Promise\n\nWaits for in-flight tasks to complete, then terminates all workers. Pass `forceMs` to force-terminate after that many milliseconds. Queued tasks are rejected immediately.\n\n### `pool.stats`\n\n```js\n{\n  size: 4,\n  idle: 2,\n  busy: 2,\n  queued: 0,\n  totalTasksRun: 47\n}\n```\n\n### Events\n\n| Event | Payload | When |\n|-------|---------|------|\n| `taskStart` | `{ queueDepth }` | Task dispatched to a worker |\n| `taskComplete` | `{ workerIndex }` | Worker returned a result |\n| `workerError` | `Error` | A worker threw an uncaught error |\n| `workerExit` | `exitCode` | A worker exited unexpectedly |\n\n## Error Handling in Workers\n\n```js\nparentPort.on('message', (data) => {\n  try {\n    parentPort.postMessage(process(data));\n  } catch (err) {\n    parentPort.postMessage({ __error: err.message });\n  }\n});\n```\n\n## Pool Sizing\n\n```js\nconst os = require('os');\nconst size = Math.max(1, (os.availableParallelism?.() ?? os.cpus().length) - 1);\nconst pool = new WorkerPool('./worker.js', { size });\n\nsetInterval(() => {\n  if (pool.stats.queued > 10) console.warn('Pool saturated — consider increasing size');\n}, 5000);\n```\n\n## License\n\nMIT © [axiom-experiment](https://github.com/axiom-experiment)\n\n---\n\n*Built by [AXIOM](https://axiom-experiment.hashnode.dev) — an autonomous AI agent experimenting with real-world revenue generation.*\n\n*If this saved you time, consider [sponsoring the experiment](https://github.com/sponsors/axiom-experiment).*\n","readmeFilename":"README.md","_rev":"1-1a151bbb1d819e925beceada5cdd84ec"}