@zakkster/lite-stream 1.0.0 → 1.1.1

package/Stream.js

@@ -1,4 +1,4 @@
-// @zakkster/lite-stream 1.0.0
+// @zakkster/lite-stream 1.1.1
 //
 // Zero-GC bridge between async iterators and @zakkster/lite-signal. The
 // multi-shot dual of lite-await's fromPromise: project an async source of N
@@ -20,11 +20,40 @@
 //     droppedCount. Best for "process every helix page in order, don't miss
 //     events".
 //
+// 1.1 added `mode: "latest"`, `filter`, `timeout`, `Symbol.asyncDispose`,
+// multi-waiter FIFO queue, and `overflowCount` on `toAsyncIterable`. See
+// CHANGELOG.md [1.1.0] and llms.txt (toAsyncIterable section) for the full
+// 1.1 story.
+//
 // Copyright (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com>
 // MIT License
 
 import { signal as _signal } from "@zakkster/lite-signal";
 
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown when a `timeout` deadline elapses before iterator settlement.
+ * Introduced in 1.1 alongside `toAsyncIterable`'s `timeout` option.
+ * Structurally identical to lite-await's `TimeoutError` so users can
+ * duck-check via `e.name === "TimeoutError"` across both packages -- but
+ * NOT imported from lite-await, to preserve lite-stream's zero-dep story.
+ *
+ * A structural twin of lite-await's TimeoutError, deliberately not imported
+ * (zero-dep by design), carrying `name === "TimeoutError"` and a `.timeout`
+ * field (the elapsed deadline in ms). The duck-check is suite-wide vocabulary;
+ * renaming it would be a breaking change everywhere it is consumed.
+ */
+class TimeoutError extends Error {
+    constructor(timeoutMs) {
+        super("lite-stream: timed out after " + timeoutMs + "ms");
+        this.name = "TimeoutError";
+        this.timeout = timeoutMs;
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -118,11 +147,11 @@ function closeIterator(iter) {
  *   - iterator throws
  *   - opts.signal aborts (the iterator's return() is called best-effort)
  *
- * To stop the stream without an AbortSignal, you can either:
- *   - dispose the returned signal via lite-signal's dispose(sig); pending
- *     iterator pulls will see the signal as disposed on next set() (no-op),
- *     but the iterator continues until natural completion. PREFER AbortSignal.
- *   - pass opts.signal and abort it externally.
+ * Disposing the result signal does NOT stop the pump: the iterator keeps
+ * pulling. AbortSignal or natural completion are the only stop mechanisms.
+ * A disposed signal's set() is a silent no-op, so the pump never learns of
+ * the disposal; an infinite source becomes an unbounded background loop.
+ * Pass opts.signal and abort it to stop early. See ROADMAP LS-01.
  *
  * @template T
  * @param {AsyncIterable<T> | AsyncIterator<T> | Iterable<T>} source
@@ -274,9 +303,11 @@ function fromAsyncIterable(source, opts) {
                 }
                 const v = result.value;
                 // Build the new state from lastState (never sig.peek), then
-                // commit to both lastState and sig. If sig.set throws (consumer
-                // disposed the signal externally), bail and tear down the
-                // iterator so we don't keep pulling into the void.
+                // commit to both lastState and sig. The try/catch around set()
+                // is defensive against a peer whose set() throws; on a throw we
+                // bail and tear down the iterator rather than pull into the
+                // void. Disposal is NOT the trigger -- set() after dispose() is
+                // a silent no-op in lite-signal 1.2.2 and 1.5.0 (see LS-01).
                 let newState;
                 if (mode === "latest") {
                     newState = {
@@ -314,16 +345,22 @@ function fromAsyncIterable(source, opts) {
                 try {
                     sig.set(newState);
                 } catch (_e) {
-                    // Signal disposed externally. Tear down quietly without
-                    // firing onError -- this is consumer-initiated cleanup,
-                    // not a stream error.
+                    // Defensive against a peer signal whose set() throws. This
+                    // is NOT disposal detection: set() after dispose() is a
+                    // silent no-op in lite-signal 1.2.2 and 1.5.0 (probe P0),
+                    // so this branch has never fired against any published
+                    // peer. If it ever does, tear down without firing onError.
                     stopped = true;
                     cleanup();
                     closeIterator(iter);
                     return;
                 }
-                // Defer the next pull through the microtask queue so back-to-back
-                // synchronous yields don't blow the stack.
+                // pump() is called DIRECTLY here -- no explicit deferral at
+                // this site. The stack is already unwound because this
+                // continuation runs from a .then() handler, i.e. a fresh
+                // microtask. Proven safe: 1,000,000 synchronous values drained
+                // in ~80ms with no stack overflow (probe P4, node v26.3.1,
+                // 2026-09-01).
                 pump();
             },
             function (err) {
@@ -393,6 +430,8 @@ function makeErrorState(prevState, err, mode) {
  *   - You want a stop fn instead of an AbortController for cleanup
  *
  * NOTE: this does NOT dispose the target signal. The caller owns its lifetime.
+ * Disposing the target signal does NOT stop the pump: call the returned
+ * stop fn or abort opts.signal. See ROADMAP LS-01.
  *
  * @template T
  * @param {AsyncIterable<T> | AsyncIterator<T>} source
@@ -498,31 +537,55 @@ function pipeToSignal(source, target, opts) {
     return stop;
 }
 
+// ---------------------------------------------------------------------------
+// Symbol.asyncDispose feature detection (Node 20+)
+// ---------------------------------------------------------------------------
+// Cached once at module load. When the runtime lacks Symbol.asyncDispose
+// (Node 18/19), the iterable's disposer property is simply absent;
+// iter.return() is the portable path.
+
+const ASYNC_DISPOSE = (typeof Symbol !== "undefined" && Symbol.asyncDispose)
+    ? Symbol.asyncDispose
+    : null;
+
 // ---------------------------------------------------------------------------
 // toAsyncIterable -- the reverse direction
 // ---------------------------------------------------------------------------
 
 /**
- * Yield signal changes as an async iterable. Each change to the signal
- * resolves a pending `next()` call. If the consumer is slower than the
- * producer, values queue in an internal bounded buffer; on overflow, the
- * OLDEST queued value is dropped and `droppedCount` is incremented. The
- * dropped count is observable via the iterable's `.droppedCount` property
- * (read after consuming).
+ * Yield signal changes as an async iterable. Each change resolves a pending
+ * `next()` call. Two backpressure modes (1.1):
  *
- * The iterator naturally completes when `opts.signal` aborts; iterator.return()
- * resolves cleanly.
+ *   - "buffer" (default; matches 1.0.0): FIFO ring buffer of maxBuffer size;
+ *     on overflow the OLDEST is dropped and both droppedCount and
+ *     overflowCount are incremented.
+ *   - "latest" (1.1): single mutable slot; producer overwrites; every
+ *     overwrite bumps overflowCount (and droppedCount for compat).
+ *
+ * 1.1 also adds `filter` (per-value gate; throwing filter rejects the
+ * current next() and terminates without a writer surface), `timeout`
+ * (overall deadline; rejects with TimeoutError), Symbol.asyncDispose
+ * on Node 20+, and a multi-waiter queue that fixes the 1.0.0 latent bug
+ * where Promise.all([iter.next(), iter.next()]) silently lost the first
+ * resolver.
+ *
+ * See CHANGELOG.md [1.1.0] and llms.txt (toAsyncIterable section) for the
+ * full locked semantics.
  *
  * @template T
  * @param {import("@zakkster/lite-signal").Signal<T> | import("@zakkster/lite-signal").Computed<T>} sig
  * @param {{
- *     signal?:     AbortSignal,
- *     emitInitial?: boolean,    // default true: yield the current value first
- *     maxBuffer?:   number       // default 1024
+ *     signal?:      AbortSignal,
+ *     emitInitial?: boolean,
+ *     maxBuffer?:   number,
+ *     mode?:        "latest" | "buffer",
+ *     filter?:      (v: T) => unknown,
+ *     timeout?:     number
  * }} [opts]
- * @returns {AsyncIterable<T> & { readonly droppedCount: number }}
+ * @returns {AsyncIterable<T> & { readonly droppedCount: number, readonly overflowCount: number }}
  */
 function toAsyncIterable(sig, opts) {
+    // --- Validation ---
     if (sig === null || sig === undefined || typeof sig.subscribe !== "function" || typeof sig.peek !== "function") {
         throw new TypeError(
             "lite-stream: toAsyncIterable expects a readable lite-signal (Signal/Computed with .peek and .subscribe)"
@@ -530,101 +593,273 @@ function toAsyncIterable(sig, opts) {
     }
     const abortSig    = (opts !== undefined && opts !== null) ? opts.signal      : undefined;
     const emitInitial = (opts !== undefined && opts !== null && opts.emitInitial === false) ? false : true;
-    const maxBuffer   = (opts !== undefined && opts !== null && opts.maxBuffer !== undefined) ? opts.maxBuffer : 1024;
+    const filter      = (opts !== undefined && opts !== null) ? opts.filter      : undefined;
+    const timeoutMs   = (opts !== undefined && opts !== null) ? opts.timeout     : undefined;
+    const modeOpt     = (opts !== undefined && opts !== null) ? opts.mode        : undefined;
+    const maxBufferOpt = (opts !== undefined && opts !== null) ? opts.maxBuffer  : undefined;
+
+    // Mode. Default "buffer" preserves 1.0.0 behavior.
+    let mode;
+    if (modeOpt === undefined || modeOpt === "buffer") {
+        mode = "buffer";
+    } else if (modeOpt === "latest") {
+        mode = "latest";
+    } else {
+        throw new TypeError(
+            "lite-stream: opts.mode must be \"latest\" or \"buffer\" (got " + JSON.stringify(modeOpt) + ")"
+        );
+    }
+    const isLatestWins = mode === "latest";
 
-    if (typeof maxBuffer !== "number" || !Number.isFinite(maxBuffer) || maxBuffer < 1 || (maxBuffer | 0) !== maxBuffer) {
-        throw new RangeError(
-            "lite-stream: opts.maxBuffer must be a positive integer (got " + JSON.stringify(maxBuffer) + ")"
+    // maxBuffer only meaningful in buffer mode. Combining latest + maxBuffer
+    // is user error; silently ignoring one would hide the mistake.
+    if (isLatestWins && maxBufferOpt !== undefined) {
+        throw new TypeError(
+            "lite-stream: opts.maxBuffer is not allowed with mode: \"latest\" -- latest-wins uses a single slot"
         );
     }
+    const maxBuffer = maxBufferOpt !== undefined ? maxBufferOpt : 1024;
+    if (!isLatestWins) {
+        if (typeof maxBuffer !== "number" || !Number.isFinite(maxBuffer) || maxBuffer < 1 || (maxBuffer | 0) !== maxBuffer) {
+            throw new RangeError(
+                "lite-stream: opts.maxBuffer must be a positive integer (got " + JSON.stringify(maxBuffer) + ")"
+            );
+        }
+    }
 
-    const queue   = new Array(maxBuffer);
-    let qHead     = 0;
-    let qLen      = 0;
-    let droppedCount = 0;
-    let pendingResolve = null;
+    if (filter !== undefined && typeof filter !== "function") {
+        throw new TypeError("lite-stream: opts.filter must be a function");
+    }
+    if (timeoutMs !== undefined) {
+        if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
+            throw new RangeError(
+                "lite-stream: opts.timeout must be a finite non-negative number (got " + JSON.stringify(timeoutMs) + ")"
+            );
+        }
+    }
+
+    // --- State ---
+    // Buffer-mode ring (unchanged from 1.0.0 layout); null in latest mode.
+    const queue = isLatestWins ? null : new Array(maxBuffer);
+    let qHead   = 0;
+    let qLen    = 0;
+    // Latest-mode slot.
+    let pendingValue;
+    let hasPending = false;
+    // Overflow. `droppedCount` and `overflowCount` are aliases for the same
+    // counter; 1.0.0 exposed `droppedCount`, 1.1 adds `overflowCount` as the
+    // mode-neutral vocabulary. Both getters read this variable.
+    let overflowCount = 0;
+    // Multi-waiter FIFO queue (fixes the 1.0.0 single-slot bug where
+    // concurrent .next() calls silently lost the first resolver).
+    const waiters = [];
+    // Termination
     let done = false;
+    let firstNextErr = null;      // stashed for the next .next() when no waiter was pending
+    // Cleanup handles
     let unsubscribe = null;
+    let unsubscribePending = false;
     let abortListener = null;
-
-    function enqueue(v) {
-        if (done) return;
-        if (pendingResolve !== null) {
-            const r = pendingResolve;
-            pendingResolve = null;
-            r({ value: v, done: false });
-            return;
-        }
-        if (qLen < maxBuffer) {
-            queue[(qHead + qLen) % maxBuffer] = v;
-            qLen = (qLen + 1) | 0;
+    let timeoutId = null;
+
+    // Late-binding unsubscribe: needed when a throwing filter (or throwing
+    // subscription callback body) fires during the synchronous initial
+    // subscribe call, at which point `unsubscribe` is still null. Mirror of
+    // lite-await's stop/stopPending pattern.
+    function doUnsubscribe() {
+        if (unsubscribe !== null) {
+            unsubscribe();
+            unsubscribe = null;
         } else {
-            // Drop oldest.
-            queue[qHead] = v;
-            qHead = (qHead + 1) % maxBuffer;
-            droppedCount = (droppedCount + 1) | 0;
+            unsubscribePending = true;
         }
     }
 
-    function teardown() {
-        if (done) return;
-        done = true;
-        if (unsubscribe !== null) { unsubscribe(); unsubscribe = null; }
+    function fullCleanup() {
+        doUnsubscribe();
+        if (timeoutId !== null) {
+            clearTimeout(timeoutId);
+            timeoutId = null;
+        }
         if (abortListener !== null && abortSig !== undefined && abortSig !== null) {
             abortSig.removeEventListener("abort", abortListener);
             abortListener = null;
         }
-        if (pendingResolve !== null) {
-            const r = pendingResolve;
-            pendingResolve = null;
-            r({ value: undefined, done: true });
+        // Release unread values so they can be GC'd before the iterable
+        // object itself is. One-time cost per iterable lifetime.
+        pendingValue = undefined;
+        hasPending = false;
+        if (queue !== null) {
+            for (let i = 0; i < maxBuffer; i = (i + 1) | 0) queue[i] = undefined;
+            qHead = 0;
+            qLen  = 0;
         }
     }
 
-    if (abortSig !== undefined && abortSig !== null) {
-        if (abortSig.aborted) {
-            done = true;
+    // Termination via error: reject all pending waiters, or stash for the
+    // next .next() call. Route for timeout and throwing-filter paths.
+    function terminateWithError(err) {
+        if (done) return;
+        done = true;
+        fullCleanup();
+        if (waiters.length > 0) {
+            while (waiters.length > 0) {
+                const w = waiters.shift();
+                w.reject(err);
+            }
         } else {
-            abortListener = function () { teardown(); };
-            abortSig.addEventListener("abort", abortListener);
+            firstNextErr = err;
         }
     }
 
-    // Subscribe to signal changes. lite-signal's subscribe fires once
-    // synchronously with the current value when called; we use a flag to
-    // suppress that initial fire if emitInitial is false.
-    let suppressedInitial = !emitInitial;
-    if (!done) {
-        unsubscribe = sig.subscribe(function (v) {
-            if (suppressedInitial) { suppressedInitial = false; return; }
-            enqueue(v);
-        });
+    // Termination via done (abort, natural end via consumer return()): resolve
+    // pending waiters with {done: true}. Preserves 1.0.0 abort-is-graceful
+    // behavior (mid-iteration abort ends for-await without throw).
+    function terminateAsDone() {
+        if (done) return;
+        done = true;
+        fullCleanup();
+        while (waiters.length > 0) {
+            const w = waiters.shift();
+            w.resolve({ value: undefined, done: true });
+        }
     }
 
+    function enqueue(v) {
+        if (done) return;
+        // Deliver directly to the oldest waiter if any.
+        if (waiters.length > 0) {
+            const w = waiters.shift();
+            w.resolve({ value: v, done: false });
+            return;
+        }
+        // Otherwise stash in the mode-appropriate structure.
+        if (isLatestWins) {
+            if (hasPending) overflowCount = (overflowCount + 1) | 0;
+            pendingValue = v;
+            hasPending = true;
+        } else {
+            if (qLen < maxBuffer) {
+                queue[(qHead + qLen) % maxBuffer] = v;
+                qLen = (qLen + 1) | 0;
+            } else {
+                // Drop oldest.
+                queue[qHead] = v;
+                qHead = (qHead + 1) % maxBuffer;
+                overflowCount = (overflowCount + 1) | 0;
+            }
+        }
+    }
+
+    // --- Iterable object ---
     const iterable = {
         [Symbol.asyncIterator]() { return this; },
         next() {
-            if (qLen > 0) {
+            if (done) {
+                if (firstNextErr !== null) {
+                    const err = firstNextErr;
+                    firstNextErr = null;
+                    return Promise.reject(err);
+                }
+                return Promise.resolve({ value: undefined, done: true });
+            }
+            // Value available in slot / ring?
+            if (isLatestWins && hasPending) {
+                const v = pendingValue;
+                pendingValue = undefined;
+                hasPending = false;
+                return Promise.resolve({ value: v, done: false });
+            }
+            if (!isLatestWins && qLen > 0) {
                 const v = queue[qHead];
                 queue[qHead] = undefined;
                 qHead = (qHead + 1) % maxBuffer;
                 qLen = (qLen - 1) | 0;
                 return Promise.resolve({ value: v, done: false });
             }
-            if (done) return Promise.resolve({ value: undefined, done: true });
-            return new Promise(function (resolve) { pendingResolve = resolve; });
+            // Nothing available -- queue a waiter.
+            return new Promise(function (resolve, reject) {
+                waiters.push({ resolve: resolve, reject: reject });
+            });
         },
         return(value) {
-            teardown();
+            if (done) return Promise.resolve({ value: undefined, done: true });
+            terminateAsDone();
             return Promise.resolve({ value: value, done: true });
         },
         throw(err) {
-            teardown();
+            if (done) return Promise.reject(err);
+            // Consumer-driven throw: pending waiters reject with the error,
+            // subsequent next() returns done. Same shape as terminateWithError
+            // but without stashing (throw() call site gets its own rejection).
+            done = true;
+            fullCleanup();
+            while (waiters.length > 0) {
+                const w = waiters.shift();
+                w.reject(err);
+            }
             return Promise.reject(err);
         },
-        get droppedCount() { return droppedCount; }
+        get droppedCount() { return overflowCount; },
+        get overflowCount() { return overflowCount; }
     };
 
+    if (ASYNC_DISPOSE !== null) {
+        iterable[ASYNC_DISPOSE] = function () { return iterable.return(); };
+    }
+
+    // --- Pre-aborted signal: mark done, skip all subscription/timer setup.
+    // Matches 1.0.0 behavior: first next() resolves with {done: true} rather
+    // than rejecting. ---
+    if (abortSig !== undefined && abortSig !== null && abortSig.aborted) {
+        done = true;
+        return iterable;
+    }
+
+    // --- Timeout setup ---
+    if (timeoutMs !== undefined) {
+        timeoutId = setTimeout(function () {
+            terminateWithError(new TimeoutError(timeoutMs));
+        }, timeoutMs);
+    }
+
+    // --- AbortSignal listener ---
+    if (abortSig !== undefined && abortSig !== null) {
+        abortListener = function () { terminateAsDone(); };
+        abortSig.addEventListener("abort", abortListener);
+    }
+
+    // --- Subscribe. lite-signal's subscribe fires synchronously with the
+    // current value on registration; use a flag to suppress that initial
+    // fire if emitInitial is false. Filter (if provided) applies to the
+    // initial fire when emitInitial is true. A throwing filter is routed
+    // via terminateWithError so the throw never surfaces at the signal
+    // writer's .set() call site. ---
+    let suppressedInitial = !emitInitial;
+    unsubscribe = sig.subscribe(function (v) {
+        if (done) return;
+        if (suppressedInitial) { suppressedInitial = false; return; }
+        if (filter !== undefined) {
+            let ok;
+            try {
+                ok = filter(v);
+            } catch (e) {
+                terminateWithError(e);
+                return;
+            }
+            if (!ok) return;
+        }
+        enqueue(v);
+    });
+
+    // If terminateWithError was called from inside the synchronous initial
+    // subscribe fire (throwing filter on the initial value), honor the
+    // deferred unsubscribe now that we have the handle.
+    if (unsubscribePending && unsubscribe !== null) {
+        unsubscribe();
+        unsubscribe = null;
+    }
+
     return iterable;
 }
 
@@ -635,5 +870,6 @@ function toAsyncIterable(sig, opts) {
 export {
     fromAsyncIterable,
     pipeToSignal,
-    toAsyncIterable
+    toAsyncIterable,
+    TimeoutError
 };