@zakkster/lite-stream 1.1.0 → 1.1.1

package/Stream.js

@@ -1,4 +1,4 @@
-// @zakkster/lite-stream 1.1.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
@@ -22,7 +22,8 @@
 //
 // 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.
+// 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
@@ -40,9 +41,10 @@ import { signal as _signal } from "@zakkster/lite-signal";
  * 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.
+ * 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) {
@@ -145,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
@@ -301,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 = {
@@ -341,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) {
@@ -420,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
@@ -557,7 +569,8 @@ const ASYNC_DISPOSE = (typeof Symbol !== "undefined" && Symbol.asyncDispose)
  * where Promise.all([iter.next(), iter.next()]) silently lost the first
  * resolver.
  *
- * See CONTRACT-toAsyncIterable-1.1.md for the full locked semantics.
+ * 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

package/llms.txt

@@ -61,7 +61,9 @@ 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, overflowCount }`
 
@@ -129,9 +131,13 @@ imported from lite-await -- lite-stream stays zero-dep.
 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
 
@@ -243,31 +249,40 @@ states: {
   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.
+  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 `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.
+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.
 
-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
+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, `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.
+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 (~830 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.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.",
+  "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"