@zakkster/lite-stream 1.0.0

package/llms.txt

@@ -0,0 +1,212 @@
+# @zakkster/lite-stream
+
+Zero-GC bridge between async iterators and `@zakkster/lite-signal`. The
+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`.
+Peer dep: `@zakkster/lite-signal ^1.2.0`.
+
+## Install
+
+    npm i @zakkster/lite-stream @zakkster/lite-signal
+
+## Imports
+
+    import { fromAsyncIterable, pipeToSignal, toAsyncIterable } from "@zakkster/lite-stream";
+
+## Exports
+
+### `fromAsyncIterable(source, opts?) -> Signal<State<T>>`
+
+Drive a signal from an async iterator. Returns a Signal whose value is a
+tagged state object reflecting the iterator's lifecycle.
+
+```js
+const live = fromAsyncIterable(asyncSource, {
+    mode: "latest" | "buffer",         // default "latest"
+    maxBuffer: 1024,                   // REQUIRED if mode = "buffer"
+    initial: undefined,                // initial signal value
+    signal: abortCtrl.signal,          // abort to stop
+    onError: (e) => {},
+    onDone: () => {}
+});
+```
+
+State shape varies by mode:
+- `"latest"`: `{ value, count, done, error }`. Signal value is the most
+  recent yielded item. Cheapest path.
+- `"buffer"`: `{ values, count, droppedCount, done, error }`. `values` is a
+  bounded array (newest last). REQUIRES `maxBuffer`. Overflow drops oldest
+  and increments `droppedCount`.
+
+Accepts `AsyncIterable<T>`, `AsyncIterator<T>` (just `.next`), or sync
+`Iterable<T>` as a convenience.
+
+Throws `TypeError` on null/undefined/wrong-shape source. Throws
+`RangeError` on missing/invalid `maxBuffer` in buffer mode.
+
+### `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.
+
+```js
+const stop = pipeToSignal(source, targetSig, {
+    signal: abortCtrl.signal,
+    onError: (e) => {},
+    onDone: () => {},
+    transform: (v) => transform(v)
+});
+```
+
+Does NOT dispose the target signal. The caller owns its lifetime.
+
+### `toAsyncIterable(sig, opts?) -> AsyncIterable<T> & { droppedCount }`
+
+Reverse direction: yield signal changes as an async iterable. Bounded
+internal queue (default 1024) with drop-oldest overflow.
+
+```js
+for await (const v of toAsyncIterable(sig, {
+    signal: abortCtrl.signal,
+    emitInitial: true,                  // default true
+    maxBuffer: 1024                     // default 1024
+})) {
+    // ...
+}
+```
+
+The iterator naturally completes when `opts.signal` aborts. Consumer-side
+`break` triggers `iterator.return()` and cleans up the subscription.
+
+## 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.
+3. AbortSignal aborts -> `iter.return()` called, error state, onError fires.
+
+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).
+
+## Key invariants
+
+- **Buffer mode REQUIRES `maxBuffer`.** No default. Missing throws
+  RangeError with "unbounded buffering is a memory bug pretending to be a
+  feature". Pick a deliberate ceiling.
+- **Drop-oldest on overflow.** Newer values win; `droppedCount` tracks
+  the loss. Observable via `live().droppedCount` for buffer mode and
+  `iterable.droppedCount` for toAsyncIterable.
+- **Snapshot arrays are fresh per yield in buffer mode.** Past observers
+  hold stable, non-mutated array references.
+- **First pull is microtask-deferred.** The caller's `effect()` can wire
+  up before the first yield arrives.
+- **Pre-aborted AbortSignal short-circuits.** The iterator is never started.
+- **Sync `Iterable` sources accepted.** Pulls happen async even for sync
+  sources, preserving wire-up semantics.
+
+## Modes -- when to pick which
+
+`"latest"`:
+- Live cursor positions
+- Current pubsub message
+- Latest network frame
+- Current SSE event
+- Anything where intermediate values can be safely discarded
+
+`"buffer"`:
+- Helix paginated results (each page must be processed)
+- EBS SSE event log (must not miss events)
+- Replay queue (every frame applies in order)
+- Anything where every value matters
+
+## Integration recipes
+
+### Helix pagination
+
+```js
+async function* helixPages(url, signal) {
+    let cursor = "";
+    while (true) {
+        const res = await fetch(url + "?after=" + cursor, { signal });
+        const { data, pagination } = await res.json();
+        yield data;
+        if (!pagination?.cursor) return;
+        cursor = pagination.cursor;
+    }
+}
+
+const pages = fromAsyncIterable(helixPages(url, ctrl.signal), {
+    mode: "buffer", maxBuffer: 100, signal: ctrl.signal
+});
+```
+
+### EBS server-sent events
+
+```js
+async function* sseEvents(url, signal) {
+    const res = await fetch(url, { signal });
+    const reader = res.body.getReader();
+    // ... parse SSE frames ...
+    while (true) { ...; yield parsedFrame; }
+}
+
+const events = fromAsyncIterable(sseEvents(url, ctrl.signal), {
+    mode: "latest", signal: ctrl.signal
+});
+```
+
+### lite-statechart entry action with ctx.signal
+
+```js
+states: {
+    fetching: {
+        entry: async (payload, ctx) => {
+            const live = fromAsyncIterable(somePager(), { signal: ctx.signal });
+            // ctx.signal aborts when machine leaves `fetching`
+            // -> fromAsyncIterable's signal aborts
+            // -> iter.return() called
+            // -> no leaks
+        }
+    }
+}
+```
+
+## What this is NOT
+
+- Not a full reactive stream library (no map/filter/merge combinators).
+  Compose iterators yourself with async generators.
+- Not a backpressure protocol. Async iterators in JS have no producer-side
+  flow control; buffer mode just bounds in-flight values.
+- Not a replacement for lite-clock for frame-rate loops.
+- Not for one-shot promises -- use lite-await's `fromPromise`.
+
+## 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.
+
+Per-yield, latest mode allocates one wrapper state object. Buffer mode
+adds one snapshot array per yield. Ring beneath is fixed pre-allocated.
+
+## Files
+
+- `Stream.js` -- single-file ESM implementation (~600 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
+
+Zahary Shinikchiev <shinikchiev@yahoo.com>
+MIT License

package/package.json

@@ -0,0 +1,71 @@
+{
+  "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.",
+  "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
+  "license": "MIT",
+  "type": "module",
+  "main": "./Stream.js",
+  "module": "./Stream.js",
+  "types": "./Stream.d.ts",
+  "exports": {
+    ".": {
+      "node": "./Stream.js",
+      "import": "./Stream.js",
+      "types": "./Stream.d.ts",
+      "default": "./Stream.js"
+    }
+  },
+  "files": [
+    "Stream.js",
+    "Stream.d.ts",
+    "README.md",
+    "llms.txt",
+    "LICENSE.txt",
+    "CHANGELOG.md",
+    "ROADMAP.md"
+  ],
+  "scripts": {
+    "test": "node --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"
+  },
+  "keywords": [
+    "stream",
+    "async-iterator",
+    "signal",
+    "signals",
+    "reactive",
+    "abortcontroller",
+    "abortsignal",
+    "backpressure",
+    "ring-buffer",
+    "zero-gc",
+    "esm",
+    "no-dependencies"
+  ],
+  "homepage": "https://github.com/PeshoVurtoleta/lite-stream#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-stream.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-stream/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@zakkster/lite-signal": "^1.2.0"
+  },
+  "devDependencies": {
+    "@zakkster/lite-signal": "^1.2.2"
+  }
+}