@zakkster/lite-stream 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,104 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 1.1.0 -- 2026-07-10
+
+**Additive `toAsyncIterable` enrichment.** Six additions, no breaking
+changes. All 1.0.0 callers continue to work without modification. See
+ROADMAP.md's "Shipped in 1.1.0" section for the triggering signals that
+justified each addition.
+
+### Added
+
+- **`mode: "latest" | "buffer"`** on `toAsyncIterable`. Default `"buffer"`
+  preserves 1.0.0 behavior. `mode: "latest"` uses a single mutable slot
+  (producer overwrites; consumer reads and clears; every overwrite bumps
+  `overflowCount`). Combining `mode: "latest"` with `maxBuffer` throws
+  `TypeError` at construction -- silently ignoring one would hide user
+  error.
+
+- **`filter: (v) => unknown`** on `toAsyncIterable`. Skip values for which
+  the predicate returns falsy. Applied to the initial value when
+  `emitInitial` is `true`. A throwing filter rejects the current pending
+  `next()` with the thrown value and terminates the iterable; the throw
+  does NOT surface at the signal writer's `.set()` call site.
+
+- **`timeout: number`** on `toAsyncIterable`. Overall deadline in ms from
+  the `toAsyncIterable(...)` call (not per-`next()`, not idle). On elapse
+  the pending `next()` rejects with `TimeoutError`; subsequent calls
+  return `{done: true}`. Negative or non-finite values throw `RangeError`
+  at construction.
+
+- **`TimeoutError`** as a new named export. Structurally identical to
+  `@zakkster/lite-await`'s `TimeoutError` (`e.name === "TimeoutError"`
+  duck-checks work across both packages). NOT imported from lite-await --
+  zero runtime dependencies preserved.
+
+- **`Symbol.asyncDispose`** on the `toAsyncIterable` return object (Node
+  20+ only; absent on older runtimes). Delegates to `iter.return()`.
+  Enables `await using iter = toAsyncIterable(sig, { mode: "latest" })`.
+
+- **`overflowCount`** getter on the `toAsyncIterable` return object.
+  Alias for `droppedCount` with mode-neutral vocabulary. In
+  `mode: "buffer"` reads the same value as `droppedCount` (drop-oldest
+  count); in `mode: "latest"` counts every slot overwrite.
+
+### Changed (invisible correctness fix)
+
+- **Multi-waiter FIFO queue** replaces `toAsyncIterable`'s 1.0.0
+  single-slot `pendingResolve`. Concurrent `.next()` calls (e.g. from
+  `Promise.all([iter.next(), iter.next()])`) now resolve in FIFO order.
+  1.0.0 silently overwrote the first resolver, causing the first
+  `.next()` to never settle. Invisible to correct callers; unblocks
+  `Promise.all`-style consumers.
+
+### Not changed
+
+- `fromAsyncIterable`, `pipeToSignal` -- unchanged behavior, unchanged
+  types, unchanged bench numbers.
+- `toAsyncIterable`'s default behavior (with no `mode` opt) exactly
+  matches 1.0.0. Every 1.0.0 test in `05-to-async-iterable.test.mjs`
+  continues to pass without modification.
+- Peer dependency remains `@zakkster/lite-signal ^1.2.0`. Node engines
+  requirement unchanged (>=18); `Symbol.asyncDispose` is feature-detected
+  and gracefully absent on Node 18/19.
+
+### Performance (Node v22, --expose-gc, 500ms runs)
+
+1.1 additions:
+- `to-async-iterable-latest-1to1-x10`: **119K ops/s** (~2.4M ops/s per
+  operation), 0.12 B/op retained
+- `to-async-iterable-latest-churn-100`: **60K ops/s** (~6M writes/s
+  absorbed into single slot), 0.28 B/op retained
+- `to-async-iterable-filter-timeout`: **141K ops/s**, NEGATIVE retained
+  heap (timer-clear discipline helps V8 reclaim more than baseline)
+- `to-async-iterable-multi-waiter-x3`: **120K ops/s**, negative retained
+
+1.0.0 scenarios: unchanged from 1.0.0 numbers.
+
+### Testing
+
+74 tests across 7 files (up from 49 in 1.0.0):
+- `01`-`04`: `fromAsyncIterable`, `pipeToSignal`, cleanup triplet
+  (unchanged)
+- `05-to-async-iterable.test.mjs` -- 10 tests, unchanged 1.0.0 behavior
+- `06-gc.test.mjs` -- 8 heap-budget tests (up from 3): 1.0.0 paths +
+  5 new 1.1 paths at 2 MB budget
+- `07-to-async-iterable-rich.test.mjs` (NEW) -- 25 tests covering the
+  six 1.1 additions
+
+All 74 tests pass under both `npm test` and `npm run test:gc`.
+
+### Bundle
+
+- ~7 KB minified (up from ~5 KB), ~3 KB gzipped
+- ESM-only, Node >= 18 (with `Symbol.asyncDispose` on 20+)
+- Single file `Stream.js`
+- Zero runtime dependencies
+- Peer dep: `@zakkster/lite-signal ^1.2.0` (unchanged)
+
+---
+
 ## 1.0.0 -- 2026-06-23
 
 **Initial public release.** API frozen; subsequent 1.x releases are purely

