@vielzeug/familiar 1.0.8 → 2.0.0

package/README.md

@@ -1,71 +1,48 @@
 # @vielzeug/familiar
 
-> Typed Web Worker pools with queuing, priorities, streaming, heartbeat, and testing utilities.
+> Typed module-worker pools with cancellation, priority scheduling, streaming, and test utilities.
 
-[![npm version](https://img.shields.io/npm/v/@vielzeug/familiar)](https://www.npmjs.com/package/@vielzeug/familiar) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-<details>
-<summary>Quick Reference</summary>
-
-**Package:** `@vielzeug/familiar` &nbsp;·&nbsp; **Category:** Workers
-
-**Key exports:** `createWorker`, `createModuleWorker`, `createTestWorker`
-
-**When to use:** Typed Web Worker pools with task queuing, priorities, per-task timeouts, AbortSignal cancellation, streaming, heartbeat monitoring, and in-process testing.
-
-**Related:** [@vielzeug/arsenal](https://vielzeug.dev/arsenal/) · [@vielzeug/ripple](https://vielzeug.dev/ripple/) · [@vielzeug/herald](https://vielzeug.dev/herald/)
-
-</details>
-
-`@vielzeug/familiar` is part of Vielzeug and ships as a zero-dependency TypeScript package with ESM+CJS output.
+`@vielzeug/familiar` runs typed work in ES module workers. Worker modules keep imports, source maps, and normal file boundaries intact.
 
 ## Installation
 
 ```sh
 pnpm add @vielzeug/familiar
-npm install @vielzeug/familiar
-yarn add @vielzeug/familiar
 ```
 
 ## Quick Start
 
 ```ts
-import { createWorker } from '@vielzeug/familiar';
+// sum.worker.ts
+import { exposeTask } from '@vielzeug/familiar/protocol';
 
-// Single worker — runs one task at a time
-const worker = createWorker<number[], number>((nums) => nums.reduce((sum, n) => sum + n, 0));
-console.log(await worker.run([1, 2, 3, 4, 5])); // 15
-worker.dispose();
-
-// Worker pool — 4 concurrent slots with a 5 s timeout
-const pool = createWorker<number, number>(
-  function fib(n) {
-    return n <= 1 ? n : fib(n - 1) + fib(n - 2);
-  },
-  { concurrency: 4, timeout: 5000 },
-);
-
-const results = await Promise.all([35, 36, 37, 38].map((n) => pool.run(n)));
-pool.dispose();
+exposeTask((values: number[]) => values.reduce((total, value) => total + value, 0));
+```
 
-// Priority queue — higher values run first
-await pool.run(heavyTask, { priority: 10 }); // runs before default-priority tasks
+```ts
+// main.ts
+import { createWorker } from '@vielzeug/familiar';
 
-// Batch processing — yield results as they arrive
-for await (const result of pool.batch([1, 2, 3, 4])) {
-  console.log(result);
-}
+const pool = createWorker<number[], number>(new URL('./sum.worker.ts', import.meta.url), {
+  concurrency: 2,
+  timeout: 5_000,
+});
 
-// Typed errors — instanceof checks for precise handling
-import { FamiliarTimeoutError, FamiliarQueueFullError } from '@vielzeug/familiar';
 try {
-  await pool.run(input, { timeout: 100 });
-} catch (err) {
-  if (err instanceof FamiliarTimeoutError) console.error(`Timed out after ${err.timeoutMs}ms`);
-  if (err instanceof FamiliarQueueFullError) console.error(`Queue full (max ${err.maxQueue})`);
+  console.log(await pool.run([1, 2, 3]));
+} finally {
+  pool.dispose();
 }
 ```
 
+## Exports
+
+- `createWorker()` creates a task pool backed by modules registered with `exposeTask()`.
+- `createStreamWorker()` creates a stream-only pool backed by modules registered with `exposeStream()`.
+- `batch()` and `createTaskGroup()` compose task-pool work without widening every pool handle.
+- `createTestWorker()` provides structured-clone, timeout, cancellation, and error-wrapping parity for task-pool tests.
+- `dispose()` stops work immediately; `drain()` waits for active work before teardown.
+
 ## Documentation
 
 - [Overview](https://vielzeug.dev/familiar/)

package/dist/_pool.cjs

@@ -1,2 +1,2 @@
-const e=require("./errors.cjs"),t=require("./_queue.cjs"),n=require("./_timers.cjs");let r=require("@vielzeug/arsenal/async");function i(i,a){let{concurrency:o,defaultTimeout:s,maxQueue:c,onFull:l}=a,u=[...i],d=new t.TaskQueue,f=new AbortController,p=[],m=[],h=0,g,_=0,v=0,y=0,b=!1;function x(){return h===0&&d.size===0}function S(){if(!x()||p.length===0)return;let e=p.splice(0);for(let t of e)t()}function C(t){return x()?Promise.resolve():new Promise((r,i)=>{if(p.push(r),t!==void 0){let a=setTimeout(()=>{let n=p.indexOf(r);n!==-1&&p.splice(n,1),i(new e.FamiliarTimeoutError(t))},t);n.unrefTimer(a)}})}function w(){let e=m.shift();e&&e()}let T=!1;function E(){if(!(b||T)){for(T=!0;!b&&u.length>0&&d.size>0;){let t=D();if(!t)break;let n=u.pop();t.cleanupAbort?.(),h+=1,w();let r=t.timeout??s;n.run(t.input,t.transferables,r).then(e=>{u.push(n),--h,_+=1,t.resolve(e),E(),x()&&S()},r=>{u.push(n),--h,r instanceof e.FamiliarTerminatedError||(v+=1),t.reject(r),E(),x()&&S()})}T=!1}}function D(){for(;d.size>0;){let e=d.shift();if(!e)break;if(e.signal?.aborted){e.cleanupAbort?.(),e.reject((0,r.abortError)(e.signal));continue}return e}S()}function O(){if(b)return;b=!0,f.abort();for(let e of i)e.terminate();for(;d.size>0;){let t=d.shift();if(!t)break;t.cleanupAbort?.(),t.reject(new e.FamiliarTerminatedError)}let t=p.splice(0);for(let e of t)e();for(let e of m.splice(0))e()}function k(e){return b?Promise.resolve():g||(g=C(e).then(O,e=>{throw O(),e}),g)}async function A(t,n={}){let{priority:i=0,signal:a,timeout:o,transferables:s=[]}=n;if(b)throw new e.FamiliarTerminatedError;if(g)throw new e.FamiliarTerminatedError(`Worker is draining`);if(a?.aborted)throw(0,r.abortError)(a);if(l===`wait`&&c!==void 0){for(;!b&&!g&&d.size>=c;)await new Promise(e=>m.push(e));if(b)throw new e.FamiliarTerminatedError;if(g)throw new e.FamiliarTerminatedError(`Worker is draining`)}let u,f,p=new Promise((e,t)=>{u=e,f=t}),h={input:t,priority:i,reject:f,resolve:u,signal:a,timeout:o,transferables:s};if(!d.enqueue(h,l===`wait`?void 0:c))throw new e.FamiliarQueueFullError(c);if(a){let e=()=>{d.remove(h)&&(h.cleanupAbort?.(),f((0,r.abortError)(a)),S())};h.cleanupAbort=()=>{a.removeEventListener(`abort`,e),h.cleanupAbort=void 0},a.addEventListener(`abort`,e,{once:!0})}return E(),p}function j(t,n={}){if(b)throw new e.FamiliarRuntimeError(`Worker was terminated`);let r=u.pop();if(!r)throw new e.FamiliarRuntimeError(`runStream() requires a free worker slot; all ${i.length} slot${i.length===1?``:`s`} are busy`);let{timeout:a,transferables:o=[]}=n,s=r.runStream(t,o,a);return{[Symbol.asyncIterator](){let e=s[Symbol.asyncIterator](),t=!1,n=()=>{t||(t=!0,u.push(r))};return{async next(){let t=await e.next();return t.done&&n(),t},async return(t){return r.cancel(),n(),e.return?.(t)??{done:!0,value:t}},async throw(t){if(r.cancel(),n(),e.throw)return e.throw(t);throw t}}}}}async function*M(e,t={}){if(e.length===0)return;let{ordered:n=!0,...r}=t,i=new AbortController;try{if(n){let t=e.map(e=>A(e,{...r,signal:i.signal}));for(let e of t)yield await e}else{let t=[],n=null,s=0,c=Math.max(1,o);function a(){if(s>=e.length)return;let a=e[s++];A(a,{...r,signal:i.signal}).then(e=>{t.push({value:e}),n?.(),n=null},e=>{t.push({error:e}),n?.(),n=null})}for(let t=0;t<c&&t<e.length;t++)a();for(let r=0;r<e.length;r++){for(;t.length===0;)await new Promise(e=>{n=e});let e=t.shift();if(`error`in e)throw e.error;yield e.value,a()}}}finally{i.abort()}}function N(e,t={}){let n=new AbortController;if(t.signal){let e=t.signal;e.aborted?n.abort(e.reason):e.addEventListener(`abort`,()=>n.abort(e.reason),{once:!0})}y+=1;let r=0,i=0,a=!1,o=[];function s(){!a&&r>0&&r===i&&(a=!0,--y)}return{abort(e){n.abort(e)},drain(){let e=o.splice(0);return a||(a=!0,--y),Promise.allSettled(e)},get name(){return e},get pending(){return r-i},run(e,t={}){r+=1;let a=A(e,{...t,signal:n.signal});return o.push(a),a.then(()=>{i+=1,s()},()=>{i+=1,s()}),a},get size(){return r}}}function P(){return b?`terminated`:h>0||d.size>0?`running`:`idle`}return{get active(){return h},batch:M,get completed(){return _},get concurrency(){return o},get disposalSignal(){return f.signal},dispose:O,get disposed(){return b},drain:k,get failed(){return v},group:N,get groupCount(){return y},prime(){return Promise.all(i.map(e=>e.prime())).then(()=>{})},get queued(){return d.size},run:A,runStream:j,get status(){return P()},[Symbol.asyncDispose]:()=>k(),[Symbol.dispose]:O}}exports.createPool=i;
+const e=require("./errors.cjs"),t=require("./_queue.cjs"),n=require("./_timers.cjs");let r=require("@vielzeug/arsenal/async");function i(i,a){let o=[...i],s=new t.TaskQueue,c=new AbortController,l=[],u=[],d=0,f=0,p=0,m,h=!1,g=!1;function _(){return d===0&&s.size===0}function v(){if(_())for(let e of l.splice(0))e.timer&&clearTimeout(e.timer),e.resolve()}function y(t={}){return _()?Promise.resolve():new Promise((r,i)=>{let a={reject:i,resolve:r};t.timeout!==void 0&&(a.timer=setTimeout(()=>{let n=l.indexOf(a);n!==-1&&l.splice(n,1),i(new e.FamiliarTimeoutError(t.timeout))},t.timeout),n.unrefTimer(a.timer)),l.push(a)})}function b(){u.shift()?.resolve()}function x(e){for(let t of u.splice(0))t.reject(e)}function S(e){return e?.aborted?Promise.reject((0,r.abortError)(e)):new Promise((t,n)=>{let i=!1,a={cleanup(){e?.removeEventListener(`abort`,o)},reject(e){if(i)return;i=!0,a.cleanup();let t=u.indexOf(a);t!==-1&&u.splice(t,1),n(e)},resolve(){i||(i=!0,a.cleanup(),t())}},o=()=>a.reject((0,r.abortError)(e));e?.addEventListener(`abort`,o,{once:!0}),u.push(a)})}function C(){for(;s.size>0;){let e=s.shift();if(!e)break;if(e.signal?.aborted){e.cleanupAbort?.(),e.reject((0,r.abortError)(e.signal)),b();continue}return e}v()}function w(){if(!(h||g)){for(h=!0;!g&&o.length>0&&s.size>0;){let i=C();if(!i)break;let s=i,c=o.pop(),l=s.timeout??a.defaultTimeout;d+=1,b();let u=()=>c.cancel((0,r.abortError)(s.signal));s.cleanupAbort=()=>{s.signal?.removeEventListener(`abort`,u),s.cleanupAbort=void 0},s.signal?.addEventListener(`abort`,u,{once:!0}),c.run(s.input,s.transferables,l).then(e=>t(e),e=>n(e));function t(e){s.cleanupAbort?.(),o.push(c),--d,f+=1,s.resolve(e),w(),v()}function n(t){s.cleanupAbort?.(),o.push(c),--d,!(t instanceof e.FamiliarTerminatedError)&&t?.constructor?.name!==`AbortError`&&(p+=1),s.reject(t),w(),v()}}h=!1}}async function T(t,n={}){let{priority:i=0,signal:o,timeout:c,transferables:l=[]}=n;if(g)throw new e.FamiliarTerminatedError;if(m)throw new e.FamiliarTerminatedError(`Worker is draining`);if(o?.aborted)throw(0,r.abortError)(o);for(;a.onFull===`wait`&&a.maxQueue!==void 0&&s.size>=a.maxQueue;){if(await S(o),g)throw new e.FamiliarTerminatedError;if(m)throw new e.FamiliarTerminatedError(`Worker is draining`);if(o?.aborted)throw(0,r.abortError)(o)}let u,d,f=new Promise((e,t)=>{u=e,d=t}),p={input:t,priority:i,reject:d,resolve:u,signal:o,timeout:c,transferables:l};if(!s.enqueue(p,a.onFull===`wait`?void 0:a.maxQueue))throw new e.FamiliarQueueFullError(a.maxQueue);if(o){let e=()=>{s.remove(p)&&(p.cleanupAbort?.(),d((0,r.abortError)(o)),b(),v())};p.cleanupAbort=()=>{o.removeEventListener(`abort`,e),p.cleanupAbort=void 0},o.addEventListener(`abort`,e,{once:!0})}return w(),f}function E(){if(!g){g=!0,c.abort();for(let e of i)e.terminate();for(;s.size>0;){let t=s.shift();if(!t)break;t.cleanupAbort?.(),t.reject(new e.FamiliarTerminatedError)}x(new e.FamiliarTerminatedError),v()}}function D(t={}){return g?Promise.resolve():m||(x(new e.FamiliarTerminatedError(`Worker is draining`)),m=y(t).then(()=>E(),e=>{throw E(),e}),m)}return{get disposalSignal(){return c.signal},dispose:E,get disposed(){return g},drain:D,async prime(){await Promise.all(i.map(e=>e.prime()))},run:T,get stats(){return{active:d,completed:f,failed:p,queued:s.size}},get status(){return g?`terminated`:d===0?`idle`:`running`},[Symbol.asyncDispose]:()=>D(),[Symbol.dispose]:E}}async function*a(e,t,n={}){let r=new AbortController,i=()=>r.abort(n.signal.reason);n.signal?.addEventListener(`abort`,i,{once:!0});let a=t.map(t=>e.run(t,{...n,signal:r.signal}));try{for(let e of a)yield await e}catch(e){throw r.abort(e),await Promise.allSettled(a),e}finally{n.signal?.removeEventListener(`abort`,i),r.abort(),await Promise.allSettled(a)}}function o(e,t=void 0,n={}){let r=new AbortController,i=new Set,a=0;return n.signal?.addEventListener(`abort`,()=>r.abort(n.signal.reason),{once:!0}),{abort(e){r.abort(e)},async drain(){return Promise.allSettled([...i])},get name(){return t},get pending(){return i.size},run(t,n={}){let o=e.run(t,{...n,signal:r.signal});return a+=1,i.add(o),o.finally(()=>i.delete(o)),o},get size(){return a}}}exports.batch=a,exports.createPool=i,exports.createTaskGroup=o;
 //# sourceMappingURL=_pool.cjs.map

package/dist/_pool.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"_pool.cjs","names":[],"sources":["../src/_pool.ts"],"sourcesContent":["/**\n * Shared pool orchestration engine used by both the real worker implementation and the test\n * double. Handles queue management, iterative drain loop, abort handling, lifecycle (drain /\n * dispose), metrics, batch streaming, task groups, and backpressure.\n *\n * Callers provide a SlotStrategy array — each slot encapsulates run/runStream/prime/terminate.\n * The pool does not care whether slots use a Web Worker or run in-process.\n *\n * Not part of the public API surface.\n */\n\nimport { abortError } from '@vielzeug/arsenal/async';\n\nimport type {\n  BatchOptions,\n  GroupOptions,\n  RunOptions,\n  SlotStrategy,\n  TaskGroup,\n  WorkerHandle,\n  WorkerStatus,\n} from './types';\n\nimport { type QueueItem, TaskQueue } from './_queue';\nimport { unrefTimer } from './_timers';\nimport { FamiliarQueueFullError, FamiliarRuntimeError, FamiliarTerminatedError, FamiliarTimeoutError } from './errors';\n\nexport type PoolOptions = {\n  concurrency: number;\n  defaultTimeout: number | undefined;\n  maxQueue: number | undefined;\n  onFull: 'reject' | 'wait';\n};\n\nexport function createPool<TInput, TOutput>(\n  slots: SlotStrategy<TInput, TOutput>[],\n  options: PoolOptions,\n): WorkerHandle<TInput, TOutput> {\n  const { concurrency, defaultTimeout, maxQueue, onFull } = options;\n  const freeSlots = [...slots];\n  const queue = new TaskQueue<TInput, TOutput>();\n  const disposeController = new AbortController();\n  const idleResolvers: Array<() => void> = [];\n  /** Waiters blocked on run() because the queue is full (onFull='wait' mode). */\n  const fullWaiters: Array<() => void> = [];\n\n  let activeCount = 0;\n  let drainPromise: Promise<void> | undefined;\n  let completedCount = 0;\n  let failedCount = 0;\n  let groupActiveCount = 0;\n  let terminated = false;\n\n  // ─── Idle tracking ────────────────────────────────────────────────────────────\n\n  function isIdle(): boolean {\n    return activeCount === 0 && queue.size === 0;\n  }\n\n  function notifyIdle(): void {\n    if (!isIdle() || idleResolvers.length === 0) return;\n\n    const resolvers = idleResolvers.splice(0);\n\n    for (const resolve of resolvers) resolve();\n  }\n\n  function waitForIdle(timeoutMs?: number): Promise<void> {\n    if (isIdle()) return Promise.resolve();\n\n    return new Promise<void>((resolve, reject) => {\n      idleResolvers.push(resolve);\n\n      if (timeoutMs !== undefined) {\n        const timer = setTimeout(() => {\n          const idx = idleResolvers.indexOf(resolve);\n\n          if (idx !== -1) idleResolvers.splice(idx, 1);\n\n          reject(new FamiliarTimeoutError(timeoutMs));\n        }, timeoutMs);\n\n        unrefTimer(timer);\n      }\n    });\n  }\n\n  // ─── Full-queue backpressure (onFull='wait') ──────────────────────────────────\n\n  function releaseOneFullWaiter(): void {\n    const waiter = fullWaiters.shift();\n\n    if (waiter) waiter();\n  }\n\n  // ─── Drain loop (iterative) ───────────────────────────────────────────────────\n\n  let draining = false;\n\n  function drainLoop(): void {\n    if (terminated || draining) return;\n\n    draining = true;\n\n    while (!terminated && freeSlots.length > 0 && queue.size > 0) {\n      const item = nextItem();\n\n      if (!item) break;\n\n      const slot = freeSlots.pop()!;\n\n      item.cleanupAbort?.();\n      activeCount += 1;\n      releaseOneFullWaiter();\n\n      const taskTimeout = item.timeout ?? defaultTimeout;\n\n      slot.run(item.input, item.transferables, taskTimeout).then(\n        (result) => {\n          freeSlots.push(slot);\n          activeCount -= 1;\n          completedCount += 1;\n          item.resolve(result);\n          drainLoop();\n\n          if (isIdle()) notifyIdle();\n        },\n        (error: unknown) => {\n          freeSlots.push(slot);\n          activeCount -= 1;\n\n          if (!(error instanceof FamiliarTerminatedError)) failedCount += 1;\n\n          item.reject(error);\n          drainLoop();\n\n          if (isIdle()) notifyIdle();\n        },\n      );\n    }\n\n    draining = false;\n  }\n\n  // ─── Queue helpers ────────────────────────────────────────────────────────────\n\n  function nextItem(): QueueItem<TInput, TOutput> | undefined {\n    while (queue.size > 0) {\n      const item = queue.shift();\n\n      if (!item) break;\n\n      if (item.signal?.aborted) {\n        item.cleanupAbort?.();\n        item.reject(abortError(item.signal));\n        continue;\n      }\n\n      return item;\n    }\n\n    // All remaining items were aborted and rejected above — the pool may now be idle.\n    // Notify any drain() waiter so it does not hang.\n    notifyIdle();\n\n    return undefined;\n  }\n\n  // ─── Lifecycle ────────────────────────────────────────────────────────────────\n\n  function dispose(): void {\n    if (terminated) return;\n\n    terminated = true;\n    disposeController.abort();\n\n    for (const slot of slots) slot.terminate();\n\n    while (queue.size > 0) {\n      const item = queue.shift();\n\n      if (!item) break;\n\n      item.cleanupAbort?.();\n      item.reject(new FamiliarTerminatedError());\n    }\n\n    const resolvers = idleResolvers.splice(0);\n\n    for (const resolve of resolvers) resolve();\n\n    for (const waiter of fullWaiters.splice(0)) waiter();\n  }\n\n  function drain(timeoutMs?: number): Promise<void> {\n    if (terminated) return Promise.resolve();\n\n    if (drainPromise) return drainPromise;\n\n    drainPromise = waitForIdle(timeoutMs).then(dispose, (err) => {\n      dispose();\n      throw err;\n    });\n\n    return drainPromise;\n  }\n\n  // ─── run() ───────────────────────────────────────────────────────────────────\n\n  async function run(input: TInput, runOptions: RunOptions = {}): Promise<TOutput> {\n    const { priority = 0, signal, timeout, transferables = [] } = runOptions;\n\n    if (terminated) {\n      throw new FamiliarTerminatedError();\n    }\n\n    if (drainPromise) {\n      throw new FamiliarTerminatedError('Worker is draining');\n    }\n\n    if (signal?.aborted) {\n      throw abortError(signal);\n    }\n\n    if (onFull === 'wait' && maxQueue !== undefined) {\n      while (!terminated && !drainPromise && queue.size >= maxQueue) {\n        await new Promise<void>((resolve) => fullWaiters.push(resolve));\n      }\n\n      if (terminated) throw new FamiliarTerminatedError();\n\n      if (drainPromise) throw new FamiliarTerminatedError('Worker is draining');\n    }\n\n    let resolve!: (value: TOutput) => void;\n    let reject!: (reason: unknown) => void;\n\n    const promise = new Promise<TOutput>((res, rej) => {\n      resolve = res;\n      reject = rej;\n    });\n\n    const item: QueueItem<TInput, TOutput> = {\n      input,\n      priority,\n      reject,\n      resolve,\n      signal,\n      timeout,\n      transferables,\n    };\n\n    if (!queue.enqueue(item, onFull === 'wait' ? undefined : maxQueue)) {\n      // maxQueue is guaranteed defined here: enqueue() only returns false when maxQueue is set.\n      throw new FamiliarQueueFullError(maxQueue as number);\n    }\n\n    if (signal) {\n      const onAbort = () => {\n        if (!queue.remove(item)) return;\n\n        item.cleanupAbort?.();\n        reject(abortError(signal));\n        notifyIdle();\n      };\n\n      item.cleanupAbort = () => {\n        signal.removeEventListener('abort', onAbort);\n        item.cleanupAbort = undefined;\n      };\n\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n\n    drainLoop();\n\n    return promise;\n  }\n\n  // ─── runStream() ─────────────────────────────────────────────────────────────\n\n  function runStream(input: TInput, options: Omit<RunOptions, 'signal'> = {}): AsyncIterable<TOutput> {\n    if (terminated) {\n      throw new FamiliarRuntimeError('Worker was terminated');\n    }\n\n    const slot = freeSlots.pop();\n\n    if (!slot) {\n      throw new FamiliarRuntimeError(\n        `runStream() requires a free worker slot; all ${slots.length} slot${slots.length === 1 ? '' : 's'} are busy`,\n      );\n    }\n\n    const { timeout, transferables = [] } = options;\n    const iter = slot.runStream(input, transferables, timeout);\n\n    return {\n      [Symbol.asyncIterator]() {\n        const inner = iter[Symbol.asyncIterator]();\n        let released = false;\n\n        const releaseSlot = () => {\n          if (!released) {\n            released = true;\n            freeSlots.push(slot);\n          }\n        };\n\n        return {\n          async next() {\n            const result = await inner.next();\n\n            if (result.done) releaseSlot();\n\n            return result;\n          },\n\n          async return(value?: unknown) {\n            slot.cancel();\n            releaseSlot();\n\n            return inner.return?.(value) ?? { done: true as const, value };\n          },\n\n          async throw(error?: unknown) {\n            slot.cancel();\n            releaseSlot();\n\n            if (inner.throw) return inner.throw(error);\n\n            throw error;\n          },\n        };\n      },\n    };\n  }\n\n  // ─── batch() ─────────────────────────────────────────────────────────────────\n\n  async function* batch(inputs: TInput[], batchOptions: BatchOptions = {}): AsyncIterable<TOutput> {\n    if (inputs.length === 0) return;\n\n    const { ordered = true, ...runOpts } = batchOptions;\n    const ac = new AbortController();\n\n    try {\n      if (ordered) {\n        const promises = inputs.map((input) => run(input, { ...runOpts, signal: ac.signal }));\n\n        for (const p of promises) {\n          yield await p;\n        }\n      } else {\n        // As-completed: yield results in the order tasks finish, not submission order.\n        // A single-slot notification channel wakes the consumer when the next result is ready.\n        // Submission is windowed to `concurrency` outstanding (in-flight or buffered-but-unread)\n        // tasks at a time — releasing capacity for one more submission each time the consumer\n        // reads a result — so a slow consumer can't let an entire large batch settle in memory.\n        type Completion = { error: unknown } | { value: TOutput };\n\n        const completions: Completion[] = [];\n        let notifier: (() => void) | null = null;\n        let nextIndex = 0;\n        const windowSize = Math.max(1, concurrency);\n\n        function submitNext(): void {\n          if (nextIndex >= inputs.length) return;\n\n          const input = inputs[nextIndex++]!;\n\n          run(input, { ...runOpts, signal: ac.signal }).then(\n            (value) => {\n              completions.push({ value });\n              notifier?.();\n              notifier = null;\n            },\n            (error: unknown) => {\n              completions.push({ error });\n              notifier?.();\n              notifier = null;\n            },\n          );\n        }\n\n        for (let i = 0; i < windowSize && i < inputs.length; i++) submitNext();\n\n        for (let i = 0; i < inputs.length; i++) {\n          while (completions.length === 0) {\n            await new Promise<void>((resolve) => {\n              notifier = resolve;\n            });\n          }\n\n          const next = completions.shift()!;\n\n          if ('error' in next) throw next.error;\n\n          yield next.value;\n\n          // Only release capacity for another submission once the consumer has actually resumed\n          // past this yield (i.e. did not break/return early) — submitting here unconditionally\n          // would over-submit by one task on every early exit.\n          submitNext();\n        }\n      }\n    } finally {\n      // Abort remaining in-flight tasks on any exit path (normal, consumer break, or error).\n      ac.abort();\n    }\n  }\n\n  // ─── group() ─────────────────────────────────────────────────────────────────\n\n  function group(name?: string, options: GroupOptions = {}): TaskGroup<TInput, TOutput> {\n    const ac = new AbortController();\n\n    if (options.signal) {\n      const sig = options.signal;\n\n      if (sig.aborted) {\n        ac.abort(sig.reason);\n      } else {\n        sig.addEventListener('abort', () => ac.abort(sig.reason), { once: true });\n      }\n    }\n\n    groupActiveCount += 1;\n\n    let submittedCount = 0;\n    let settledCount = 0;\n    let groupClosed = false;\n    const pendingPromises: Promise<TOutput>[] = [];\n\n    function decrementGroupIfDone(): void {\n      if (!groupClosed && submittedCount > 0 && submittedCount === settledCount) {\n        groupClosed = true;\n        groupActiveCount -= 1;\n      }\n    }\n\n    return {\n      abort(reason?: unknown): void {\n        ac.abort(reason);\n      },\n\n      drain(): Promise<PromiseSettledResult<TOutput>[]> {\n        const snapshot = pendingPromises.splice(0);\n\n        if (!groupClosed) {\n          groupClosed = true;\n          groupActiveCount -= 1;\n        }\n\n        return Promise.allSettled(snapshot);\n      },\n\n      get name() {\n        return name;\n      },\n\n      get pending() {\n        return submittedCount - settledCount;\n      },\n\n      run(input: TInput, runOpts: Omit<RunOptions, 'signal'> = {}): Promise<TOutput> {\n        submittedCount += 1;\n\n        const p = run(input, { ...runOpts, signal: ac.signal });\n\n        pendingPromises.push(p);\n        p.then(\n          () => {\n            settledCount += 1;\n            decrementGroupIfDone();\n          },\n          () => {\n            settledCount += 1;\n            decrementGroupIfDone();\n          },\n        );\n\n        return p;\n      },\n\n      get size() {\n        return submittedCount;\n      },\n    };\n  }\n\n  // ─── Status ──────────────────────────────────────────────────────────────────\n\n  function getStatus(): WorkerStatus {\n    if (terminated) return 'terminated';\n\n    return activeCount > 0 || queue.size > 0 ? 'running' : 'idle';\n  }\n\n  return {\n    get active(): number {\n      return activeCount;\n    },\n    batch,\n    get completed(): number {\n      return completedCount;\n    },\n    get concurrency(): number {\n      return concurrency;\n    },\n    get disposalSignal(): AbortSignal {\n      return disposeController.signal;\n    },\n    dispose,\n    get disposed(): boolean {\n      return terminated;\n    },\n    drain,\n    get failed(): number {\n      return failedCount;\n    },\n    group,\n    get groupCount(): number {\n      return groupActiveCount;\n    },\n    prime(): Promise<void> {\n      return Promise.all(slots.map((s) => s.prime())).then(() => {});\n    },\n    get queued(): number {\n      return queue.size;\n    },\n    run,\n    runStream,\n    get status(): WorkerStatus {\n      return getStatus();\n    },\n    [Symbol.asyncDispose]: () => drain(),\n    [Symbol.dispose]: dispose,\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"_pool.cjs","names":[],"sources":["../src/_pool.ts"],"sourcesContent":["import { abortError } from '@vielzeug/arsenal/async';\n\nimport type {\n  BatchOptions,\n  DrainOptions,\n  RunOptions,\n  SlotStrategy,\n  TaskGroup,\n  TaskGroupOptions,\n  WorkerPool,\n  WorkerStats,\n  WorkerStatus,\n} from './types';\n\nimport { type QueueItem, TaskQueue } from './_queue';\nimport { unrefTimer } from './_timers';\nimport { FamiliarQueueFullError, FamiliarTerminatedError, FamiliarTimeoutError } from './errors';\n\nexport type PoolOptions = {\n  concurrency: number;\n  defaultTimeout: number | undefined;\n  maxQueue: number | undefined;\n  onFull: 'reject' | 'wait';\n};\n\ntype IdleWaiter = {\n  reject: (reason: unknown) => void;\n  resolve: () => void;\n  timer?: ReturnType<typeof setTimeout>;\n};\n\ntype CapacityWaiter = {\n  cleanup(): void;\n  reject(reason: unknown): void;\n  resolve(): void;\n};\n\nexport function createPool<TInput, TOutput>(\n  slots: SlotStrategy<TInput, TOutput>[],\n  options: PoolOptions,\n): WorkerPool<TInput, TOutput> {\n  const freeSlots = [...slots];\n  const queue = new TaskQueue<TInput, TOutput>();\n  const disposalController = new AbortController();\n  const idleWaiters: IdleWaiter[] = [];\n  const capacityWaiters: CapacityWaiter[] = [];\n  let active = 0;\n  let completed = 0;\n  let failed = 0;\n  let drainPromise: Promise<void> | undefined;\n  let draining = false;\n  let terminated = false;\n\n  function isIdle(): boolean {\n    return active === 0 && queue.size === 0;\n  }\n\n  function settleIdle(): void {\n    if (!isIdle()) return;\n\n    for (const waiter of idleWaiters.splice(0)) {\n      if (waiter.timer) clearTimeout(waiter.timer);\n\n      waiter.resolve();\n    }\n  }\n\n  function waitForIdle(drainOptions: DrainOptions = {}): Promise<void> {\n    if (isIdle()) return Promise.resolve();\n\n    return new Promise<void>((resolve, reject) => {\n      const waiter: IdleWaiter = { reject, resolve };\n\n      if (drainOptions.timeout !== undefined) {\n        waiter.timer = setTimeout(() => {\n          const index = idleWaiters.indexOf(waiter);\n\n          if (index !== -1) idleWaiters.splice(index, 1);\n\n          reject(new FamiliarTimeoutError(drainOptions.timeout!));\n        }, drainOptions.timeout);\n        unrefTimer(waiter.timer);\n      }\n\n      idleWaiters.push(waiter);\n    });\n  }\n\n  function releaseCapacity(): void {\n    capacityWaiters.shift()?.resolve();\n  }\n\n  function rejectCapacity(reason: unknown): void {\n    for (const waiter of capacityWaiters.splice(0)) waiter.reject(reason);\n  }\n\n  function waitForCapacity(signal: AbortSignal | undefined): Promise<void> {\n    if (signal?.aborted) return Promise.reject(abortError(signal));\n\n    return new Promise<void>((resolve, reject) => {\n      let settled = false;\n      const waiter: CapacityWaiter = {\n        cleanup() {\n          signal?.removeEventListener('abort', onAbort);\n        },\n        reject(reason) {\n          if (settled) return;\n\n          settled = true;\n          waiter.cleanup();\n\n          const index = capacityWaiters.indexOf(waiter);\n\n          if (index !== -1) capacityWaiters.splice(index, 1);\n\n          reject(reason);\n        },\n        resolve() {\n          if (settled) return;\n\n          settled = true;\n          waiter.cleanup();\n          resolve();\n        },\n      };\n      const onAbort = () => waiter.reject(abortError(signal!));\n\n      signal?.addEventListener('abort', onAbort, { once: true });\n      capacityWaiters.push(waiter);\n    });\n  }\n\n  function nextItem(): QueueItem<TInput, TOutput> | undefined {\n    while (queue.size > 0) {\n      const item = queue.shift();\n\n      if (!item) break;\n\n      if (item.signal?.aborted) {\n        item.cleanupAbort?.();\n        item.reject(abortError(item.signal));\n        releaseCapacity();\n        continue;\n      }\n\n      return item;\n    }\n\n    settleIdle();\n\n    return undefined;\n  }\n\n  function drainQueue(): void {\n    if (draining || terminated) return;\n\n    draining = true;\n\n    while (!terminated && freeSlots.length > 0 && queue.size > 0) {\n      const next = nextItem();\n\n      if (!next) break;\n\n      const item = next;\n      const slot = freeSlots.pop()!;\n      const timeout = item.timeout ?? options.defaultTimeout;\n\n      active += 1;\n      releaseCapacity();\n\n      const onAbort = () => slot.cancel(abortError(item.signal!));\n\n      item.cleanupAbort = () => {\n        item.signal?.removeEventListener('abort', onAbort);\n        item.cleanupAbort = undefined;\n      };\n      item.signal?.addEventListener('abort', onAbort, { once: true });\n\n      slot.run(item.input, item.transferables, timeout).then(\n        (value) => finish(value),\n        (error: unknown) => fail(error),\n      );\n\n      function finish(value: TOutput): void {\n        item.cleanupAbort?.();\n        freeSlots.push(slot);\n        active -= 1;\n        completed += 1;\n        item.resolve(value);\n        drainQueue();\n        settleIdle();\n      }\n\n      function fail(error: unknown): void {\n        item.cleanupAbort?.();\n        freeSlots.push(slot);\n        active -= 1;\n\n        if (!(error instanceof FamiliarTerminatedError) && error?.constructor?.name !== 'AbortError') failed += 1;\n\n        item.reject(error);\n        drainQueue();\n        settleIdle();\n      }\n    }\n\n    draining = false;\n  }\n\n  async function run(input: TInput, runOptions: RunOptions = {}): Promise<TOutput> {\n    const { priority = 0, signal, timeout, transferables = [] } = runOptions;\n\n    if (terminated) throw new FamiliarTerminatedError();\n\n    if (drainPromise) throw new FamiliarTerminatedError('Worker is draining');\n\n    if (signal?.aborted) throw abortError(signal);\n\n    while (options.onFull === 'wait' && options.maxQueue !== undefined && queue.size >= options.maxQueue) {\n      await waitForCapacity(signal);\n\n      if (terminated) throw new FamiliarTerminatedError();\n\n      if (drainPromise) throw new FamiliarTerminatedError('Worker is draining');\n\n      if (signal?.aborted) throw abortError(signal);\n    }\n\n    let resolve!: (value: TOutput) => void;\n    let reject!: (reason: unknown) => void;\n    const promise = new Promise<TOutput>((res, rej) => {\n      resolve = res;\n      reject = rej;\n    });\n    const item: QueueItem<TInput, TOutput> = { input, priority, reject, resolve, signal, timeout, transferables };\n\n    if (!queue.enqueue(item, options.onFull === 'wait' ? undefined : options.maxQueue)) {\n      throw new FamiliarQueueFullError(options.maxQueue!);\n    }\n\n    if (signal) {\n      const onAbort = () => {\n        if (!queue.remove(item)) return;\n\n        item.cleanupAbort?.();\n        reject(abortError(signal));\n        releaseCapacity();\n        settleIdle();\n      };\n\n      item.cleanupAbort = () => {\n        signal.removeEventListener('abort', onAbort);\n        item.cleanupAbort = undefined;\n      };\n      signal.addEventListener('abort', onAbort, { once: true });\n    }\n\n    drainQueue();\n\n    return promise;\n  }\n\n  function dispose(): void {\n    if (terminated) return;\n\n    terminated = true;\n    disposalController.abort();\n    for (const slot of slots) slot.terminate();\n\n    while (queue.size > 0) {\n      const item = queue.shift();\n\n      if (!item) break;\n\n      item.cleanupAbort?.();\n      item.reject(new FamiliarTerminatedError());\n    }\n\n    rejectCapacity(new FamiliarTerminatedError());\n    settleIdle();\n  }\n\n  function drain(drainOptions: DrainOptions = {}): Promise<void> {\n    if (terminated) return Promise.resolve();\n\n    if (drainPromise) return drainPromise;\n\n    rejectCapacity(new FamiliarTerminatedError('Worker is draining'));\n    drainPromise = waitForIdle(drainOptions).then(\n      () => dispose(),\n      (error: unknown) => {\n        dispose();\n        throw error;\n      },\n    );\n\n    return drainPromise;\n  }\n\n  return {\n    get disposalSignal() {\n      return disposalController.signal;\n    },\n    dispose,\n    get disposed() {\n      return terminated;\n    },\n    drain,\n    async prime(): Promise<void> {\n      await Promise.all(slots.map((slot) => slot.prime()));\n    },\n    run,\n    get stats(): WorkerStats {\n      return { active, completed, failed, queued: queue.size };\n    },\n    get status(): WorkerStatus {\n      if (terminated) return 'terminated';\n\n      return active === 0 ? 'idle' : 'running';\n    },\n    [Symbol.asyncDispose]: () => drain(),\n    [Symbol.dispose]: dispose,\n  };\n}\n\nexport async function* batch<TInput, TOutput>(\n  pool: WorkerPool<TInput, TOutput>,\n  inputs: readonly TInput[],\n  options: BatchOptions = {},\n): AsyncIterable<TOutput> {\n  const controller = new AbortController();\n  const onAbort = () => controller.abort(options.signal!.reason);\n\n  options.signal?.addEventListener('abort', onAbort, { once: true });\n\n  const tasks = inputs.map((input) => pool.run(input, { ...options, signal: controller.signal }));\n\n  try {\n    for (const task of tasks) yield await task;\n  } catch (error) {\n    controller.abort(error);\n    await Promise.allSettled(tasks);\n    throw error;\n  } finally {\n    options.signal?.removeEventListener('abort', onAbort);\n    controller.abort();\n    await Promise.allSettled(tasks);\n  }\n}\n\nexport function createTaskGroup<TInput, TOutput>(\n  pool: WorkerPool<TInput, TOutput>,\n  name: string | undefined = undefined,\n  options: TaskGroupOptions = {},\n): TaskGroup<TInput, TOutput> {\n  const controller = new AbortController();\n  const tasks = new Set<Promise<TOutput>>();\n  let size = 0;\n  const onAbort = () => controller.abort(options.signal!.reason);\n\n  options.signal?.addEventListener('abort', onAbort, { once: true });\n\n  return {\n    abort(reason?: unknown): void {\n      controller.abort(reason);\n    },\n    async drain(): Promise<PromiseSettledResult<TOutput>[]> {\n      return Promise.allSettled([...tasks]);\n    },\n    get name() {\n      return name;\n    },\n    get pending() {\n      return tasks.size;\n    },\n    run(input, runOptions = {}): Promise<TOutput> {\n      const task = pool.run(input, { ...runOptions, signal: controller.signal });\n\n      size += 1;\n      tasks.add(task);\n      void task.finally(() => tasks.delete(task));\n\n      return task;\n    },\n    get size() {\n      return size;\n    },\n  };\n}\n"],"mappings":"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"}

package/dist/_pool.d.ts

@@ -1,19 +1,11 @@
-/**
- * Shared pool orchestration engine used by both the real worker implementation and the test
- * double. Handles queue management, iterative drain loop, abort handling, lifecycle (drain /
- * dispose), metrics, batch streaming, task groups, and backpressure.
- *
- * Callers provide a SlotStrategy array — each slot encapsulates run/runStream/prime/terminate.
- * The pool does not care whether slots use a Web Worker or run in-process.
- *
- * Not part of the public API surface.
- */
-import type { SlotStrategy, WorkerHandle } from './types';
+import type { BatchOptions, SlotStrategy, TaskGroup, TaskGroupOptions, WorkerPool } from './types';
 export type PoolOptions = {
     concurrency: number;
     defaultTimeout: number | undefined;
     maxQueue: number | undefined;
     onFull: 'reject' | 'wait';
 };
-export declare function createPool<TInput, TOutput>(slots: SlotStrategy<TInput, TOutput>[], options: PoolOptions): WorkerHandle<TInput, TOutput>;
+export declare function createPool<TInput, TOutput>(slots: SlotStrategy<TInput, TOutput>[], options: PoolOptions): WorkerPool<TInput, TOutput>;
+export declare function batch<TInput, TOutput>(pool: WorkerPool<TInput, TOutput>, inputs: readonly TInput[], options?: BatchOptions): AsyncIterable<TOutput>;
+export declare function createTaskGroup<TInput, TOutput>(pool: WorkerPool<TInput, TOutput>, name?: string | undefined, options?: TaskGroupOptions): TaskGroup<TInput, TOutput>;
 //# sourceMappingURL=_pool.d.ts.map

package/dist/_pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_pool.d.ts","sourceRoot":"","sources":["../src/_pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAIV,YAAY,EAEZ,YAAY,EAEb,MAAM,SAAS,CAAC;AAMjB,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC3B,CAAC;AAEF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EACxC,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACtC,OAAO,EAAE,WAAW,GACnB,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAsf/B"}
+{"version":3,"file":"_pool.d.ts","sourceRoot":"","sources":["../src/_pool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,YAAY,EAGZ,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,UAAU,EAGX,MAAM,SAAS,CAAC;AAMjB,MAAM,MAAM,WAAW,GAAG;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;CAC3B,CAAC;AAcF,wBAAgB,UAAU,CAAC,MAAM,EAAE,OAAO,EACxC,KAAK,EAAE,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACtC,OAAO,EAAE,WAAW,GACnB,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CA2R7B;AAED,wBAAuB,KAAK,CAAC,MAAM,EAAE,OAAO,EAC1C,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,OAAO,GAAE,YAAiB,GACzB,aAAa,CAAC,OAAO,CAAC,CAmBxB;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,EAC7C,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,IAAI,GAAE,MAAM,GAAG,SAAqB,EACpC,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAkC5B"}