error-codes

(no submodules)

Purpose

Defines the MidiError class and the MIDI_CODES namespaced registry used by every @suaveplan/midi module that raises faults. The registry exists so consumers can pattern-match on stable strings rather than instanceof checks against transient class identities, and so dashboards can attribute incidents to the exact failure mode without scraping freeform messages.

The codes themselves are produced by defineCodes from @suaveplan/error, which guarantees the resulting object is Object.freeze-d and that every value is a fully-qualified MIDI.<REASON> string. MidiError extends SuaveplanError so cause chains, OTel span events, and i18n message resolution work uniformly with the rest of the platform.

Features

Five stable codes: INVALID_MESSAGE, INVALID_SYSEX, BUFFER_UNDERRUN, UNSUPPORTED_UMP_VARIANT, NRPN_INCOMPLETE.
Frozen MIDI_ERROR_METADATA registry exposing a description and severity tag for every code.
MidiError subclass with category: "midi" tag and runtime-checkable name: "MidiError".
Cause-chain support via the optional options.cause constructor argument.

Usage: Basic

import { MidiError, MIDI_CODES } from "@suaveplan/midi";

if (something.invalid) {
  throw new MidiError(MIDI_CODES.INVALID_MESSAGE);
}

Usage: Advanced

import { MidiError, MIDI_CODES, MIDI_ERROR_METADATA } from "@suaveplan/midi";

try {
  // ...decode logic
} catch (cause) {
  throw new MidiError(MIDI_CODES.BUFFER_UNDERRUN, "midi.decode.short_input", {
    cause,
    context: { offset: 12 },
  });
}

// Build a dashboard label.
const label = MIDI_ERROR_METADATA[MIDI_CODES.BUFFER_UNDERRUN].description;

API Reference

MIDI_CODES: Readonly<{ INVALID_MESSAGE: "MIDI.INVALID_MESSAGE", ... }> — frozen namespaced lookup table.
MidiErrorCode — string-literal union of every value in MIDI_CODES.
MIDI_ERROR_METADATA: Readonly<Record<MidiErrorCode, { description: string; severity: "warning" | "error" }>> — per-code metadata for UI surfaces.
class MidiError extends SuaveplanError<MidiErrorCode> — constructor (code, messageKey?, options?); carries category: "midi" and name: "MidiError".

Implementation Notes

MidiError defaults messageKey to the code itself when none is supplied; this means an unhandled raise still produces a useful i18n key without forcing every call site to invent one. The base class clock is the platform defaultClock, so timestamps line up across packages without per-package configuration. The metadata object is frozen at module load to prevent ad-hoc mutation; downstream packages compose dialect-specific metadata by spreading rather than mutating in place.

2.7 KiB Raw Blame History