WebWorker and Node Worker Threads wrapper with better usability.
npm install @cloudpss/worker
Provide WebWorker and Node Worker Threads wrapper with better usability. Include:
- WebWorker polyfill/ponyfill for Node.js environment.
- Worker thread pool implementation for both browser and Node.js environment.
``bash`
npm install @cloudpss/worker
In both Node.js and the browser you can use the ponyfill API instead of the global Worker:
`ts
// main.ts
import { Worker } from '@cloudpss/worker/ponyfill';
const worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
worker.addEventListener('message', (ev) => {
console.log('got from worker:', ev.data);
});
worker.postMessage({ hello: 'world' });
`
`ts
// worker.ts
import { onMessage, postMessage } from '@cloudpss/worker/ponyfill';
onMessage((value) => {
// value is the data of the incoming MessageEvent`
postMessage({ echo: value });
});
If you prefer to use the standard Worker global in Node.js, import the polyfill once at startup:
`ts
import '@cloudpss/worker/polyfill';
// Now Worker is available on globalThis in Node.js`
const worker = new Worker(new URL('./worker.js', import.meta.url), { type: 'module' });
The worker code can still use the ponyfill helpers:
`ts
import { onMessage, postMessage } from '@cloudpss/worker/ponyfill';
onMessage((value) => {
postMessage({ ok: true, value });
});
`
The worker pool lets you run many small tasks on a set of shared workers with automatic scaling and cleanup.
Define the worker script and expose the API:
`ts
// pool-worker.ts
import { expose } from '@cloudpss/worker/pool';
export default expose({
async sleep(ms: number, value?: unknown) {
await new Promise((resolve) => setTimeout(resolve, ms));
return value;
},
sum(...values: number[]) {
return values.reduce((a, b) => a + b, 0);
},
});
`
Create a pool and call the exposed methods from the main thread:
`ts
// main.ts
import { WorkerPool, type WorkerInterface } from '@cloudpss/worker/pool';
// Use import type to avoid runtime dependency
import type WorkerAPI from './pool-worker.js';
const pool = new WorkerPool
// Use a factory that creates a new Worker instance to make bundlers deal with it correctly
() => new Worker(new URL('./pool-worker.js', import.meta.url)),
{
maxWorkers: 4,
},
);
const result = await pool.call('sleep', [100, 'hello']);
console.log(result); // => 'hello'
// When you are done with the pool
pool.destroy();
`
- class Worker extends EventTarget
- Compatible with the standard Web Worker API (, terminate, message / messageerror / error events).worker_threads
- Uses under Node.js and the native Worker in the browser.function onMessage(handler: (value: unknown) => unknown): void
-
- Helper for worker-side code. Subscribes to the event and passes event.data to the handler.function postMessage(value: unknown, transfer?: Transferable[]): void
-
- Worker-side helper that forwards to the underlying implementation.const IS_WORKER_THREAD: boolean
-
- when running inside a worker, false in the main thread.const HARDWARE_CONCURRENCY: number
-
- Estimated number of hardware threads ( in browsers, os.availableParallelism() in Node.js).
- Side-effect-only module.
- Defines globalThis.Worker using the ponyfill implementation when it does not already exist (primarily for Node.js).
- class WorkerPool
-
- : JavaScript worker source, such as:Blob
- A string of worker code.
- A containing the code.URL
- A (including data: or blob: URLs).Worker
- A factory function returning any of the above or an existing /ponyfill Worker.options
- : see WorkerPoolOptions below.call
-
- Enqueues a call to on the pool and returns a Promise of the result.callWorker(...)
-
- Low-level variant that calls a specific instance from the pool.status(): { total: number; idle: number; busy: number; initializing: number }
-
- Returns current pool statistics.
-
- Aborts all pending work, terminates all workers, and frees resources.
- type WorkerFunction
- Signature of functions that can be exposed from a worker. May return a value, a , or a WorkerResult to control transferable objects.function WorkerResult
-
- Helper to create a object that wraps a result and a list of transferable objects.type WorkerInterface
-
- Maps a plain object of s to a callable TypeScript interface used as the generic parameter of WorkerPool.type WorkerMethods
- / type WorkerMethod
- Utility types that extract method names and signatures from a .interface WorkerPoolOptions
-
- – Name of the pool (used in error messages). Default: 'worker-pool'.maxWorkers?: number
- – Maximum number of workers in the pool. Default: HARDWARE_CONCURRENCY - 1, at least 1.minIdleWorkers?: number
- – Minimum number of idle workers to keep. Default: 0.idleTimeout?: number
- – Milliseconds before extra idle workers are cleaned up. 0 disables cleanup. Default: 5000.initTimeout?: number
- – Milliseconds to wait for a worker to signal readiness before failing. Default: 30000.creationDelay?: number
- – Delay before creating a new worker when the pool is already warm. Default: 0.workerOptions?: WorkerOptions
- – Extra options passed to the underlying Worker constructor (e.g. type, name).
- function expose
- Worker-side helper that exposes an object of functions to the main thread.
- Must be called exactly once inside a worker; it automatically sets up message handling and calls .function notifyReady(ready?: Promise
-
- Low-level worker-side API. Manually notifies the main thread that initialization has completed (successfully or with an error).
-
- Low-level main-thread API. Waits until the worker calls or until timeout/signal` aborts.
MIT