# 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.