skills/docs/foundation/flow/streams/src/utils/stream/validate-integrity/validate-integrity.md

validateStreamIntegrity

(no submodules)

Purpose

validateStreamIntegrity walks a ReadableStream<Uint8Array> chunk by chunk and applies a caller-supplied predicate to each chunk. It returns true if every chunk satisfies the predicate and the stream closes cleanly, or false the first time the predicate rejects a chunk. On a rejection it cancels the underlying reader so upstream producers can release resources rather than continuing to fill a buffer that will be discarded.

The function is the streams-package equivalent of "fold a boolean over the chunks". It is small but worth centralising because the short-circuit + reader cancel + lock-release dance is easy to get wrong, especially when combined with WHATWG Streams' lock semantics around early teardown.

Features

• Short-circuits on first failure — does not consume the rest of the stream.
• Cancels the underlying reader on failure to free upstream resources.
• Always releases the reader lock via finally, even on validator throws.
• Returns true for an empty stream (vacuous truth).
• Synchronous predicate keeps the per-chunk cost minimal.

Usage: Basic Example

import { validateStreamIntegrity } from "@suaveplan/streams/utils/stream/validate-integrity/validate-integrity";

const allEven = await validateStreamIntegrity(stream, (chunk) =>
    chunk.every((b) => b % 2 === 0)
);

Usage: Advanced Example

import { validateStreamIntegrity } from "@suaveplan/streams/utils/stream/validate-integrity/validate-integrity";

// Each frame: 4-byte big-endian length || N payload bytes || 1-byte checksum.
// Verify checksum without buffering the whole stream.
function checksummed(chunk: Uint8Array): boolean {
    if (chunk.byteLength < 5) return false;
    const dv = new DataView(chunk.buffer, chunk.byteOffset, chunk.byteLength);
    const len = dv.getUint32(0);
    if (chunk.byteLength !== 4 + len + 1) return false;
    let sum = 0;
    for (let i = 0; i < 4 + len; i++) sum = (sum + chunk[i]!) & 0xff;
    return sum === chunk[chunk.byteLength - 1];
}

const ok = await validateStreamIntegrity(stream, checksummed);

API Reference

validateStreamIntegrity(stream, validate): Promise<boolean>

• stream: ReadableStream<Uint8Array> — source stream.
• validate: (chunk: Uint8Array) => boolean — predicate run per chunk.
• Returns — Promise<boolean> resolving to true if all chunks pass, false on first failure.
• Throws — rejects with whatever the underlying stream throws.

Implementation Notes

• The reader is acquired via getReader() and released in finally. On the failure path we additionally await reader.cancel() to ensure the upstream source observes the cancellation before we resolve false.
• The predicate is invoked exactly once per non-empty chunk; chunks of size 0 still trigger a call (a zero-byte chunk is observable in the WHATWG model and a strict validator may want to reject it).
• A predicate throw propagates as a rejection rather than a false; callers who wish otherwise can wrap their predicate in a try/catch.