node-worker-pool-lite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arman Mikoyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# Worker Pool
+
+A lightweight Node.js `worker_threads` pool with callback and Promise APIs.
+
+Worker Pool helps you move CPU-heavy work off the main event loop while keeping a small, predictable API. It supports named worker tasks, a fixed-size worker pool, queued jobs, worker replacement after failures, and TypeScript declarations.
+
+## Features
+
+- Callback-first API from the main package entrypoint.
+- Promise API from `worker-pool/promise`.
+- Named task handlers inside worker files.
+- Automatic task queueing when all workers are busy.
+- Worker error propagation to callbacks or rejected promises.
+- Graceful shutdown with `pool.destroy()`.
+- ESM and TypeScript declaration support.
+
+## Requirements
+
+- Node.js 18 or newer.
+- ESM projects, or files using `.mjs` / `"type": "module"`.
+
+## Installation
+
+```sh
+npm install worker-pool
+```
+
+If you publish this under a scoped package name, install it with your final package name instead:
+
+```sh
+npm install @your-username/worker-pool
+```
+
+## Quick Start
+
+Create a worker file with named task handlers:
+
+```js
+// worker.js
+import { createWorkerHandler } from 'worker-pool';
+
+createWorkerHandler({
+  double(value) {
+    return value * 2;
+  },
+
+  async hashPassword(input) {
+    return runExpensiveHash(input);
+  },
+});
+```
+
+Run tasks with the callback API:
+
+```js
+// index.js
+import { WorkerPool } from 'worker-pool';
+
+const pool = new WorkerPool(new URL('./worker.js', import.meta.url), {
+  size: 4,
+});
+
+pool.run('double', 21, async (error, result) => {
+  if (error) {
+    console.error(error);
+    await pool.destroy();
+    return;
+  }
+
+  console.log(result); // 42
+  await pool.destroy();
+});
+```
+
+## Promise API
+
+Import from `worker-pool/promise` when you prefer `async` / `await`:
+
+```js
+import { WorkerPool } from 'worker-pool/promise';
+
+const pool = new WorkerPool(new URL('./worker.js', import.meta.url), {
+  size: 4,
+});
+
+try {
+  const result = await pool.run('double', 21);
+  console.log(result); // 42
+} finally {
+  await pool.destroy();
+}
+```
+
+## Worker Tasks
+
+Workers are registered with `createWorkerHandler()`. Each key is the task name used by `pool.run()`.
+
+```js
+import { createWorkerHandler } from 'worker-pool';
+
+createWorkerHandler({
+  resizeImage(payload) {
+    return resizeImage(payload);
+  },
+
+  generateReport(payload) {
+    return generateReport(payload);
+  },
+});
+```
+
+Handlers may be synchronous or asynchronous. If a handler throws, the error is passed to the callback API or rejects the Promise API.
+
+## API
+
+### `new WorkerPool(workerUrl, options)`
+
+Creates a fixed-size pool of worker threads.
+
+- `workerUrl`: a worker file URL or path passed to Node.js `new Worker()`.
+- `options.size`: number of workers to start. Defaults to one less than the available CPU count.
+- `options.workerOptions`: extra options passed to Node.js `new Worker()`.
+
+```js
+const pool = new WorkerPool(new URL('./worker.js', import.meta.url), {
+  size: 4,
+  workerOptions: {
+    resourceLimits: {
+      maxOldGenerationSizeMb: 128,
+    },
+  },
+});
+```
+
+### `pool.run(name, payload, callback)`
+
+Queues a named task and calls `callback(error, result)` when the task completes.
+
+```js
+pool.run('double', 21, (error, result) => {
+  if (error) {
+    console.error(error);
+    return;
+  }
+
+  console.log(result);
+});
+```
+
+You can omit `payload` for tasks that do not need input:
+
+```js
+pool.run('refreshCache', error => {
+  if (error) {
+    console.error(error);
+  }
+});
+```
+
+### `pool.run(name, payload)` from `worker-pool/promise`
+
+Queues a named task and returns a promise.
+
+```js
+const result = await pool.run('double', 21);
+```
+
+### `pool.destroy()`
+
+Terminates all workers and rejects queued work.
+
+```js
+await pool.destroy();
+```
+
+### `createWorkerHandler(handlers)`
+
+Registers named task handlers inside a worker file.
+
+```js
+createWorkerHandler({
+  taskName(payload) {
+    return doWork(payload);
+  },
+});
+```
+
+## Examples
+
+This repository includes runnable examples:
+
+```sh
+node examples/basic.js
+node examples/promise.js
+```
+
+## Development
+
+Run the test suite:
+
+```sh
+npm test
+```
+
+Preview the package contents before publishing:
+
+```sh
+npm pack --dry-run
+```
+
+## Publishing Notes
+
+Before publishing to npm:
+
+- Choose a unique package name and update `package.json`.
+- Add `author`, `repository`, `homepage`, and `bugs` fields to `package.json`.
+- Update `LICENSE` with your name.
+- Run `npm test` and `npm pack --dry-run`.
+- Publish scoped public packages with `npm publish --access public`.
+
+## License
+
+MIT

