Initial Commit

packages/foundation/flow/streams/src/utils/stream/process-data-stream/process-data-stream.md

@@ -0,0 +1,71 @@
+# processDataStream
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`processDataStream` is the drain-side complement to `createDataStream`. It
+collects every byte emitted by a `ReadableStream<Uint8Array>` into a single
+`Uint8Array` and hands the result to a processor function that maps the bytes
+into a domain value `T`. It exists so consumers can write straight-line code —
+"give me the parsed result" — without explicitly looping over the reader.
+
+The function is intentionally small but centralising it pays off: it standardises
+how upstream errors propagate, how an empty stream is represented (as an empty
+`Uint8Array`, not `undefined`), and gives observability/instrumentation a
+single chokepoint to wrap when needed.
+
+## Features
+
+- Accepts sync and async processor functions.
+- Returns the processor's resolved value with full type inference.
+- Concatenates multiple chunks transparently before processing.
+- Propagates upstream stream errors and processor throws as a rejected promise.
+
+## Usage: Basic Example
+
+```ts
+import { processDataStream } from "@suaveplan/streams/utils/stream/process-data-stream/process-data-stream";
+
+const text = await processDataStream(stream, (b) =>
+    new TextDecoder().decode(b)
+);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { processDataStream } from "@suaveplan/streams/utils/stream/process-data-stream/process-data-stream";
+import { decode } from "@msgpack/msgpack";
+
+interface Record {
+    id: string;
+    payload: unknown;
+}
+
+async function readMsgpack<T = Record>(stream: ReadableStream<Uint8Array>) {
+    return processDataStream(stream, async (bytes) => {
+        // hand off to a worker thread for large payloads
+        return decode(bytes) as T;
+    });
+}
+```
+
+## API Reference
+
+### `processDataStream<T>(stream, processor): Promise<T>`
+
+- **`stream: ReadableStream<Uint8Array>`** — source of bytes to drain.
+- **`processor: (data: Uint8Array) => T | Promise<T>`** — function that maps
+  the concatenated bytes into a domain value.
+- **Returns** — `Promise<T>` resolving with `processor`'s return value.
+- **Throws** — rejects with whatever the underlying stream or processor throws.
+
+## Implementation Notes
+
+- Built on top of `streamToUint8Array`; the same single-allocation behaviour
+  applies (chunks pre-summed before allocation).
+- The processor is awaited even when its return type is synchronous to keep a
+  single promise contract for callers.
+- Universal — no Node or DOM globals beyond the WHATWG Streams API.