`error-codes`

(no submodules)

Purpose

This module owns the stable, namespaced error-code registry for @suaveplan/audio-codec-ffmpeg-native. Every operational failure raised by the package — binary-resolution mishaps, spawn/IO errors, codec-level decode/encode failures, lifecycle events (timeout, abort) and input-validation rejections — flows through a single AudioCodecFfmpegNativeError typed subclass whose code field is narrowed to the union of AUDIO_CODEC_FFMPEG_NATIVE.* strings.

This centralisation lets consumers do exhaustive switch (err.code) dispatch with TypeScript checking, and it gives observability the canonical label set to attribute span events and metric counters against without per-call-site stringly-typed labels.

Features

Eight stable codes covering binary, spawn, decode, encode, timeout, abort, unsupported-codec and invalid-PCM failure modes.
defineCodes("AUDIO_CODEC_FFMPEG_NATIVE", [...]) produces frozen <namespace>.<reason> constants and a precise literal-union type.
AudioCodecFfmpegNativeError subclass of SuaveplanError preserves cause, context, traceId, and the inherited timestamp.
AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA records per-code description + severity for human-readable surfacing (logs, dashboards).

Usage: Basic

import {
    AUDIO_CODEC_FFMPEG_NATIVE_CODES,
    AudioCodecFfmpegNativeError,
} from "@suaveplan/audio-codec-ffmpeg-native/error-codes";

throw new AudioCodecFfmpegNativeError(
    AUDIO_CODEC_FFMPEG_NATIVE_CODES.BINARY_MISSING,
    "ffmpeg-native.binary.missing",
);

Usage: Advanced

import {
    AUDIO_CODEC_FFMPEG_NATIVE_CODES,
    AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA,
    AudioCodecFfmpegNativeError,
} from "@suaveplan/audio-codec-ffmpeg-native/error-codes";

try {
    await someFfmpegOperation();
} catch (cause) {
    const code = AUDIO_CODEC_FFMPEG_NATIVE_CODES.DECODE_FAILED;
    throw new AudioCodecFfmpegNativeError(code, "ffmpeg-native.decode.failed", {
        cause,
        context: {
            severity: AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA[code].severity,
            stderr: "...last 4 KiB of ffmpeg stderr...",
        },
    });
}

API Reference

AUDIO_CODEC_FFMPEG_NATIVE_CODES — frozen record of namespaced codes.
AudioCodecFfmpegNativeErrorCode — string-literal union of all codes.
AUDIO_CODEC_FFMPEG_NATIVE_ERROR_METADATA — Record<Code, { description, severity }>.
AudioCodecFfmpegNativeError — concrete SuaveplanError subclass; constructor takes (code, messageKey, options); options.context.stderr carries the ffmpeg stderr tail when available.

Implementation Notes

The eight codes are intentionally minimal: spec-level failure scenarios collapse into one of these eight. BINARY_MISSING is reserved for the resolution preflight, SPAWN_FAILED for child_process.spawn errors before any output is read, and DECODE_FAILED / ENCODE_FAILED are the post-spawn ffmpeg-exit failures. TIMEOUT and ABORTED share the SIGTERM-then-SIGKILL escalation path; only their code distinguishes the trigger.

AudioCodecFfmpegNativeError deliberately mirrors the AudioCodecsError shape (public constructor + category literal + name override) so that multi-codec error funnels can discriminate by category without runtime-importing every package.

3.3 KiB Raw Permalink Blame History

error-codes