@vielzeug/familiar 1.0.2

package/dist/worker.cjs

@@ -0,0 +1,28 @@
+const e=require("./errors.cjs"),t=require("./_dev.cjs"),n=require("./_timers.cjs"),r=require("./_pool.cjs");function i(t){if(t.toString().includes(`[native code]`))throw new e.FamiliarInvalidOptionsError(`Task function cannot be a bound or native function`);return t}var a=512;function o(t){if(t===void 0)return 1;if(t===`auto`)return Math.max(1,globalThis.navigator?.hardwareConcurrency??1);if(!Number.isInteger(t)||t<1||t>a)throw new e.FamiliarInvalidOptionsError(`\`concurrency\` must be a positive integer ≤ ${a} or "auto"`);return t}function s(t={}){let n=o(t.concurrency),{heartbeatWindow:r,maxQueue:i,onFull:a=`reject`,onSlotError:s,timeout:c}=t;if(c!==void 0&&(!Number.isFinite(c)||c<=0))throw new e.FamiliarInvalidOptionsError("`timeout` must be a finite number greater than 0");if(i!==void 0&&(!Number.isInteger(i)||i<1))throw new e.FamiliarInvalidOptionsError("`maxQueue` must be a positive integer");if(r!==void 0&&(!Number.isFinite(r)||r<=0))throw new e.FamiliarInvalidOptionsError("`heartbeatWindow` must be a finite number greater than 0");return{concurrency:n,heartbeatWindow:r,maxQueue:i,onFull:a,onSlotError:s,timeout:c}}function c(e,t){return`
+const __fn = (${e.toString()});
+
+self.onmessage = async function (event) {
+  const { id, input, stream } = event.data;
+
+  // Automatically send heartbeats at half the heartbeatWindow interval.
+  let heartbeatTimer = null;
+  ${t==null?``:`heartbeatTimer = setInterval(() => self.postMessage({ id, heartbeat: true }), ${t});`}
+
+  try {
+    if (stream) {
+      const iterable = await __fn(input);
+      for await (const chunk of iterable) {
+        self.postMessage({ id, chunk });
+      }
+      self.postMessage({ id, result: undefined });
+    } else {
+      const result = await __fn(input);
+      self.postMessage({ id, result });
+    }
+  } catch (error) {
+    self.postMessage({ id, error });
+  } finally {
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+  }
+}`.trim()}var l=class{config;onSlotError;disposed=!1;pending=null;taskId=0;worker=null;constructor(e,t){this.config=e,this.onSlotError=t}prime(){if(this.disposed)return Promise.resolve();try{this.ensureWorker()}catch{}return Promise.resolve()}run(e,t,n){return this.dispatch(e,t,n,!1)}runStream(e,t,n){let r=[],i=!1,a,o=[],s=e=>{r.push(e),o.shift()?.()},c=e=>{i=!0,a=e;for(let e of o.splice(0))e()};return this.dispatch(e,t,n,!0,s).then(()=>c(),c),this.pending&&(this.pending.finishStream=c),{[Symbol.asyncIterator](){let e=0;return{async next(){for(;e>=r.length&&!i;)await new Promise(e=>o.push(e));if(e<r.length){let t=r[e];return r[e]=null,e++,{done:!1,value:t}}if(a!==void 0)throw a;return{done:!0,value:void 0}}}}}}cancel(){let t=this.pending;t&&(clearTimeout(t.timer),clearTimeout(t.heartbeatWatchdog),this.pending=null,this.stopWorker(),t.finishStream?.(new e.FamiliarTerminatedError(`Stream was cancelled`)))}terminate(){this.disposed=!0,this.stopWorker(),this.failPending(new e.FamiliarTerminatedError)}dispatch(t,r,i,a,o){if(this.disposed)return Promise.reject(new e.FamiliarTerminatedError);let s;try{s=this.ensureWorker()}catch(e){return Promise.reject(e)}let c=this.config.kind===`inline`&&this.config.heartbeatInterval!=null?this.config.heartbeatInterval*2:void 0;return new Promise((l,u)=>{let d=this.taskId++,f={emit:o,id:d,reject:u,resolve:l,watchdogMs:c};i!==void 0&&(f.timer=setTimeout(()=>{this.restart(new e.FamiliarTimeoutError(i))},i),n.unrefTimer(f.timer)),c!==void 0&&(f.heartbeatWatchdog=setTimeout(()=>{this.restart(new e.FamiliarTimeoutError(c))},c),n.unrefTimer(f.heartbeatWatchdog)),this.pending=f;try{s.postMessage({id:d,input:t,stream:a},r)}catch(t){this.failPending(new e.FamiliarRuntimeError(t instanceof Error?t.message:String(t),{cause:t}))}})}ensureWorker(){if(this.worker)return this.worker;if(typeof globalThis.Worker!=`function`)throw new e.FamiliarRuntimeError(`Worker API is unavailable in this runtime`);let t;if(this.config.kind===`module`)try{t=new Worker(this.config.url,{type:`module`})}catch(t){throw new e.FamiliarRuntimeError(`Failed to create Worker`,{cause:t})}else try{let e=new Blob([c(this.config.fn,this.config.heartbeatInterval)],{type:`application/javascript`}),n=URL.createObjectURL(e);try{t=new Worker(n)}finally{URL.revokeObjectURL(n)}}catch(t){throw new e.FamiliarRuntimeError(`Failed to create Worker`,{cause:t})}return t.onmessage=t=>{let r=this.pending;if(!(!r||t.data.id!==r.id)){if(`heartbeat`in t.data){r.watchdogMs!==void 0&&(clearTimeout(r.heartbeatWatchdog),r.heartbeatWatchdog=setTimeout(()=>{this.restart(new e.FamiliarTimeoutError(r.watchdogMs))},r.watchdogMs),n.unrefTimer(r.heartbeatWatchdog));return}if(`chunk`in t.data){r.emit?.(t.data.chunk);return}if(clearTimeout(r.timer),clearTimeout(r.heartbeatWatchdog),this.pending=null,`error`in t.data){let n=t.data.error instanceof Error?t.data.error:Error(String(t.data.error));r.reject(new e.FamiliarTaskError(n.message,{cause:n}))}else r.resolve(t.data.result)}},t.onerror=t=>{let n=new e.FamiliarRuntimeError(t.message);this.stopWorker(),this.failPending(n),this.onSlotError?.(n,()=>void this.prime())},this.worker=t,t}failPending(e){let t=this.pending;t&&(clearTimeout(t.timer),clearTimeout(t.heartbeatWatchdog),this.pending=null,t.reject(e))}restart(e){this.stopWorker(),this.failPending(e)}stopWorker(){this.worker&&=(this.worker.terminate(),null)}};function u(e,t){let{concurrency:n,heartbeatWindow:i,maxQueue:a,onFull:o,onSlotError:c,timeout:u}=s(t),d=i==null?void 0:Math.floor(i/2);return r.createPool(Array.from({length:n},()=>new l({fn:e,heartbeatInterval:d,kind:`inline`},c)),{concurrency:n,defaultTimeout:u,maxQueue:a,onFull:o})}function d(e,n){let{concurrency:i,heartbeatWindow:a,maxQueue:o,onFull:c,onSlotError:u,timeout:d}=s(n);a!==void 0&&t.warn("`heartbeatWindow` has no effect on module workers — the worker script must implement the heartbeat protocol manually.");let f=typeof e==`string`?e:e.href;return r.createPool(Array.from({length:i},()=>new l({kind:`module`,url:f},u)),{concurrency:i,defaultTimeout:d,maxQueue:o,onFull:c})}exports.FamiliarError=e.FamiliarError,exports.FamiliarInvalidOptionsError=e.FamiliarInvalidOptionsError,exports.FamiliarQueueFullError=e.FamiliarQueueFullError,exports.FamiliarRuntimeError=e.FamiliarRuntimeError,exports.FamiliarTaskError=e.FamiliarTaskError,exports.FamiliarTerminatedError=e.FamiliarTerminatedError,exports.FamiliarTimeoutError=e.FamiliarTimeoutError,exports.createModuleWorker=d,exports.createWorker=u,exports.task=i;
+//# sourceMappingURL=worker.cjs.map