package/README.md

@@ -190,10 +190,19 @@ toAsyncIterable<T>(
     sig: Signal<T> | Computed<T>,
     opts?: {
         signal?:      AbortSignal,
-        emitInitial?: boolean,    // default true
-        maxBuffer?:   number      // default 1024
+        emitInitial?: boolean,               // default true
+        maxBuffer?:   number,                // default 1024 (buffer mode)
+
+        // Added in 1.1
+        mode?:        "latest" | "buffer",   // default "buffer"
+        filter?:      (v: T) => unknown,
+        timeout?:     number
     }
-): AsyncIterable<T> & { readonly droppedCount: number }
+): AsyncIterable<T> & {
+    readonly droppedCount:  number,
+    readonly overflowCount: number,          // 1.1 alias for droppedCount
+    [Symbol.asyncDispose]?: () => Promise<IteratorResult<T, undefined>>
+}
 ```
 
 The reverse direction -- yield signal changes as an async iterable. Useful
@@ -201,12 +210,41 @@ when you have signal-driven state and want to pipe its changes into a
 WebSocket, log sink, replay tool, or any consumer that wants for-await
 semantics.
 
-Internal queue is bounded (default 1024). On overflow, the OLDEST value is
-dropped and `iterable.droppedCount` increments. The iterator naturally
-completes when `opts.signal` aborts; consumer-side `break` triggers
-`iterator.return()`.
-
-Treat this as the secondary API. Most consumers want the forward direction.
+**Two backpressure modes:**
+
+- `"buffer"` (default; matches 1.0.0) -- FIFO ring buffer of `maxBuffer`
+  size. On overflow the OLDEST value is dropped and `droppedCount` (and
+  `overflowCount`) increments. Use when every value matters and must be
+  seen in order.
+- `"latest"` (1.1) -- single mutable slot. Producer overwrites; consumer
+  reads and clears. Every overwrite bumps `overflowCount`. Use for
+  reactive-state consumers ("show the current frame / latest cursor /
+  live price") where intermediate values can be safely discarded.
+
+**1.1 additions worth calling out:**
+
+- `filter` -- skip values for which the predicate returns falsy. A
+  throwing filter rejects the current pending `next()` and terminates
+  the iterable; the throw does NOT surface at the signal writer's
+  `.set()` call site.
+- `timeout` -- overall deadline in ms; on elapse the pending `next()`
+  rejects with `TimeoutError` (a new named export in 1.1). Subsequent
+  calls return `{done: true}`.
+- `Symbol.asyncDispose` -- delegates to `iter.return()` on Node 20+;
+  enables `await using iter = toAsyncIterable(sig, { mode: "latest" })`.
+- Multi-waiter queue -- concurrent `.next()` calls (e.g. from
+  `Promise.all([iter.next(), iter.next()])`) now resolve in FIFO order.
+  In 1.0.0 the second call silently overwrote the first resolver; the
+  1.1 fix is invisible to correct callers.
+
+The iterator naturally completes when `opts.signal` aborts; consumer-side
+`break` triggers `iterator.return()`. `mode: "latest"` combined with
+`maxBuffer` is rejected with `TypeError` at construction -- a single-slot
+mode plus a buffer size is a user error worth surfacing loudly.
+
+Treat this as the secondary API for classic "consume signal changes"
+patterns; for the streaming pipeline case (paginated APIs, SSE, pubsub)
+the forward direction is what most consumers want.
 
 ## Modes: latest vs buffer
 
@@ -216,6 +254,8 @@ Pick `"latest"` when you only care about the most recent value:
 - Current pubsub message
 - Latest network frame
 - Current SSE event
+- Reactive state bridged into `@zakkster/lite-query`'s `streamQuery`
+  (matches its `mode: "latest"` on the forward direction)
 
 Pick `"buffer"` when every value matters and you want them in order:
 
@@ -223,16 +263,44 @@ Pick `"buffer"` when every value matters and you want them in order:
 - EBS SSE event log (must not miss an event)
 - Replay queue (every frame applies in order)
 
-**`"buffer"` mode requires `maxBuffer`.** There is no default, and missing
-the option throws a `RangeError` with this message:
+**Availability:**
+- `fromAsyncIterable` has both modes from 1.0.0.
+- `toAsyncIterable` has both modes from 1.1 (was `"buffer"`-only in 1.0.0;
+  the option was added as `mode: "latest"` while preserving default
+  behavior).
+
+**`"buffer"` mode requires `maxBuffer` on `fromAsyncIterable`.** There is
+no default there, and missing the option throws a `RangeError` with this
+message:
 
 > `lite-stream: "buffer" mode requires opts.maxBuffer to be a positive
 > integer. Unbounded buffering is a memory bug pretending to be a feature;
 > pick a deliberate ceiling.`
 
-On overflow, the OLDEST value is dropped and `droppedCount` increments.
-Watch `droppedCount` in your effect to know when your consumer is falling
-behind.
+`toAsyncIterable`'s `"buffer"` mode defaults `maxBuffer` to 1024
+(unchanged in 1.1). On overflow the OLDEST value is dropped and
+`droppedCount` increments. Watch `droppedCount` in your effect to know
+when your consumer is falling behind.
+
+**streamQuery integration** (matching vocabulary on both directions):
+
+```js
+import { toAsyncIterable } from "@zakkster/lite-stream";
+import { streamQuery } from "@zakkster/lite-query/stream";
+
+streamQuery(qc, {
+    key: ["price", ticker],
+    stream: ({ signal }) => toAsyncIterable(priceSig, {
+        signal,
+        mode: "latest"                     // matches streamQuery's mode
+    }),
+    mode: "latest"
+});
+```
+
+The `signal` from the stream context wires straight through: streamQuery
+aborts on detach, `toAsyncIterable` catches the abort and calls
+`return()`. Zero glue code.
 
 ## Zero-GC hot paths
 
@@ -433,6 +501,20 @@ Run via `npm run bench` (requires `--expose-gc`).
 
 [6] toAsyncIterable -- producer overflow, drop-oldest
   to-async-iterable-overflow            62,164 ops/s   retained: ~25 B/op
+
+--- 1.1 additions ---
+
+[7] toAsyncIterable mode:latest -- 10 write/next pairs per cycle
+  to-async-iterable-latest-1to1-x10    119,278 ops/s   retained:  0.12 B/op
+
+[8] toAsyncIterable mode:latest -- 100 writes coalesced, single read
+  to-async-iterable-latest-churn-100    60,674 ops/s   retained:  0.28 B/op
+
+[9] toAsyncIterable filter + timeout -- consumer wins before timeout
+  to-async-iterable-filter-timeout     141,080 ops/s   retained: -11.80 B/op
+
+[10] toAsyncIterable multi-waiter -- 3 concurrent next() calls
+  to-async-iterable-multi-waiter-x3    120,020 ops/s   retained: -0.01 B/op
 ```
 
 (Node v22, 150ms warmup, 500ms runs.)
