# Error Codes

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

## Purpose

This module centralises every error code, metadata description, and severity level that the `@suaveplan/audio-sprite-packer` package can emit. By defining codes through the `@suaveplan/error` registry, consumers can rely on stable string identifiers instead of brittle message matching when handling failures. The module also exports a concrete `AudioSpriteError` class so that all sprite-packer exceptions share a single, recognisable type.

## Features

- **Typed error codes** — `AUDIO_SPRITE_CODES` provides strongly-typed constants such as `UNSUPPORTED_FORMAT` and `CLIP_NOT_FOUND`.
- **Per-code metadata** — `AUDIO_SPRITE_ERROR_METADATA` maps every code to a human-readable description and a severity of `"warning"` or `"error"`.
- **Dedicated exception class** — `AudioSpriteError` extends `SuaveplanError` and carries the `AudioSpriteErrorCode` discriminator.
- **Idempotent registration** — `registerAudioSpriteErrorCodes` may be called repeatedly without side effects because the metadata record is frozen at module load time.

## Usage: Basic Example

```ts
import { AudioSpriteError, AUDIO_SPRITE_CODES } from "@suaveplan/audio-sprite-packer";

function unpackClip(sprite: AudioSprite, name: string) {
  const packer = createAudioSpritePacker({ adapter: new MyAdapter() });
  try {
    return packer.unpack(sprite, name);
  } catch (err) {
    if (err instanceof AudioSpriteError && err.code === AUDIO_SPRITE_CODES.CLIP_NOT_FOUND) {
      console.warn(`Clip "${name}" missing from sprite`);
      return null;
    }
    throw err;
  }
}
```

## Usage: Advanced Example

```ts
import {
  AudioSpriteError,
  AUDIO_SPRITE_CODES,
  AUDIO_SPRITE_ERROR_METADATA,
} from "@suaveplan/audio-sprite-packer";

function handleSpriteError(err: unknown) {
  if (err instanceof AudioSpriteError) {
    const meta = AUDIO_SPRITE_ERROR_METADATA[err.code];
    console.error(`[${meta.severity}] ${meta.description}`);

    if (err.code === AUDIO_SPRITE_CODES.ABORTED) {
      // Warning-level; safe to retry.
      return "aborted";
    }
    throw err;
  }
}
```

## API Reference

### `AUDIO_SPRITE_CODES`

A frozen record of error-code constants created via `defineCodes("AUDIO_SPRITE", [...])`.

- `UNSUPPORTED_FORMAT`
- `DECODE_FAILED`
- `ENCODE_FAILED`
- `CLIP_NOT_FOUND`
- `INVALID_OPTIONS`
- `EMPTY_INPUT`
- `INVALID_MANIFEST`
- `ABORTED`

### `AudioSpriteErrorCode`

```ts
type AudioSpriteErrorCode = (typeof AUDIO_SPRITE_CODES)[keyof typeof AUDIO_SPRITE_CODES];
```

The union of all values contained in `AUDIO_SPRITE_CODES`.

### `AudioSpriteErrorMetadata`

```ts
interface AudioSpriteErrorMetadata {
  readonly description: string;
  readonly severity: "warning" | "error";
}
```

Describes the human-readable explanation and severity for a single error code.

### `AUDIO_SPRITE_ERROR_METADATA`

```ts
const AUDIO_SPRITE_ERROR_METADATA: Readonly<Record<AudioSpriteErrorCode, AudioSpriteErrorMetadata>>
```

Frozen lookup table that maps every `AudioSpriteErrorCode` to its metadata. Useful for localising or logging errors without parsing exception messages.

### `AudioSpriteError`

```ts
class AudioSpriteError extends SuaveplanError<AudioSpriteErrorCode> {}
```

The exception type thrown by `@suaveplan/audio-sprite-packer`. Its `code` property is constrained to `AudioSpriteErrorCode`, allowing consumers to branch on specific failure modes. The constructor is public (widened from the protected `SuaveplanError` base constructor).

**Throws:**

- This class is thrown, not caught internally.

### `registerAudioSpriteErrorCodes(): void`

An idempotent hook that exists for compatibility with the `@suaveplan/error` registration lifecycle. The metadata is already frozen and exported, so the function body is empty. It is invoked automatically at module load time.

## Implementation Notes

- The module depends on `@suaveplan/error` for `defineCodes` and the base `SuaveplanError` class.
- `AUDIO_SPRITE_ERROR_METADATA` is frozen with `Object.freeze` so that downstream code cannot accidentally mutate severity or descriptions at runtime.
- `registerAudioSpriteErrorCodes` is called immediately after definition, ensuring the codes are available as soon as the module is imported.