package/dist/worker.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.cjs","names":[],"sources":["../src/worker.ts"],"sourcesContent":["// Re-export all public types and classes so consumers only need one import.\nexport type {\n  BatchOptions,\n  GroupOptions,\n  RunOptions,\n  TaskFn,\n  TaskGroup,\n  WorkerHandle,\n  WorkerOptions,\n  WorkerStatus,\n} from './types';\nexport {\n  FamiliarError,\n  FamiliarInvalidOptionsError,\n  FamiliarQueueFullError,\n  FamiliarRuntimeError,\n  FamiliarTaskError,\n  FamiliarTerminatedError,\n  FamiliarTimeoutError,\n} from './errors';\n\nimport type { SlotStrategy, TaskFn, WorkerHandle, WorkerOptions } from './types';\n\nimport { warn } from './_dev';\nimport { createPool } from './_pool';\nimport { unrefTimer } from './_timers';\nimport {\n  FamiliarInvalidOptionsError,\n  FamiliarRuntimeError,\n  FamiliarTaskError,\n  FamiliarTerminatedError,\n  FamiliarTimeoutError,\n} from './errors';\n\n// ─── task() — optional validation helper ─────────────────────────────────────\n\n/**\n * Optional helper that validates a function is safe to serialize for use in `createWorker`.\n *\n * `createWorker` accepts any `TaskFn` directly — this helper exists only to catch the common\n * mistake of passing a bound or native function whose body cannot be serialized.\n *\n * IMPORTANT: The function is serialized via `.toString()` and runs in an isolated Worker scope.\n * It **cannot** close over variables from the surrounding module — any outer reference resolves\n * to `undefined` inside the worker.\n *\n * @throws FamiliarInvalidOptionsError if the function is bound or native.\n *\n * @example\n * // Without task() — works fine for plain arrow functions:\n * const worker = createWorker((n: number) => n * 2);\n *\n * // With task() — catches the mistake of passing Math.sqrt directly:\n * const worker = createWorker(task((n: number) => Math.sqrt(n)));\n */\nexport function task<TInput, TOutput>(fn: TaskFn<TInput, TOutput>): TaskFn<TInput, TOutput> {\n  if (fn.toString().includes('[native code]')) {\n    throw new FamiliarInvalidOptionsError('Task function cannot be a bound or native function');\n  }\n\n  return fn;\n}\n\n// ─── Options resolution ───────────────────────────────────────────────────────\n\n/** Upper bound on `concurrency`: generous headroom over realistic hardware/IO limits while still catching obvious misconfiguration (e.g. a typo like `50000`). */\nconst MAX_CONCURRENCY = 512;\n\nfunction resolveConcurrency(value: WorkerOptions['concurrency']): number {\n  if (value === undefined) return 1;\n\n  if (value === 'auto') {\n    return Math.max(1, globalThis.navigator?.hardwareConcurrency ?? 1);\n  }\n\n  if (!Number.isInteger(value) || value < 1 || value > MAX_CONCURRENCY) {\n    throw new FamiliarInvalidOptionsError(`\\`concurrency\\` must be a positive integer ≤ ${MAX_CONCURRENCY} or \"auto\"`);\n  }\n\n  return value;\n}\n\nfunction resolveOptions(options: WorkerOptions = {}): {\n  concurrency: number;\n  heartbeatWindow: number | undefined;\n  maxQueue: number | undefined;\n  onFull: 'reject' | 'wait';\n  onSlotError: WorkerOptions['onSlotError'];\n  timeout: number | undefined;\n} {\n  const concurrency = resolveConcurrency(options.concurrency);\n  const { heartbeatWindow, maxQueue, onFull = 'reject', onSlotError, timeout } = options;\n\n  if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0)) {\n    throw new FamiliarInvalidOptionsError('`timeout` must be a finite number greater than 0');\n  }\n\n  if (maxQueue !== undefined && (!Number.isInteger(maxQueue) || maxQueue < 1)) {\n    throw new FamiliarInvalidOptionsError('`maxQueue` must be a positive integer');\n  }\n\n  if (heartbeatWindow !== undefined && (!Number.isFinite(heartbeatWindow) || heartbeatWindow <= 0)) {\n    throw new FamiliarInvalidOptionsError('`heartbeatWindow` must be a finite number greater than 0');\n  }\n\n  return { concurrency, heartbeatWindow, maxQueue, onFull, onSlotError, timeout };\n}\n\n// ─── Worker script builder ────────────────────────────────────────────────────\n\n/**\n * @security `fn.toString()` is injected verbatim into the blob script. Any code embedded in the\n * serialized function executes only inside the isolated Worker scope — no shared memory, no access\n * to the host page's globals. Risk is therefore low, but callers should only pass plain functions\n * that do not close over module scope.\n */\nfunction buildWorkerScript(fn: TaskFn<unknown, unknown>, heartbeatInterval: number | undefined): string {\n  return `\nconst __fn = (${fn.toString()});\n\nself.onmessage = async function (event) {\n  const { id, input, stream } = event.data;\n\n  // Automatically send heartbeats at half the heartbeatWindow interval.\n  let heartbeatTimer = null;\n  ${heartbeatInterval != null ? `heartbeatTimer = setInterval(() => self.postMessage({ id, heartbeat: true }), ${heartbeatInterval});` : ''}\n\n  try {\n    if (stream) {\n      const iterable = await __fn(input);\n      for await (const chunk of iterable) {\n        self.postMessage({ id, chunk });\n      }\n      self.postMessage({ id, result: undefined });\n    } else {\n      const result = await __fn(input);\n      self.postMessage({ id, result });\n    }\n  } catch (error) {\n    self.postMessage({ id, error });\n  } finally {\n    if (heartbeatTimer) clearInterval(heartbeatTimer);\n  }\n}`.trim();\n}\n\n// ─── SlotConfig discriminated union ──────────────────────────────────────────\n\ntype SlotConfig<TInput, TOutput> =\n  | { fn: TaskFn<TInput, TOutput>; heartbeatInterval: number | undefined; kind: 'inline' }\n  | { kind: 'module'; url: string };\n\n// ─── PendingTask ─────────────────────────────────────────────────────────────\n\ntype SlotMessage<TOutput> =\n  | { error: unknown; id: number }\n  | { chunk: TOutput; id: number }\n  | { heartbeat: true; id: number }\n  | { id: number; result: TOutput };\n\ntype PendingTask<TOutput> = {\n  /** Emits intermediate stream chunks. Undefined for non-streaming tasks. */\n  emit?: (chunk: TOutput) => void;\n  /** Called with an error when the streaming dispatch is cancelled mid-flight, so the finish closure drains its waiters. */\n  finishStream?: (err: unknown) => void;\n  /**\n   * Single-shot timer that fires if no heartbeat is received within watchdogMs.\n   * Reset (cleared + recreated) on every incoming heartbeat message.\n   * Uses setTimeout because the watchdog is conceptually one-shot with manual reset,\n   * not a recurring interval.\n   */\n  heartbeatWatchdog?: ReturnType<typeof setTimeout>;\n  id: number;\n  reject: (reason: unknown) => void;\n  resolve: (value: TOutput) => void;\n  timer?: ReturnType<typeof setTimeout>;\n  /** Watchdog window in ms (= heartbeatWindow). Stored on PendingTask to reset the timer on each heartbeat. */\n  watchdogMs?: number;\n};\n\n// ─── Slot — implements SlotStrategy ──────────────────────────────────────────\n\nclass Slot<TInput, TOutput> implements SlotStrategy<TInput, TOutput> {\n  private readonly config: SlotConfig<TInput, TOutput>;\n  private readonly onSlotError: WorkerOptions['onSlotError'];\n  private disposed = false;\n  private pending: PendingTask<TOutput> | null = null;\n  private taskId = 0;\n  private worker: Worker | null = null;\n\n  constructor(config: SlotConfig<TInput, TOutput>, onSlotError?: WorkerOptions['onSlotError']) {\n    this.config = config;\n    this.onSlotError = onSlotError;\n  }\n\n  prime(): Promise<void> {\n    if (this.disposed) return Promise.resolve();\n\n    try {\n      this.ensureWorker();\n    } catch {\n      // Best-effort — errors surface on the first run() call.\n    }\n\n    return Promise.resolve();\n  }\n\n  run(input: TInput, transferables: Transferable[], timeout: number | undefined): Promise<TOutput> {\n    return this.dispatch(input, transferables, timeout, false) as Promise<TOutput>;\n  }\n\n  runStream(input: TInput, transferables: Transferable[], timeout: number | undefined): AsyncIterable<TOutput> {\n    const chunks: TOutput[] = [];\n    let done = false;\n    let error: unknown;\n    const waiters: Array<() => void> = [];\n\n    const emit = (chunk: TOutput) => {\n      chunks.push(chunk);\n      waiters.shift()?.();\n    };\n\n    const finish = (err?: unknown) => {\n      done = true;\n      error = err;\n\n      for (const w of waiters.splice(0)) w();\n    };\n\n    // Dispatch the task in stream mode. The promise resolves when the worker signals done.\n    // finishStream is stored on the PendingTask so cancel() can drain the waiters if the\n    // consumer exits early (break/throw from for-await), preventing a permanently dangling Promise.\n    // this.pending is set synchronously inside dispatch(), so this assignment is safe.\n    this.dispatch(input, transferables, timeout, true, emit).then(() => finish(), finish);\n\n    if (this.pending) this.pending.finishStream = finish;\n\n    return {\n      [Symbol.asyncIterator]() {\n        let cursor = 0;\n\n        return {\n          async next(): Promise<IteratorResult<TOutput>> {\n            while (cursor >= chunks.length && !done) {\n              await new Promise<void>((resolve) => waiters.push(resolve));\n            }\n\n            if (cursor < chunks.length) {\n              const value = chunks[cursor]!;\n\n              // Null-out the consumed slot so GC can collect the value\n              // without waiting for the entire stream to close.\n              (chunks as (TOutput | null)[])[cursor] = null;\n              cursor++;\n\n              return { done: false, value };\n            }\n\n            if (error !== undefined) throw error;\n\n            return { done: true, value: undefined as unknown as TOutput };\n          },\n        };\n      },\n    };\n  }\n\n  cancel(): void {\n    const pending = this.pending;\n\n    if (!pending) return;\n\n    clearTimeout(pending.timer);\n    clearTimeout(pending.heartbeatWatchdog);\n    this.pending = null;\n    // Terminate the worker: the streaming task may still be running and sending chunks.\n    // A fresh worker is created on the next run() or runStream() call via ensureWorker().\n    this.stopWorker();\n    // Drain the stream finish closure so any pending .next() waiters resolve immediately\n    // rather than leaking as permanently dangling Promises.\n    pending.finishStream?.(new FamiliarTerminatedError('Stream was cancelled'));\n  }\n\n  terminate(): void {\n    this.disposed = true;\n    this.stopWorker();\n    this.failPending(new FamiliarTerminatedError());\n  }\n\n  private dispatch(\n    input: TInput,\n    transferables: Transferable[],\n    timeout: number | undefined,\n    stream: boolean,\n    emit?: (chunk: TOutput) => void,\n  ): Promise<TOutput | void> {\n    if (this.disposed) {\n      return Promise.reject(new FamiliarTerminatedError());\n    }\n\n    let worker: Worker;\n\n    try {\n      worker = this.ensureWorker();\n    } catch (error) {\n      return Promise.reject(error);\n    }\n\n    // watchdogMs = heartbeatInterval * 2 (Nyquist margin: worker beats at interval, host allows 2× before firing).\n    const watchdogMs =\n      this.config.kind === 'inline' && this.config.heartbeatInterval != null\n        ? this.config.heartbeatInterval * 2\n        : undefined;\n\n    return new Promise<TOutput | void>((resolve, reject) => {\n      const id = this.taskId++;\n      const pending: PendingTask<TOutput> = {\n        emit,\n        id,\n        reject,\n        resolve: resolve as (v: TOutput) => void,\n        watchdogMs,\n      };\n\n      if (timeout !== undefined) {\n        pending.timer = setTimeout(() => {\n          this.restart(new FamiliarTimeoutError(timeout));\n        }, timeout);\n        unrefTimer(pending.timer);\n      }\n\n      if (watchdogMs !== undefined) {\n        pending.heartbeatWatchdog = setTimeout(() => {\n          this.restart(new FamiliarTimeoutError(watchdogMs));\n        }, watchdogMs);\n        unrefTimer(pending.heartbeatWatchdog);\n      }\n\n      this.pending = pending;\n\n      try {\n        worker.postMessage({ id, input, stream }, transferables);\n      } catch (err) {\n        this.failPending(new FamiliarRuntimeError(err instanceof Error ? err.message : String(err), { cause: err }));\n      }\n    });\n  }\n\n  private ensureWorker(): Worker {\n    if (this.worker) return this.worker;\n\n    if (typeof globalThis.Worker !== 'function') {\n      throw new FamiliarRuntimeError('Worker API is unavailable in this runtime');\n    }\n\n    let worker: Worker;\n\n    if (this.config.kind === 'module') {\n      try {\n        worker = new Worker(this.config.url, { type: 'module' });\n      } catch (error) {\n        throw new FamiliarRuntimeError('Failed to create Worker', { cause: error });\n      }\n    } else {\n      try {\n        const blob = new Blob(\n          [buildWorkerScript(this.config.fn as TaskFn<unknown, unknown>, this.config.heartbeatInterval)],\n          { type: 'application/javascript' },\n        );\n        const url = URL.createObjectURL(blob);\n\n        try {\n          worker = new Worker(url);\n        } finally {\n          URL.revokeObjectURL(url);\n        }\n      } catch (error) {\n        throw new FamiliarRuntimeError('Failed to create Worker', { cause: error });\n      }\n    }\n\n    worker.onmessage = (event: MessageEvent<SlotMessage<TOutput>>) => {\n      const pending = this.pending;\n\n      if (!pending || event.data.id !== pending.id) return;\n\n      // Handle heartbeat message — reset the watchdog timer.\n      if ('heartbeat' in event.data) {\n        if (pending.watchdogMs !== undefined) {\n          clearTimeout(pending.heartbeatWatchdog);\n          pending.heartbeatWatchdog = setTimeout(() => {\n            this.restart(new FamiliarTimeoutError(pending.watchdogMs!));\n          }, pending.watchdogMs);\n          unrefTimer(pending.heartbeatWatchdog);\n        }\n\n        return;\n      }\n\n      if ('chunk' in event.data) {\n        pending.emit?.(event.data.chunk);\n\n        return;\n      }\n\n      clearTimeout(pending.timer);\n      clearTimeout(pending.heartbeatWatchdog);\n      this.pending = null;\n\n      if ('error' in event.data) {\n        const cause = event.data.error instanceof Error ? event.data.error : new Error(String(event.data.error));\n\n        pending.reject(new FamiliarTaskError(cause.message, { cause }));\n      } else {\n        pending.resolve(event.data.result);\n      }\n    };\n\n    worker.onerror = (event: ErrorEvent) => {\n      const error = new FamiliarRuntimeError(event.message);\n\n      // Stop and fail before calling the external callback so it sees a clean state.\n      this.stopWorker();\n      this.failPending(error);\n\n      this.onSlotError?.(error, () => void this.prime());\n    };\n\n    this.worker = worker;\n\n    return worker;\n  }\n\n  private failPending(reason: unknown): void {\n    const pending = this.pending;\n\n    if (!pending) return;\n\n    clearTimeout(pending.timer);\n    clearTimeout(pending.heartbeatWatchdog);\n    this.pending = null;\n    pending.reject(reason);\n  }\n\n  private restart(reason: unknown): void {\n    this.stopWorker();\n    this.failPending(reason);\n  }\n\n  private stopWorker(): void {\n    if (!this.worker) return;\n\n    this.worker.terminate();\n    this.worker = null;\n  }\n}\n\n// ─── createWorker ─────────────────────────────────────────────────────────────\n\n/**\n * Creates a pool of Web Workers that run `fn` in parallel.\n *\n * The task function is serialized via `.toString()` and runs in a separate global scope.\n * It cannot close over variables from the surrounding module.\n *\n * Use the optional `task()` helper to validate that the function is not bound or native.\n * For workers that need imports, see `createModuleWorker`.\n *\n * @example\n * // Plain arrow function — most common case:\n * const worker = createWorker((n: number) => n * 2);\n *\n * // With task() for validation:\n * const worker = createWorker(task((n: number) => n * 2));\n */\nexport function createWorker<TInput, TOutput>(\n  fn: TaskFn<TInput, TOutput>,\n  options?: WorkerOptions,\n): WorkerHandle<TInput, TOutput> {\n  const { concurrency, heartbeatWindow, maxQueue, onFull, onSlotError, timeout } = resolveOptions(options);\n  const heartbeatInterval = heartbeatWindow != null ? Math.floor(heartbeatWindow / 2) : undefined;\n\n  const slots = Array.from(\n    { length: concurrency },\n    () => new Slot<TInput, TOutput>({ fn, heartbeatInterval, kind: 'inline' }, onSlotError),\n  );\n\n  return createPool(slots, {\n    concurrency,\n    defaultTimeout: timeout,\n    maxQueue,\n    onFull,\n  });\n}\n\n// ─── createModuleWorker ───────────────────────────────────────────────────────\n\n/**\n * Creates a pool of module-type Web Workers loaded from a real URL.\n *\n * Unlike `createWorker`, the worker file is a regular module — it can import utilities,\n * use top-level await, and reference module scope.\n *\n * Use `handleMessages` from `@vielzeug/familiar/protocol` in the worker file to implement\n * the message protocol without boilerplate.\n *\n * **Protocol**: The worker module must handle the `{ id, input }` message format and reply\n * with `{ id, result }` or `{ id, error: { name, message, stack } }`. For streaming, it must\n * send one or more `{ id, chunk }` messages followed by `{ id, result: undefined }`.\n * For heartbeat support, send `{ id, heartbeat: true }` at regular intervals.\n *\n * @example\n * ```ts\n * // my-worker.ts — use handleMessages for zero boilerplate:\n * import { handleMessages } from '@vielzeug/familiar/protocol';\n * handleMessages(async (input: number) => input * 2);\n *\n * // main.ts\n * const pool = createModuleWorker<number, number>(\n *   new URL('./my-worker.ts', import.meta.url),\n *   { concurrency: 4 },\n * );\n * ```\n */\nexport function createModuleWorker<TInput, TOutput>(\n  url: URL | string,\n  options?: WorkerOptions,\n): WorkerHandle<TInput, TOutput> {\n  const { concurrency, heartbeatWindow, maxQueue, onFull, onSlotError, timeout } = resolveOptions(options);\n\n  if (heartbeatWindow !== undefined) {\n    warn(\n      '`heartbeatWindow` has no effect on module workers — the worker script must implement the heartbeat protocol manually.',\n    );\n  }\n\n  const href = typeof url === 'string' ? url : url.href;\n\n  const slots = Array.from(\n    { length: concurrency },\n    () => new Slot<TInput, TOutput>({ kind: 'module', url: href }, onSlotError),\n  );\n\n  return createPool(slots, {\n    concurrency,\n    defaultTimeout: timeout,\n    maxQueue,\n    onFull,\n  });\n}\n"],"mappings":"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"}

