# `stream`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`stream.ts` exposes `sendStream`, a streaming RPC primitive that returns
an `AsyncIterable<TChunk>` driven by frames the worker pushes back to the
main thread. It complements the `sendRequest` request/response API by
letting workers stream partial results — useful for progressive renders,
chunked compression, log tails, or any long-running operation that
produces incremental output.

The protocol is intentionally minimal: the consumer posts an initial
envelope `{ streamId, payload }` to the worker; the worker pushes
`{ id: streamId, payload: { chunk } }` frames, and signals completion
with `{ id: streamId, payload: { done: true } }`. Aborting the consumer's
signal posts a `stream:cancel` frame to the worker and throws
`WEB_WORKERS.STREAM_ABORTED`.

## Features

- Async-iterable interface: `for await (const chunk of stream) ...`.
- `AbortSignal` cancellation: aborts both the iterator and posts a cancel
  frame to the worker.
- Pre-aborted signal short-circuits with `WEB_WORKERS.STREAM_ABORTED` and
  no initial message is posted.
- Frame correlation by stream id: foreign-worker frames and foreign-id
  frames are ignored, so multiple concurrent streams over the same
  manager coexist cleanly.
- Optional `idFactory` for deterministic ids in tests.
- Optional `transfer` list for zero-copy initial payload handoff.

## Usage: Basic Example

```ts
import { sendStream, WorkerManager } from "@suaveplan/web-workers";

const manager = new WorkerManager({ factory });
manager.create({ name: "tail", url: WORKER_URL });

for await (const line of sendStream<string, string>(
    manager,
    "tail",
    "tail-log",
    "/var/log/app.log"
)) {
    appendLine(line);
}
```

## Usage: Advanced Example

```ts
import { sendStream, WEB_WORKERS_CODES } from "@suaveplan/web-workers";

const ctrl = new AbortController();
const buf = new ArrayBuffer(8 * 1024 * 1024);
const stream = sendStream<ArrayBuffer, ArrayBuffer>(
    manager,
    "compress",
    "lz4-stream",
    buf,
    { signal: ctrl.signal, transfer: [buf] }
);

const chunks: ArrayBuffer[] = [];
try {
    for await (const chunk of stream) {
        chunks.push(chunk);
        if (cancelRequested) ctrl.abort();
    }
} catch (err) {
    if (
        err instanceof Error &&
        (err as { code?: string }).code === WEB_WORKERS_CODES.STREAM_ABORTED
    ) {
        // expected when ctrl.abort() fires
    } else {
        throw err;
    }
}
```

## API Reference

- `sendStream<TReq, TChunk>(manager, name, type, payload, options?): AsyncIterable<TChunk>`.
- `interface StreamCapableManager { events; postMessage<T>(name, type, payload, options?) }`.
- `interface StreamRequestEnvelope<TReq> { streamId: string; payload: TReq }`.
- `type StreamIdFactory = () => string`.
- `interface SendStreamOptions { signal?: AbortSignal; transfer?: Transferable[]; idFactory?: StreamIdFactory }`.

## Implementation Notes

The iterator uses an internal queue + `resolveNext` continuation pattern:
every received frame pushes onto the queue and calls `resolveNext` if the
consumer was waiting; the consumer's next-iteration loop drains the queue
and then awaits on a fresh promise. This avoids buffering the whole stream
in memory and gives the consumer natural backpressure (the consumer pulls).
The initial payload is wrapped in a `StreamRequestEnvelope` so the worker
sees both the `streamId` and the original payload — without that wrapper
the worker would have no way to correlate frame ids to incoming requests.
The cancel frame `stream:cancel` is sent via the same `postMessage` channel
so the worker side can stop producing without needing a separate control
channel.