Interface: ByteStore<R>

Defined in: lib/contracts/byte_store.ts:28

Unified "give bytes, get a reader" persistence contract.

Remarks

For the purposes of storage there is no meaningful distinction between text and binary — bytes are bytes. ByteStore is the single low-level shape every ADK storage layer implements: hand it bytes under an id, get back a replayable reader R; read or delete by the same id later. The generic R is the reader the store hands out — different reader contracts (line-indexed @nhtio/adk!SpoolReader vs binary-streamed @nhtio/adk!MediaReader) are distinguished by the R instantiation, not by separate store interfaces. See the SpoolStore and MediaStore aliases for the two concrete semantics.

write accepts a string, a Uint8Array, or a ReadableStream<Uint8Array>. The stream form is the point of the contract: a durable store can persist an arbitrarily large payload straight to disk/object storage without first materializing it in memory. String input is encoded as UTF-8. The returned reader is only guaranteed readable once the write result has resolved.

All three methods may be synchronous or asynchronous so that in-memory implementations are not forced to pay promise overhead while I/O-backed implementations stay async. Note that any implementation accepting a ReadableStream must return a Promise for that input — draining a stream cannot be synchronous.

Type Parameters

Type Parameter
R

Methods

delete()

delete(id: string): boolean | Promise<boolean>;

Defined in: lib/contracts/byte_store.ts:58

Removes the entry under id.

Parameters

Parameter	Type	Description
id	string	Identifier whose entry should be removed.

Returns

boolean | Promise<boolean>

true if an entry existed and was removed; false otherwise (or a Promise of one).

---

read()

read(id: string): R | Promise<R | undefined> | undefined;

Defined in: lib/contracts/byte_store.ts:50

Returns a reader over the bytes previously written under id, or undefined if no entry exists.

Parameters

Parameter	Type	Description
id	string	Identifier supplied to a prior ByteStore.write call.

Returns

R | Promise<R | undefined> | undefined

A reader over the stored bytes, undefined, or a Promise of either.

---

write()

write(id: string, bytes:
  | string
  | Uint8Array<ArrayBufferLike>
| ReadableStream<Uint8Array<ArrayBufferLike>>): R | Promise<R>;

Defined in: lib/contracts/byte_store.ts:41

Persists bytes under id and returns a reader over them.

Parameters

Parameter	Type	Description
id	string	Identifier used to retrieve or delete the bytes later.
bytes	| string | Uint8Array<ArrayBufferLike> | ReadableStream<Uint8Array<ArrayBufferLike>>	The payload, as a string, Uint8Array, or ReadableStream<Uint8Array>.

Returns

R | Promise<R>

A reader over the stored bytes (or a Promise of one).

Remarks

Re-writing the same id replaces the prior entry. string input is encoded as UTF-8; Uint8Array and ReadableStream<Uint8Array> are stored byte-faithfully. Stream input necessarily resolves asynchronously.