package/dist/worker.d.ts

@@ -0,0 +1,69 @@
+export type { BatchOptions, GroupOptions, RunOptions, TaskFn, TaskGroup, WorkerHandle, WorkerOptions, WorkerStatus, } from './types';
+export { FamiliarError, FamiliarInvalidOptionsError, FamiliarQueueFullError, FamiliarRuntimeError, FamiliarTaskError, FamiliarTerminatedError, FamiliarTimeoutError, } from './errors';
+import type { TaskFn, WorkerHandle, WorkerOptions } from './types';
+/**
+ * Optional helper that validates a function is safe to serialize for use in `createWorker`.
+ *
+ * `createWorker` accepts any `TaskFn` directly — this helper exists only to catch the common
+ * mistake of passing a bound or native function whose body cannot be serialized.
+ *
+ * IMPORTANT: The function is serialized via `.toString()` and runs in an isolated Worker scope.
+ * It **cannot** close over variables from the surrounding module — any outer reference resolves
+ * to `undefined` inside the worker.
+ *
+ * @throws FamiliarInvalidOptionsError if the function is bound or native.
+ *
+ * @example
+ * // Without task() — works fine for plain arrow functions:
+ * const worker = createWorker((n: number) => n * 2);
+ *
+ * // With task() — catches the mistake of passing Math.sqrt directly:
+ * const worker = createWorker(task((n: number) => Math.sqrt(n)));
+ */
+export declare function task<TInput, TOutput>(fn: TaskFn<TInput, TOutput>): TaskFn<TInput, TOutput>;
+/**
+ * Creates a pool of Web Workers that run `fn` in parallel.
+ *
+ * The task function is serialized via `.toString()` and runs in a separate global scope.
+ * It cannot close over variables from the surrounding module.
+ *
+ * Use the optional `task()` helper to validate that the function is not bound or native.
+ * For workers that need imports, see `createModuleWorker`.
+ *
+ * @example
+ * // Plain arrow function — most common case:
+ * const worker = createWorker((n: number) => n * 2);
+ *
+ * // With task() for validation:
+ * const worker = createWorker(task((n: number) => n * 2));
+ */
+export declare function createWorker<TInput, TOutput>(fn: TaskFn<TInput, TOutput>, options?: WorkerOptions): WorkerHandle<TInput, TOutput>;
+/**
+ * Creates a pool of module-type Web Workers loaded from a real URL.
+ *
+ * Unlike `createWorker`, the worker file is a regular module — it can import utilities,
+ * use top-level await, and reference module scope.
+ *
+ * Use `handleMessages` from `@vielzeug/familiar/protocol` in the worker file to implement
+ * the message protocol without boilerplate.
+ *
+ * **Protocol**: The worker module must handle the `{ id, input }` message format and reply
+ * with `{ id, result }` or `{ id, error: { name, message, stack } }`. For streaming, it must
+ * send one or more `{ id, chunk }` messages followed by `{ id, result: undefined }`.
+ * For heartbeat support, send `{ id, heartbeat: true }` at regular intervals.
+ *
+ * @example
+ * ```ts
+ * // my-worker.ts — use handleMessages for zero boilerplate:
+ * import { handleMessages } from '@vielzeug/familiar/protocol';
+ * handleMessages(async (input: number) => input * 2);
+ *
+ * // main.ts
+ * const pool = createModuleWorker<number, number>(
+ *   new URL('./my-worker.ts', import.meta.url),
+ *   { concurrency: 4 },
+ * );
+ * ```
+ */
+export declare function createModuleWorker<TInput, TOutput>(url: URL | string, options?: WorkerOptions): WorkerHandle<TInput, TOutput>;
+//# sourceMappingURL=worker.d.ts.map

