---
url: 'https://adk.nht.io/api/@nhtio/adk/common/interfaces/ByteStore.md'
description: 'Unified "give bytes, get a reader" persistence contract.'
---

# Interface: ByteStore\<R>

Defined in: [lib/contracts/byte\_store.ts:28](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/byte_store.ts#L28)

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](../../spooled_artifact/interfaces/SpoolReader.md) vs binary-streamed [@nhtio/adk!MediaReader](MediaReader.md)) are
distinguished by the `R` instantiation, not by separate store interfaces. See the [SpoolStore](../type-aliases/SpoolStore.md)
and [MediaStore](../type-aliases/MediaStore.md) 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()

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

Defined in: [lib/contracts/byte\_store.ts:58](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/byte_store.ts#L58)

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()

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

Defined in: [lib/contracts/byte\_store.ts:50](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/byte_store.ts#L50)

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](#write) call. |

#### Returns

`R` | `Promise`<`R` | `undefined`> | `undefined`

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

***

### write()

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

Defined in: [lib/contracts/byte\_store.ts:41](https://github.com/NHTIO/ADK/blob/v1.20260605.0/src/lib/contracts/byte_store.ts#L41)

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.