Worker - node__worker_threads.d.ts - Node

class Worker

extends EventEmitter

Usage in Deno

```typescript import { Worker } from "node:node__worker_threads.d.ts"; ```

> [!WARNING] Deno compatibility > The `getHeapSnapshot` method is not supported. The `Worker` class represents an independent JavaScript execution thread. Most Node.js APIs are available inside of it. Notable differences inside a Worker environment are: * The `process.stdin`, `process.stdout`, and `process.stderr` streams may be redirected by the parent thread. * The `import { isMainThread } from 'node:worker_threads'` variable is set to `false`. * The `import { parentPort } from 'node:worker_threads'` message port is available. * `process.exit()` does not stop the whole program, just the single thread, and `process.abort()` is not available. * `process.chdir()` and `process` methods that set group or user ids are not available. * `process.env` is a copy of the parent thread's environment variables, unless otherwise specified. Changes to one copy are not visible in other threads, and are not visible to native add-ons (unless `worker.SHARE_ENV` is passed as the `env` option to the `Worker` constructor). On Windows, unlike the main thread, a copy of the environment variables operates in a case-sensitive manner. * `process.title` cannot be modified. * Signals are not delivered through `process.on('...')`. * Execution may stop at any point as a result of `worker.terminate()` being invoked. * IPC channels from parent processes are not accessible. * The `trace_events` module is not supported. * Native add-ons can only be loaded from multiple threads if they fulfill `certain conditions`. Creating `Worker` instances inside of other `Worker`s is possible. Like [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) and the `node:cluster module`, two-way communication can be achieved through inter-thread message passing. Internally, a `Worker` has a built-in pair of `MessagePort` s that are already associated with each other when the `Worker` is created. While the `MessagePort` object on the parent side is not directly exposed, its functionalities are exposed through `worker.postMessage()` and the `worker.on('message')` event on the `Worker` object for the parent thread. To create custom messaging channels (which is encouraged over using the default global channel because it facilitates separation of concerns), users can create a `MessageChannel` object on either thread and pass one of the`MessagePort`s on that `MessageChannel` to the other thread through a pre-existing channel, such as the global one. See `port.postMessage()` for more information on how messages are passed, and what kind of JavaScript values can be successfully transported through the thread barrier. ```js import assert from 'node:assert'; import { Worker, MessageChannel, MessagePort, isMainThread, parentPort, } from 'node:worker_threads'; if (isMainThread) { const worker = new Worker(__filename); const subChannel = new MessageChannel(); worker.postMessage({ hereIsYourPort: subChannel.port1 }, [subChannel.port1]); subChannel.port2.on('message', (value) => { console.log('received:', value); }); } else { parentPort.once('message', (value) => { assert(value.hereIsYourPort instanceof MessagePort); value.hereIsYourPort.postMessage('the worker is sending this'); value.hereIsYourPort.close(); }); } ```

Constructors

new



Worker(filename: string | URL,
options?: WorkerOptions,
)

Properties

readonly



performance: WorkerPerformance

An object that can be used to query performance information from a worker instance. Similar to `perf_hooks.performance`.

readonly

abstract



resourceLimits: ResourceLimits | undefined

Provides the set of JS engine resource constraints for this Worker thread. If the `resourceLimits` option was passed to the `Worker` constructor, this matches its values. If the worker has stopped, the return value is an empty object.

readonly



stderr: Readable

This is a readable stream which contains data written to `process.stderr` inside the worker thread. If `stderr: true` was not passed to the `Worker` constructor, then data is piped to the parent thread's `process.stderr` stream.

readonly



stdin: Writable | null

If `stdin: true` was passed to the `Worker` constructor, this is a writable stream. The data written to this stream will be made available in the worker thread as `process.stdin`.

readonly



stdout: Readable

This is a readable stream which contains data written to `process.stdout` inside the worker thread. If `stdout: true` was not passed to the `Worker` constructor, then data is piped to the parent thread's `process.stdout` stream.

readonly



threadId: number

An integer identifier for the referenced thread. Inside the worker thread, it is available as `import { threadId } from 'node:worker_threads'`. This value is unique for each `Worker` instance inside a single process.

Methods



addListener(event: "error",
listener: (err: Error) => void,
): this



