@zakkster/lite-stream 1.0.0 → 1.1.1

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
 
@@ -61,25 +61,64 @@ const stop = pipeToSignal(source, targetSig, {
 });
 ```
 
-Does NOT dispose the target signal. The caller owns its lifetime.
+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(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
 
@@ -92,9 +131,13 @@ The iterator naturally completes when `opts.signal` aborts. Consumer-side
 The abort listener is always removed on any of the three paths -- no
 AbortSignal accumulates dangling listeners.
 
-If the consumer disposes the result signal via lite-signal's `dispose()`,
-the pump detects on next `sig.set()` and tears down silently (no onError --
-this is consumer-initiated cleanup, not a stream error).
+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 neither `onError` nor `onDone` ever
+fire, because lite-signal's `set()` after `dispose()` is a silent no-op (in
+1.2.2 and 1.5.0), so the pump never learns of the disposal. For an infinite
+source (SSE, a live feed) this turns the stream into an unbounded background
+loop. Abort `opts.signal` to stop early. See ROADMAP LS-01.
 
 ## Key invariants
 
@@ -188,18 +231,58 @@ 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. A pending `next()` at the moment of
+  disposal never settles -- it neither resolves nor rejects; the only escape
+  hatch is the `timeout` option, which rejects the pending `next()` with
+  `TimeoutError` once its deadline elapses. See ROADMAP LS-04.
+
 ## 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.
+Measured 2026-09-01 on node v26.3.1 (macOS arm64, laptop class), 150ms
+warmup / 500ms runs, via npm run bench. Your numbers will differ -- re-run
+npm run bench on your target.
+
+The six scenarios `bench/bench.mjs` actually runs (ops/s, retained B/op):
+
+- `from-latest-10`: 68,156 ops/s, 0.3218 B/op
+- `from-buffer-20-drop`: 61,960 ops/s, 0.4715 B/op
+- `abort-cycle`: 29,078 ops/s, 1.5132 B/op
+- `pipe-to-signal`: 50,098 ops/s, 0.0853 B/op
+- `to-async-iterable`: 198,948 ops/s, -8.4923 B/op
+- `to-async-iterable-overflow`: 208,790 ops/s, 0.1013 B/op
+
+The negative B/op on `to-async-iterable` is a GC-timing artifact (the
+post-run gc() reclaims more than the pre-run baseline held); it is not a
+zero-alloc guarantee. Per-scenario numbers only -- there is no "sub-byte
+across all scenarios" claim.
 
-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
+(structural claim; gated by the alloc tier in 1.2.0).
 
 ## Files
 
-- `Stream.js` -- single-file ESM implementation (~600 lines)
+- `Stream.js` -- single-file ESM implementation (~875 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,7 +1,7 @@
 {
   "name": "@zakkster/lite-stream",
-  "version": "1.0.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.",
+  "version": "1.1.1",
+  "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, iterator throws, AbortSignal abort). The multi-shot dual of lite-await's fromPromise.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
   "type": "module",
@@ -26,7 +26,7 @@
     "ROADMAP.md"
   ],
   "scripts": {
-    "test": "node --test --test-reporter=spec",
+    "test": "node --expose-gc --test --test-reporter=spec",
     "test:gc": "node --expose-gc --test --test-reporter=spec",
     "bench": "node --expose-gc bench/bench.mjs",
     "verify": "npm test && npm run test:gc && npm run bench"