`error-codes` — AudioCliError and EXIT_CODES

(no submodules)

Purpose

This module is the structured error and exit-code boundary for @suaveplan/audio-cli. It defines the six AUDIO_CLI.* codes the package throws, the AudioCliError class extending SuaveplanError carrying code, cause, and context, the AUDIO_CLI_ERROR_METADATA table with descriptions and severity, and the EXIT_CODES table that maps every code onto a stable non-zero Unix exit integer.

It also exports exitCodeFor, which the CLI entry point calls in its global catch to convert any thrown value into a process.exit argument. The mapping is part of the public contract: CI pipelines and shell scripts depend on it, so changing a code-to-integer mapping is a breaking change.

Features

Six-code registry (INVALID_ARGS, UNKNOWN_OP, INPUT_NOT_FOUND, BAD_OUTPUT, PIPELINE_FAILED, ABORTED) via defineCodes.
AudioCliError extends SuaveplanError with strongly-typed code.
EXIT_CODES immutable table (0-reserved, 2/3/4/5/130).
exitCodeFor(err) unknown-shape fallback to 1.
Idempotent registerAudioCliErrorCodes() for cross-package code-table fans.

Usage: Basic

import { AudioCliError, AUDIO_CLI_CODES, exitCodeFor } from "@suaveplan/audio-cli/error-codes";

try {
    throw new AudioCliError(AUDIO_CLI_CODES.INPUT_NOT_FOUND, "audio-cli.input-not-found", {
        context: { path: "missing.wav" },
    });
} catch (err) {
    process.exit(exitCodeFor(err));
}

Usage: Advanced

import {
    AUDIO_CLI_CODES,
    AUDIO_CLI_ERROR_METADATA,
    EXIT_CODES,
    type AudioCliErrorCode,
} from "@suaveplan/audio-cli/error-codes";

// Render a help table of every code, its severity, and the exit it produces.
for (const [code, meta] of Object.entries(AUDIO_CLI_ERROR_METADATA)) {
    const c = code as AudioCliErrorCode;
    console.log(`${c}\t${meta.severity}\texit=${EXIT_CODES[c]}\t${meta.description}`);
}

API Reference

AUDIO_CLI_CODES — frozen string-literal record of the six codes.
AudioCliErrorCode — union of those code values.
AudioCliError(code, messageKey, options?) — SuaveplanError subclass.
AUDIO_CLI_ERROR_METADATA — per-code { description, severity }.
EXIT_CODES — per-code non-zero integer.
registerAudioCliErrorCodes() — idempotent registry hook.
exitCodeFor(err) — map a thrown value to an exit code (0/1/EXIT_CODES).

Implementation Notes

The error class follows the same pattern as AudioEngineServerError and AudioCodecsError in sibling packages. defineCodes ensures the literal record is frozen at the type level so a typo in AUDIO_CLI_CODES.foo fails to compile. exitCodeFor walks two shapes: an AudioCliError instance (cheap typeof check) and a duck-typed { code: string } so foreign errors carrying a known AUDIO_CLI.* code still map correctly. Anything else falls through to 1, the canonical "uncaught error" Unix convention.

3.0 KiB Raw Blame History

error-codes — AudioCliError and EXIT_CODES