package/dist/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../src/worker.ts"],"names":[],"mappings":"AACA,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,MAAM,EACN,SAAS,EACT,YAAY,EACZ,aAAa,EACb,YAAY,GACb,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,aAAa,EACb,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,UAAU,CAAC;AAElB,OAAO,KAAK,EAAgB,MAAM,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAejF;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAM1F;AA8YD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAC1C,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3B,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAe/B;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,OAAO,EAChD,GAAG,EAAE,GAAG,GAAG,MAAM,EACjB,OAAO,CAAC,EAAE,aAAa,GACtB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAsB/B"}

package/dist/worker.js

@@ -0,0 +1,229 @@
+import { FamiliarError as e, FamiliarInvalidOptionsError as t, FamiliarQueueFullError as n, FamiliarRuntimeError as r, FamiliarTaskError as i, FamiliarTerminatedError as a, FamiliarTimeoutError as o } from "./errors.js";
+import { warn as s } from "./_dev.js";
+import { unrefTimer as c } from "./_timers.js";
+import { createPool as l } from "./_pool.js";
+//#region src/worker.ts
+function u(e) {
+	if (e.toString().includes("[native code]")) throw new t("Task function cannot be a bound or native function");
+	return e;
+}
+var d = 512;
+function f(e) {
+	if (e === void 0) return 1;
+	if (e === "auto") return Math.max(1, globalThis.navigator?.hardwareConcurrency ?? 1);
+	if (!Number.isInteger(e) || e < 1 || e > d) throw new t(`\`concurrency\` must be a positive integer ≤ ${d} or "auto"`);
+	return e;
+}
+function p(e = {}) {
+	let n = f(e.concurrency), { heartbeatWindow: r, maxQueue: i, onFull: a = "reject", onSlotError: o, timeout: s } = e;
+	if (s !== void 0 && (!Number.isFinite(s) || s <= 0)) throw new t("`timeout` must be a finite number greater than 0");
+	if (i !== void 0 && (!Number.isInteger(i) || i < 1)) throw new t("`maxQueue` must be a positive integer");
+	if (r !== void 0 && (!Number.isFinite(r) || r <= 0)) throw new t("`heartbeatWindow` must be a finite number greater than 0");
+	return {
+		concurrency: n,
+		heartbeatWindow: r,
+		maxQueue: i,
+		onFull: a,
+		onSlotError: o,
+		timeout: s
+	};
+}
+function m(e, t) {
+	return `
+const __fn = (${e.toString()});
+
+self.onmessage = async function (event) {
+  const { id, input, stream } = event.data;
+
+  // Automatically send heartbeats at half the heartbeatWindow interval.
+  let heartbeatTimer = null;
+  ${t == null ? "" : `heartbeatTimer = setInterval(() => self.postMessage({ id, heartbeat: true }), ${t});`}
+
+  try {
+    if (stream) {
+      const iterable = await __fn(input);
+      for await (const chunk of iterable) {
+        self.postMessage({ id, chunk });
+      }
+      self.postMessage({ id, result: undefined });
+    } else {
+      const result = await __fn(input);
+      self.postMessage({ id, result });
+    }
+  } catch (error) {
+    self.postMessage({ id, error });
+  } finally {
+    if (heartbeatTimer) clearInterval(heartbeatTimer);
+  }
+}`.trim();
+}
+var h = class {
+	config;
+	onSlotError;
+	disposed = !1;
+	pending = null;
+	taskId = 0;
+	worker = null;
+	constructor(e, t) {
+		this.config = e, this.onSlotError = t;
+	}
+	prime() {
+		if (this.disposed) return Promise.resolve();
+		try {
+			this.ensureWorker();
+		} catch {}
+		return Promise.resolve();
+	}
+	run(e, t, n) {
+		return this.dispatch(e, t, n, !1);
+	}
+	runStream(e, t, n) {
+		let r = [], i = !1, a, o = [], s = (e) => {
+			r.push(e), o.shift()?.();
+		}, c = (e) => {
+			i = !0, a = e;
+			for (let e of o.splice(0)) e();
+		};
+		return this.dispatch(e, t, n, !0, s).then(() => c(), c), this.pending && (this.pending.finishStream = c), { [Symbol.asyncIterator]() {
+			let e = 0;
+			return { async next() {
+				for (; e >= r.length && !i;) await new Promise((e) => o.push(e));
+				if (e < r.length) {
+					let t = r[e];
+					return r[e] = null, e++, {
+						done: !1,
+						value: t
+					};
+				}
+				if (a !== void 0) throw a;
+				return {
+					done: !0,
+					value: void 0
+				};
+			} };
+		} };
+	}
+	cancel() {
+		let e = this.pending;
+		e && (clearTimeout(e.timer), clearTimeout(e.heartbeatWatchdog), this.pending = null, this.stopWorker(), e.finishStream?.(new a("Stream was cancelled")));
+	}
+	terminate() {
+		this.disposed = !0, this.stopWorker(), this.failPending(new a());
+	}
+	dispatch(e, t, n, i, s) {
+		if (this.disposed) return Promise.reject(new a());
+		let l;
+		try {
+			l = this.ensureWorker();
+		} catch (e) {
+			return Promise.reject(e);
+		}
+		let u = this.config.kind === "inline" && this.config.heartbeatInterval != null ? this.config.heartbeatInterval * 2 : void 0;
+		return new Promise((a, d) => {
+			let f = this.taskId++, p = {
+				emit: s,
+				id: f,
+				reject: d,
+				resolve: a,
+				watchdogMs: u
+			};
+			n !== void 0 && (p.timer = setTimeout(() => {
+				this.restart(new o(n));
+			}, n), c(p.timer)), u !== void 0 && (p.heartbeatWatchdog = setTimeout(() => {
+				this.restart(new o(u));
+			}, u), c(p.heartbeatWatchdog)), this.pending = p;
+			try {
+				l.postMessage({
+					id: f,
+					input: e,
+					stream: i
+				}, t);
+			} catch (e) {
+				this.failPending(new r(e instanceof Error ? e.message : String(e), { cause: e }));
+			}
+		});
+	}
+	ensureWorker() {
+		if (this.worker) return this.worker;
+		if (typeof globalThis.Worker != "function") throw new r("Worker API is unavailable in this runtime");
+		let e;
+		if (this.config.kind === "module") try {
+			e = new Worker(this.config.url, { type: "module" });
+		} catch (e) {
+			throw new r("Failed to create Worker", { cause: e });
+		}
+		else try {
+			let t = new Blob([m(this.config.fn, this.config.heartbeatInterval)], { type: "application/javascript" }), n = URL.createObjectURL(t);
+			try {
+				e = new Worker(n);
+			} finally {
+				URL.revokeObjectURL(n);
+			}
+		} catch (e) {
+			throw new r("Failed to create Worker", { cause: e });
+		}
+		return e.onmessage = (e) => {
+			let t = this.pending;
+			if (!(!t || e.data.id !== t.id)) {
+				if ("heartbeat" in e.data) {
+					t.watchdogMs !== void 0 && (clearTimeout(t.heartbeatWatchdog), t.heartbeatWatchdog = setTimeout(() => {
+						this.restart(new o(t.watchdogMs));
+					}, t.watchdogMs), c(t.heartbeatWatchdog));
+					return;
+				}
+				if ("chunk" in e.data) {
+					t.emit?.(e.data.chunk);
+					return;
+				}
+				if (clearTimeout(t.timer), clearTimeout(t.heartbeatWatchdog), this.pending = null, "error" in e.data) {
+					let n = e.data.error instanceof Error ? e.data.error : Error(String(e.data.error));
+					t.reject(new i(n.message, { cause: n }));
+				} else t.resolve(e.data.result);
+			}
+		}, e.onerror = (e) => {
+			let t = new r(e.message);
+			this.stopWorker(), this.failPending(t), this.onSlotError?.(t, () => void this.prime());
+		}, this.worker = e, e;
+	}
+	failPending(e) {
+		let t = this.pending;
+		t && (clearTimeout(t.timer), clearTimeout(t.heartbeatWatchdog), this.pending = null, t.reject(e));
+	}
+	restart(e) {
+		this.stopWorker(), this.failPending(e);
+	}
+	stopWorker() {
+		this.worker &&= (this.worker.terminate(), null);
+	}
+};
+function g(e, t) {
+	let { concurrency: n, heartbeatWindow: r, maxQueue: i, onFull: a, onSlotError: o, timeout: s } = p(t), c = r == null ? void 0 : Math.floor(r / 2);
+	return l(Array.from({ length: n }, () => new h({
+		fn: e,
+		heartbeatInterval: c,
+		kind: "inline"
+	}, o)), {
+		concurrency: n,
+		defaultTimeout: s,
+		maxQueue: i,
+		onFull: a
+	});
+}
+function _(e, t) {
+	let { concurrency: n, heartbeatWindow: r, maxQueue: i, onFull: a, onSlotError: o, timeout: c } = p(t);
+	r !== void 0 && s("`heartbeatWindow` has no effect on module workers — the worker script must implement the heartbeat protocol manually.");
+	let u = typeof e == "string" ? e : e.href;
+	return l(Array.from({ length: n }, () => new h({
+		kind: "module",
+		url: u
+	}, o)), {
+		concurrency: n,
+		defaultTimeout: c,
+		maxQueue: i,
+		onFull: a
+	});
+}
+//#endregion
+export { e as FamiliarError, t as FamiliarInvalidOptionsError, n as FamiliarQueueFullError, r as FamiliarRuntimeError, i as FamiliarTaskError, a as FamiliarTerminatedError, o as FamiliarTimeoutError, _ as createModuleWorker, g as createWorker, u as task };
+
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","names":[],"sources":["../src/worker.ts"],"sourcesContent":["// Re-export all public types and classes so consumers only need one import.\nexport type {\n  BatchOptions,\n  GroupOptions,\n  RunOptions,\n  TaskFn,\n  TaskGroup,\n  WorkerHandle,\n  WorkerOptions,\n  WorkerStatus,\n} from './types';\nexport {\n  FamiliarError,\n  FamiliarInvalidOptionsError,\n  FamiliarQueueFullError,\n  FamiliarRuntimeError,\n  FamiliarTaskError,\n  FamiliarTerminatedError,\n  FamiliarTimeoutError,\n} from './errors';\n\nimport type { SlotStrategy, TaskFn, WorkerHandle, WorkerOptions } from './types';\n\nimport { warn } from './_dev';\nimport { createPool } from './_pool';\nimport { unrefTimer } from './_timers';\nimport {\n  FamiliarInvalidOptionsError,\n  FamiliarRuntimeError,\n  FamiliarTaskError,\n  FamiliarTerminatedError,\n  FamiliarTimeoutError,\n} from './errors';\n\n// ─── task() — optional validation helper ─────────────────────────────────────\n\n/**\n * Optional helper that validates a function is safe to serialize for use in `createWorker`.\n *\n * `createWorker` accepts any `TaskFn` directly — this helper exists only to catch the common\n * mistake of passing a bound or native function whose body cannot be serialized.\n *\n * IMPORTANT: The function is serialized via `.toString()` and runs in an isolated Worker scope.\n * It **cannot** close over variables from the surrounding module — any outer reference resolves\n * to `undefined` inside the worker.\n *\n * @throws FamiliarInvalidOptionsError if the function is bound or native.\n *\n * @example\n * // Without task() — works fine for plain arrow functions:\n * const worker = createWorker((n: number) => n * 2);\n *\n * // With task() — catches the mistake of passing Math.sqrt directly:\n * const worker = createWorker(task((n: number) => Math.sqrt(n)));\n */\nexport function task<TInput, TOutput>(fn: TaskFn<TInput, TOutput>): TaskFn<TInput, TOutput> {\n  if (fn.toString().includes('[native code]')) {\n    throw new FamiliarInvalidOptionsError('Task function cannot be a bound or native function');\n  }\n\n  return fn;\n}\n\n// ─── Options resolution ───────────────────────────────────────────────────────\n\n/** Upper bound on `concurrency`: generous headroom over realistic hardware/IO limits while still catching obvious misconfiguration (e.g. a typo like `50000`). */\nconst MAX_CONCURRENCY = 512;\n\nfunction resolveConcurrency(value: WorkerOptions['concurrency']): number {\n  if (value === undefined) return 1;\n\n  if (value === 'auto') {\n    return Math.max(1, globalThis.navigator?.hardwareConcurrency ?? 1);\n  }\n\n  if (!Number.isInteger(value) || value < 1 || value > MAX_CONCURRENCY) {\n    throw new FamiliarInvalidOptionsError(`\\`concurrency\\` must be a positive integer ≤ ${MAX_CONCURRENCY} or \"auto\"`);\n  }\n\n  return value;\n}\n\nfunction resolveOptions(options: WorkerOptions = {}): {\n  concurrency: number;\n  heartbeatWindow: number | undefined;\n  maxQueue: number | undefined;\n  onFull: 'reject' | 'wait';\n  onSlotError: WorkerOptions['onSlotError'];\n  timeout: number | undefined;\n} {\n  const concurrency = resolveConcurrency(options.concurrency);\n  const { heartbeatWindow, maxQueue, onFull = 'reject', onSlotError, timeout } = options;\n\n  if (timeout !== undefined && (!Number.isFinite(timeout) || timeout <= 0)) {\n    throw new FamiliarInvalidOptionsError('`timeout` must be a finite number greater than 0');\n  }\n\n  if (maxQueue !== undefined && (!Number.isInteger(maxQueue) || maxQueue < 1)) {\n    throw new FamiliarInvalidOptionsError('`maxQueue` must be a positive integer');\n  }\n\n  if (heartbeatWindow !== undefined && (!Number.isFinite(heartbeatWindow) || heartbeatWindow <= 0)) {\n    throw new FamiliarInvalidOptionsError('`heartbeatWindow` must be a finite number greater than 0');\n  }\n\n  return { concurrency, heartbeatWindow, maxQueue, onFull, onSlotError, timeout };\n}\n\n// ─── Worker script builder ────────────────────────────────────────────────────\n\n/**\n * @security `fn.toString()` is injected verbatim into the blob script. Any code embedded in the\n * serialized function executes only inside the isolated Worker scope — no shared memory, no access\n * to the host page's globals. Risk is therefore low, but callers should only pass plain functions\n * that do not close over module scope.\n */\nfunction buildWorkerScript(fn: TaskFn<unknown, unknown>, heartbeatInterval: number | undefined): string {\n  return `\nconst __fn = (${fn.toString()});\n\nself.onmessage = async function (event) {\n  const { id, input, stream } = event.data;\n\n  // Automatically send heartbeats at half the heartbeatWindow interval.\n  let heartbeatTimer = null;\n  ${heartbeatInterval != null ? `heartbeatTimer = setInterval(() => self.postMessage({ id, heartbeat: true }), ${heartbeatInterval});` : ''}\n\n  try {\n    if (stream) {\n      const iterable = await __fn(input);\n      for await (const chunk of iterable) {\n        self.postMessage({ id, chunk });\n      }\n      self.postMessage({ id, result: undefined });\n    } else {\n      const result = await __fn(input);\n      self.postMessage({ id, result });\n    }\n  } catch (error) {\n    self.postMessage({ id, error });\n  } finally {\n    if (heartbeatTimer) clearInterval(heartbeatTimer);\n  }\n}`.trim();\n}\n\n// ─── SlotConfig discriminated union ──────────────────────────────────────────\n\ntype SlotConfig<TInput, TOutput> =\n  | { fn: TaskFn<TInput, TOutput>; heartbeatInterval: number | undefined; kind: 'inline' }\n  | { kind: 'module'; url: string };\n\n// ─── PendingTask ─────────────────────────────────────────────────────────────\n\ntype SlotMessage<TOutput> =\n  | { error: unknown; id: number }\n  | { chunk: TOutput; id: number }\n  | { heartbeat: true; id: number }\n  | { id: number; result: TOutput };\n\ntype PendingTask<TOutput> = {\n  /** Emits intermediate stream chunks. Undefined for non-streaming tasks. */\n  emit?: (chunk: TOutput) => void;\n  /** Called with an error when the streaming dispatch is cancelled mid-flight, so the finish closure drains its waiters. */\n  finishStream?: (err: unknown) => void;\n  /**\n   * Single-shot timer that fires if no heartbeat is received within watchdogMs.\n   * Reset (cleared + recreated) on every incoming heartbeat message.\n   * Uses setTimeout because the watchdog is conceptually one-shot with manual reset,\n   * not a recurring interval.\n   */\n  heartbeatWatchdog?: ReturnType<typeof setTimeout>;\n  id: number;\n  reject: (reason: unknown) => void;\n  resolve: (value: TOutput) => void;\n  timer?: ReturnType<typeof setTimeout>;\n  /** Watchdog window in ms (= heartbeatWindow). Stored on PendingTask to reset the timer on each heartbeat. */\n  watchdogMs?: number;\n};\n\n// ─── Slot — implements SlotStrategy ──────────────────────────────────────────\n\nclass Slot<TInput, TOutput> implements SlotStrategy<TInput, TOutput> {\n  private readonly config: SlotConfig<TInput, TOutput>;\n  private readonly onSlotError: WorkerOptions['onSlotError'];\n  private disposed = false;\n  private pending: PendingTask<TOutput> | null = null;\n  private taskId = 0;\n  private worker: Worker | null = null;\n\n  constructor(config: SlotConfig<TInput, TOutput>, onSlotError?: WorkerOptions['onSlotError']) {\n    this.config = config;\n    this.onSlotError = onSlotError;\n  }\n\n  prime(): Promise<void> {\n    if (this.disposed) return Promise.resolve();\n\n    try {\n      this.ensureWorker();\n    } catch {\n      // Best-effort — errors surface on the first run() call.\n    }\n\n    return Promise.resolve();\n  }\n\n  run(input: TInput, transferables: Transferable[], timeout: number | undefined): Promise<TOutput> {\n    return this.dispatch(input, transferables, timeout, false) as Promise<TOutput>;\n  }\n\n  runStream(input: TInput, transferables: Transferable[], timeout: number | undefined): AsyncIterable<TOutput> {\n    const chunks: TOutput[] = [];\n    let done = false;\n    let error: unknown;\n    const waiters: Array<() => void> = [];\n\n    const emit = (chunk: TOutput) => {\n      chunks.push(chunk);\n      waiters.shift()?.();\n    };\n\n    const finish = (err?: unknown) => {\n      done = true;\n      error = err;\n\n      for (const w of waiters.splice(0)) w();\n    };\n\n    // Dispatch the task in stream mode. The promise resolves when the worker signals done.\n    // finishStream is stored on the PendingTask so cancel() can drain the waiters if the\n    // consumer exits early (break/throw from for-await), preventing a permanently dangling Promise.\n    // this.pending is set synchronously inside dispatch(), so this assignment is safe.\n    this.dispatch(input, transferables, timeout, true, emit).then(() => finish(), finish);\n\n    if (this.pending) this.pending.finishStream = finish;\n\n    return {\n      [Symbol.asyncIterator]() {\n        let cursor = 0;\n\n        return {\n          async next(): Promise<IteratorResult<TOutput>> {\n            while (cursor >= chunks.length && !done) {\n              await new Promise<void>((resolve) => waiters.push(resolve));\n            }\n\n            if (cursor < chunks.length) {\n              const value = chunks[cursor]!;\n\n              // Null-out the consumed slot so GC can collect the value\n              // without waiting for the entire stream to close.\n              (chunks as (TOutput | null)[])[cursor] = null;\n              cursor++;\n\n              return { done: false, value };\n            }\n\n            if (error !== undefined) throw error;\n\n            return { done: true, value: undefined as unknown as TOutput };\n          },\n        };\n      },\n    };\n  }\n\n  cancel(): void {\n    const pending = this.pending;\n\n    if (!pending) return;\n\n    clearTimeout(pending.timer);\n    clearTimeout(pending.heartbeatWatchdog);\n    this.pending = null;\n    // Terminate the worker: the streaming task may still be running and sending chunks.\n    // A fresh worker is created on the next run() or runStream() call via ensureWorker().\n    this.stopWorker();\n    // Drain the stream finish closure so any pending .next() waiters resolve immediately\n    // rather than leaking as permanently dangling Promises.\n    pending.finishStream?.(new FamiliarTerminatedError('Stream was cancelled'));\n  }\n\n  terminate(): void {\n    this.disposed = true;\n    this.stopWorker();\n    this.failPending(new FamiliarTerminatedError());\n  }\n\n  private dispatch(\n    input: TInput,\n    transferables: Transferable[],\n    timeout: number | undefined,\n    stream: boolean,\n    emit?: (chunk: TOutput) => void,\n  ): Promise<TOutput | void> {\n    if (this.disposed) {\n      return Promise.reject(new FamiliarTerminatedError());\n    }\n\n    let worker: Worker;\n\n    try {\n      worker = this.ensureWorker();\n    } catch (error) {\n      return Promise.reject(error);\n    }\n\n    // watchdogMs = heartbeatInterval * 2 (Nyquist margin: worker beats at interval, host allows 2× before firing).\n    const watchdogMs =\n      this.config.kind === 'inline' && this.config.heartbeatInterval != null\n        ? this.config.heartbeatInterval * 2\n        : undefined;\n\n    return new Promise<TOutput | void>((resolve, reject) => {\n      const id = this.taskId++;\n      const pending: PendingTask<TOutput> = {\n        emit,\n        id,\n        reject,\n        resolve: resolve as (v: TOutput) => void,\n        watchdogMs,\n      };\n\n      if (timeout !== undefined) {\n        pending.timer = setTimeout(() => {\n          this.restart(new FamiliarTimeoutError(timeout));\n        }, timeout);\n        unrefTimer(pending.timer);\n      }\n\n      if (watchdogMs !== undefined) {\n        pending.heartbeatWatchdog = setTimeout(() => {\n          this.restart(new FamiliarTimeoutError(watchdogMs));\n        }, watchdogMs);\n        unrefTimer(pending.heartbeatWatchdog);\n      }\n\n      this.pending = pending;\n\n      try {\n        worker.postMessage({ id, input, stream }, transferables);\n      } catch (err) {\n        this.failPending(new FamiliarRuntimeError(err instanceof Error ? err.message : String(err), { cause: err }));\n      }\n    });\n  }\n\n  private ensureWorker(): Worker {\n    if (this.worker) return this.worker;\n\n    if (typeof globalThis.Worker !== 'function') {\n      throw new FamiliarRuntimeError('Worker API is unavailable in this runtime');\n    }\n\n    let worker: Worker;\n\n    if (this.config.kind === 'module') {\n      try {\n        worker = new Worker(this.config.url, { type: 'module' });\n      } catch (error) {\n        throw new FamiliarRuntimeError('Failed to create Worker', { cause: error });\n      }\n    } else {\n      try {\n        const blob = new Blob(\n          [buildWorkerScript(this.config.fn as TaskFn<unknown, unknown>, this.config.heartbeatInterval)],\n          { type: 'application/javascript' },\n        );\n        const url = URL.createObjectURL(blob);\n\n        try {\n          worker = new Worker(url);\n        } finally {\n          URL.revokeObjectURL(url);\n        }\n      } catch (error) {\n        throw new FamiliarRuntimeError('Failed to create Worker', { cause: error });\n      }\n    }\n\n    worker.onmessage = (event: MessageEvent<SlotMessage<TOutput>>) => {\n      const pending = this.pending;\n\n      if (!pending || event.data.id !== pending.id) return;\n\n      // Handle heartbeat message — reset the watchdog timer.\n      if ('heartbeat' in event.data) {\n        if (pending.watchdogMs !== undefined) {\n          clearTimeout(pending.heartbeatWatchdog);\n          pending.heartbeatWatchdog = setTimeout(() => {\n            this.restart(new FamiliarTimeoutError(pending.watchdogMs!));\n          }, pending.watchdogMs);\n          unrefTimer(pending.heartbeatWatchdog);\n        }\n\n        return;\n      }\n\n      if ('chunk' in event.data) {\n        pending.emit?.(event.data.chunk);\n\n        return;\n      }\n\n      clearTimeout(pending.timer);\n      clearTimeout(pending.heartbeatWatchdog);\n      this.pending = null;\n\n      if ('error' in event.data) {\n        const cause = event.data.error instanceof Error ? event.data.error : new Error(String(event.data.error));\n\n        pending.reject(new FamiliarTaskError(cause.message, { cause }));\n      } else {\n        pending.resolve(event.data.result);\n      }\n    };\n\n    worker.onerror = (event: ErrorEvent) => {\n      const error = new FamiliarRuntimeError(event.message);\n\n      // Stop and fail before calling the external callback so it sees a clean state.\n      this.stopWorker();\n      this.failPending(error);\n\n      this.onSlotError?.(error, () => void this.prime());\n    };\n\n    this.worker = worker;\n\n    return worker;\n  }\n\n  private failPending(reason: unknown): void {\n    const pending = this.pending;\n\n    if (!pending) return;\n\n    clearTimeout(pending.timer);\n    clearTimeout(pending.heartbeatWatchdog);\n    this.pending = null;\n    pending.reject(reason);\n  }\n\n  private restart(reason: unknown): void {\n    this.stopWorker();\n    this.failPending(reason);\n  }\n\n  private stopWorker(): void {\n    if (!this.worker) return;\n\n    this.worker.terminate();\n    this.worker = null;\n  }\n}\n\n// ─── createWorker ─────────────────────────────────────────────────────────────\n\n/**\n * Creates a pool of Web Workers that run `fn` in parallel.\n *\n * The task function is serialized via `.toString()` and runs in a separate global scope.\n * It cannot close over variables from the surrounding module.\n *\n * Use the optional `task()` helper to validate that the function is not bound or native.\n * For workers that need imports, see `createModuleWorker`.\n *\n * @example\n * // Plain arrow function — most common case:\n * const worker = createWorker((n: number) => n * 2);\n *\n * // With task() for validation:\n * const worker = createWorker(task((n: number) => n * 2));\n */\nexport function createWorker<TInput, TOutput>(\n  fn: TaskFn<TInput, TOutput>,\n  options?: WorkerOptions,\n): WorkerHandle<TInput, TOutput> {\n  const { concurrency, heartbeatWindow, maxQueue, onFull, onSlotError, timeout } = resolveOptions(options);\n  const heartbeatInterval = heartbeatWindow != null ? Math.floor(heartbeatWindow / 2) : undefined;\n\n  const slots = Array.from(\n    { length: concurrency },\n    () => new Slot<TInput, TOutput>({ fn, heartbeatInterval, kind: 'inline' }, onSlotError),\n  );\n\n  return createPool(slots, {\n    concurrency,\n    defaultTimeout: timeout,\n    maxQueue,\n    onFull,\n  });\n}\n\n// ─── createModuleWorker ───────────────────────────────────────────────────────\n\n/**\n * Creates a pool of module-type Web Workers loaded from a real URL.\n *\n * Unlike `createWorker`, the worker file is a regular module — it can import utilities,\n * use top-level await, and reference module scope.\n *\n * Use `handleMessages` from `@vielzeug/familiar/protocol` in the worker file to implement\n * the message protocol without boilerplate.\n *\n * **Protocol**: The worker module must handle the `{ id, input }` message format and reply\n * with `{ id, result }` or `{ id, error: { name, message, stack } }`. For streaming, it must\n * send one or more `{ id, chunk }` messages followed by `{ id, result: undefined }`.\n * For heartbeat support, send `{ id, heartbeat: true }` at regular intervals.\n *\n * @example\n * ```ts\n * // my-worker.ts — use handleMessages for zero boilerplate:\n * import { handleMessages } from '@vielzeug/familiar/protocol';\n * handleMessages(async (input: number) => input * 2);\n *\n * // main.ts\n * const pool = createModuleWorker<number, number>(\n *   new URL('./my-worker.ts', import.meta.url),\n *   { concurrency: 4 },\n * );\n * ```\n */\nexport function createModuleWorker<TInput, TOutput>(\n  url: URL | string,\n  options?: WorkerOptions,\n): WorkerHandle<TInput, TOutput> {\n  const { concurrency, heartbeatWindow, maxQueue, onFull, onSlotError, timeout } = resolveOptions(options);\n\n  if (heartbeatWindow !== undefined) {\n    warn(\n      '`heartbeatWindow` has no effect on module workers — the worker script must implement the heartbeat protocol manually.',\n    );\n  }\n\n  const href = typeof url === 'string' ? url : url.href;\n\n  const slots = Array.from(\n    { length: concurrency },\n    () => new Slot<TInput, TOutput>({ kind: 'module', url: href }, onSlotError),\n  );\n\n  return createPool(slots, {\n    concurrency,\n    defaultTimeout: timeout,\n    maxQueue,\n    onFull,\n  });\n}\n"],"mappings":"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"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@vielzeug/familiar",
+  "version": "1.0.2",
+  "description": "Typed Web Worker pool with task queuing, streaming, AbortSignal cancellation, and heartbeat",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./protocol": {
+      "source": "./src/protocol.ts",
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js",
+      "require": "./dist/protocol.cjs"
+    },
+    "./testing": {
+      "source": "./src/testing/index.ts",
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && pnpm run build:bundle && pnpm run build:types",
+    "build:types": "tsc -p tsconfig.declarations.json",
+    "fix": "eslint --fix src",
+    "lint": "eslint src",
+    "prepublishOnly": "pnpm run build",
+    "preview": "vite preview",
+    "test": "vitest",
+    "build:bundle": "vite build --config vite.bundle.config.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@vielzeug/arsenal": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "~6.0.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9"
+  }
+}