# `error-codes`

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

## Purpose

Stable error-code registry for `@suaveplan/react-audio-player`.
Every error thrown by a public surface in this package carries a
code from `REACT_AUDIO_PLAYER_CODES`, a `messageKey` for i18n
resolution, and an optional `context` / `cause` chain. Codes are
namespaced under the `REACT_AUDIO_PLAYER.` prefix so the wire format
`{ code: "REACT_AUDIO_PLAYER.LRC_PARSE_FAILED" }` is greppable and
stable across versions.

The registry is the single source of truth for the package's error
contract — the test suite walks `REACT_AUDIO_PLAYER_ERROR_METADATA`
and confirms every code is reachable from a real call site, so a
code that gets added without a thrower (or a thrower whose code
gets removed) is a build break.

## Features

- Five public codes: `NO_PROVIDER`, `PLAYLIST_EMPTY`,
  `PERSISTENCE_FAILED`, `LRC_PARSE_FAILED`, `INVALID_OPTIONS`.
- Frozen metadata map keyed by code; every entry has a `description`
  and `severity` (`"error"` | `"warning"`).
- `ReactAudioPlayerError` class extends `SuaveplanError`; carries a
  stable `category = "react-audio-player"` field.
- Idempotent `registerReactAudioPlayerErrorCodes()` for parity with
  sibling audio packages.

## Usage: Basic

```ts
import {
    REACT_AUDIO_PLAYER_CODES,
    ReactAudioPlayerError,
} from "@suaveplan/react-audio-player/error-codes";

if (!provider) {
    throw new ReactAudioPlayerError(
        REACT_AUDIO_PLAYER_CODES.NO_PROVIDER,
        "react-audio-player.no-provider"
    );
}
```

## Usage: Advanced

```ts
import {
    REACT_AUDIO_PLAYER_CODES,
    REACT_AUDIO_PLAYER_ERROR_METADATA,
    ReactAudioPlayerError,
} from "@suaveplan/react-audio-player/error-codes";

try {
    parseLrc(input);
} catch (cause) {
    const code = REACT_AUDIO_PLAYER_CODES.LRC_PARSE_FAILED;
    const meta = REACT_AUDIO_PLAYER_ERROR_METADATA[code];
    throw new ReactAudioPlayerError(code, "lrc.parse.failed", {
        cause,
        context: { severity: meta.severity, bytes: input.length },
    });
}
```

## API Reference

- `REACT_AUDIO_PLAYER_CODES` — `Readonly<Record<…, string>>` of the
  five public codes (frozen).
- `ReactAudioPlayerErrorCode` — union of the code string-literals.
- `REACT_AUDIO_PLAYER_ERROR_METADATA` — frozen metadata map.
- `ReactAudioPlayerError extends SuaveplanError<ReactAudioPlayerErrorCode>`.
- `registerReactAudioPlayerErrorCodes(): void` — idempotent no-op.

## Implementation Notes

`defineCodes` is the workspace's standard helper for producing
namespaced code maps; it freezes the result and asserts that every
key is a valid identifier at module load. Metadata is declared with
`Object.freeze` so consumers (and the test suite) cannot mutate it
at runtime.

`SuaveplanError` is the universal base error from
`@suaveplan/error`; it carries `code`, `messageKey`, `context`, and
`cause` plus a stable wire-format serialisation. The
`category = "react-audio-player"` literal is the discriminator used
by the cross-package error router when an error crosses a package
boundary.

`name` is set to `ReactAudioPlayerError(<severity>)` so stack-trace
output includes the severity at a glance. This is a string-only
augmentation; it does not change the prototype chain so
`instanceof ReactAudioPlayerError` still narrows correctly.