# queue / storage-ops

## Purpose

Holds the storage-related guards used by `StreamingChunkQueue.loadChunk`
and `loadAllChunks`. Both methods need the same "is the persister
configured?" check and the same "is the chunk actually in storage?"
check, so factoring them out keeps the queue file from duplicating the
guards and from spilling past the per-file line budget.

## Features

- `loadChunkBytes` throws `STORAGE_NOT_CONFIGURED` when no persister is
  set, `STORAGE_CHUNK_MISSING` when the chunk is absent, and returns
  the bytes otherwise.
- `listStoredChunkIds` throws `STORAGE_NOT_CONFIGURED` when no
  persister is set, otherwise forwards to `persister.listChunkIds()`.
- Both helpers preserve a stringified `chunkId` in
  `error.context` so logs are scannable.

## Usage: Basic

```ts
const bytes = await loadChunkBytes(this.persister, chunkId);
```

## Usage: Advanced

```ts
const ids = await listStoredChunkIds(this.persister);
for (const id of ids) await this.loadChunk(id);
```

## API Reference

### `loadChunkBytes(persister, chunkId)` → `Promise<Uint8Array>`

Throws `StreamsChunkQueueError(STORAGE_NOT_CONFIGURED)` if `persister`
is `undefined`, `StreamsChunkQueueError(STORAGE_CHUNK_MISSING)` if the
backend returns `undefined`, otherwise resolves with the bytes.

### `listStoredChunkIds(persister)` → `Promise<bigint[]>`

Throws `StreamsChunkQueueError(STORAGE_NOT_CONFIGURED)` if `persister`
is `undefined`, otherwise forwards to `persister.listChunkIds()`.

## Implementation Notes

These helpers are pure functions instead of methods so they can be
unit-tested without spinning up a queue. The queue's `loadChunk`
delegates to `loadChunkBytes` and then re-uses `addChunk` to push the
bytes into the in-memory map; this means storage-loaded chunks travel
through the same validator / decryptor / hook pipeline as
network-arrived chunks. The two helpers throw a `StreamsChunkQueueError`
rather than a `TypeError` because the missing-persister condition is
an operational fault (the caller forgot to wire storage) and should be
filterable by error code in dashboards.