@@ -442,11 +524,19 @@ in latest mode runs at 178K ops/s with sub-byte/op retained heap. Per-pull
 allocation is dominated by the iterator's own microtask cost, not by
 lite-stream's wrapper state.
 
+1.1's `toAsyncIterable mode:"latest"` amortizes to ~2.4M ops/s per operation
+(divide the reported cycle rate by the inner loop count). The filter+timeout
+scenario `[9]` runs at 141K ops/s with NEGATIVE retained heap -- the
+timer-clear discipline on `iter.return()` lets V8's subsequent GC pass
+reclaim more than the pre-run measurement. The multi-waiter scenario `[10]`
+confirms the 1.0.0 latent-bug fix (single-slot `pendingResolve` overwriting
+the first resolver) works cleanly under bench load.
+
 ## Testing strategy
 
 ### Tier 1 -- behavior (unit tests, fast)
 
-49 tests across `test/01-*` through `test/06-*`:
+74 tests across `test/01-*` through `test/07-*`:
 
 - `01-from-async-iterable-latest.test.mjs` -- state shape, lifecycle,
   Iterable acceptance variants, pre-aborted, subscriber observability
@@ -456,23 +546,28 @@ lite-stream's wrapper state.
   return() invocation, abort reason propagation, 200-cycle leak smoke test
 - `04-pipe-to-signal.test.mjs` -- target write, stop fn idempotency,
   transform, abort behavior, target-not-disposed invariant
