`error-codes`

(no submodules)

Purpose

This module is the canonical registry of every error code raised by @suaveplan/audio-decode-wav, alongside the structured AudioDecodeWavError class that carries discriminants for filtering. The registry is the contract — every code is reachable from a real call site exercised by the test suite, per AGENTS.md §2c. The error class extends @suaveplan/error's SuaveplanError so it threads through the repo-wide error machinery (OTel span event adapter, redaction, i18n resolver, Zod-validated wire format) without bespoke wiring.

Features

Seven codes via defineCodes("AUDIO_DECODE.WAV", […]): INVALID_INPUT, UNSUPPORTED_FORMAT, CORRUPT_HEADER, TRUNCATED_BODY, ABORTED, RESAMPLE_UNSUPPORTED, STREAM_INVARIANT_VIOLATION.
AudioDecodeWavError carries six dimension-specific discriminants: format (for UNSUPPORTED_FORMAT), decodedSampleRate + requestedSampleRate (for RESAMPLE_UNSUPPORTED), op (every error), bytesAvailable + bytesDeclared (for TRUNCATED_BODY).
AudioFormatType union covers the WAV format codes recognised at the inspect layer: pcm, ieee-float, alaw, mulaw, ima-adpcm, ms-adpcm, extensible, unknown.
Registry is frozen at module load; Object.values(AUDIO_DECODE_WAV_CODES) is the authoritative list for exhaustion tests.

Usage: Basic

import {
    AUDIO_DECODE_WAV_CODES,
    AudioDecodeWavError,
} from "@suaveplan/audio-decode-wav";

throw new AudioDecodeWavError(
    AUDIO_DECODE_WAV_CODES.INVALID_INPUT,
    "WAV byte buffer is empty",
    { op: "decodeWav" }
);

Usage: Advanced

import {
    AUDIO_DECODE_WAV_CODES,
    AudioDecodeWavError,
    decodeWav,
} from "@suaveplan/audio-decode-wav";

try {
    await decodeWav(bytes, { targetSampleRate: 48000 });
} catch (err) {
    if (
        err instanceof AudioDecodeWavError &&
        err.code === AUDIO_DECODE_WAV_CODES.RESAMPLE_UNSUPPORTED
    ) {
        console.warn(
            `cannot decode-and-resample: ${err.decodedSampleRate} → ${err.requestedSampleRate}`
        );
    }
}

API Reference

const AUDIO_DECODE_WAV_CODES — { INVALID_INPUT: "AUDIO_DECODE.WAV.INVALID_INPUT", … }. Frozen.
type AudioDecodeWavErrorCode — union of every code's string value.
type AudioFormatType — "pcm" | "ieee-float" | "alaw" | "mulaw" | "ima-adpcm" | "ms-adpcm" | "extensible" | "unknown".
interface AudioDecodeWavErrorOptions extends SuaveplanErrorOptions — adds format, decodedSampleRate, requestedSampleRate, op, bytesAvailable, bytesDeclared.
class AudioDecodeWavError extends SuaveplanError<AudioDecodeWavErrorCode> — exposes every option above as a readonly field; name === "AudioDecodeWavError".

Implementation Notes

The registry uses defineCodes so the code-string format is uniform across the project (<namespace>.<reason>), making OTel attribute filtering by code prefix trivial. The error class follows the same discriminant-surface pattern as BundleUriError in @suaveplan/storage-uri-plugin-bundle — every dimension a downstream observer might filter on is a typed readonly field rather than buried in the message string. RESAMPLE_UNSUPPORTED deliberately carries both rates so the failing call can be replayed against a downstream resampler without re-decoding to discover the source rate.

3.4 KiB Raw Blame History

error-codes