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

processDataStream

(no submodules)

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

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

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.