@zakkster/lite-stream 1.1.1 → 1.3.0

package/llms.txt

@@ -5,7 +5,7 @@ multi-shot dual of lite-await's `fromPromise`. Project async streams
 (paginated APIs, SSE, network frames, pubsub topics) into signals with
 bounded buffering and structural cleanup.
 
-ESM-only. Node >= 18. ~5 KB minified. Single file `Stream.js`.
+ESM-only. Node >= 18. Zero runtime dependencies. Single file `Stream.js`.
 Peer dep: `@zakkster/lite-signal ^1.2.0`.
 
 ## Install
@@ -14,7 +14,7 @@ Peer dep: `@zakkster/lite-signal ^1.2.0`.
 
 ## Imports
 
-    import { fromAsyncIterable, pipeToSignal, toAsyncIterable, TimeoutError } from "@zakkster/lite-stream";
+    import { fromAsyncIterable, pipeToSignal, toAsyncIterable, TimeoutError, VERSION } from "@zakkster/lite-stream";
 
 ## Exports
 
@@ -49,22 +49,72 @@ Throws `TypeError` on null/undefined/wrong-shape source. Throws
 
 ### `pipeToSignal(source, target, opts?) -> stop`
 
-Pump an existing writable signal from an async iterator. The signal's
-value is replaced directly (no wrapper). Returns an idempotent stop fn.
+Pump an existing writable signal from an async iterator. In the default
+`"latest"` mode the signal's value is replaced directly (no wrapper). Returns
+an idempotent stop fn that also carries `droppedCount` / `overflowCount`
+getters.
 
 ```js
 const stop = pipeToSignal(source, targetSig, {
     signal: abortCtrl.signal,
+    mode: "latest" | "buffer",         // default "latest"
+    maxBuffer: 64,                     // REQUIRED if mode = "buffer"
+    transform: (v) => transform(v),    // per-value map, runs first
+    onValue: (v) => {},                // tap: fires ONCE per value BEFORE set
+    onAbort: (reason) => {},           // aborts route HERE instead of onError
     onError: (e) => {},
-    onDone: () => {},
-    transform: (v) => transform(v)
+    onDone: () => {}
 });
+
+stop();                 // idempotent -- calling again is a no-op
+stop.droppedCount;      // buffer-mode overflow count (0 in latest mode)
+stop.overflowCount;     // alias of droppedCount
 ```
 
+Enrichment (1.3.0, all ADDITIVE -- the un-optioned path is byte-identical to
+1.1.0):
+
+- `mode: "buffer"` drives the target with a bounded newest-last snapshot array
+  (a fresh array per set) instead of the raw value. REQUIRES `maxBuffer` (a
+  positive integer; missing/invalid throws `RangeError` -- same
+  "unbounded buffering is a memory bug pretending to be a feature" voice as
+  `fromAsyncIterable`). Overflow drops the oldest and increments the stop fn's
+  `droppedCount`. `mode: "latest"` + `maxBuffer` throws `TypeError`; an unknown
+  mode throws `TypeError`. All validated ONCE at construction.
+- `onValue(v)` is a per-value tap that fires exactly once per value BEFORE the
+  `set` (and after `transform`). A THROWING `onValue` routes through the same
+  leg as a throwing transform -- `stop()` then `onError` (precedent: test/04
+  "transform throwing stops the pump cleanly").
+- `onAbort(reason)`, when present, receives aborts INSTEAD of `onError` (both at
+  the abort listener and the pre-aborted early return), so consumers stop
+  filtering intentional aborts out of their error handler. Absent -> 1.1.0
+  behavior byte-identical (aborts flow through `onError`). See the abort
+  vocabulary contract table below and `decisions/0001-abort-vocabulary.md`.
+- `stop.droppedCount` and `stop.overflowCount` are getters ON the returned stop
+  fn (aliases of one overflow counter); the stop fn stays callable and
+  idempotent exactly as 1.1.0.
+
 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.
 
+#### Abort vocabulary contract
+
+The two directions frame an AbortSignal abort differently, by design. See
+`decisions/0001-abort-vocabulary.md` (a repo-only doc, not shipped in the
+tarball).
+
+| Direction | On abort | Framing | Escape hatch |
+| --- | --- | --- | --- |
+| `fromAsyncIterable` (from-side) | interrupt production; `iter.return()` best-effort; terminal error state | error (`onError`, `state.error`) | -- |
+| `pipeToSignal` (from-side) | interrupt production; `iter.return()` best-effort | error (`onError`) by default | `onAbort` routes aborts away from `onError` |
+| `toAsyncIterable` (to-side) | stop listening; pending `next()` resolves `{ done: true }` | graceful done | already graceful; nothing to filter |
+
+Aborting a producer is an interruption of work in flight (error framing);
+aborting a consumer is a subscriber leaving (graceful done). `onAbort` is added
+to `pipeToSignal` ONLY -- the sole direction that carried a shipped consumer
+workaround.
+
 ### `toAsyncIterable(sig, opts?) -> AsyncIterable<T> & { droppedCount, overflowCount }`
 
 Reverse direction: yield signal changes as an async iterable.
