error-codes

(no submodules)

Purpose

Defines the stable SPESSASYNTH.* error-code namespace used by every other module in @suaveplan/audio-fx-plugin-spessasynth. The codes are surfaced through defineCodes from @suaveplan/error, which makes them discoverable to wire-format consumers (the API gateway, the OpenTelemetry span-event adapter, the i18n message resolver) without importing this package directly.

Every operational failure raised by the loader, MIDI router, parameter surface, voice manager, or the SpessaSynthPlugin orchestrator carries one of these codes plus a stable message key. The codes are intentionally narrow — load-failure vs parse-failure vs unsupported-format vs voice-limit vs initialisation vs MIDI/parameter validation vs module-unavailable — so that consumers can pattern-match on error.code and decide whether to retry, fall back to a smaller SoundFont, or surface a permanent error to the operator.

Features

SPESSASYNTH_CODES — closed enum of nine codes registered via defineCodes so cross-package consumers can refer to them by literal string.
SPESSASYNTH_ERROR_METADATA — frozen record giving every code a one-line human description and a severity (warning for VOICE_LIMIT_EXCEEDED, error for the rest).
SpessaSynthError — SuaveplanError subclass with a category: "audio-fx-spessasynth" discriminator and a descriptive name derived from the code's severity, suitable for log-aggregation grouping.
Re-exported through the package barrel and the ./error-codes subpath so consumers tree-shake to just the codes they need.

Usage: Basic

import {
    SpessaSynthError,
    SPESSASYNTH_CODES,
} from "@suaveplan/audio-fx-plugin-spessasynth/error-codes";

throw new SpessaSynthError(
    SPESSASYNTH_CODES.NOT_INITIALIZED,
    "spessasynth.process-before-init"
);

Usage: Advanced

import {
    SpessaSynthError,
    SPESSASYNTH_CODES,
    SPESSASYNTH_ERROR_METADATA,
} from "@suaveplan/audio-fx-plugin-spessasynth/error-codes";

try {
    await plugin.init({ soundFontBytes });
} catch (err) {
    if (err instanceof SpessaSynthError) {
        const meta = SPESSASYNTH_ERROR_METADATA[err.code];
        logger[meta.severity]("spessasynth init failed", {
            code: err.code,
            description: meta.description,
            cause: err.cause,
        });
        if (err.code === SPESSASYNTH_CODES.SOUNDFONT_PARSE_FAILED) {
            // attempt a known-good fallback SF2
        }
    }
}

API Reference

SPESSASYNTH_CODES — Record<Code, "SPESSASYNTH.<Code>">.
SpessaSynthErrorCode — string-literal union of every code.
SPESSASYNTH_ERROR_METADATA[code]: { description, severity }.
class SpessaSynthError extends SuaveplanError<SpessaSynthErrorCode> — constructor takes (code, messageKey, options?) with optional cause/context.

Implementation Notes

The constructor reads SPESSASYNTH_ERROR_METADATA[code] to populate this.name, which serves the secondary purpose of guaranteeing the constructor body is not elided by noUselessConstructor lint. The metadata table is Object.freezed so consumers can't accidentally mutate it; the codes themselves are an as const tuple supplied to defineCodes, so changing them requires editing the source — no run-time mutation is possible. The class extends SuaveplanError directly (no intermediate base) so the redaction, span-event, and i18n hooks defined on SuaveplanError apply uniformly.

3.5 KiB Raw Blame History