Single Worker

useWorker() — main-thread composable, wraps a single lazily-created worker.

const { run, isRunning, progress, error, cancel, warmup } = useWorker<typeof import('./x.worker')>(
  () => new Worker(new URL('./x.worker.ts', import.meta.url), { type: 'module' }),
  { idleTimeout: 30_000, retries: 0 },
)

// Optional: pre-create the worker without running a task (avoids cold-start latency on first run)
await warmup()

const output = await run(input, { transfer: [input.buffer], signal: controller.signal })

run()'s input is passed through toRaw() before being posted — a ref/reactive value read straight off a component (() => list.value) is not structured-cloneable as a live Proxy, so the raw snapshot is what actually gets sent.

Options

idleTimeout

number | false · default: 30000

Worker self-terminates after this many ms idle (frees memory); the next run() transparently recreates it.

retries

number · default: 0

Automatic retries on rejection — never applied to cancellations (AbortError always rejects immediately). See Retry Strategy with Backoff.

retryDelay

(attempt: number) => number

Delay before each retry — see Retry Strategy with Backoff.

hardCancelOnAbort

boolean · default: false

On abort(), terminate and recreate the worker immediately instead of waiting for cooperative ctx.signal handling.

cache

{ cache: 'lru', maxCacheSize?: number }

Memoizes results by input — see Memoization / Result Cache.

streaming

boolean · default: false

Enables ctx.reportChunk()/chunks — see Streaming / Chunked Results.

Return value

run(input, options?)

(input: In, options?: { transfer?: Transferable[]; signal?: AbortSignal }) => Promise<Out>

isRunning

ComputedRef<boolean>

progress

ShallowRef<number>

error

ShallowRef<WorkerError | null>

cancel()

() => void

Aborts the current run() call(s) that didn't receive their own signal.

warmup()

() => Promise<void>

Pre-creates the worker without executing a task (useful for avoiding cold-start latency).

terminate()

() => void

Terminates the underlying worker immediately, if one exists — the next run()/warmup() transparently creates a fresh one. Call it directly when you need to tear a worker down on demand instead of waiting for idleTimeout or an abort — this matters in particular for a useWorker() created outside an active effect scope (for example inside a Pinia store or a plain factory function), where onScopeDispose never fires and the worker would otherwise only ever stop via the idle timer or hardCancelOnAbort.

chunks

ShallowRef<unknown[]> | undefined

Present only when streaming: true — see Streaming / Chunked Results.

Automatic terminate() on onScopeDispose when useWorker() is called inside an active effect scope — call terminate() yourself when there is no such scope.