# metadata-error

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

Provides the stable error code registry (`METADATA_CODES`) and the `MetadataError` class used by every module in `@suaveplan/audio-metadata`. Centralising error identifiers in one place guarantees that callers can branch on a well-known string constant rather than pattern-matching on human-readable messages, which are subject to change.

The package intentionally does **not** extend `@suaveplan/error`'s `SuaveplanError` — `@suaveplan/audio-metadata` is a leaf package that carries no `@suaveplan/*` runtime dependencies, keeping its install footprint minimal for both Node.js and browser environments.

## Features

- Three stable error codes: `UNSUPPORTED_FORMAT`, `PARSE_ERROR`, `FETCH_FAILED`
- `MetadataError` extends `Error` and exposes a typed `code` property
- `name` is always `"MetadataError"` for easy `instanceof` / `error.name` branching
- Exported `MetadataCode` union type for use in catch-block type narrowing

## Usage: Basic Example

```ts
import { MetadataError, METADATA_CODES } from "@suaveplan/audio-metadata/errors";

try {
  // ... parse audio buffer
} catch (err) {
  if (err instanceof MetadataError && err.code === METADATA_CODES.PARSE_ERROR) {
    console.error("Malformed audio data:", err.message);
  }
}
```

## Usage: Advanced Example

```ts
import { MetadataError, METADATA_CODES, type MetadataCode } from "@suaveplan/audio-metadata/errors";

function handleMetadataError(err: MetadataError): never {
  const actions: Record<MetadataCode, () => never> = {
    [METADATA_CODES.UNSUPPORTED_FORMAT]: () => { throw new Error("Format not supported by this build"); },
    [METADATA_CODES.PARSE_ERROR]:        () => { throw new Error("Audio data is corrupt"); },
    [METADATA_CODES.FETCH_FAILED]:       () => { throw new Error("Network failure — retry later"); },
  };
  return actions[err.code]();
}
```

## API Reference

### `METADATA_CODES`

```ts
const METADATA_CODES: {
  UNSUPPORTED_FORMAT: "METADATA.UNSUPPORTED_FORMAT";
  PARSE_ERROR:        "METADATA.PARSE_ERROR";
  FETCH_FAILED:       "METADATA.FETCH_FAILED";
}
```

Immutable `as const` object containing every stable error code string.

### `MetadataCode`

```ts
type MetadataCode = "METADATA.UNSUPPORTED_FORMAT" | "METADATA.PARSE_ERROR" | "METADATA.FETCH_FAILED";
```

Union of all code values for use in type narrowing.

### `MetadataError`

```ts
class MetadataError extends Error {
  readonly code: MetadataCode;
  constructor(message: string, code: MetadataCode);
}
```

| Member | Type | Description |
|--------|------|-------------|
| `message` | `string` | Human-readable description of the failure |
| `code` | `MetadataCode` | Stable machine-readable identifier |
| `name` | `"MetadataError"` | Always set for `instanceof`-free discrimination |

## Implementation Notes

The `name` property is assigned in the constructor body (not via a class-level initialiser) to ensure it survives TypeScript's `super()` call ordering and remains correct when the class is extended. The `code` field is `readonly` to prevent accidental mutation after construction. No external dependencies are used — this file is intentionally dependency-free so it can be imported by any part of the package without creating cycles.