Talking to a Worker

1. 1
   Serialise (sender thread)

   Structured clone walks the value and produces a serialised form.

   fails by Blocking the sender proportionally to payload size; throwing DataCloneError on a function, a DOM node or a class instance it cannot represent.

2. 2
   Queue

   A message event is queued as a task on the receiving thread's task queue.

   fails by Growing without bound when the producer outruns the consumer — no backpressure exists.

3. 3
   Wait

   The receiver finishes whatever task it is running.

   fails by A long task on the receiver delaying a message that was ready immediately.

4. 4
   Deserialise (receiver thread)

   A fresh object graph is allocated in the receiving realm.

   fails by Blocking the receiver, again proportionally to size; firing messageerror if it cannot be deserialised.

5. 5
   Dispatch

   onmessage runs, to completion, as one task.

   fails by An uncaught throw here rejects nothing on the other side — the requester waits forever.

6. 6
   Correlate

   Your code matches this reply to the request that asked for it.

   fails by Not existing. If you did not write it, a stale reply renders over a fresh one.

Steps 1 and 4 are why payload size matters. Steps 3 and 6 are why "the worker is slow" is usually not about the worker.

1type Pending = { resolve: (v: unknown) => void; reject: (e: Error) => void; timer: number }
2 
3export function createWorkerClient(url: URL, timeoutMs = 30_000) {
4  const worker = new Worker(url, { type: 'module' })
5  const pending = new Map<number, Pending>()
6  let nextId = 0
7 
8  const settle = (id: number, fn: (p: Pending) => void) => {
9    const p = pending.get(id)
10    if (!p) return                 // already timed out, or a stale reply
11    clearTimeout(p.timer)
12    pending.delete(id)             // every path deletes. every one.
13    fn(p)
14  }
15 
16  worker.onmessage = (e: MessageEvent<{ id: number; ok: boolean; value?: unknown; error?: string }>) => {
17    const { id, ok, value, error } = e.data
18    settle(id, (p) => (ok ? p.resolve(value) : p.reject(new Error(error))))
19  }
20 
21  // three separate silences, all of which must reject something
22  const failAll = (reason: string) => {
23    for (const id of [...pending.keys()]) settle(id, (p) => p.reject(new Error(reason)))
24  }
25  worker.onerror = (e) => failAll(`worker error: ${e.message}`)
26  worker.onmessageerror = () => failAll('worker sent an undeserialisable message')
27 
28  return {
29    call<T>(type: string, payload: unknown, transfer: Transferable[] = []): Promise<T> {
30      const id = ++nextId
31      return new Promise<T>((resolve, reject) => {
32        const timer = self.setTimeout(
33          () => settle(id, (p) => p.reject(new Error(`${type} timed out`))),
34          timeoutMs,
35        )
36        pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer })
37        worker.postMessage({ id, type, payload }, transfer)
38      })
39    },
40    dispose() { failAll('worker disposed'); worker.terminate() },
41  }
42}

Three distinct silences — a throw, an undeserialisable message, and a worker that simply never replies — all need to reject something. Handling only onerror covers one of the three.