@zakkster/lite-stream 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+All notable changes to `@zakkster/lite-stream` are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## 1.0.0 -- 2026-06-23
+
+**Initial public release.** API frozen; subsequent 1.x releases are purely
+additive.
+
+### Added
+
+- **`fromAsyncIterable(source, opts?)`** -- drive a signal from an async
+  iterator. Two modes:
+  - `"latest"` (default): signal value is `{ value, count, done, error }`.
+    The most recent yielded item wins; cheapest path.
+  - `"buffer"`: signal value is `{ values, count, droppedCount, done, error }`.
+    Bounded ring buffer (newest-last). REQUIRES `maxBuffer`. Overflow drops
+    oldest and increments `droppedCount`. Unbounded buffering is rejected
+    with a `RangeError`.
+
+  Accepts `AsyncIterable`, `AsyncIterator` (just `.next()`), or sync
+  `Iterable` as a convenience.
+
+- **`pipeToSignal(source, target, opts?)`** -- lower-level companion that
+  pumps an existing writable signal from an async iterator. The signal's
+  value is replaced directly (no wrapper). Returns an idempotent stop fn.
+  Does NOT dispose the target signal.
+
+- **`toAsyncIterable(sig, opts?)`** -- reverse direction. Yield signal
+  changes as an async iterable. Bounded internal queue (default 1024) with
+  drop-oldest overflow. `iterable.droppedCount` is observable. Consumer
+  `break` triggers `iterator.return()`. Pre-aborted AbortSignal short-
+  circuits with `done: true`.
+
+### Cleanup termination triplet
+
+All three paths handled structurally; abort listeners always removed.
+
+1. Iterator natural completion (`{ done: true }`) -> done state, `onDone`
+   fires.
+2. Iterator throws -> error state with the thrown value, `onError` fires.
+3. AbortSignal aborts -> `iter.return()` called best-effort, error state
+   with `AbortError`, `onError` fires.
+
+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).
+
+### Performance (Node v22, --expose-gc, 500ms runs)
+
+- `from-latest-10`: **178K ops/s**, 0.07 B/op retained
+- `from-buffer-20-drop`: **128K ops/s**, 0.13 B/op retained
+- `abort-cycle`: **84K ops/s**, 0.71 B/op retained
+- `pipe-to-signal`: **235K ops/s**, 0.10 B/op retained
+- `to-async-iterable`: **42K ops/s**, ~0 B/op retained
+- `to-async-iterable-overflow`: **62K ops/s**, ~25 B/op retained
+
+### Testing
+
+49 tests across 6 files:
+- `01-from-async-iterable-latest.test.mjs` (11 tests)
+- `02-from-async-iterable-buffer.test.mjs` (8 tests)
+- `03-cleanup-triplet.test.mjs` (7 tests including a 200-cycle leak smoke)
+- `04-pipe-to-signal.test.mjs` (10 tests)
+- `05-to-async-iterable.test.mjs` (10 tests)
+- `06-gc.test.mjs` (3 heap-budget tests under `--expose-gc`)
+
+All 49 tests pass under both `npm test` and `npm run test:gc`.
+
+### Bundle
+
+- ~5 KB minified, ~2 KB gzipped
+- ESM-only, Node >= 18
+- Single file `Stream.js`
+- Zero runtime dependencies
+- Peer dep: `@zakkster/lite-signal ^1.2.0`
+
+### License
+
+MIT. Copyright (c) 2026 Zahary Shinikchiev.

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zahary Shinikchiev <shinikchiev@yahoo.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,521 @@
+# @zakkster/lite-stream
+
+[![npm version](https://img.shields.io/npm/v/@zakkster/lite-stream.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-stream)
+![Zero-GC](https://img.shields.io/badge/Zero--GC-Hot%20path-00C853?style=for-the-badge&logo=leaf&logoColor=white)
+[![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-stream?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-stream)
+[![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-stream?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-stream)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-stream?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-stream)
+[![lite-signal peer](https://img.shields.io/badge/peer-lite--signal-blue?style=for-the-badge)](https://github.com/PeshoVurtoleta/lite-signal)
+![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)
+
+Zero-GC bridge between async iterators and
+[`@zakkster/lite-signal`](https://www.npmjs.com/package/@zakkster/lite-signal).
+The multi-shot dual of [`lite-await`](https://www.npmjs.com/package/@zakkster/lite-await)'s
+`fromPromise`: project an async source of N values (paginated APIs, SSE
+streams, network frame queues, pubsub topics) into a signal-shaped reactive
+surface, with bounded buffering and structural cleanup on every termination
+path.
+
+## Why this exists
+
+The hand-rolled version of "drive a signal from an async iterator" is a
+five-line for-await loop that leaks the iterator forever the moment the
+consumer navigates away, the AbortSignal aborts, or the parent component
+unmounts. Every place in the `@zakkster/lite-*` ecosystem that handles a
+multi-shot async source -- helix pagination, EBS server-sent events,
+pubsub topic subscriptions, rollback input-frame queues -- would otherwise
+write that broken loop. This library is the one correct implementation.
+
+```
++-------------------------+        +-----------------+        +-----------------+
+|  AsyncIterable<T>       |        |  lite-stream    |        |  Signal<State>  |
+|  (helix pagination,     | -----> |  fromAsync-     | -----> |  (your effect() |
+|   EBS SSE, pubsub,      |        |  Iterable       |        |   reads this)   |
+|   rollback frames)      |        +-----------------+        +-----------------+
++-------------------------+                |
+                                           |  three structural cleanup paths:
+                                           |    (a) iterator done    -> done: true
+                                           |    (b) iterator throws  -> error: ...
+                                           |    (c) AbortSignal abort -> iter.return()
+                                           v
+                                  no leaks. no listeners outliving the stream.
+```
+
+## Install
+
+```sh
+npm install @zakkster/lite-stream @zakkster/lite-signal
+```
+
+`@zakkster/lite-signal` is a peer dependency (^1.2.0). No other runtime deps.
+
+## Quick start
+
+```js
+import { fromAsyncIterable } from "@zakkster/lite-stream";
+import { effect } from "@zakkster/lite-signal";
+
+const ctrl = new AbortController();
+
+const live = fromAsyncIterable(networkFrames(), {
+    signal: ctrl.signal,
+    onDone:  () => console.log("frame stream ended"),
+    onError: (e) => console.error("frame stream error", e)
+});
+
+effect(() => {
+    const s = live();
+    if (s.error)        renderError(s.error);
+    else if (s.done)    renderEndCard();
+    else if (s.value)   renderFrame(s.value);
+});
+
+// Later -- consumer navigates away:
+ctrl.abort();   // iterator.return() called; signal settles; no leaks
+```
+
+## Table of contents
+
+- [The cleanup termination triplet](#the-cleanup-termination-triplet)
+- [API reference](#api-reference)
+  - [fromAsyncIterable](#fromasynciterable)
+  - [pipeToSignal](#pipetosignal)
+  - [toAsyncIterable](#toasynciterable)
+- [Modes: latest vs buffer](#modes-latest-vs-buffer)
+- [Zero-GC hot paths](#zero-gc-hot-paths)
+- [Integration recipes](#integration-recipes)
+- [Edge cases pinned down](#edge-cases-pinned-down)
+- [Benchmarks](#benchmarks)
+- [Testing strategy](#testing-strategy)
+- [What this is not](#what-this-is-not)
+- [Ecosystem](#ecosystem)
+
+## The cleanup termination triplet
+
+A stream-to-signal bridge ends on exactly three paths. `lite-stream` handles
+all three structurally:
+
+1. **Iterator natural completion** -- the source yields `{ done: true }`. The
+   signal state settles with `done: true`. `onDone` fires once. No further
+   state mutations occur.
+
+2. **Iterator throws** -- the source rejects a pull or throws synchronously
+   from `next()`. The signal state settles with `error: <thrown>` and
+   `done: true`. `onError` fires once with the thrown value. The last
+   successfully yielded value is preserved.
+
+3. **AbortSignal aborts** -- the caller-provided `opts.signal` enters the
+   aborted state. `iter.return()` is called best-effort to give the
+   generator a chance to clean up. The signal state settles with
+   `error: <AbortError>` and `done: true`. `onError` fires.
+
+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.
+
+## API reference
+
+### fromAsyncIterable
+
+```ts
+fromAsyncIterable<T>(
+    source: AsyncIterable<T> | AsyncIterator<T> | Iterable<T>,
+    opts?: {
+        mode?:      "latest" | "buffer",     // default "latest"
+        maxBuffer?: number,                   // REQUIRED if mode = "buffer"
+        initial?:   T,                        // initial signal value
+        signal?:    AbortSignal,              // abort to stop
+        onError?:   (err: unknown) => void,
+        onDone?:    () => void
+    }
+): 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.
+
+State shape varies by mode:
+
+```ts
+// "latest" mode
+{ value: T | undefined, count: number, done: boolean, error: unknown }
+
+// "buffer" mode
+{ values: T[], count: number, droppedCount: number, done: boolean, error: unknown }
+```
+
+`count` increments on every yielded value (regardless of whether it survives
+buffering). `done` flips to `true` on any of the three termination paths.
+`error` is `undefined` on natural completion, populated otherwise.
+
+### pipeToSignal
+
+```ts
+pipeToSignal<T>(
+    source: AsyncIterable<T> | AsyncIterator<T>,
+    target: Signal<T>,
+    opts?: {
+        signal?:    AbortSignal,
+        onError?:   (err: unknown) => void,
+        onDone?:    () => void,
+        transform?: (value: T) => T
+    }
+): () => void   // stop fn (idempotent)
+```
+
+Lower-level companion: pump an existing writable signal from an async
+iterator. The signal's value is replaced directly with each yielded value
+(no `{ value, count, ... }` wrapper). Returns a `stop` function.
+
+Use `pipeToSignal` when:
+
+- You already have a signal you want to drive
+- You don't need the lifecycle metadata wrapper
+- You want a `stop` fn instead of an `AbortController` for cleanup
+
+**Does NOT dispose the target signal.** The caller owns its lifetime.
+
+### toAsyncIterable
+
+```ts
+toAsyncIterable<T>(
+    sig: Signal<T> | Computed<T>,
+    opts?: {
+        signal?:      AbortSignal,
+        emitInitial?: boolean,    // default true
+        maxBuffer?:   number      // default 1024
+    }
+): AsyncIterable<T> & { readonly droppedCount: number }
+```
+
+The reverse direction -- yield signal changes as an async iterable. Useful
+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.
+
+## Modes: latest vs buffer
+
+Pick `"latest"` when you only care about the most recent value:
+
+- Live cursor positions
+- Current pubsub message
+- Latest network frame
+- Current SSE event
+
+Pick `"buffer"` when every value matters and you want them in order:
+
+- Helix paginated results (each page must be processed)
+- 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:
+
+> `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.
+
+## 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
+```
+
+Per-yield, `"latest"` mode allocates exactly one wrapper state object. The
+underlying signal node is reused via lite-signal's pool. `"buffer"` mode
+adds one snapshot array per yield (so consumer effects see a stable
+non-mutated array view at each tick) -- the ring beneath it is a fixed
+pre-allocated array reused across all yields.
+
+The only per-op allocations beyond intrinsic iterator cost:
+
+- One wrapper state object per yield (`"latest"`) or wrapper + snapshot
+  array (`"buffer"`)
+- One AbortListener function and registration on the AbortSignal (once per
+  stream lifetime, not per yield)
+- The Promise chain from `iter.next().then(...)` itself
+
+V8's escape analysis covers the wrapper object closures in most JIT modes.
+
+## Integration recipes
+
+### lite-twitch-helix paginated endpoint
+
+```js
+import { fromAsyncIterable } from "@zakkster/lite-stream";
+import { effect } from "@zakkster/lite-signal";
+
+async function* getFollowers(channelId, signal) {
+    let cursor = "";
+    while (true) {
+        const res = await fetch(
+            "https://api.twitch.tv/helix/channels/followers"
+                + "?broadcaster_id=" + channelId
+                + (cursor ? "&after=" + cursor : ""),
+            { signal, headers: { Authorization: bearer, "Client-Id": clientId } }
+        );
+        const { data, pagination } = await res.json();
+        yield data;                                  // yield one page at a time
+        cursor = pagination?.cursor;
+        if (!cursor) return;
+    }
+}
+
+const ctrl = new AbortController();
+const pages = fromAsyncIterable(getFollowers(channelId, ctrl.signal), {
+    mode: "buffer",
+    maxBuffer: 100,                                  // 100 pages = 10K followers max
+    signal: ctrl.signal
+});
+
+effect(() => {
+    const s = pages();
+    if (s.droppedCount > 0) console.warn("dropped pages:", s.droppedCount);
+    renderFollowerList(s.values.flat());
+    if (s.done && !s.error) renderDoneCard(s.count);
+});
+```
+
+### lite-twitch-ebs server-sent events
+
+```js
+import { fromAsyncIterable } from "@zakkster/lite-stream";
+
+async function* sseEvents(url, signal) {
+    const res = await fetch(url, { signal });
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) return;
+        buffer += decoder.decode(value, { stream: true });
+        for (const line of buffer.split("\n\n").slice(0, -1)) {
+            yield parseSSE(line);
+        }
+        buffer = buffer.split("\n\n").slice(-1)[0];
+    }
+}
+
+const ctrl = new AbortController();
+const events = fromAsyncIterable(sseEvents("/ebs/events", ctrl.signal), {
+    mode: "latest",                                  // only newest matters
+    signal: ctrl.signal
+});
+```
+
+### lite-rollback input-frame queue
+
+```js
+import { fromAsyncIterable } from "@zakkster/lite-stream";
+
+async function* gamepadFrames(signal) {
+    while (!signal.aborted) {
+        await nextAnimationFrame();
+        yield sampleGamepad();
+    }
+}
+
+const frames = fromAsyncIterable(gamepadFrames(ctrl.signal), {
+    mode: "buffer",
+    maxBuffer: 60,                                   // 1 second at 60fps
+    signal: ctrl.signal
+});
+
+effect(() => {
+    const s = frames();
+    for (const frame of s.values) applyInputFrame(frame);
+    if (s.droppedCount) console.warn("rollback drops:", s.droppedCount);
+});
+```
+
+### lite-twitch-pubsub topic subscription
+
+```js
+import { pipeToSignal } from "@zakkster/lite-stream";
+import { signal } from "@zakkster/lite-signal";
+
+const subs = signal(null);
+
+const ctrl = new AbortController();
+const stop = pipeToSignal(subscribeToTopic("channel-subscribe-events.v1"), subs, {
+    signal:    ctrl.signal,
+    transform: (raw) => JSON.parse(raw.data),
+    onError:   (e) => console.error("pubsub error", e)
+});
+
+// Later: ctrl.abort() OR stop() -- either ends the pipe.
+```
+
+### Reverse direction: pipe signal changes into a WebSocket
+
+```js
+import { toAsyncIterable } from "@zakkster/lite-stream";
+
+const ctrl = new AbortController();
+const ws = new WebSocket("wss://logs.example.com/ingest");
+
+(async () => {
+    for await (const event of toAsyncIterable(loggerSig, { signal: ctrl.signal })) {
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify(event));
+        }
+    }
+})();
+```
+
+## Edge cases pinned down
+
+- **Pre-aborted AbortSignal**: the iterator is never started. The signal
+  settles synchronously with an `AbortError`. No pulls.
+- **Synchronous throw from `iter.next()`**: caught and surfaced via the
+  same error path as async rejections.
+- **Iterator yields `null`/`undefined`**: passed through as-is. `lite-stream`
+  doesn't interpret values; only `{ done: true }` terminates.
+- **Iterator returns a non-object from `next()`**: treated as a protocol
+  error; settles with a `TypeError`.
+- **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.
+- **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
+  idempotent; lite-stream tolerates concurrent abort + dispose without
+  double-firing callbacks.
+
+## 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.
+
+## Testing strategy
+
+### Tier 1 -- behavior (unit tests, fast)
+
+49 tests across `test/01-*` through `test/06-*`:
+
+- `01-from-async-iterable-latest.test.mjs` -- state shape, lifecycle,
+  Iterable acceptance variants, pre-aborted, subscriber observability
+- `02-from-async-iterable-buffer.test.mjs` -- ring buffer correctness,
+  drop-oldest, snapshot freshness, maxBuffer validation, helix shape
+- `03-cleanup-triplet.test.mjs` -- all three termination paths, iterator
+  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
+
+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).
+
+Run via `npm run test:gc`.
+
+### Tier 3 -- performance (measured throughput)
+
+`bench/bench.mjs` -- six scenarios; throughput and B/op retained. Run via
+`npm run bench`.
+
+## What this is not
+
+- **Not a full reactive stream library.** No `map`, `filter`, `merge`, or
+  any other combinator surface. Compose iterators yourself with async
+  generators -- `for await (const x of source) { if (pred(x)) yield x; }` --
+  and pass the composed iterator to `fromAsyncIterable`.
+- **Not a backpressure protocol.** Async iterators in JS don't have a way
+  to tell the producer "wait, I'm full." The buffer mode's `maxBuffer` is a
+  ceiling on in-flight values; overflow drops oldest. If you need
+  bidirectional backpressure, your source needs to expose that surface.
+- **Not a replacement for `lite-clock`**. For frame-rate driven loops, use
+  `lite-clock`. Use `lite-stream` for one-way async sources where the
+  source's pace is external.
+- **Not for one-shot promises.** Use `lite-await`'s `fromPromise` for that.
+  `lite-stream` is the multi-shot dual; the cleanup model is fundamentally
+  different.
+
+## Ecosystem
+
+`lite-stream` composes with the rest of the `@zakkster/lite-*` family:
+
+- **`@zakkster/lite-signal`** -- the reactive signal core. Required peer.
+- **`@zakkster/lite-await`** -- single-shot async primitives
+  (`whenSignal`, `withTimeout`, `withAbort`, `fromPromise`). Pair
+  `withTimeout` with each `next()` call to add per-pull timeouts to your
+  iterator.
+- **`@zakkster/lite-statechart`** -- finite state machines. Use
+  `ctx.signal` (1.1+) from a state's entry action to drive a `lite-stream`
+  pump that auto-aborts on state transitions.
+- **`@zakkster/lite-twitch`** (upcoming) -- Twitch Extension SDK. Helix
+  pagination, EBS SSE, pubsub topics all consume `lite-stream`.
+
+## Bundle
+
+```
+~5 KB minified (gzipped: ~2 KB)
+ESM-only, Node >= 18
+Single file: Stream.js
+Peer dep: @zakkster/lite-signal ^1.2.0
+Zero runtime deps.
+```
+
+## License
+
+MIT (c) 2026 Zahary Shinikchiev. See [LICENSE.txt](./LICENSE.txt).