-- `05-to-async-iterable.test.mjs` -- emitInitial, ordering, overflow,
-  consumer break triggers return(), pre-aborted path
+- `05-to-async-iterable.test.mjs` -- 1.0.0 behavior: emitInitial, ordering,
+  overflow, consumer break triggers return(), pre-aborted path
+- `07-to-async-iterable-rich.test.mjs` (1.1) -- `mode:"latest"` behavior,
+  filter (including throwing-filter no-writer-surface discipline), timeout
+  + TimeoutError, Symbol.asyncDispose (Node 20+ guarded), multi-waiter
+  queue, `overflowCount` alias, 4K structural cleanup cycles
 
 Run via `npm test`.
 
 ### Tier 2 -- memory (allocation-free verification)
 
 `test/06-gc.test.mjs` -- runs under `--expose-gc`. Asserts heap budget
-ceilings for 2K latest cycles (< 2 MB), 1K buffer cycles (< 2 MB), and
-1K abort cycles (< 2 MB).
+ceilings at 2 MB for the 1.0.0 paths (2K latest, 1K buffer, 1K abort) and
+the 1.1 additions (5K `mode:"latest"` resolve, 3K timeout, 1K buffer
+fill+drain, 2K `mode:"latest"` churn, 2K filter-throw).
 
 Run via `npm run test:gc`.
 
 ### Tier 3 -- performance (measured throughput)
 
-`bench/bench.mjs` -- six scenarios; throughput and B/op retained. Run via
-`npm run bench`.
+`bench/bench.mjs` -- ten scenarios (six 1.0.0 + four 1.1); throughput and
+B/op retained. Run via `npm run bench`.
 
 ## What this is not
 

package/ROADMAP.md

