# error-codes

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

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

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

## Usage: Advanced

```ts
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.