Vielzeug

Appearance

Workit API Reference ​

API At a Glance ​

SymbolPurposeExecution modeCommon gotcha
createWorker()Create a typed worker or worker poolSyncDispose workers to release threads/resources
worker.run()Execute a typed task in worker/fallbackAsyncPass transferables for large buffers when possible
createTestWorker()Run worker tasks in-process for testsAsyncUse call recording assertions to verify behavior

Package Exports ​

ts
export { createWorker, TaskError, TaskTimeoutError, TerminatedError, WorkerError } from '@vielzeug/workit';

export type { RunOptions, TaskFn, WorkerHandle, WorkerOptions, WorkerStatus } from '@vielzeug/workit';

export { createTestWorker } from '@vielzeug/workit/test';
export type { TestWorkerHandle } from '@vielzeug/workit/test';

Types ​

TaskFn ​

ts
type TaskFn<TInput, TOutput> = (input: TInput) => TOutput | Promise<TOutput>;

The signature for the task function passed to createWorker. Accepts a single typed input and returns a value or a Promise.

WorkerStatus ​

ts
type WorkerStatus = 'idle' | 'running' | 'terminated';
ValueMeaning
'idle'All worker slots are free
'running'One or more slots are executing a task
'terminated'dispose() was called

WorkerOptions ​

ts
type WorkerOptions = {
  size?: number | 'auto';
  timeout?: number;
  fallback?: boolean;
  scripts?: string[];
};
PropertyTypeDefaultDescription
sizenumber | 'auto'1Number of concurrent worker slots. 'auto' uses navigator.hardwareConcurrency.
timeoutnumberundefinedMilliseconds before a task rejects with TaskTimeoutError.
fallbackbooleantrueRun on the main thread when Web Workers are unavailable.
scriptsstring[][]URLs loaded via importScripts() inside each Worker.

RunOptions ​

ts
type RunOptions = {
  signal?: AbortSignal;
  transfer?: Transferable[];
};
PropertyTypeDescription
signalAbortSignalCancel a queued task. In-flight tasks cannot be interrupted.
transferTransferable[]Objects to move (not copy) to the worker thread.

WorkerHandle ​

ts
type WorkerHandle<TInput, TOutput> = {
  run(input: TInput, options?: RunOptions): Promise<TOutput>;
  dispose(): void;
  readonly size: number;
  readonly status: WorkerStatus;
  readonly isNative: boolean;
  [Symbol.dispose](): void;
};

The return type of createWorker. See WorkerHandle Interface for per-member documentation.

createWorker ​

ts
declare function createWorker<TInput, TOutput>(
  fn: TaskFn<TInput, TOutput>,
  options?: WorkerOptions,
): WorkerHandle<TInput, TOutput>;

Creates a worker (or pool) that executes fn in a Web Worker. If Workers are unavailable and fallback is true, tasks run on the main thread and a warning is logged.

Parameters

ParameterTypeDescription
fnTaskFn<TInput, TOutput>The task function. Must be self-contained — no closure over outer scope.
optionsWorkerOptionsOptional configuration (size, timeout, fallback, scripts).

Returns WorkerHandle<TInput, TOutput>

Example

ts
import { createWorker } from '@vielzeug/workit';

// Single worker
const worker = createWorker<string, string>((text) => text.toUpperCase());

// Pool of 4
const pool = createWorker<number, number>((n) => n ** 2, { size: 4, timeout: 3000 });

WorkerHandle Interface ​

run(input, options?) ​

run(input: TInput, options?: RunOptions): Promise<TOutput>

Dispatches a task to the next available worker slot. If all slots are busy, the task is queued.

Rejects with:

  • TaskTimeoutError — if timeout is configured and the task exceeds it
  • TerminatedError — if dispose() was called before or during the task
  • TaskError — if the task function throws
  • DOMException (AbortError) — if the provided signal is aborted before the task starts

WARNING

The task function is serialized via .toString() and runs in an isolated scope. It cannot close over variables from the surrounding module. Keep task functions entirely self-contained.

dispose() ​

dispose(): void

Terminates all worker threads and rejects any pending or in-flight tasks with TerminatedError. After calling dispose(), status becomes 'terminated' and further calls to run() reject immediately.

size ​

readonly size: number

The number of worker slots configured for this handle (always ≥ 1).

status ​

readonly status: WorkerStatus

The current state of the worker handle. See WorkerStatus.

isNative ​

readonly isNative: boolean

true when tasks run in a real Web Worker; false when falling back to the main thread. Useful for logging or telemetry.

[Symbol.dispose]() ​

[Symbol.dispose](): void

Alias for dispose(). Enables the ES2025 explicit resource management using keyword:

ts
{
  using worker = createWorker<number, number>((n) => n * 2);
  const result = await worker.run(21); // 42
} // automatically disposed here

Error Classes ​

All error classes extend WorkerError, so a single catch can cover every workit error:

ts
import { WorkerError, TaskTimeoutError, TerminatedError, TaskError } from '@vielzeug/workit';

try {
  await worker.run(input);
} catch (err) {
  if (err instanceof WorkerError) {
    // handles TaskTimeoutError, TerminatedError, or TaskError
  }
}

WorkerError ​

ts
class WorkerError extends Error {}

Base class for all workit errors. Use instanceof WorkerError to catch any error thrown by this library.

TaskTimeoutError ​

txt
class TaskTimeoutError extends WorkerError {
  constructor(ms: number)
}

Thrown when a task exceeds the configured timeout. The error message includes the configured limit in milliseconds.

TerminatedError ​

txt
class TerminatedError extends WorkerError {
  constructor()
}

Thrown when run() is called on a disposed handle, or when dispose() is called while a task is in flight.

TaskError ​

txt
class TaskError extends WorkerError {
  constructor(message: string, cause?: unknown)
}

Thrown when the task function itself throws. The message is the stringified original error.

WARNING

cause is only populated in fallback (main-thread) mode. In native Worker mode, errors cross the message boundary as strings, so cause is always undefined.

Testing Utilities ​

Import from the /test subpath — not included in the main bundle:

ts
import { createTestWorker } from '@vielzeug/workit/test';
import type { TestWorkerHandle } from '@vielzeug/workit/test';

createTestWorker ​

ts
declare function createTestWorker<TInput, TOutput>(fn: TaskFn<TInput, TOutput>): TestWorkerHandle<TInput, TOutput>;

Creates a TestWorkerHandle that runs fn in-process on the same thread and records successful calls. No Worker is ever spawned, so tests work in any environment.

TestWorkerHandle ​

ts
type TestWorkerHandle<TInput, TOutput> = WorkerHandle<TInput, TOutput> & {
  readonly calls: ReadonlyArray<{ input: TInput; output: TOutput }>;
};

Extends WorkerHandle with:

MemberTypeDescription
callsReadonlyArray<{ input, output }>All successful run() calls in order.
isNativebooleanAlways false — no Worker is spawned.
[Symbol.dispose]()voidSame as dispose().