# Workers

Maligator 0.1.0-alpha.28 · Experimental
Source revision: 32744809d2e859c7d0f4323e88410d700d741163
Canonical: https://maligator.ddv.tools/api/workers

Parallel computation and isolated event loops. Declared entries are bundled into the application image; workers do not compile or load source files at runtime. Native executors and GC helpers are shared across JavaScript isolates.

Import from `maligator:workers`. This API is experimental. Load declarations as described in [Use TypeScript](/guides/typescript). Platform imports do not require a surface flag.
Start with [Run tasks in workers](/guides/workers) for a complete pool example. Use [messages and transfers](/guides/workers/messages) for buffer ownership, or [cancellation and shutdown](/guides/workers/cancellation) for lifecycle handling.

Task submissions can throw before admission: invalid task names or argument tuples (`TypeError`), a closed pool (`InvalidStateError`), saturation (`QueueFullError`), clone/transfer validation (`DataCloneError`), and an already-aborted signal's reason. Once admitted, execution and cancellation settle through the returned promise. A failed worker does not replay accepted work.

A running task must cooperate with cancellation. `close()` drains work; `terminate()` rejects outstanding work and waits for running tasks to settle and workers to be joined. Pool queue defaults differ from direct worker/channel message defaults; use the corresponding option type below.

<a id="createPool"></a>

## createPool

Create a bounded pool of persistent workers for a declared entry. Submission failures throw synchronously; admitted tasks settle asynchronously. Await ready before submitting startup-dependent work and close the pool when finished. Throws NotSupportedError without threads and RangeError for invalid bounds.

```typescript
export const createPool: <Module>(entry: WorkerUrl<Module>, options?: PoolOptions) => WorkerPool<Module>;
```

