# validateStreamIntegrity

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## 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

```ts
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

```ts
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.