@vielzeug/familiar 1.0.6 → 1.0.8

package/dist/worker.js

@@ -1,21 +1,21 @@
 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";
+import "./_dev.js";
+import { unrefTimer as s } from "./_timers.js";
+import { createPool as c } from "./_pool.js";
 //#region src/worker.ts
-function u(e) {
+function l(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) {
+var u = 512;
+function d(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"`);
+	if (!Number.isInteger(e) || e < 1 || e > u) throw new t(`\`concurrency\` must be a positive integer ≤ ${u} or "auto"`);
 	return e;
 }
-function p(e = {}) {
-	let n = f(e.concurrency), { heartbeatWindow: r, maxQueue: i, onFull: a = "reject", onSlotError: o, timeout: s } = e;
+function f(e = {}) {
+	let n = d(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");
@@ -28,7 +28,7 @@ function p(e = {}) {
 		timeout: s
 	};
 }
-function m(e, t) {
+function p(e, t) {
 	return `
 const __fn = (${e.toString()});
 
@@ -57,7 +57,7 @@ self.onmessage = async function (event) {
   }
 }`.trim();
 }
-var h = class {
+var m = class {
 	config;
 	onSlotError;
 	disposed = !1;
@@ -110,7 +110,7 @@ var h = class {
 	terminate() {
 		this.disposed = !0, this.stopWorker(), this.failPending(new a());
 	}
-	dispatch(e, t, n, i, s) {
+	dispatch(e, t, n, i, c) {
 		if (this.disposed) return Promise.reject(new a());
 		let l;
 		try {
@@ -121,7 +121,7 @@ var h = class {
 		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,
+				emit: c,
 				id: f,
 				reject: d,
 				resolve: a,
@@ -129,9 +129,9 @@ var h = class {
 			};
 			n !== void 0 && (p.timer = setTimeout(() => {
 				this.restart(new o(n));
-			}, n), c(p.timer)), u !== void 0 && (p.heartbeatWatchdog = setTimeout(() => {
+			}, n), s(p.timer)), u !== void 0 && (p.heartbeatWatchdog = setTimeout(() => {
 				this.restart(new o(u));
-			}, u), c(p.heartbeatWatchdog)), this.pending = p;
+			}, u), s(p.heartbeatWatchdog)), this.pending = p;
 			try {
 				l.postMessage({
 					id: f,
@@ -153,7 +153,7 @@ var h = class {
 			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);
+			let t = new Blob([p(this.config.fn, this.config.heartbeatInterval)], { type: "application/javascript" }), n = URL.createObjectURL(t);
 			try {
 				e = new Worker(n);
 			} finally {
@@ -168,7 +168,7 @@ var h = class {
 				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));
+					}, t.watchdogMs), s(t.heartbeatWatchdog));
 					return;
 				}
 				if ("chunk" in e.data) {
@@ -196,34 +196,32 @@ var h = class {
 		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({
+function h(e, t) {
+	let { concurrency: n, heartbeatWindow: r, maxQueue: i, onFull: a, onSlotError: o, timeout: s } = f(t), l = r == null ? void 0 : Math.floor(r / 2), u = Array.from({ length: n }, () => new m({
 		fn: e,
-		heartbeatInterval: c,
+		heartbeatInterval: l,
 		kind: "inline"
-	}, o)), {
+	}, o));
+	return c(u, {
 		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({
+function g(e, t) {
+	let { concurrency: n, heartbeatWindow: r, maxQueue: i, onFull: a, onSlotError: o, timeout: s } = f(t), l = typeof e == "string" ? e : e.href, u = Array.from({ length: n }, () => new m({
 		kind: "module",
-		url: u
-	}, o)), {
+		url: l
+	}, o));
+	return c(u, {
 		concurrency: n,
-		defaultTimeout: c,
+		defaultTimeout: s,
 		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 };
+export { e as FamiliarError, t as FamiliarInvalidOptionsError, n as FamiliarQueueFullError, r as FamiliarRuntimeError, i as FamiliarTaskError, a as FamiliarTerminatedError, o as FamiliarTimeoutError, g as createModuleWorker, h as createWorker, l as task };
 
 //# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -1 +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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"}
+{"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

@@ -1,6 +1,6 @@
 {
   "name": "@vielzeug/familiar",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Typed Web Worker pool with task queuing, streaming, AbortSignal cancellation, and heartbeat",
   "type": "module",
   "files": [
@@ -11,19 +11,16 @@
   "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"
@@ -47,12 +44,22 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@vielzeug/arsenal": "1.1.2"
+    "@vielzeug/arsenal": "2.0.1"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "vite": "^8.1.3",
+    "vite": "^8.2.0",
     "vitest": "^4.1.10"
+  },
+  "typesVersions": {
+    "*": {
+      "protocol": [
+        "dist/protocol.d.ts"
+      ],
+      "testing": [
+        "dist/testing/index.d.ts"
+      ]
+    }
   }
 }