@@ -15,6 +15,49 @@ triggering signal."
 
 ---
 
+## Shipped in 1.1.0 -- toAsyncIterable enrichment
+
+The six additions below landed together in 1.1.0. Each is documented with
+the triggering signal that justified moving it out of "deferred" status.
+
+### `mode: "latest" | "buffer"` (default `"buffer"`)
+**Triggering signal:** vocabulary mismatch with `@zakkster/lite-query`'s
+`streamQuery`, which already offers `mode: "latest"` on its
+`fromAsyncIterable` side. Bridging a signal INTO streamQuery via
+`toAsyncIterable` needed a matching option. Twitch overlay reactive-state
+use ("show current frame, not the backlog") is the second consumer.
+
+### `filter` option
+**Triggering signal:** per-value gating was previously done with async-
+generator wrappers around `toAsyncIterable`. In hot-path use (reactive
+state filtered by predicate) the wrapper adds an allocation per yield.
+Inlining the filter into the subscription callback removes the wrapper
+cost.
+
+### `timeout` option + new `TimeoutError` export
+**Triggering signal:** consumers wrap `toAsyncIterable` with external
+`AbortController` + `setTimeout` boilerplate today. Native `timeout` opt
+saves ~10 lines per usage. `TimeoutError` is structurally identical to
+lite-await's class (`e.name === "TimeoutError"` duck-checks work across
+both packages), NOT imported from lite-await -- zero-dep story preserved.
+
+### `Symbol.asyncDispose` on Node 20+
+**Triggering signal:** Node 20 shipped, `await using` is idiomatic modern
+async-iterator ergonomics. Absent on older runtimes; `iter.return()`
+remains the portable path.
+
+### Multi-waiter FIFO queue (latent bug fix)
+**Triggering signal:** correctness. `Promise.all([iter.next(),
+iter.next()])` silently lost the first resolver in 1.0.0 (single-slot
+`pendingResolve`). Async generators queue concurrent .next() calls; ours
+now does too. Invisible fix for correct callers; unblocks
+`Promise.all`-style consumers.
+
+### `overflowCount` getter (alias for `droppedCount`)
+**Triggering signal:** vocabulary consistency with `mode: "latest"`.
+"Dropped" reads as FIFO-specific; "overflow" is mode-neutral.
+`droppedCount` continues to work identically in both modes.
+
 ## 1.1.0 candidates
 
 ### Concurrent mapping (`mapLimit`)
@@ -40,16 +83,21 @@ identical "transform-with-concurrency-limit" wrappers around
 
 ---
 
-### Reverse-direction buffering modes
+### Reverse-direction buffering overflow policies
 
-`toAsyncIterable` currently only does drop-oldest on overflow. Some
-consumers might want:
+`toAsyncIterable` in `mode: "buffer"` currently only does drop-oldest on
+overflow. Some consumers might want:
 
 - `overflow: "drop-newest"` -- reject incoming when full
 - `overflow: "throw"` -- iterator throws on overflow
 - `overflow: "block"` -- producer-side signal back-channel (requires
   consumer cooperation; significant API change)
 
+**Not to be confused with `mode: "latest"`** (shipped in 1.1), which is a
+different backpressure MODEL -- single-slot overwrite semantics rather
+than a bounded FIFO with a different overflow policy. See the "Shipped in
+1.1.0" section above.
+
 **Why deferred from 1.0:** Drop-oldest is the only mode any real consumer
 in the roadmap actually wants. Adding alternatives speculatively grows the
 API surface for no measurable benefit.

package/Stream.js

@@ -1,4 +1,4 @@
-// @zakkster/lite-stream 1.0.0
+// @zakkster/lite-stream 1.1.0
 //
 // 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,38 @@
 //     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
