@vielzeug/familiar 1.0.2

package/README.md

@@ -0,0 +1,78 @@
+# @vielzeug/familiar
+
+> Typed Web Worker pools with queuing, priorities, streaming, heartbeat, and testing 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.
+
+## Installation
+
+```sh
+pnpm add @vielzeug/familiar
+npm install @vielzeug/familiar
+yarn add @vielzeug/familiar
+```
+
+## Quick Start
+
+```ts
+import { createWorker } from '@vielzeug/familiar';
+
+// 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();
+
+// Priority queue — higher values run first
+await pool.run(heavyTask, { priority: 10 }); // runs before default-priority tasks
+
+// Batch processing — yield results as they arrive
+for await (const result of pool.batch([1, 2, 3, 4])) {
+  console.log(result);
+}
+
+// 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})`);
+}
+```
+
+## Documentation
+
+- [Overview](https://vielzeug.dev/familiar/)
+- [Usage Guide](https://vielzeug.dev/familiar/usage)
+- [API Reference](https://vielzeug.dev/familiar/api)
+- [Examples](https://vielzeug.dev/familiar/examples)
+
+## License
+
+MIT © [Helmuth Saatkamp](https://github.com/helmuthdu) — part of the [Vielzeug](https://github.com/helmuthdu/vielzeug) monorepo.

package/dist/_dev.cjs

@@ -0,0 +1,2 @@
+var e=!globalThis.__FAMILIAR_PROD__;function t(t){e&&console.warn(`[@vielzeug/familiar] ${t}`)}exports.warn=t;
+//# sourceMappingURL=_dev.cjs.map

package/dist/_dev.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dev.cjs","names":[],"sources":["../src/_dev.ts"],"sourcesContent":["const isDev = !(globalThis as { __FAMILIAR_PROD__?: boolean }).__FAMILIAR_PROD__;\n\n/** @internal */\nexport function warn(msg: string): void {\n  if (isDev) console.warn(`[@vielzeug/familiar] ${msg}`);\n}\n\n/** @internal — Run fn only in dev builds. Use when dev-only logic goes beyond a single warn() / error() call. */\nexport function devOnly(fn: () => void): void {\n  if (isDev) fn();\n}\n"],"mappings":"AAAA,IAAM,EAAQ,CAAE,WAA+C,kBAG/D,SAAgB,EAAK,EAAmB,CAClC,GAAO,QAAQ,KAAK,wBAAwB,GAAK,CACvD"}

package/dist/_dev.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=_dev.d.ts.map

package/dist/_dev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dev.d.ts","sourceRoot":"","sources":["../src/_dev.ts"],"names":[],"mappings":""}

package/dist/_dev.js

@@ -0,0 +1,9 @@
+//#region src/_dev.ts
+var e = !globalThis.__FAMILIAR_PROD__;
+function t(t) {
+	e && console.warn(`[@vielzeug/familiar] ${t}`);
+}
+//#endregion
+export { t as warn };
+
+//# sourceMappingURL=_dev.js.map

package/dist/_dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_dev.js","names":[],"sources":["../src/_dev.ts"],"sourcesContent":["const isDev = !(globalThis as { __FAMILIAR_PROD__?: boolean }).__FAMILIAR_PROD__;\n\n/** @internal */\nexport function warn(msg: string): void {\n  if (isDev) console.warn(`[@vielzeug/familiar] ${msg}`);\n}\n\n/** @internal — Run fn only in dev builds. Use when dev-only logic goes beyond a single warn() / error() call. */\nexport function devOnly(fn: () => void): void {\n  if (isDev) fn();\n}\n"],"mappings":";AAAA,IAAM,IAAQ,CAAE,WAA+C;AAG/D,SAAgB,EAAK,GAAmB;CACtC,AAAI,KAAO,QAAQ,KAAK,wBAAwB,GAAK;AACvD"}

package/dist/_pool.cjs

@@ -0,0 +1,2 @@
+const e=require("./errors.cjs"),t=require("./_queue.cjs"),n=require("./_timers.cjs");let r=require("@vielzeug/arsenal");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)=>{p.push(r),t!==void 0&&n.unrefTimer(setTimeout(()=>{let n=p.indexOf(r);n!==-1&&p.splice(n,1),i(new e.FamiliarTimeoutError(t))},t))})}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;
+//# sourceMappingURL=_pool.cjs.map

package/dist/_pool.cjs.map

@@ -0,0 +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';\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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"}

package/dist/_pool.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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';
+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>;
+//# sourceMappingURL=_pool.d.ts.map

package/dist/_pool.d.ts.map

@@ -0,0 +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"}

package/dist/_pool.js

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

package/dist/_pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_pool.js","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';\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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"}

package/dist/_queue.cjs

@@ -0,0 +1,2 @@
+var e=class{heap=[];liveCount=0;seq=0;get size(){return this.liveCount}enqueue(e,t){return t!==void 0&&this.liveCount>=t?!1:(this.heap.push({_seq:this.seq++,item:e}),this.siftUp(this.heap.length-1),this.liveCount++,!0)}shift(){for(;this.heap.length>0;){let{item:e}=this.extractTop();if(!e.cancelled)return this.liveCount--,e}}remove(e){if(e.cancelled)return!1;for(let t=0;t<this.heap.length;t++)if(this.heap[t].item===e)return e.cancelled=!0,this.liveCount--,!0;return!1}extractTop(){let e=this.heap[0],t=this.heap.pop();return this.heap.length>0&&(this.heap[0]=t,this.siftDown(0)),e}higher(e,t){return e.item.priority===t.item.priority?e._seq<t._seq:e.item.priority>t.item.priority}siftUp(e){for(;e>0;){let t=e-1>>1;if(this.higher(this.heap[e],this.heap[t]))[this.heap[e],this.heap[t]]=[this.heap[t],this.heap[e]],e=t;else break}}siftDown(e){let t=this.heap.length;for(;;){let n=e,r=2*e+1,i=2*e+2;if(r<t&&this.higher(this.heap[r],this.heap[n])&&(n=r),i<t&&this.higher(this.heap[i],this.heap[n])&&(n=i),n===e)break;[this.heap[e],this.heap[n]]=[this.heap[n],this.heap[e]],e=n}}};exports.TaskQueue=e;
+//# sourceMappingURL=_queue.cjs.map

package/dist/_queue.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"_queue.cjs","names":[],"sources":["../src/_queue.ts"],"sourcesContent":["/**\n * Internal priority-queue for @vielzeug/familiar.\n * Not part of the public API surface.\n *\n * Uses a binary max-heap ordered by priority (higher value = runs first), with\n * insertion-sequence tiebreaking to ensure FIFO ordering within the same priority.\n * Cancelled items are marked lazily and silently skipped by shift().\n *\n * Complexity:\n *   enqueue  O(log n)\n *   shift    O(log n) amortised (lazy cancellation may scan multiple cancelled tops)\n *   remove   O(n) scan + O(1) mark — adequate for typical queue depths\n */\n\nexport type QueueItem<TInput, TOutput> = {\n  /** Marked true by remove(); the next shift() discards the item silently. */\n  cancelled?: boolean;\n  cleanupAbort?: () => void;\n  input: TInput;\n  /** Scheduling priority. Higher value = runs first. Default: 0. */\n  priority: number;\n  reject: (reason: unknown) => void;\n  resolve: (value: TOutput) => void;\n  signal?: AbortSignal;\n  timeout?: number;\n  transferables: Transferable[];\n};\n\n/**\n * Internal heap node: wraps a QueueItem with an insertion sequence for FIFO tiebreaking.\n * Using a wrapper instead of mutating QueueItem keeps queue items free of internal\n * scheduling metadata (_seq).\n */\ntype HeapEntry<TInput, TOutput> = { readonly _seq: number; readonly item: QueueItem<TInput, TOutput> };\n\nexport class TaskQueue<TInput, TOutput> {\n  private readonly heap: HeapEntry<TInput, TOutput>[] = [];\n  /** Accurate count of live (non-cancelled) items. */\n  private liveCount = 0;\n  private seq = 0;\n\n  /** Number of live (non-cancelled) items. Always accurate. */\n  get size(): number {\n    return this.liveCount;\n  }\n\n  /**\n   * Enqueue item. Returns false (without modifying state) when maxQueue is set and\n   * liveCount has already reached it; returns true on success.\n   */\n  enqueue(item: QueueItem<TInput, TOutput>, maxQueue: number | undefined): boolean {\n    if (maxQueue !== undefined && this.liveCount >= maxQueue) return false;\n\n    this.heap.push({ _seq: this.seq++, item });\n    this.siftUp(this.heap.length - 1);\n    this.liveCount++;\n\n    return true;\n  }\n\n  /**\n   * Dequeue the highest-priority live item. Silently discards cancelled tombstones.\n   * Returns undefined only when there are no live items left.\n   */\n  shift(): QueueItem<TInput, TOutput> | undefined {\n    while (this.heap.length > 0) {\n      const { item } = this.extractTop();\n\n      if (!item.cancelled) {\n        this.liveCount--;\n\n        return item;\n      }\n      // Cancelled: liveCount was already decremented in remove(). Just discard and continue.\n    }\n\n    return undefined;\n  }\n\n  /**\n   * Mark item as cancelled (O(n) scan). The heap slot is reclaimed lazily by the next shift().\n   * Returns true when found and marked, false when the item is not in the queue.\n   */\n  remove(item: QueueItem<TInput, TOutput>): boolean {\n    if (item.cancelled) return false;\n\n    for (let i = 0; i < this.heap.length; i++) {\n      if (this.heap[i]!.item === item) {\n        item.cancelled = true;\n        this.liveCount--;\n\n        return true;\n      }\n    }\n\n    return false;\n  }\n\n  // ─── Heap internals ────────────────────────────────────────────────────────\n\n  private extractTop(): HeapEntry<TInput, TOutput> {\n    const top = this.heap[0]!;\n    const last = this.heap.pop()!;\n\n    if (this.heap.length > 0) {\n      this.heap[0] = last;\n      this.siftDown(0);\n    }\n\n    return top;\n  }\n\n  /** Returns true when entry a should be dispatched before entry b. */\n  private higher(a: HeapEntry<TInput, TOutput>, b: HeapEntry<TInput, TOutput>): boolean {\n    if (a.item.priority !== b.item.priority) return a.item.priority > b.item.priority;\n\n    return a._seq < b._seq; // earlier insertion wins for equal priority (FIFO)\n  }\n\n  private siftUp(i: number): void {\n    while (i > 0) {\n      const parent = (i - 1) >> 1;\n\n      if (this.higher(this.heap[i]!, this.heap[parent]!)) {\n        [this.heap[i], this.heap[parent]] = [this.heap[parent]!, this.heap[i]!];\n        i = parent;\n      } else {\n        break;\n      }\n    }\n  }\n\n  private siftDown(i: number): void {\n    const n = this.heap.length;\n\n    for (;;) {\n      let top = i;\n      const left = 2 * i + 1;\n      const right = 2 * i + 2;\n\n      if (left < n && this.higher(this.heap[left]!, this.heap[top]!)) top = left;\n\n      if (right < n && this.higher(this.heap[right]!, this.heap[top]!)) top = right;\n\n      if (top === i) break;\n\n      [this.heap[i], this.heap[top]] = [this.heap[top]!, this.heap[i]!];\n      i = top;\n    }\n  }\n}\n"],"mappings":"AAmCA,IAAa,EAAb,KAAwC,CACtC,KAAsD,CAAC,EAEvD,UAAoB,EACpB,IAAc,EAGd,IAAI,MAAe,CACjB,OAAO,KAAK,SACd,CAMA,QAAQ,EAAkC,EAAuC,CAO/E,OANI,IAAa,IAAA,IAAa,KAAK,WAAa,EAAiB,IAEjE,KAAK,KAAK,KAAK,CAAE,KAAM,KAAK,MAAO,MAAK,CAAC,EACzC,KAAK,OAAO,KAAK,KAAK,OAAS,CAAC,EAChC,KAAK,YAEE,GACT,CAMA,OAAgD,CAC9C,KAAO,KAAK,KAAK,OAAS,GAAG,CAC3B,GAAM,CAAE,QAAS,KAAK,WAAW,EAEjC,GAAI,CAAC,EAAK,UAGR,MAFA,MAAK,YAEE,CAGX,CAGF,CAMA,OAAO,EAA2C,CAChD,GAAI,EAAK,UAAW,MAAO,GAE3B,IAAK,IAAI,EAAI,EAAG,EAAI,KAAK,KAAK,OAAQ,IACpC,GAAI,KAAK,KAAK,EAAE,CAAE,OAAS,EAIzB,MAHA,GAAK,UAAY,GACjB,KAAK,YAEE,GAIX,MAAO,EACT,CAIA,YAAiD,CAC/C,IAAM,EAAM,KAAK,KAAK,GAChB,EAAO,KAAK,KAAK,IAAI,EAO3B,OALI,KAAK,KAAK,OAAS,IACrB,KAAK,KAAK,GAAK,EACf,KAAK,SAAS,CAAC,GAGV,CACT,CAGA,OAAe,EAA+B,EAAwC,CAGpF,OAFI,EAAE,KAAK,WAAa,EAAE,KAAK,SAExB,EAAE,KAAO,EAAE,KAF8B,EAAE,KAAK,SAAW,EAAE,KAAK,QAG3E,CAEA,OAAe,EAAiB,CAC9B,KAAO,EAAI,GAAG,CACZ,IAAM,EAAU,EAAI,GAAM,EAE1B,GAAI,KAAK,OAAO,KAAK,KAAK,GAAK,KAAK,KAAK,EAAQ,EAC/C,CAAC,KAAK,KAAK,GAAI,KAAK,KAAK,IAAW,CAAC,KAAK,KAAK,GAAU,KAAK,KAAK,EAAG,EACtE,EAAI,OAEJ,KAEJ,CACF,CAEA,SAAiB,EAAiB,CAChC,IAAM,EAAI,KAAK,KAAK,OAEpB,OAAS,CACP,IAAI,EAAM,EACJ,EAAO,EAAI,EAAI,EACf,EAAQ,EAAI,EAAI,EAMtB,GAJI,EAAO,GAAK,KAAK,OAAO,KAAK,KAAK,GAAQ,KAAK,KAAK,EAAK,IAAG,EAAM,GAElE,EAAQ,GAAK,KAAK,OAAO,KAAK,KAAK,GAAS,KAAK,KAAK,EAAK,IAAG,EAAM,GAEpE,IAAQ,EAAG,MAEf,CAAC,KAAK,KAAK,GAAI,KAAK,KAAK,IAAQ,CAAC,KAAK,KAAK,GAAO,KAAK,KAAK,EAAG,EAChE,EAAI,CACN,CACF,CACF"}

package/dist/_queue.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Internal priority-queue for @vielzeug/familiar.
+ * Not part of the public API surface.
+ *
+ * Uses a binary max-heap ordered by priority (higher value = runs first), with
+ * insertion-sequence tiebreaking to ensure FIFO ordering within the same priority.
+ * Cancelled items are marked lazily and silently skipped by shift().
+ *
+ * Complexity:
+ *   enqueue  O(log n)
+ *   shift    O(log n) amortised (lazy cancellation may scan multiple cancelled tops)
+ *   remove   O(n) scan + O(1) mark — adequate for typical queue depths
+ */
+export type QueueItem<TInput, TOutput> = {
+    /** Marked true by remove(); the next shift() discards the item silently. */
+    cancelled?: boolean;
+    cleanupAbort?: () => void;
+    input: TInput;
+    /** Scheduling priority. Higher value = runs first. Default: 0. */
+    priority: number;
+    reject: (reason: unknown) => void;
+    resolve: (value: TOutput) => void;
+    signal?: AbortSignal;
+    timeout?: number;
+    transferables: Transferable[];
+};
+export declare class TaskQueue<TInput, TOutput> {
+    private readonly heap;
+    /** Accurate count of live (non-cancelled) items. */
+    private liveCount;
+    private seq;
+    /** Number of live (non-cancelled) items. Always accurate. */
+    get size(): number;
+    /**
+     * Enqueue item. Returns false (without modifying state) when maxQueue is set and
+     * liveCount has already reached it; returns true on success.
+     */
+    enqueue(item: QueueItem<TInput, TOutput>, maxQueue: number | undefined): boolean;
+    /**
+     * Dequeue the highest-priority live item. Silently discards cancelled tombstones.
+     * Returns undefined only when there are no live items left.
+     */
+    shift(): QueueItem<TInput, TOutput> | undefined;
+    /**
+     * Mark item as cancelled (O(n) scan). The heap slot is reclaimed lazily by the next shift().
+     * Returns true when found and marked, false when the item is not in the queue.
+     */
+    remove(item: QueueItem<TInput, TOutput>): boolean;
+    private extractTop;
+    /** Returns true when entry a should be dispatched before entry b. */
+    private higher;
+    private siftUp;
+    private siftDown;
+}
+//# sourceMappingURL=_queue.d.ts.map

package/dist/_queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_queue.d.ts","sourceRoot":"","sources":["../src/_queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,SAAS,CAAC,MAAM,EAAE,OAAO,IAAI;IACvC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,YAAY,EAAE,CAAC;CAC/B,CAAC;AASF,qBAAa,SAAS,CAAC,MAAM,EAAE,OAAO;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoC;IACzD,oDAAoD;IACpD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,GAAG,CAAK;IAEhB,6DAA6D;IAC7D,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO;IAUhF;;;OAGG;IACH,KAAK,IAAI,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAe/C;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;IAiBjD,OAAO,CAAC,UAAU;IAYlB,qEAAqE;IACrE,OAAO,CAAC,MAAM;IAMd,OAAO,CAAC,MAAM;IAad,OAAO,CAAC,QAAQ;CAkBjB"}

package/dist/_queue.js

@@ -0,0 +1,52 @@
+//#region src/_queue.ts
+var e = class {
+	heap = [];
+	liveCount = 0;
+	seq = 0;
+	get size() {
+		return this.liveCount;
+	}
+	enqueue(e, t) {
+		return t !== void 0 && this.liveCount >= t ? !1 : (this.heap.push({
+			_seq: this.seq++,
+			item: e
+		}), this.siftUp(this.heap.length - 1), this.liveCount++, !0);
+	}
+	shift() {
+		for (; this.heap.length > 0;) {
+			let { item: e } = this.extractTop();
+			if (!e.cancelled) return this.liveCount--, e;
+		}
+	}
+	remove(e) {
+		if (e.cancelled) return !1;
+		for (let t = 0; t < this.heap.length; t++) if (this.heap[t].item === e) return e.cancelled = !0, this.liveCount--, !0;
+		return !1;
+	}
+	extractTop() {
+		let e = this.heap[0], t = this.heap.pop();
+		return this.heap.length > 0 && (this.heap[0] = t, this.siftDown(0)), e;
+	}
+	higher(e, t) {
+		return e.item.priority === t.item.priority ? e._seq < t._seq : e.item.priority > t.item.priority;
+	}
+	siftUp(e) {
+		for (; e > 0;) {
+			let t = e - 1 >> 1;
+			if (this.higher(this.heap[e], this.heap[t])) [this.heap[e], this.heap[t]] = [this.heap[t], this.heap[e]], e = t;
+			else break;
+		}
+	}
+	siftDown(e) {
+		let t = this.heap.length;
+		for (;;) {
+			let n = e, r = 2 * e + 1, i = 2 * e + 2;
+			if (r < t && this.higher(this.heap[r], this.heap[n]) && (n = r), i < t && this.higher(this.heap[i], this.heap[n]) && (n = i), n === e) break;
+			[this.heap[e], this.heap[n]] = [this.heap[n], this.heap[e]], e = n;
+		}
+	}
+};
+//#endregion
+export { e as TaskQueue };
+
+//# sourceMappingURL=_queue.js.map