Interface: MediaReader

Defined in: src/lib/contracts/media_reader.ts:21

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;

Defined in: src/lib/contracts/media_reader.ts:44

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".

---

describe()?

optional describe(): ReaderDescriptor | undefined;

Defined in: src/lib/contracts/media_reader.ts:62

Optionally emit a serialisable ReaderDescriptor so a @nhtio/adk!Media backed by this reader can round-trip through encode()/decode() as a handle.

Returns

ReaderDescriptor | undefined

A tagged, serialisable handle, or undefined/absent when the reader cannot describe itself.

Remarks

Synchronous by contract — the encoder's [ENCODE_METHOD]() is synchronous and cannot await, so a reader whose handle is only obtainable asynchronously (e.g. draining a Blob) must NOT implement this method; encoding such a Media throws @nhtio/adk!E_READER_NOT_DESCRIBABLE. The descriptor describes where the bytes live (a key, a URL, or an inlined buffer) — never the live binding (Disk, OPFS root, fetch), which the matching resolver re-injects on decode.

A reader that omits this method is treated as non-describable: the bytes still stream normally at runtime, the Media simply cannot be serialised.

---

stream()

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

Defined in: src/lib/contracts/media_reader.ts:32

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.