# streams-chunk-queue-error

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`StreamsChunkQueueError` is the single typed error class raised by every
public surface of `@suaveplan/streams-chunk-queue`. It extends
`SuaveplanError` so callers get the full enterprise error contract: a
stable `code` string, a structured `context` map, a redactable wire form,
OpenTelemetry span-event mapping, and an unbroken cause chain. The
package registers every code through `defineCodes`, guaranteeing the
codes are immutable, frozen, and reachable from real call sites.

## Features

- One frozen registry — `STREAMS_CHUNK_QUEUE_CODES` — exposes the eight
  canonical codes (`INVALID_TOTAL_CHUNKS`, `INVALID_CHUNK_ID`,
  `STORAGE_NOT_CONFIGURED`, `STORAGE_CHUNK_MISSING`, `VALIDATION_FAILED`,
  `DECRYPTION_FAILED`, `STREAM_TIMEOUT`, `RATE_LIMIT_EXHAUSTED`).
- One literal-typed error class — `StreamsChunkQueueError` — narrows
  `code` through `instanceof`.
- Cause chaining via `SuaveplanError`'s `{ cause }` option, so the
  underlying network or crypto failure is preserved.
- Structured `context` map (e.g. `{ chunkId, fileId, totalChunks }`) for
  observability and i18n.

## Usage: Basic

```ts
import {
    STREAMS_CHUNK_QUEUE_CODES,
    StreamsChunkQueueError,
} from "@suaveplan/streams-chunk-queue";

throw new StreamsChunkQueueError(
    STREAMS_CHUNK_QUEUE_CODES.INVALID_CHUNK_ID,
    `chunk ${chunkId} out of range`,
    { context: { chunkId: chunkId.toString() } },
);
```

## Usage: Advanced

```ts
try {
    await queue.addChunk(chunkId, bytes);
} catch (err) {
    if (
        err instanceof StreamsChunkQueueError &&
        err.code === STREAMS_CHUNK_QUEUE_CODES.VALIDATION_FAILED
    ) {
        observabilityBus.publish("chunk-fraud", {
            chunkId: err.context?.chunkId,
            cause: err.cause,
        });
    }
    throw err;
}
```

## API Reference

### `STREAMS_CHUNK_QUEUE_CODES`

A frozen record built by `defineCodes("STREAMS_CHUNK_QUEUE", […])`. Each
key maps to the fully-qualified code string
`STREAMS_CHUNK_QUEUE.<reason>`.

### `StreamsChunkQueueErrorCode`

Discriminated union of every code in the registry.

### `StreamsChunkQueueError`

```ts
new StreamsChunkQueueError(
    code: StreamsChunkQueueErrorCode,
    message: string,
    options?: { cause?: unknown; context?: Record<string, unknown> },
)
```

- `code` — one of the registered code strings.
- `message` — human-readable description (or i18n message key).
- `options.cause` — underlying error preserved for `walkCauses`.
- `options.context` — structured fields surfaced through the wire schema.

## Implementation Notes

`SuaveplanError` is `abstract`, so this module supplies the concrete
subclass. The constructor delegates to `super` with the cause and context
forwarded through `SuaveplanErrorOptions`. Codes are intentionally
namespaced with `STREAMS_CHUNK_QUEUE.` so multi-package log scans can
filter by prefix without false positives from sibling packages.