addListener(event: "exit",
listener: (exitCode: number) => void,
): this



addListener(event: "message",
listener: (value: any) => void,
): this



addListener(event: "messageerror",
listener: (error: Error) => void,
): this



addListener(event: "online",
listener: () => void,
): this



addListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



emit(event: "error",
err: Error,
): boolean



emit(event: "exit",
exitCode: number,
): boolean



emit(event: "message",
value: any,
): boolean



emit(event: "messageerror",
error: Error,
): boolean



emit(event: "online"): boolean



emit(event: string | symbol,
...args: any[],
): boolean



getHeapSnapshot(): Promise<Readable>

Returns a readable stream for a V8 snapshot of the current state of the Worker. See `v8.getHeapSnapshot()` for more details. If the Worker thread is no longer running, which may occur before the `'exit' event` is emitted, the returned `Promise` is rejected immediately with an `ERR_WORKER_NOT_RUNNING` error.



off(event: "error",
listener: (err: Error) => void,
): this



off(event: "exit",
listener: (exitCode: number) => void,
): this



off(event: "message",
listener: (value: any) => void,
): this



off(event: "messageerror",
listener: (error: Error) => void,
): this



off(event: "online",
listener: () => void,
): this



off(event: string | symbol,
listener: (...args: any[]) => void,
): this



on(event: "error",
listener: (err: Error) => void,
): this



on(event: "exit",
listener: (exitCode: number) => void,
): this



on(event: "message",
listener: (value: any) => void,
): this



on(event: "messageerror",
listener: (error: Error) => void,
): this



on(event: "online",
listener: () => void,
): this



on(event: string | symbol,
listener: (...args: any[]) => void,
): this



once(event: "error",
listener: (err: Error) => void,
): this



once(event: "exit",
listener: (exitCode: number) => void,
): this



once(event: "message",
listener: (value: any) => void,
): this



once(event: "messageerror",
listener: (error: Error) => void,
): this



once(event: "online",
listener: () => void,
): this



once(event: string | symbol,
listener: (...args: any[]) => void,
): this



postMessage(value: any,
transferList?: readonly TransferListItem[],
): void

Send a message to the worker that is received via `require('node:worker_threads').parentPort.on('message')`. See `port.postMessage()` for more details.



postMessageToThread(threadId: number,
value: any,
timeout?: number,
): Promise<void>

Sends a value to another worker, identified by its thread ID.



postMessageToThread(threadId: number,
value: any,
transferList: readonly TransferListItem[],
timeout?: number,
): Promise<void>



prependListener(event: "error",
listener: (err: Error) => void,
): this



prependListener(event: "exit",
listener: (exitCode: number) => void,
): this



prependListener(event: "message",
listener: (value: any) => void,
): this



prependListener(event: "messageerror",
listener: (error: Error) => void,
): this



prependListener(event: "online",
listener: () => void,
): this



prependListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



prependOnceListener(event: "error",
listener: (err: Error) => void,
): this



prependOnceListener(event: "exit",
listener: (exitCode: number) => void,
): this



prependOnceListener(event: "message",
listener: (value: any) => void,
): this



prependOnceListener(event: "messageerror",
listener: (error: Error) => void,
): this



prependOnceListener(event: "online",
listener: () => void,
): this



prependOnceListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



ref(): void

Opposite of `unref()`, calling `ref()` on a previously `unref()`ed worker does _not_ let the program exit if it's the only active handle left (the default behavior). If the worker is `ref()`ed, calling `ref()` again has no effect.



removeListener(event: "error",
listener: (err: Error) => void,
): this



removeListener(event: "exit",
listener: (exitCode: number) => void,
): this



removeListener(event: "message",
listener: (value: any) => void,
): this



removeListener(event: "messageerror",
listener: (error: Error) => void,
): this



removeListener(event: "online",
listener: () => void,
): this



removeListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



terminate(): Promise<number>

Stop all JavaScript execution in the worker thread as soon as possible. Returns a Promise for the exit code that is fulfilled when the `'exit' event` is emitted.



unref(): void

Calling `unref()` on a worker allows the thread to exit if this is the only active handle in the event system. If the worker is already `unref()`ed calling `unref()` again has no effect.