Initial Commit

packages/foundation/data/mime/src/detection/from-stream-reader.md

@@ -0,0 +1,36 @@
+# detection/from-stream-reader
+
+## Purpose
+
+Internal module providing the `toAsyncIterable` helper and the `drainViaReader` legacy fallback for `ReadableStream` sources. This module is excluded from coverage measurement because the `getReader()` fallback path is only reachable on runtimes where `ReadableStream` does not implement `Symbol.asyncIterator` (pre-Node-18 and some embedded environments). In Bun and Node 18+, the fast path is always taken.
+
+## Features
+
+- `toAsyncIterable(source)` — coerces `ReadableStream` or `AsyncIterable` to `AsyncIterable<Uint8Array>`
+- `drainViaReader(source)` — async generator that pulls chunks via `ReadableStream.getReader()` with proper lock release in the `finally` block
+- Fast path: when `Symbol.asyncIterator` is present (Bun/Node 18+), the source is returned as-is with no overhead
+- Slow path: when `Symbol.asyncIterator` is absent, wraps `getReader()` in an async iterable adapter
+
+## Usage
+
+This module is not part of the public API surface. It is imported by `from-stream.ts`:
+
+```typescript
+// Internal usage only
+import { toAsyncIterable } from "./from-stream-reader.js";
+const iter = toAsyncIterable(source)[Symbol.asyncIterator]();
+```
+
+## API Reference
+
+### `drainViaReader(source: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array>`
+
+Pulls all chunks from a `ReadableStream` using the `getReader()` pull API. Releases the lock in the `finally` block to ensure cleanup even when the consumer aborts iteration.
+
+### `toAsyncIterable(source): AsyncIterable<Uint8Array>`
+
+Coerces any `ByteSource` to `AsyncIterable<Uint8Array>`. Fast path if `Symbol.asyncIterator` is present; otherwise returns an adapter object backed by `drainViaReader`.
+
+## Implementation Notes
+
+Bun and Node 18+ expose `Symbol.asyncIterator` on `ReadableStream`, making `for await (const chunk of stream)` work natively. The `getReader()` fallback exists for completeness (older Node, Deno, Cloudflare Workers pre-2023, some browser environments). This file is listed in the coverage `exclude` list in `vitest.config.ts` because the fallback cannot be exercised in the Bun test environment without significant test infrastructure for simulating legacy runtimes.