Initial Commit

packages/media/audio/audio-analysis-spectrum/src/error-codes/error-codes.ts

@@ -0,0 +1,73 @@
+import {
+    defineCodes,
+    SuaveplanError,
+    type SuaveplanErrorOptions,
+} from "@suaveplan/error";
+
+/**
+ * Stable error-code registry for `@suaveplan/audio-analysis-spectrum`.
+ * `defineCodes` namespaces the string values as `AUDIO_ANALYSIS_SPECTRUM.<REASON>`.
+ */
+export const AUDIO_ANALYSIS_SPECTRUM_CODES = defineCodes(
+    "AUDIO_ANALYSIS_SPECTRUM",
+    ["INVALID_OPTIONS", "INVALID_FRAME", "ABORTED"] as const
+);
+
+export type AudioAnalysisSpectrumErrorCode =
+    (typeof AUDIO_ANALYSIS_SPECTRUM_CODES)[keyof typeof AUDIO_ANALYSIS_SPECTRUM_CODES];
+
+export interface AudioAnalysisSpectrumErrorMetadata {
+    readonly description: string;
+    readonly severity: "warning" | "error";
+}
+
+export const AUDIO_ANALYSIS_SPECTRUM_ERROR_METADATA: Readonly<
+    Record<AudioAnalysisSpectrumErrorCode, AudioAnalysisSpectrumErrorMetadata>
+> = Object.freeze({
+    [AUDIO_ANALYSIS_SPECTRUM_CODES.INVALID_OPTIONS]: {
+        description:
+            "A public options object failed Zod boundary validation. The Zod `issues` array is attached on `error.context.issues`.",
+        severity: "error",
+    },
+    [AUDIO_ANALYSIS_SPECTRUM_CODES.INVALID_FRAME]: {
+        description:
+            "The FFT was asked to transform a frame whose size is not a power of two between 256 and 32768 inclusive. The offending size is on `error.context.frameSize`.",
+        severity: "error",
+    },
+    [AUDIO_ANALYSIS_SPECTRUM_CODES.ABORTED]: {
+        description:
+            "Analysis was cancelled by an `AbortSignal` before or during the scan. The signal reason, if any, is on `error.context.reason`.",
+        severity: "warning",
+    },
+});
+
+/**
+ * Concrete `SuaveplanError` subclass for every fault raised by this package.
+ * The base constructor is `protected`; this subclass widens it to `public`
+ * while remaining non-trivial via the `category` field, so it constructs
+ * without any static-analysis suppression.
+ */
+export class AudioAnalysisSpectrumError extends SuaveplanError<AudioAnalysisSpectrumErrorCode> {
+    public readonly category = "audio-analysis-spectrum" as const;
+
+    public constructor(
+        code: AudioAnalysisSpectrumErrorCode,
+        messageKey: string,
+        options: SuaveplanErrorOptions = {}
+    ) {
+        super(code, messageKey, options);
+        this.name = "AudioAnalysisSpectrumError";
+    }
+}
+
+/**
+ * Idempotent registration hook. Metadata is already frozen and exported for
+ * direct lookup; consumers binding code registries to OTel attributes or
+ * report-builders can call this once at startup to ensure the registry
+ * has been touched.
+ */
+export function registerAudioAnalysisSpectrumErrorCodes(): void {
+    // No-op — registry side-effects are static at module load.
+}
+
+registerAudioAnalysisSpectrumErrorCodes();