@@ -120,12 +170,25 @@ 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.
 
+### `VERSION`
+
+String, always equals the installed package.json version. Not re-exported
+by consumers (suite ruling); the surface-guard asserts the equality on
+every test run.
+
 ## Cleanup termination triplet
 
 `fromAsyncIterable` ends on exactly three paths, all structural:
 
 1. Iterator natural completion (`{ done: true }`) -> done state, onDone fires.
-2. Iterator throws -> error state, onError fires.
+2. Iterator throws -> error state, onError fires. As of 1.3.0 (LS-13) this leg
+   also covers a `next()` result whose `done` or `value` is a THROWING getter:
+   the thrown value routes to the error state with onError fired exactly once,
+   instead of escaping as an unhandledRejection with the signal never settling.
+   `pipeToSignal` gets the same fix (stop + onError). Both pumps read the two
+   result properties once, inside a dedicated try/catch that routes to the
+   existing "iterator throws" leg; the peer-defense catch around `set()` (LS-01)
+   is separate and untouched.
 3. AbortSignal aborts -> `iter.return()` called, error state, onError fires.
 
 The abort listener is always removed on any of the three paths -- no
@@ -278,16 +341,15 @@ 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).
+(gated: test/torture.mjs s5, per-scenario budgets).
 
 ## Files
 
-- `Stream.js` -- single-file ESM implementation (~875 lines)
+- `Stream.js` -- single-file ESM implementation (~995 lines)
 - `Stream.d.ts` -- TypeScript types with discriminated state union
 - `README.md` -- full docs with integration recipes
 - `llms.txt` -- this file
 - `CHANGELOG.md` -- version history
-- `ROADMAP.md` -- deferred features
 
 ## Author
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zakkster/lite-stream",
-  "version": "1.1.1",
+  "version": "1.3.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, iterator throws, AbortSignal abort). The multi-shot dual of lite-await's fromPromise.",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
   "license": "MIT",
@@ -22,14 +22,16 @@
     "README.md",
     "llms.txt",
     "LICENSE.txt",
-    "CHANGELOG.md",
-    "ROADMAP.md"
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "test": "node --expose-gc --test --test-reporter=spec",
-    "test:gc": "node --expose-gc --test --test-reporter=spec",
+    "test": "node --expose-gc --test --test-reporter=spec test/*.test.mjs",
+    "test:gc": "node --expose-gc --test --test-reporter=spec test/*.test.mjs",
     "bench": "node --expose-gc bench/bench.mjs",
-    "verify": "npm test && npm run test:gc && npm run bench"
+    "torture": "node --expose-gc test/torture.mjs",
+    "torture:control": "for t in s0 s1 s2 s3 s4 s5 s6 s7 s7e s8; do if STREAM_TORTURE_BREAK=$t node --expose-gc test/torture.mjs >/dev/null 2>&1; then echo \"control $t FAILED-TO-FAIL\"; exit 1; else echo \"control $t failed-as-expected\"; fi; done",
+    "test:floor": "echo '== floor lane: pin @zakkster/lite-signal@1.2.2 (torture NOT run here -- lite-leak peers lite-signal>=1.5.0, LS-09 amendment) ==' && npm i --no-save --no-package-lock @zakkster/lite-signal@1.2.2 --legacy-peer-deps && npm test && echo 'FLOOR-PASS: npm test green @ lite-signal@1.2.2' && echo '== latest lane: restore @zakkster/lite-signal@^1.2.0 ==' && npm i --no-save --no-package-lock @zakkster/lite-signal@^1.2.0 && npm test && npm run torture && echo 'LATEST-PASS: npm test + torture green @ lite-signal latest'",
+    "verify": "npm test && npm run test:gc && npm run bench && npm run torture"
   },
   "keywords": [
     "stream",
@@ -66,6 +68,8 @@
     "@zakkster/lite-signal": "^1.2.0"
   },
   "devDependencies": {
+    "@zakkster/lite-gc-profiler": "^1.16.0",
+    "@zakkster/lite-leak": "^1.10.0",
     "@zakkster/lite-signal": "^1.2.2"
   }
 }