@zakkster/lite-stream 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -7,6 +7,159 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## 1.1.1 -- 2026-09-01
+
+**Truth patch. No API change, no behavior change; the `Stream.js` diff is
+comment-only.** Every shipped sentence the runnable probes could refute is
+corrected, and the previously dark GC tier now gates on the default test run.
+
+### Fixed
+
+- **dispose-teardown claim (LS-01)** -- llms.txt, README, the `Stream.js`
+  `fromAsyncIterable` docstring, and the `package.json` description all
+  claimed the pump detects a disposed result signal on the next `sig.set()`
+  and cleans up silently. It never did: `set()` after `dispose()` is a
+  silent no-op in lite-signal 1.2.2 and 1.5.0, so the pump keeps pulling and
+  neither `iterator.return()` nor any callback fires. Corrected to the true
+  behavior -- AbortSignal or natural completion are the only stop mechanisms.
+  The defensive `catch` around `set()` and its comment were re-framed
+  accordingly.
+- **phantom contract doc + session narrative (LS-06)** -- three references
+  to a non-existent `CONTRACT-toAsyncIterable-1.1.md` (in `Stream.js` and
+  `test/07-to-async-iterable-rich.test.mjs`) and the "Session A/Session B"
+  development narrative were removed; the locked 1.1 semantics now point at
+  CHANGELOG.md [1.1.0] and llms.txt.
+- **pump deferral comment (LS-07)** -- the comment claimed a microtask
+  deferral that is not in the code. `pump()` is called directly; the stack
+  stays bounded because the continuation runs from a `.then()` handler.
+- **perf numbers (LS-08)** -- the shipped ops/s figures named no node
+  version, date, or machine and no longer matched a current run. Re-measured
+  once with provenance; llms.txt (Performance) is now the single source of
+  truth and README cites it. Four 1.1 `toAsyncIterable` bench scenarios
+  (`latest-1to1-x10`, `latest-churn-100`, `filter-timeout`, `multi-waiter-x3`)
+  were removed from the docs as unreproducible -- no runnable source for them
+  exists in the repo; only the six scenarios `bench/bench.mjs` runs are cited.
+
+### Added
+
+- **`test/08-dispose-behavior.test.mjs`** -- 6 tests pinning the TRUE dispose
+  semantics (LS-01: disposing a result/target signal does not stop the pump;
+  LS-04: a pending `next()` on a disposed source never settles, `timeout` is
+  the escape hatch).
+- **`--expose-gc` on the default `npm test`** (LS-02) -- the 8 GC-tier tests
+  were dark under the default gate (71 run, 8 skipped); they now run on every
+  `npm test` (85 total, 0 skipped on Node 20+). `npm run test:gc` is retained
+  as an alias.
+- **no-lockfile policy** (LS-10) -- one sentence in the README Testing
+  strategy documents why no `package-lock.json` is committed and how the peer
+  floor is verified.
+
+### Testing
+
+- 85 tests across `test/01-*` through `test/08-*` (up from 79 in 1.1.0). All
+  pass under `npm test` and `npm run test:gc`; per-scenario bench numbers with
+  provenance live in llms.txt (no ops/s digits are pinned in this changelog).
+
+---
+
+## 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
@@ -50,6 +203,8 @@ All three paths handled structurally; abort listeners always removed.
 Additionally: if the consumer disposes the result signal externally, the
 pump detects on next `sig.set()` and tears down silently (no `onError` --
 this is consumer-initiated cleanup).
+(Superseded in 1.1.1: this claim was never true -- see [1.1.1] and ROADMAP
+LS-01.)
 
 ### Performance (Node v22, --expose-gc, 500ms runs)
 

package/README.md

@@ -116,10 +116,11 @@ The abort listener is registered with `addEventListener("abort", ...)` and
 **always removed** on any of the three paths -- no AbortSignal accumulates
 dangling listeners across stream lifecycles.
 
-If the consumer disposes the result signal via `lite-signal`'s `dispose()`,
-the pump detects the disposal on its next attempted `sig.set()`, tears down
-the iterator silently (no `onError` fired -- this is consumer-initiated
-cleanup, not a stream error), and exits.
+Disposing the result signal does NOT stop the pump: the iterator keeps
+pulling. AbortSignal or natural completion are the only stop mechanisms.
+`iterator.return()` is never called and no callback fires, because
+`lite-signal`'s `set()` after `dispose()` is a silent no-op -- the pump never
+learns of the disposal. Abort `opts.signal` to stop early. See ROADMAP LS-01.
 
 ## API reference
 
