error-codes

(no submodules)

Purpose

This module owns the stable, machine-readable error-code registry for @suaveplan/audio-analysis-loudness. Every fault raised by the loudness analyser is reported through a single AudioAnalysisLoudnessError subclass of SuaveplanError, carrying a code drawn from AUDIO_ANALYSIS_LOUDNESS_CODES and rich context such as Zod issue lists or abort reasons.

The registry exists so downstream observability, alerting, and i18n layers can bind to stable string identifiers instead of fragile message strings. Codes never change once shipped — new fault classes get new codes, never re-purposed old ones.

Features

Three stable codes: INVALID_OPTIONS, EMPTY_DOCUMENT, ABORTED.
Frozen metadata table (description, severity) keyed by code.
AudioAnalysisLoudnessError subclass with public constructor and a category discriminant that satisfies the no-suppression-comment rule without any // biome-ignore.
Idempotent registerAudioAnalysisLoudnessErrorCodes() hook.

Usage: Basic

import {
  AUDIO_ANALYSIS_LOUDNESS_CODES,
  AudioAnalysisLoudnessError,
} from "@suaveplan/audio-analysis-loudness/error-codes";

throw new AudioAnalysisLoudnessError(
  AUDIO_ANALYSIS_LOUDNESS_CODES.EMPTY_DOCUMENT,
  "audio-analysis-loudness.empty-document",
  { context: { sourceLength: 0 } },
);

Usage: Advanced

import {
  AUDIO_ANALYSIS_LOUDNESS_CODES,
  AUDIO_ANALYSIS_LOUDNESS_ERROR_METADATA,
  registerAudioAnalysisLoudnessErrorCodes,
} from "@suaveplan/audio-analysis-loudness/error-codes";

registerAudioAnalysisLoudnessErrorCodes();

for (const code of Object.values(AUDIO_ANALYSIS_LOUDNESS_CODES)) {
  const meta = AUDIO_ANALYSIS_LOUDNESS_ERROR_METADATA[code];
  console.log(code, meta.severity, meta.description);
}

API Reference

AUDIO_ANALYSIS_LOUDNESS_CODES — frozen object mapping reason names to namespaced code strings.
AudioAnalysisLoudnessErrorCode — union of every code string.
AUDIO_ANALYSIS_LOUDNESS_ERROR_METADATA — frozen lookup keyed by code.
AudioAnalysisLoudnessError — SuaveplanError subclass.
registerAudioAnalysisLoudnessErrorCodes() — idempotent startup hook.

Implementation Notes

defineCodes produces both the runtime object and the literal type union; the returned object is frozen, so attempts to mutate codes at runtime fail in strict mode. The metadata table is independently Object.freeze-d so consumers cannot mutate descriptions or severities. The category field on the error class is what keeps the subclass "non-trivial" enough for the static analyser — without it, biome flags the override as useless.

2.7 KiB Raw Blame History