suaveplan/packages/foundation/flow/streams-chunk-queue/src/errors/streams-chunk-queue-error.md

streams-chunk-queue-error

(no submodules)

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

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

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

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.