# `error-codes`

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

## Purpose

Defines the stable `REACT_MIDI.*` error-code namespace published by
`@suaveplan/react-midi`. Every code is generated via `defineCodes`
from `@suaveplan/error`, paired with metadata (description, severity)
in a frozen registry, and thrown via the `ReactMidiError` class which
extends `SuaveplanError`. The metadata table is the single source of
truth for downstream documentation generators, i18n resolvers, and
the test suite that cross-checks code/metadata parity.

## Features

- Five stable codes: `ACCESS_DENIED`, `UNSUPPORTED_PLATFORM`,
  `PORT_NOT_FOUND`, `SYSEX_NOT_PERMITTED`, `NO_PROVIDER`.
- `ReactMidiError` carries `code`, `messageKey`, optional `context`
  and `cause`, plus a severity-flavoured `name` for log filtering.
- `registerReactMidiErrorCodes()` is an idempotent registration hook
  (no-op; metadata is module-static).

## Usage: Basic

```ts
import { REACT_MIDI_CODES, ReactMidiError } from "@suaveplan/react-midi";

throw new ReactMidiError(
    REACT_MIDI_CODES.PORT_NOT_FOUND,
    "react-midi.port-not-found",
    { context: { portId: "midi-in-1" } }
);
```

## Usage: Advanced

```ts
import {
    REACT_MIDI_CODES,
    REACT_MIDI_ERROR_METADATA,
    ReactMidiError,
} from "@suaveplan/react-midi";

function logIfWarning(err: unknown): void {
    if (err instanceof ReactMidiError) {
        const meta = REACT_MIDI_ERROR_METADATA[err.code];
        if (meta.severity === "warning") {
            console.warn(err.code, meta.description);
        } else {
            throw err;
        }
    }
}
```

## API Reference

- `REACT_MIDI_CODES` — frozen `{ readonly [Reason]: "REACT_MIDI.<Reason>" }`.
- `REACT_MIDI_ERROR_METADATA` — frozen `{ readonly [Code]: { description, severity } }`.
- `class ReactMidiError extends SuaveplanError<ReactMidiErrorCode>`.
- `function registerReactMidiErrorCodes(): void`.

## Implementation Notes

The five codes are deliberately small in number: every public hook
surfaces at most one of them, and the four runtime codes
(`ACCESS_DENIED`, `UNSUPPORTED_PLATFORM`, `PORT_NOT_FOUND`,
`SYSEX_NOT_PERMITTED`) map one-to-one onto the four failure modes a
Web MIDI consumer must handle. `NO_PROVIDER` is the structural error
thrown by hooks invoked outside `<MidiProvider>`.

`ReactMidiError` extends `SuaveplanError` and therefore inherits the
standard `code`, `messageKey`, `context`, and `cause` fields plus
the package-wide `category` constant. The thrown `name` carries the
severity in parentheses (e.g. `ReactMidiError(error)`) so log
aggregators can filter on the rendered string when the consumer has
not chained an i18n resolver. The metadata table is intentionally
`Object.freeze`d so consumers can rely on it as a stable read-only
lookup across the process lifetime.