Interface: MediaReader

Re-openable byte source contract for a Media instance.

Remarks

Peer to @nhtio/adk!SpoolReader but tuned for binary streaming rather than line-indexed text. Each stream() call must return a fresh, drainable ReadableStream over the same underlying bytes — implementations model replay: in-memory readers reconstitute the stream from the buffer, file-backed readers reopen the file handle, HTTP-backed readers re-issue the fetch, cloud blob readers re-issue the GET. The implementor owns the storage and the cost of keeping the underlying source addressable. Implementors whose underlying source is genuinely non-replayable (a raw HTTP body they were handed once) are responsible for caching locally before constructing the Media.

Both methods may be synchronous or asynchronous to accommodate both in-memory and I/O-backed implementations without forcing unnecessary promise overhead on simple cases.

Methods

byteLength()

byteLength(): number | Promise<number | undefined> | undefined;

Returns the total number of bytes in the underlying data, or undefined if unknown.

Returns

number | Promise<number | undefined> | undefined

The byte length of the underlying data, or undefined when unknown.

Remarks

Used for telemetry, budget checks, and pre-flight provider size validation without forcing a stream drain. Sources of unknown length may return undefined — absence is treated as "unknown", not "zero".

---

stream()

stream():
  | ReadableStream<Uint8Array<ArrayBufferLike>>
| Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;

Re-opens the underlying byte source and returns a fresh ReadableStream.

Returns

| ReadableStream<Uint8Array<ArrayBufferLike>> | Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>

A drainable ReadableStream of Uint8Array chunks over the underlying bytes.

Remarks

Each call yields a new, drainable stream over the same bytes. Render code that needs the full buffer (e.g. base64-encoding an inline image_url) drains the stream; render code that can forward the stream (e.g. multipart upload) passes the stream through without buffering.