Types: [`WorkerUrl`](/api/workers#WorkerUrl), [`PoolOptions`](/api/workers#PoolOptions), [`WorkerPool`](/api/workers#WorkerPool)



```typescript pool.ts
import { createPool, createWorkerUrl } from "maligator:workers";

const tasks = createWorkerUrl<typeof import("./tasks.ts")>(
	"./tasks.ts",
	import.meta.url,
);
const pool = createPool(tasks, { size: 2, maxQueuedTasks: 4 });

try {
	await pool.ready;
	console.log(await pool.run("sum", [[1, 2, 3]]));

	const inputs: Array<[Array<number>]> = [[[1, 2]], [[3, 4]]];
	for await (const total of pool.map("sum", inputs, { window: 2 })) {
		console.log(total);
	}

	const controller = new AbortController();
	const pending = pool.run("waitForCancellation", [], {
		signal: controller.signal,
	});
	const cancelled = pending.then(
		() => false,
		(reason: unknown) => reason === controller.signal.reason,
	);
	controller.abort();
	console.log(await cancelled);
} finally {
	await pool.close();
}
```

```typescript tasks.ts
import type { TaskContext } from "maligator:workers";

export function sum(context: TaskContext, values: Array<number>): number {
	let total = 0;
	for (const value of values) {
		context.throwIfCancelled();
		total += value;
	}
	return total;
}

export async function waitForCancellation(context: TaskContext): Promise<void> {
	context.throwIfCancelled();
	await new Promise<void>((resolve) => {
		context.signal.addEventListener("abort", () => resolve(), { once: true });
	});
	context.throwIfCancelled();
}
```

<a id="createWorkerUrl"></a>

## createWorkerUrl

Declare an entry using a static string literal and explicit import.meta.url base. The immutable href projection can be passed to existing worker libraries.

```typescript
export const createWorkerUrl: <Module = unknown>(specifier: string, base: string) => WorkerUrl<Module>;
```

Types: [`WorkerUrl`](/api/workers#WorkerUrl)



```typescript declaration.ts
import { createWorkerUrl } from "maligator:workers";

export const tasks = createWorkerUrl<typeof import("./sum.ts")>(
	"./sum.ts",
	import.meta.url,
);

console.log(Object.isFrozen(tasks), tasks.href.startsWith("file:"));
```

```typescript sum.ts
import type { TaskContext } from "maligator:workers";

export function sum(context: TaskContext, values: Array<number>): number {
	context.throwIfCancelled();
	return values.reduce((total, value) => total + value, 0);
}
```

<a id="transfer"></a>

## transfer

Wrap a result for transfer when the worker publishes it.

```typescript
export const transfer: <Value>(value: Value, transfer: ReadonlyArray<Transferable>) => TransferResult<Value>;
```

Types: [`Transferable`](/api/workers#Transferable), [`TransferResult`](/api/workers#TransferResult)



```typescript transfer-task.ts
import { transfer } from "maligator:workers";
import type { TaskContext } from "maligator:workers";

export function reverse(context: TaskContext, buffer: ArrayBuffer) {
	context.throwIfCancelled();
	new Uint8Array(buffer).reverse();
	return transfer(buffer, [buffer]);
}
```

```typescript transfer.ts
import { createPool, createWorkerUrl } from "maligator:workers";

const tasks = createWorkerUrl<typeof import("./transfer-task.ts")>(
	"./transfer-task.ts",
	import.meta.url,
);
const pool = createPool(tasks, { size: 1 });

try {
	await pool.ready;
	const bytes = new Uint8Array([1, 2, 3]);
	const pending = pool.run("reverse", [bytes.buffer], {
		transfer: [bytes.buffer],
	});
	console.log(bytes.byteLength);
	const result = new Uint8Array(await pending);
	console.log(Array.from(result).join(","));
} finally {
	await pool.close();
}
```

<a id="Worker"></a>

## Worker

Start a declared isolated module and expose its ordered port and complete lifecycle.

```typescript
export const Worker: { new<Send = unknown, Receive = unknown>(entry: WorkerUrl, options?: WorkerOptions): Worker<Send, Receive> };
```

Types: [`WorkerUrl`](/api/workers#WorkerUrl), [`WorkerOptions`](/api/workers#WorkerOptions)



```typescript worker.ts
import { createWorkerUrl, Worker } from "maligator:workers";

const entry = createWorkerUrl("./echo.ts", import.meta.url);
const worker = new Worker<string, string>(entry);

try {
	const reply = new Promise<string>((resolve) => {
		worker.port.onmessage = (event) => resolve(event.data);
	});
	worker.port.start();
	await worker.ready;
	worker.port.postMessage("workers");
	console.log(await reply);
} finally {
	const exit = await worker.terminate();
	console.log(exit.reason);
}
```

```typescript echo.ts
import { parentPort } from "maligator:workers";

if (parentPort === null) throw new Error("Run this module as a worker");
const port = parentPort;
port.onmessage = (event) => {
	port.postMessage(String(event.data));
};
port.start();
```

<a id="MessageChannel"></a>

## MessageChannel

Create two transferable endpoints independently of worker startup.

```typescript
export const MessageChannel: { new(options?: MessageChannelOptions): MessageChannel };
```

Types: [`MessageChannelOptions`](/api/workers#MessageChannelOptions)



```typescript channel.ts
import { MessageChannel, MessagePort } from "maligator:workers";

const channel = new MessageChannel();
try {
	console.log(channel.port1 instanceof MessagePort);
	const received = new Promise<unknown>((resolve) => {
		channel.port2.onmessage = (event) => resolve(event.data);
	});
	channel.port2.start();
	channel.port1.postMessage({ answer: 42 });
	console.log(JSON.stringify(await received));
} finally {
	channel.port1.close();
	channel.port2.close();
}
```

<a id="MessagePort"></a>

## MessagePort

The port prototype for type and identity checks. Ports are created by channels and workers.

```typescript
export const MessagePort: { readonly prototype: MessagePort };
```


```typescript port.ts
import { MessageChannel, type MessagePort } from "maligator:workers";

function installResponder(port: MessagePort): void {
	port.onmessage = (event) => port.postMessage("reply:" + String(event.data));
	port.start();
}

const { port1, port2 } = new MessageChannel();
try {
	installResponder(port2);
	const reply = new Promise<unknown>((resolve) => {
		port1.onmessage = (event) => resolve(event.data);
	});
	port1.start();
	port1.postMessage("hello");
	console.log(await reply);
} finally {
	port1.close();
	port2.close();
}
```

<a id="receiveMessageOnPort"></a>

## receiveMessageOnPort

Synchronously dequeue one pending message without running unrelated callbacks.

```typescript
export const receiveMessageOnPort: <Receive>(port: MessagePort<unknown, Receive>) => { message: Receive } | undefined;
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



```typescript receive.ts
import { MessageChannel, receiveMessageOnPort } from "maligator:workers";

const channel = new MessageChannel();
try {
	channel.port1.postMessage("first");
	channel.port1.postMessage("second");
	console.log(receiveMessageOnPort(channel.port2)?.message);
	console.log(receiveMessageOnPort(channel.port2)?.message);
	console.log(receiveMessageOnPort(channel.port2));
} finally {
	channel.port1.close();
	channel.port2.close();
}
```

<a id="capabilities"></a>

## capabilities

Report the running host's worker facilities and capacity.

```typescript
export const capabilities: () => { readonly threads: boolean; readonly sharedMemory: boolean; readonly parallelism: number; readonly maxWorkers: number };
```


```typescript capabilities.ts
import { capabilities } from "maligator:workers";

const host = capabilities();
console.log(host.threads, host.sharedMemory);
console.log(host.parallelism >= 1, host.maxWorkers >= 1);
```

<a id="parentPort"></a>

## parentPort

The worker's parent endpoint; null in the main isolate.

```typescript
export const parentPort: MessagePort | null;
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



```typescript echo.ts
import { parentPort } from "maligator:workers";

if (parentPort === null) throw new Error("Run this module as a worker");
const port = parentPort;
port.onmessage = (event) => {
	port.postMessage(String(event.data));
};
port.start();
```

<a id="workerData"></a>

## workerData

The worker-owned clone of startup data.

```typescript
export const workerData: unknown;
```


```typescript worker-data.ts
import { workerData } from "maligator:workers";

function readConfig(value: unknown): { label: string } {
	if (
		typeof value !== "object" ||
		value === null ||
		!("label" in value) ||
		typeof value.label !== "string"
	) {
		throw new TypeError("Expected worker data with a string label");
	}
	return { label: value.label };
}

const config = readConfig(workerData);
console.log(config.label);
```

```typescript configuration.ts
import { createWorkerUrl, Worker } from "maligator:workers";

const entry = createWorkerUrl("./worker-data.ts", import.meta.url);
const worker = new Worker(entry, { data: { label: "thumbnail" } });
try {
	await worker.ready;
	const exit = await worker.closed;
	if (exit.code !== 0) throw new Error("Worker failed");
} finally {
	await worker.terminate();
}
```

<a id="WorkerUrl"></a>

## WorkerUrl

An immutable image-local worker entry declaration. The compiler resolves the declaration independently of how libraries pass the descriptor or its href onward. Erased module types express the caller's assertion; runtime entry identity is validated.
<details><summary>Full TypeScript declaration</summary>


```typescript
type WorkerUrl<Module = unknown> = { readonly href: string; readonly __workerModule?: Module };
```

</details>


<a id="WorkerUrl.href"></a>

### WorkerUrl.href



```typescript
readonly href: string;
```


<a id="WorkerUrl.__workerModule"></a>

### WorkerUrl.__workerModule



```typescript
readonly __workerModule?: Module
```


<a id="Transferable"></a>

## Transferable

ArrayBuffer stores move at admission. MessagePort endpoints transfer ownership. SharedArrayBuffer is cloned by sharing its backing and cannot be transferred.

```typescript
type Transferable = ArrayBuffer | MessagePort;
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



<a id="TaskContext"></a>

## TaskContext

Cancellation is cooperative while a pool task runs. The worker remains occupied until the task's returned promise settles.
<details><summary>Full TypeScript declaration</summary>


```typescript
type TaskContext = {
 /** Worker-local cancellation signal. Cancellation does not preempt JavaScript. */
 readonly signal: AbortSignal;
 /** Throws if cancelled. Check between bounded pieces of work. */
 throwIfCancelled(): void;
};
```

Types: [`Worker`](/api/workers#Worker.type)


</details>


<a id="TaskContext.signal"></a>

### TaskContext.signal

Worker-local cancellation signal. Cancellation does not preempt JavaScript.

```typescript
readonly signal: AbortSignal;
```


<a id="TaskContext.throwIfCancelled"></a>

### TaskContext.throwIfCancelled

Throws if cancelled. Check between bounded pieces of work.

```typescript
throwIfCancelled(): void;
```


<a id="TransferResult"></a>

## TransferResult

An opaque result envelope. Constructing it does not detach buffers; publication commits transfers.
<details><summary>Full TypeScript declaration</summary>


```typescript
type TransferResult<Value> = { readonly value: Value; readonly __transferResult: unique symbol };
```

</details>


<a id="TransferResult.value"></a>

### TransferResult.value



```typescript
readonly value: Value;
```


<a id="TransferResult.__transferResult"></a>

### TransferResult.__transferResult



```typescript
readonly __transferResult: unique symbol
```


<a id="TaskNames"></a>

## TaskNames

Names of context-first exported task functions.

```typescript
type TaskNames<Module> = { [Key in keyof Module]-?: Module[Key] extends (context: TaskContext, ...args: infer Args) => unknown ? Key : never }[keyof Module] & string;
```

Types: [`TaskContext`](/api/workers#TaskContext)



<a id="TaskArgs"></a>

## TaskArgs

The task's argument tuple, excluding its local cancellation context.

```typescript
type TaskArgs<Function> = Function extends (context: TaskContext, ...args: infer Args) => unknown ? Args : never;
```

Types: [`TaskContext`](/api/workers#TaskContext)



<a id="TaskValue"></a>

## TaskValue

The settled task result after unwrapping an explicit transfer envelope.

```typescript
type TaskValue<Function> = Function extends (...args: Array<never>) => infer Result ? Awaited<Result> extends TransferResult<infer Value> ? Value : Awaited<Result> : never;
```

Types: [`TransferResult`](/api/workers#TransferResult)



<a id="PoolOptions"></a>

## PoolOptions

Fixed persistent worker count and admission bounds. Every worker has independent module state. A size-one pool dispatches admitted tasks serially.
<details><summary>Full TypeScript declaration</summary>


```typescript
type PoolOptions = {
 /** Positive safe integer; defaults to host parallelism, falling back to 1. */
 size?: number;
 /** Nonnegative safe integer; defaults to four times size. Zero disables the waiting queue. */
 maxQueuedTasks?: number;
 /** Positive safe integer in bytes; defaults to 67108864 (64 MiB). */
 maxQueuedBytes?: number;
 /** Positive safe integer in bytes; defaults to maxQueuedBytes. */
 maxMessageBytes?: number;
 /** Worker name prefix; each worker receives a one-based suffix. */
 name?: string;
};
```

Types: [`Worker`](/api/workers#Worker.type)


</details>


<a id="PoolOptions.size"></a>

### PoolOptions.size

Positive safe integer; defaults to host parallelism, falling back to 1.

```typescript
size?: number;
```


<a id="PoolOptions.maxQueuedTasks"></a>

### PoolOptions.maxQueuedTasks

Nonnegative safe integer; defaults to four times size. Zero disables the waiting queue.

```typescript
maxQueuedTasks?: number;
```


<a id="PoolOptions.maxQueuedBytes"></a>

### PoolOptions.maxQueuedBytes

Positive safe integer in bytes; defaults to 67108864 (64 MiB).

```typescript
maxQueuedBytes?: number;
```


<a id="PoolOptions.maxMessageBytes"></a>

### PoolOptions.maxMessageBytes

Positive safe integer in bytes; defaults to maxQueuedBytes.

```typescript
maxMessageBytes?: number;
```


<a id="PoolOptions.name"></a>

### PoolOptions.name

Worker name prefix; each worker receives a one-based suffix.

```typescript
name?: string;
```


<a id="RunOptions"></a>

## RunOptions

The transfer list commits synchronously when run returns normally. Validation, saturation, closed pools and already-aborted signals throw before admission.
<details><summary>Full TypeScript declaration</summary>


```typescript
type RunOptions = {
 /** Already-aborted signals throw before admission. Running cancellation is cooperative. */
 signal?: AbortSignal;
 /** Ownership moves synchronously on successful admission; rejection leaves values unchanged. */
 transfer?: ReadonlyArray<Transferable>;
};
```

Types: [`Transferable`](/api/workers#Transferable)


</details>


<a id="RunOptions.signal"></a>

### RunOptions.signal

Already-aborted signals throw before admission. Running cancellation is cooperative.

```typescript
signal?: AbortSignal;
```


<a id="RunOptions.transfer"></a>

### RunOptions.transfer

Ownership moves synchronously on successful admission; rejection leaves values unchanged.

```typescript
transfer?: ReadonlyArray<Transferable>;
```

Types: [`Transferable`](/api/workers#Transferable)



<a id="MapOptions"></a>

## MapOptions

The window bounds pulled inputs and buffered results together. Results are yielded in input order; iterator return cancels this map's work and closes its input.
<details><summary>Full TypeScript declaration</summary>


```typescript
type MapOptions<Args> = {
 /** Cancels only work owned by this map; running tasks must cooperate. */
 signal?: AbortSignal;
 /** Positive safe integer; defaults to pool size. Bounds pulled inputs and buffered results together. */
 window?: number;
 /** Called for each input before admission to choose values whose ownership moves. */
 transfer?: (args: Args, index: number) => ReadonlyArray<Transferable>;
};
```

Types: [`Transferable`](/api/workers#Transferable)


</details>


<a id="MapOptions.signal"></a>

### MapOptions.signal

Cancels only work owned by this map; running tasks must cooperate.

```typescript
signal?: AbortSignal;
```


<a id="MapOptions.window"></a>

### MapOptions.window

Positive safe integer; defaults to pool size. Bounds pulled inputs and buffered results together.

```typescript
window?: number;
```


<a id="MapOptions.transfer"></a>

### MapOptions.transfer

Called for each input before admission to choose values whose ownership moves.

```typescript
transfer?: (args: Args, index: number) => ReadonlyArray<Transferable>;
```

Types: [`Transferable`](/api/workers#Transferable)



<a id="PoolStats"></a>

## PoolStats

A snapshot of this pool's scheduling and settled operations.
<details><summary>Full TypeScript declaration</summary>


```typescript
type PoolStats = { readonly size: number; readonly active: number; readonly queued: number; readonly completed: number; readonly failed: number; readonly cancelled: number };
```

</details>


<a id="PoolStats.size"></a>

### PoolStats.size



```typescript
readonly size: number;
```


<a id="PoolStats.active"></a>

### PoolStats.active



```typescript
readonly active: number;
```


<a id="PoolStats.queued"></a>

### PoolStats.queued



```typescript
readonly queued: number;
```


<a id="PoolStats.completed"></a>

### PoolStats.completed



```typescript
readonly completed: number;
```


<a id="PoolStats.failed"></a>

### PoolStats.failed



```typescript
readonly failed: number;
```


<a id="PoolStats.cancelled"></a>

### PoolStats.cancelled



```typescript
readonly cancelled: number
```


<a id="WorkerPool"></a>

## WorkerPool

A bounded task scheduler over isolated persistent workers. Each worker executes one task through asynchronous settlement. No accepted task is replayed after worker failure.
<details><summary>Full TypeScript declaration</summary>


```typescript
type WorkerPool<Module> = {
 /** Resolves after every worker evaluates the entry; rejects on startup failure. */
 readonly ready: Promise<void>;
 /** Throws on failed admission; returns a promise for the accepted task's result or failure. */
 run<Key extends TaskNames<Module>>(name: Key, args: TaskArgs<Module[Key]>, options?: RunOptions): Promise<TaskValue<Module[Key]>>;
 /** Yields in input order. Returning from the iterator cancels its work and closes its input. */
 map<Key extends TaskNames<Module>>(name: Key, args: Iterable<TaskArgs<Module[Key]>> | AsyncIterable<TaskArgs<Module[Key]>>, options?: MapOptions<TaskArgs<Module[Key]>>): AsyncIterable<TaskValue<Module[Key]>>;
 /** Stops admission, drains accepted tasks, then joins every worker. Idempotent. */
 close(): Promise<void>;
 /** Rejects outstanding tasks with AbortError; joins workers after running tasks cooperate and settle. */
 terminate(): Promise<void>;
 /** Returns a scheduling snapshot; counts are not a subscription. */
 stats(): PoolStats;
 /** Keeps the process alive while pool workers exist; returns this pool. */
 ref(): WorkerPool<Module>;
 /** Allows the process to exit without waiting for this pool; returns this pool. */
 unref(): WorkerPool<Module>;
 /** Reports whether this pool currently keeps the process alive. */
 hasRef(): boolean;
};
```

Types: [`TaskNames`](/api/workers#TaskNames), [`TaskArgs`](/api/workers#TaskArgs), [`TaskValue`](/api/workers#TaskValue), [`RunOptions`](/api/workers#RunOptions), [`MapOptions`](/api/workers#MapOptions), [`PoolStats`](/api/workers#PoolStats)


</details>


<a id="WorkerPool.ready"></a>

### WorkerPool.ready

Resolves after every worker evaluates the entry; rejects on startup failure.

```typescript
readonly ready: Promise<void>;
```


<a id="WorkerPool.run"></a>

### WorkerPool.run

Throws on failed admission; returns a promise for the accepted task's result or failure.

```typescript
run<Key extends TaskNames<Module>>(name: Key, args: TaskArgs<Module[Key]>, options?: RunOptions): Promise<TaskValue<Module[Key]>>;
```

Types: [`TaskNames`](/api/workers#TaskNames), [`TaskArgs`](/api/workers#TaskArgs), [`TaskValue`](/api/workers#TaskValue), [`RunOptions`](/api/workers#RunOptions)



<a id="WorkerPool.map"></a>

### WorkerPool.map

Yields in input order. Returning from the iterator cancels its work and closes its input.

```typescript
map<Key extends TaskNames<Module>>(name: Key, args: Iterable<TaskArgs<Module[Key]>> | AsyncIterable<TaskArgs<Module[Key]>>, options?: MapOptions<TaskArgs<Module[Key]>>): AsyncIterable<TaskValue<Module[Key]>>;
```

Types: [`TaskNames`](/api/workers#TaskNames), [`TaskArgs`](/api/workers#TaskArgs), [`TaskValue`](/api/workers#TaskValue), [`MapOptions`](/api/workers#MapOptions)



<a id="WorkerPool.close"></a>

### WorkerPool.close

Stops admission, drains accepted tasks, then joins every worker. Idempotent.

```typescript
close(): Promise<void>;
```


<a id="WorkerPool.terminate"></a>

### WorkerPool.terminate

Rejects outstanding tasks with AbortError; joins workers after running tasks cooperate and settle.

```typescript
terminate(): Promise<void>;
```


<a id="WorkerPool.stats"></a>

### WorkerPool.stats

Returns a scheduling snapshot; counts are not a subscription.

```typescript
stats(): PoolStats;
```

Types: [`PoolStats`](/api/workers#PoolStats)



<a id="WorkerPool.ref"></a>

### WorkerPool.ref

Keeps the process alive while pool workers exist; returns this pool.

```typescript
ref(): WorkerPool<Module>;
```

Types: [`WorkerPool`](/api/workers#WorkerPool)



<a id="WorkerPool.unref"></a>

### WorkerPool.unref

Allows the process to exit without waiting for this pool; returns this pool.

```typescript
unref(): WorkerPool<Module>;
```

Types: [`WorkerPool`](/api/workers#WorkerPool)



<a id="WorkerPool.hasRef"></a>

### WorkerPool.hasRef

Reports whether this pool currently keeps the process alive.

```typescript
hasRef(): boolean;
```


<a id="WorkerExit"></a>

## WorkerExit

A terminal record published only after the native worker is joined and its slot is released.
<details><summary>Full TypeScript declaration</summary>


```typescript
type WorkerExit = { readonly id: number; readonly code: number; readonly reason: 'completed' | 'terminated' | 'error'; readonly error?: unknown };
```

</details>


<a id="WorkerExit.id"></a>

### WorkerExit.id



```typescript
readonly id: number;
```


<a id="WorkerExit.code"></a>

### WorkerExit.code



```typescript
readonly code: number;
```


<a id="WorkerExit.reason"></a>

### WorkerExit.reason



```typescript
readonly reason: 'completed' | 'terminated' | 'error';
```


<a id="WorkerExit.error"></a>

### WorkerExit.error



```typescript
readonly error?: unknown
```


<a id="WorkerOptions"></a>

## WorkerOptions

Worker data is snapshotted before startup. The native host bounds live workers and message admission process-wide.
<details><summary>Full TypeScript declaration</summary>


```typescript
type WorkerOptions = {
 name?: string;
 /** Cloned into workerData before startup; later caller mutations are not shared. */
 data?: unknown;
 /** Values moved as part of startup-data admission. */
 transfer?: ReadonlyArray<Transferable>;
 /** Positive safe integer, at most 4294967295; defaults to 4096 messages per endpoint. */
 maxQueuedMessages?: number;
 /** Positive safe integer in bytes; defaults to 67108864 (64 MiB) per endpoint. */
 maxQueuedBytes?: number;
 /** Positive safe integer in bytes; defaults to 16777216 (16 MiB) per message. */
 maxMessageBytes?: number;
};
```

Types: [`Transferable`](/api/workers#Transferable)


</details>


<a id="WorkerOptions.name"></a>

### WorkerOptions.name



```typescript
name?: string;
```


<a id="WorkerOptions.data"></a>

### WorkerOptions.data

Cloned into workerData before startup; later caller mutations are not shared.

```typescript
data?: unknown;
```


<a id="WorkerOptions.transfer"></a>

### WorkerOptions.transfer

Values moved as part of startup-data admission.

```typescript
transfer?: ReadonlyArray<Transferable>;
```

Types: [`Transferable`](/api/workers#Transferable)



<a id="WorkerOptions.maxQueuedMessages"></a>

### WorkerOptions.maxQueuedMessages

Positive safe integer, at most 4294967295; defaults to 4096 messages per endpoint.

```typescript
maxQueuedMessages?: number;
```


<a id="WorkerOptions.maxQueuedBytes"></a>

### WorkerOptions.maxQueuedBytes

Positive safe integer in bytes; defaults to 67108864 (64 MiB) per endpoint.

```typescript
maxQueuedBytes?: number;
```


<a id="WorkerOptions.maxMessageBytes"></a>

### WorkerOptions.maxMessageBytes

Positive safe integer in bytes; defaults to 16777216 (16 MiB) per message.

```typescript
maxMessageBytes?: number;
```


<a id="MessageChannelOptions"></a>

## MessageChannelOptions

Each endpoint bounds its pending message count and bytes. Rejection leaves the sender's transferables unchanged.
<details><summary>Full TypeScript declaration</summary>


```typescript
type MessageChannelOptions = {
 /** Positive safe integer, at most 4294967295; defaults to 4096 messages per endpoint. */
 maxQueuedMessages?: number;
 /** Positive safe integer in bytes; defaults to 67108864 (64 MiB) per endpoint. */
 maxQueuedBytes?: number;
 /** Positive safe integer in bytes; defaults to 16777216 (16 MiB) per message. */
 maxMessageBytes?: number;
};
```

</details>


<a id="MessageChannelOptions.maxQueuedMessages"></a>

### MessageChannelOptions.maxQueuedMessages

Positive safe integer, at most 4294967295; defaults to 4096 messages per endpoint.

```typescript
maxQueuedMessages?: number;
```


<a id="MessageChannelOptions.maxQueuedBytes"></a>

### MessageChannelOptions.maxQueuedBytes

Positive safe integer in bytes; defaults to 67108864 (64 MiB) per endpoint.

```typescript
maxQueuedBytes?: number;
```


<a id="MessageChannelOptions.maxMessageBytes"></a>

### MessageChannelOptions.maxMessageBytes

Positive safe integer in bytes; defaults to 16777216 (16 MiB) per message.

```typescript
maxMessageBytes?: number;
```


<a id="MessagePort.type"></a>

## MessagePort instance

An ordered bidirectional endpoint with transactional transfer and bounded queues. Message listeners and values are owned by the receiving isolate.
<details><summary>Full TypeScript declaration</summary>


```typescript
interface MessagePort<Send = unknown, Receive = unknown> extends EventTarget {
 /** Clones and admits a message synchronously. Transfer commits only after successful validation/admission. */
 postMessage(value: Send, transfer?: ReadonlyArray<Transferable>): void;
 /** Setting this handler starts delivery. addEventListener listeners need start(). */
 onmessage: ((event: MessageEvent<Receive>) => void) | null;
 /** Receives message decoding failures in the receiving isolate. */
 onmessageerror: ((event: MessageEvent<unknown>) => void) | null;
 /** Enables delivery to event listeners; repeated calls are harmless. */
 start(): void;
 /** Discards queued messages and closes this endpoint. */
 close(): void;
 /** Keeps the receiving isolate alive; returns this port. */
 ref(): MessagePort<Send, Receive>;
 /** Allows the receiving isolate to exit; returns this port. */
 unref(): MessagePort<Send, Receive>;
 hasRef(): boolean;
}
```

Types: [`Transferable`](/api/workers#Transferable)


</details>


<a id="MessagePort.postMessage"></a>

### MessagePort.postMessage

Clones and admits a message synchronously. Transfer commits only after successful validation/admission.

```typescript
postMessage(value: Send, transfer?: ReadonlyArray<Transferable>): void;
```

Types: [`Transferable`](/api/workers#Transferable)



<a id="MessagePort.onmessage"></a>

### MessagePort.onmessage

Setting this handler starts delivery. addEventListener listeners need start().

```typescript
onmessage: ((event: MessageEvent<Receive>) => void) | null;
```


<a id="MessagePort.onmessageerror"></a>

### MessagePort.onmessageerror

Receives message decoding failures in the receiving isolate.

```typescript
onmessageerror: ((event: MessageEvent<unknown>) => void) | null;
```


<a id="MessagePort.start"></a>

### MessagePort.start

Enables delivery to event listeners; repeated calls are harmless.

```typescript
start(): void;
```


<a id="MessagePort.close"></a>

### MessagePort.close

Discards queued messages and closes this endpoint.

```typescript
close(): void;
```


<a id="MessagePort.ref"></a>

### MessagePort.ref

Keeps the receiving isolate alive; returns this port.

```typescript
ref(): MessagePort<Send, Receive>;
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



<a id="MessagePort.unref"></a>

### MessagePort.unref

Allows the receiving isolate to exit; returns this port.

```typescript
unref(): MessagePort<Send, Receive>;
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



<a id="MessagePort.hasRef"></a>

### MessagePort.hasRef



```typescript
hasRef(): boolean;
```


<a id="MessageChannel.type"></a>

## MessageChannel instance

A standalone channel whose endpoints may be transferred to workers.
<details><summary>Full TypeScript declaration</summary>


```typescript
type MessageChannel = { readonly port1: MessagePort; readonly port2: MessagePort };
```

Types: [`MessagePort`](/api/workers#MessagePort.type)


</details>


<a id="MessageChannel.port1"></a>

### MessageChannel.port1



```typescript
readonly port1: MessagePort;
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



<a id="MessageChannel.port2"></a>

### MessageChannel.port2



```typescript
readonly port2: MessagePort
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



<a id="Worker.type"></a>

## Worker instance

A long-lived isolated module and its parent communication port. Startup completes after module evaluation; shutdown completes after native thread reaping.
<details><summary>Full TypeScript declaration</summary>


```typescript
type Worker<Send = unknown, Receive = unknown> = EventTarget & {
 readonly id: number;
 /** Resolves after entry evaluation; rejects on startup failure. */
 readonly ready: Promise<void>;
 /** Resolves with a terminal record after the native thread is joined and its slot released. */
 readonly closed: Promise<WorkerExit>;
 readonly port: MessagePort<Send, Receive>;
 /** Requests shutdown and resolves after thread reaping. */
 terminate(): Promise<WorkerExit>;
 ref(): Worker<Send, Receive>;
 unref(): Worker<Send, Receive>;
 hasRef(): boolean;
};
```

Types: [`WorkerExit`](/api/workers#WorkerExit), [`MessagePort`](/api/workers#MessagePort.type)


</details>


<a id="Worker.id"></a>

### Worker.id



```typescript
readonly id: number;
```


<a id="Worker.ready"></a>

### Worker.ready

Resolves after entry evaluation; rejects on startup failure.

```typescript
readonly ready: Promise<void>;
```


<a id="Worker.closed"></a>

### Worker.closed

Resolves with a terminal record after the native thread is joined and its slot released.

```typescript
readonly closed: Promise<WorkerExit>;
```

Types: [`WorkerExit`](/api/workers#WorkerExit)



<a id="Worker.port"></a>

### Worker.port



```typescript
readonly port: MessagePort<Send, Receive>;
```

Types: [`MessagePort`](/api/workers#MessagePort.type)



<a id="Worker.terminate"></a>

### Worker.terminate

Requests shutdown and resolves after thread reaping.

```typescript
terminate(): Promise<WorkerExit>;
```

Types: [`WorkerExit`](/api/workers#WorkerExit)



<a id="Worker.ref"></a>

### Worker.ref



```typescript
ref(): Worker<Send, Receive>;
```

Types: [`Worker`](/api/workers#Worker.type)



<a id="Worker.unref"></a>

### Worker.unref



```typescript
unref(): Worker<Send, Receive>;
```

Types: [`Worker`](/api/workers#Worker.type)



<a id="Worker.hasRef"></a>

### Worker.hasRef



```typescript
hasRef(): boolean;
```