package/examples/basic.js

@@ -0,0 +1,24 @@
+import { WorkerPool } from '../lib/index.js';
+
+const pool = new WorkerPool(new URL('./prime-worker.js', import.meta.url), {
+  size: 3,
+});
+
+let pendingTasks = 2;
+
+pool.run('primes', { count: 10 }, handleResult);
+pool.run('primes', { count: 20 }, handleResult);
+
+async function handleResult(error, primes) {
+  pendingTasks -= 1;
+
+  if (error) {
+    console.error(error);
+  } else {
+    console.log(primes);
+  }
+
+  if (pendingTasks === 0) {
+    await pool.destroy();
+  }
+}

package/examples/prime-worker.js

@@ -0,0 +1,36 @@
+import { createWorkerHandler } from '../lib/index.js';
+
+createWorkerHandler({
+  primes({ count = 1 } = {}) {
+    return generatePrimes(count);
+  },
+});
+
+function generatePrimes(count) {
+  const primes = [];
+  let candidate = 2;
+
+  while (primes.length < count) {
+    if (isPrime(candidate)) {
+      primes.push(candidate);
+    }
+
+    candidate += 1;
+  }
+
+  return primes;
+}
+
+function isPrime(value) {
+  if (value < 2) {
+    return false;
+  }
+
+  for (let divisor = 2; divisor * divisor <= value; divisor += 1) {
+    if (value % divisor === 0) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/examples/promise.js

@@ -0,0 +1,17 @@
+import { WorkerPool } from '../lib/promise.js';
+
+const pool = new WorkerPool(new URL('./prime-worker.js', import.meta.url), {
+  size: 3,
+});
+
+try {
+  const [firstBatch, secondBatch] = await Promise.all([
+    pool.run('primes', { count: 10 }),
+    pool.run('primes', { count: 20 }),
+  ]);
+
+  console.log(firstBatch);
+  console.log(secondBatch);
+} finally {
+  await pool.destroy();
+}

package/lib/index.d.ts

@@ -0,0 +1,41 @@
+import type { WorkerOptions } from 'node:worker_threads';
+
+export interface WorkerPoolOptions {
+  size?: number;
+  workerOptions?: WorkerOptions;
+}
+
+export type WorkerTaskHandler<TPayload = unknown, TResult = unknown> = (
+  payload: TPayload,
+) => TResult | Promise<TResult>;
+
+export type WorkerTaskCallback<TResult = unknown> = (
+  error: Error | null,
+  result?: TResult,
+) => void;
+
+export class WorkerPool {
+  constructor(workerUrl: URL | string, options?: WorkerPoolOptions);
+
+  readonly size: number;
+  readonly queuedTaskCount: number;
+  readonly busyWorkerCount: number;
+  readonly idleWorkerCount: number;
+
+  run<TPayload = unknown, TResult = unknown>(
+    name: string,
+    payload: TPayload,
+    callback: WorkerTaskCallback<TResult>,
+  ): void;
+
+  run<TResult = unknown>(
+    name: string,
+    callback: WorkerTaskCallback<TResult>,
+  ): void;
+
+  destroy(): Promise<void>;
+}
+
+export function createWorkerHandler(
+  handlers: Record<string, WorkerTaskHandler>,
+): void;

package/lib/index.js

@@ -0,0 +1 @@
+export { WorkerPool, createWorkerHandler } from './worker-pool.js';

package/lib/promise-worker-pool.js

@@ -0,0 +1,18 @@
+import { WorkerPool as CallbackWorkerPool, createWorkerHandler } from './worker-pool.js';
+
+export { createWorkerHandler };
+
+export class WorkerPool extends CallbackWorkerPool {
+  run(name, payload) {
+    return new Promise((resolve, reject) => {
+      super.run(name, payload, (error, result) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+
+        resolve(result);
+      });
+    });
+  }
+}

package/lib/promise.d.ts

@@ -0,0 +1,24 @@
+import type { WorkerPoolOptions } from './index.js';
+
+export type {
+  WorkerPoolOptions,
+  WorkerTaskHandler,
+} from './index.js';
+
+export { createWorkerHandler } from './index.js';
+
+export class WorkerPool {
+  constructor(workerUrl: URL | string, options?: WorkerPoolOptions);
+
+  readonly size: number;
+  readonly queuedTaskCount: number;
+  readonly busyWorkerCount: number;
+  readonly idleWorkerCount: number;
+
+  run<TPayload = unknown, TResult = unknown>(
+    name: string,
+    payload?: TPayload,
+  ): Promise<TResult>;
+
+  destroy(): Promise<void>;
+}

package/lib/promise.js

@@ -0,0 +1 @@
+export { WorkerPool, createWorkerHandler } from './promise-worker-pool.js';

package/lib/worker-pool.js

@@ -0,0 +1,243 @@
+import os from 'node:os';
+import { Worker, parentPort as defaultParentPort } from 'node:worker_threads';
+
+export class WorkerPool {
+  #idleWorkers = [];
+  #isDestroyed = false;
+  #queue = [];
+  #runningTasks = new Map();
+  #workerOptions;
+  #workerUrl;
+  #workers = new Set();
+
+  constructor(workerUrl, options = {}) {
+    if (!workerUrl) {
+      throw new TypeError('WorkerPool requires a worker file URL or path.');
+    }
+
+    const size = options.size ?? defaultPoolSize();
+    if (!Number.isInteger(size) || size < 1) {
+      throw new RangeError('WorkerPool size must be a positive integer.');
+    }
+
+    this.size = size;
+    this.#workerUrl = workerUrl;
+    this.#workerOptions = options.workerOptions ?? {};
+
+    for (let index = 0; index < this.size; index += 1) {
+      this.#spawnWorker();
+    }
+  }
+
+  get queuedTaskCount() {
+    return this.#queue.length;
+  }
+
+  get busyWorkerCount() {
+    return this.#runningTasks.size;
+  }
+
+  get idleWorkerCount() {
+    return this.#idleWorkers.length;
+  }
+
+  run(name, payload, callback) {
+    if (typeof payload === 'function') {
+      callback = payload;
+      payload = undefined;
+    }
+
+    if (typeof callback !== 'function') {
+      throw new TypeError('WorkerPool.run requires a callback function.');
+    }
+
+    if (this.#isDestroyed) {
+      queueMicrotask(() => callback(new Error('WorkerPool has been destroyed.')));
+      return;
+    }
+
+    if (typeof name !== 'string' || name.length === 0) {
+      queueMicrotask(() => callback(new TypeError('Task name must be a non-empty string.')));
+      return;
+    }
+
+    this.#queue.push({
+      callback,
+      message: { name, payload },
+    });
+
+    this.#dispatch();
+  }
+
+  async destroy() {
+    if (this.#isDestroyed) {
+      return;
+    }
+
+    this.#isDestroyed = true;
+
+    const destroyError = new Error('WorkerPool was destroyed before the task completed.');
+    for (const task of this.#queue.splice(0)) {
+      this.#completeTask(task, destroyError);
+    }
+
+    const terminations = [...this.#workers].map(worker => worker.terminate());
+    this.#idleWorkers = [];
+
+    await Promise.allSettled(terminations);
+  }
+
+  #dispatch() {
+    while (!this.#isDestroyed && this.#idleWorkers.length > 0 && this.#queue.length > 0) {
+      const worker = this.#idleWorkers.shift();
+
+      if (!this.#workers.has(worker)) {
+        continue;
+      }
+
+      const task = this.#queue.shift();
+      this.#runningTasks.set(worker, task);
+
+      try {
+        worker.postMessage(task.message);
+      } catch (error) {
+        this.#runningTasks.delete(worker);
+        this.#idleWorkers.push(worker);
+        this.#completeTask(task, error);
+      }
+    }
+  }
+
+  #handleMessage(worker, message) {
+    const task = this.#runningTasks.get(worker);
+    if (!task) {
+      return;
+    }
+
+    this.#runningTasks.delete(worker);
+
+    if (isWorkerResult(message)) {
+      if (message.ok) {
+        this.#completeTask(task, null, message.value);
+      } else {
+        this.#completeTask(task, createWorkerError(message.error));
+      }
+    } else {
+      this.#completeTask(task, null, message);
+    }
+
+    if (!this.#isDestroyed && this.#workers.has(worker)) {
+      this.#idleWorkers.push(worker);
+      this.#dispatch();
+    }
+  }
+
+  #retireWorker(worker, error) {
+    if (!this.#workers.has(worker)) {
+      return;
+    }
+
+    this.#workers.delete(worker);
+    this.#idleWorkers = this.#idleWorkers.filter(idleWorker => idleWorker !== worker);
+
+    const task = this.#runningTasks.get(worker);
+    if (task) {
+      this.#runningTasks.delete(worker);
+      this.#completeTask(task, error);
+    }
+
+    if (!this.#isDestroyed) {
+      this.#spawnWorker();
+      this.#dispatch();
+    }
+  }
+
+  #spawnWorker() {
+    const worker = new Worker(this.#workerUrl, this.#workerOptions);
+
+    worker.on('message', message => {
+      this.#handleMessage(worker, message);
+    });
+
+    worker.on('error', error => {
+      this.#retireWorker(worker, error);
+    });
+
+    worker.on('exit', code => {
+      const error = code === 0
+        ? new Error('Worker exited before completing its current task.')
+        : new Error(`Worker exited with code ${code}.`);
+
+      this.#retireWorker(worker, error);
+    });
+
+    this.#workers.add(worker);
+    this.#idleWorkers.push(worker);
+  }
+
+  #completeTask(task, error, result) {
+    queueMicrotask(() => {
+      task.callback(error, result);
+    });
+  }
+}
+
+export function createWorkerHandler(handlers, options = {}) {
+  const port = options.parentPort ?? defaultParentPort;
+
+  if (!port) {
+    throw new Error('createWorkerHandler must be called inside a worker thread.');
+  }
+
+  if (!handlers || typeof handlers !== 'object') {
+    throw new TypeError('Task handlers must be provided as an object.');
+  }
+
+  port.on('message', async ({ name, payload }) => {
+    try {
+      const handler = handlers[name];
+
+      if (typeof handler !== 'function') {
+        throw new Error(`Unknown task: ${String(name)}`);
+      }
+
+      const value = await handler(payload);
+      port.postMessage({ ok: true, value });
+    } catch (error) {
+      port.postMessage({ ok: false, error: serializeError(error) });
+    }
+  });
+}
+
+function defaultPoolSize() {
+  const availableParallelism = os.availableParallelism?.() ?? os.cpus().length;
+  return Math.max(1, availableParallelism - 1);
+}
+
+function isWorkerResult(message) {
+  return Boolean(
+    message
+    && typeof message === 'object'
+    && Object.hasOwn(message, 'ok')
+    && typeof message.ok === 'boolean',
+  );
+}
+
+function serializeError(error) {
+  return {
+    message: error instanceof Error ? error.message : String(error),
+    name: error instanceof Error ? error.name : 'Error',
+    stack: error instanceof Error ? error.stack : undefined,
+  };
+}
+
+function createWorkerError(error) {
+  const workerError = new Error(error?.message ?? 'Worker task failed.');
+  workerError.name = error?.name ?? 'WorkerTaskError';
+
+  if (error?.stack) {
+    workerError.stack = error.stack;
+  }
+
+  return workerError;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "node-worker-pool-lite",
+  "author": "Arman Mikoyan <arman@mikoyan1@gmail.com>",
+  "version": "0.1.0",
+  "description": "A lightweight callback and promise worker_threads pool for Node.js.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    },
+    "./promise": {
+      "types": "./lib/promise.d.ts",
+      "import": "./lib/promise.js"
+    }
+  },
+  "files": [
+    "lib",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "worker_threads",
+    "worker-pool",
+    "thread-pool",
+    "concurrency",
+    "pool",
+    "parallelism",
+    "cpu-intensive"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}