zeroworker

zeroworker is a library for Node.js and the Browser that provides a wrapper around the Web Worker API. It allows execution of pure functions in background threads and provides a queuing pool for concurrency management.

By explicitly providing Transferable objects (like ArrayBuffer), data can be transferred to workers without the overhead of structured cloning. The library auto-detects ArrayBuffer objects in the return payload and transfers them back to the main thread.

Installation

npm install zeroworker

Usage

Functions passed to zeroworker must be pure and contain no closures over external scope. The library serializes the function via Function.toString().

import { ZeroWorker } from 'zeroworker';

// Initialize a worker with a pure function
const worker = new ZeroWorker((data: Uint8Array) => {
  for (let i = 0; i < data.length; i++) {
    data[i] = data[i] * 2; 
  }
  return data;
});

// Execute with explicitly defined transferables to avoid copying
const buffer = new Uint8Array(1024 * 1024 * 50); // 50 MB
const result = await worker.execute(buffer, { transferables: [buffer.buffer] });

Constraints

• Closures: Variables from the outer scope cannot be accessed inside the worker logic.
• Serialization: Native code or bound functions cannot be serialized. Arrow functions without blocks (implicit returns) or arrow functions relying on this context are not supported.
• Transferables: To achieve zero-copy, you must manually extract the .buffer property of TypedArrays and pass it in the transferables option array. Failure to do so will result in a structured clone operation.

API Reference

ZeroWorker

A single worker thread wrapper.

• constructor(workerLogic: WorkerFunction | string, setupLogic?: SetupFunction | string) Initializes the worker. workerLogic is the function executed for tasks. setupLogic is an optional function executed once during initialization for state setup.
• initialize(setupPayload?: any): Promise<void> Must be called if setupLogic was provided.
• execute(payload: any, options?: ExecuteOptions): Promise<any> Sends a payload to the thread. Returns a Promise resolving to the output.
  • options.transferables: Array of ArrayBuffer or MessagePort objects.
  • options.timeout: Execution timeout in milliseconds.
• terminate(): void Terminates the worker and rejects pending promises.

WorkerPool

A queue that manages multiple ZeroWorker instances.

• constructor(workerLogic: WorkerFunction | string, setupLogic?: SetupFunction | string, options?: WorkerPoolOptions)
  • options.maxWorkers: Maximum number of spawned workers (defaults to navigator.hardwareConcurrency or available CPU cores).
• initialize(setupPayload?: any): Promise<void> Bootstraps all workers in the pool.
• execute(payload: any, options?: ExecuteOptions): Promise<any> Enqueues a task. Tasks are routed to idle workers or queued.
• terminate(): void Terminates all workers and clears the queue.

License

MIT License