@@ -182,6 +183,8 @@ Use `pipeToSignal` when:
 - You want a `stop` fn instead of an `AbortController` for cleanup
 
 **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`.
 
 ### toAsyncIterable
 
@@ -190,10 +193,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 +213,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 +257,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,29 +266,50 @@ 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
 
 `lite-stream`'s hot paths -- per-yield state allocation and per-pull abort
-checks -- minimize per-op allocation. Measured retention is sub-byte per op
-across all scenarios:
-
-```
-from-latest-10                 178K ops/s   0.07 B/op
-from-buffer-20-drop            128K ops/s   0.13 B/op
-abort-cycle                     84K ops/s   0.71 B/op
-pipe-to-signal                 235K ops/s   0.10 B/op
-```
+checks -- minimize per-op allocation. Current numbers with provenance live in
+`llms.txt` (Performance); re-run `npm run bench` on your target.
 
 Per-yield, `"latest"` mode allocates exactly one wrapper state object. The
 underlying signal node is reused via lite-signal's pool. `"buffer"` mode
@@ -403,8 +467,9 @@ const ws = new WebSocket("wss://logs.example.com/ingest");
 - **Sync `Iterable<T>`**: accepted via `Symbol.iterator`. Pulls happen
   microtask-asynchronously even for sync sources, so caller's `effect()`
   can wire up before the first yield.
-- **Consumer disposes the signal mid-stream**: pump detects on next
-  `sig.set()`, tears down the iterator silently. No `onError` fired.
+- **Consumer disposes the signal mid-stream**: the pump keeps pulling.
+  `iterator.return()` is not called and no callback fires; abort
+  `opts.signal` to stop.
 - **Buffer mode snapshot array**: a fresh array per yield. Past observers
   hold stable, non-mutated references.
 - **Disposing the signal multiple times**: lite-signal's `dispose` is
@@ -413,40 +478,15 @@ const ws = new WebSocket("wss://logs.example.com/ingest");
 
 ## Benchmarks
 
-Run via `npm run bench` (requires `--expose-gc`).
-
-```
-[1] fromAsyncIterable latest mode -- 10-item async gen
-  from-latest-10                       178,554 ops/s   retained: 0.07 B/op
-
-[2] fromAsyncIterable buffer mode -- 20-item gen, maxBuffer 5
-  from-buffer-20-drop                  128,630 ops/s   retained: 0.13 B/op
-
-[3] Abort cycle -- infinite gen, abort after first yield
-  abort-cycle                           84,102 ops/s   retained: 0.71 B/op
-
-[4] pipeToSignal -- pump existing signal directly
-  pipe-to-signal                       235,376 ops/s   retained: 0.10 B/op
-
-[5] toAsyncIterable -- 10 signal updates, consumer drains in order
-  to-async-iterable                     42,480 ops/s   retained: ~0 B/op
-
-[6] toAsyncIterable -- producer overflow, drop-oldest
-  to-async-iterable-overflow            62,164 ops/s   retained: ~25 B/op
-```
-
-(Node v22, 150ms warmup, 500ms runs.)
-
-The full lifecycle (construct, pull, settle, dispose) of `fromAsyncIterable`
-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.
+Run via `npm run bench` (requires `--expose-gc`). Current numbers with
+provenance live in `llms.txt` (Performance); re-run `npm run bench` on your
+target.
 
 ## Testing strategy
 
 ### Tier 1 -- behavior (unit tests, fast)
 
-49 tests across `test/01-*` through `test/06-*`:
+85 tests across `test/01-*` through `test/08-*`:
 
 - `01-from-async-iterable-latest.test.mjs` -- state shape, lifecycle,
   Iterable acceptance variants, pre-aborted, subscriber observability
@@ -456,24 +496,40 @@ 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
+- `08-dispose-behavior.test.mjs` -- pins the TRUE dispose semantics
+  (LS-01: disposing a result/target signal does NOT stop the pump;
+  LS-04: a pending `next()` on a disposed source never settles, `timeout`
+  is the only escape hatch)
 
 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`.
+The GC tier now runs under the default `npm test` (the script carries
+`--expose-gc`), so these budgets gate on every run; `npm run test:gc` is
+retained as an alias.
 
 ### Tier 3 -- performance (measured throughput)
 
 `bench/bench.mjs` -- six scenarios; throughput and B/op retained. Run via
 `npm run bench`.
 
+No `package-lock.json` is committed: devDependencies float within their
+stated ranges, and correctness against the peer floor is proven by running
+the suite against `@zakkster/lite-signal@1.2.2` rather than by pinning a
+lockfile.
+
 ## What this is not
 
 - **Not a full reactive stream library.** No `map`, `filter`, `merge`, or