+// CONTRACT-toAsyncIterable-1.1.md and CHANGELOG.md 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.
+ *
+ * The wiring (start / clear / reject with) is Session B's territory; this
+ * class exists in Session A only so the exported shape is stable and the
+ * failing test suite can compile.
+ */
+class TimeoutError extends Error {
+    constructor(timeoutMs) {
+        super("lite-stream: timed out after " + timeoutMs + "ms");
+        this.name = "TimeoutError";
+        this.timeout = timeoutMs;
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
@@ -498,31 +525,54 @@ 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 CONTRACT-toAsyncIterable-1.1.md 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 +580,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 +857,6 @@ function toAsyncIterable(sig, opts) {
 export {
     fromAsyncIterable,
     pipeToSignal,
-    toAsyncIterable
+    toAsyncIterable,
+    TimeoutError
 };

package/llms.txt

@@ -14,7 +14,7 @@ Peer dep: `@zakkster/lite-signal ^1.2.0`.
 
 ## Imports
 
-    import { fromAsyncIterable, pipeToSignal, toAsyncIterable } from "@zakkster/lite-stream";
+    import { fromAsyncIterable, pipeToSignal, toAsyncIterable, TimeoutError } from "@zakkster/lite-stream";
 
 ## Exports
 
@@ -63,23 +63,60 @@ const stop = pipeToSignal(source, targetSig, {
 
 Does NOT dispose the target signal. The caller owns its lifetime.
 
-### `toAsyncIterable(sig, opts?) -> AsyncIterable<T> & { droppedCount }`
+### `toAsyncIterable(sig, opts?) -> AsyncIterable<T> & { droppedCount, overflowCount }`
 
-Reverse direction: yield signal changes as an async iterable. Bounded
-internal queue (default 1024) with drop-oldest overflow.
+Reverse direction: yield signal changes as an async iterable.
+
+**1.0.0 shape (still the default):** bounded FIFO ring buffer, drop-oldest
+overflow, `droppedCount` observable.
+
+**1.1 additions (all opt-in, no default changes):**
+- `mode: "latest"` -- single-slot overwrite semantics; use for reactive
+  state / "current frame" style consumers
+- `filter` -- per-value gate; throwing filter rejects pending next() and
+  terminates (no writer surface)
+- `timeout` -- overall deadline; pending next() rejects with `TimeoutError`
+- `Symbol.asyncDispose` on Node 20+ -- enables `await using iter = ...`
+- `overflowCount` -- alias for `droppedCount`, mode-neutral vocabulary
+- Multi-waiter queue -- concurrent .next() calls resolve in FIFO order
+  (1.0.0 silently overwrote the first resolver)
 
 ```js
+// 1.0.0-style: bounded FIFO buffer (default)
 for await (const v of toAsyncIterable(sig, {
     signal: abortCtrl.signal,
-    emitInitial: true,                  // default true
-    maxBuffer: 1024                     // default 1024
+    emitInitial: true,                    // default true
+    maxBuffer: 1024                       // default 1024
+})) {
+    // ...
+}
+
+// 1.1: latest-wins slot for reactive state
+for await (const v of toAsyncIterable(sig, {
+    mode: "latest",                       // opt in to single-slot overwrite
+    filter: (v) => v.priority > 0,
+    timeout: 5000                         // overall deadline
 })) {
     // ...
 }
 ```
 
-The iterator naturally completes when `opts.signal` aborts. Consumer-side
-`break` triggers `iterator.return()` and cleans up the subscription.
+Constraints:
+- `mode: "latest"` + `maxBuffer` throws TypeError (single slot has no buffer size)
+- Negative or non-finite `timeout` throws RangeError
+- Non-function `filter` throws TypeError
+
+The iterator naturally completes when `opts.signal` aborts (resolves as
+done, not rejection -- graceful termination). Consumer-side `break`
+triggers `iterator.return()` and cleans up. `timeout` elapsing rejects
+the pending next() with `TimeoutError`; subsequent calls return done.
+
+### `TimeoutError` (added 1.1)
+
+Thrown when the `timeout` option on `toAsyncIterable` elapses.
+Structurally identical to `@zakkster/lite-await`'s TimeoutError so
+`e.name === "TimeoutError"` duck-checks work across both packages. Not
+imported from lite-await -- lite-stream stays zero-dep.
 
 ## Cleanup termination triplet
 
@@ -188,18 +225,49 @@ states: {
 - Not a replacement for lite-clock for frame-rate loops.
 - Not for one-shot promises -- use lite-await's `fromPromise`.
 
+## Anti-patterns
+
+- DO NOT combine `mode: "latest"` with `maxBuffer` on `toAsyncIterable`.
+  It throws TypeError at construction -- a single-slot mode with a buffer
+  size is user error. Pick one or the other.
+- DO NOT reach for lite-stream for one-shot Signal<->Promise coordination.
+  That is `@zakkster/lite-await`'s job (`whenSignal`, `fromPromise`,
+  `allOf`/`anyOf`/`raceOf`). lite-stream owns the AsyncIterable boundary;
+  lite-await owns the Promise boundary.
+- DO NOT wrap `toAsyncIterable` with an async-generator debounce / throttle
+  for reactive-state use cases. Use `mode: "latest"` directly -- it
+  already gives you "consume newest, discard intermediates" semantics with
+  zero per-value allocation.
+- DO NOT rely on the value passed to `iter.return(value)` reaching pending
+  waiters. Pending `next()` calls resolve with `{value: undefined, done:
+  true}` per the async iteration protocol; only `return()`'s own returned
+  Promise carries the value.
+- DO NOT dispose the source signal while an iterable is still consuming
+  from it. Call `iter.return()` first; disposing an in-flight source is
+  undefined behavior.
+
 ## Performance
 
-178K ops/s for the full lifecycle in latest mode (construct + pull + settle
-+ dispose), sub-byte/op retained heap. 235K ops/s for pipeToSignal direct.
-84K ops/s for the full abort cycle.
+178K ops/s for the full lifecycle in `fromAsyncIterable` latest mode
+(construct + pull + settle + dispose), sub-byte/op retained heap. 235K
+ops/s for `pipeToSignal` direct. 84K ops/s for the full abort cycle.
+
+1.1 `toAsyncIterable` throughput (Node v22, 500ms runs):
+- `mode: "latest"` 1:1 alternation: 119K cycles/s (2.4M ops/s per pair)
+- `mode: "latest"` churn (100 writes coalesced): 60K cycles/s (6M
+  writes/s absorbed into the single slot)
+- `filter + timeout`: 141K ops/s, negative retained (the timer-clear
+  discipline on `iter.return()` helps V8 reclaim more than baseline)
+- multi-waiter x3 concurrent .next(): 120K cycles/s
 
-Per-yield, latest mode allocates one wrapper state object. Buffer mode
-adds one snapshot array per yield. Ring beneath is fixed pre-allocated.
+Per-yield, `fromAsyncIterable` latest mode allocates one wrapper state
+object; buffer mode adds one snapshot array. `toAsyncIterable` `mode:
+"latest"` allocates zero on the steady-state hot path when the consumer
+is caught up; `mode: "buffer"` also zero when no waiter is pending.
 
 ## Files
 
-- `Stream.js` -- single-file ESM implementation (~600 lines)
+- `Stream.js` -- single-file ESM implementation (~830 lines)
 - `Stream.d.ts` -- TypeScript types with discriminated state union
 - `README.md` -- full docs with integration recipes
 - `llms.txt` -- this file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-stream",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Zero-GC bridge between async iterators and @zakkster/lite-signal. Project async streams (paginated APIs, SSE, network frames, pubsub topics) into signals. Bounded buffering with explicit overflow diagnostics, structural cleanup on three termination paths (iterator done, abort, dispose). The multi-shot dual of lite-await's fromPromise.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",