# locale-data-error

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

Defines the typed error class and stable code registry for `@suaveplan/locale-data`. All errors
thrown by this package extend `SuaveplanError`, ensuring consistent structured error handling across
the project — with machine-readable codes, cause-chain propagation, and OTel span-event support
inherited from `@suaveplan/error`.

## Features

- **Stable code registry** via `defineCodes("LOCALE_DATA", [...])` — codes are namespaced under
  `LOCALE_DATA` and never change once published, ensuring forward compatibility for error consumers.
- **Two error codes**: `COUNTRY.NOT_FOUND` for unknown ISO 3166-1 alpha-2 codes and
  `LANGUAGE.NOT_FOUND` for unknown ISO 639-1 language codes.
- **Full `SuaveplanError` inheritance**: cause chaining, redaction, wire-format serialisation,
  and OTel span-event emission are all available on every `LocaleDataError` instance.
- **Typed generic**: `LocaleDataError` is parameterised on `LocaleDataCode`, so TypeScript narrows
  `.code` to the union of defined codes in `catch` blocks.

## Usage: Basic Example

```ts
import { LocaleDataError, LOCALE_DATA_CODES } from "@suaveplan/locale-data/errors";

throw new LocaleDataError(
  LOCALE_DATA_CODES["COUNTRY.NOT_FOUND"],
  "No country found for code: ZZ"
);
```

## Usage: Advanced Example

```ts
import { LocaleDataError, LOCALE_DATA_CODES } from "@suaveplan/locale-data/errors";
import { isSuaveplanError } from "@suaveplan/error";

try {
  const country = getCountry("ZZ");
} catch (err) {
  if (isSuaveplanError(err) && err.code === LOCALE_DATA_CODES["COUNTRY.NOT_FOUND"]) {
    console.error("Country lookup failed:", err.message);
    // err.cause, err.context, err.toJSON() all available
  }
  throw err;
}
```

## API Reference

### `LOCALE_DATA_CODES`

```ts
const LOCALE_DATA_CODES: {
  "COUNTRY.NOT_FOUND": "LOCALE_DATA/COUNTRY.NOT_FOUND";
  "LANGUAGE.NOT_FOUND": "LOCALE_DATA/LANGUAGE.NOT_FOUND";
}
```

A frozen record produced by `defineCodes`. Use these values as the `code` argument to
`LocaleDataError` and for equality checks in catch blocks.

### `LocaleDataCode`

```ts
type LocaleDataCode = "LOCALE_DATA/COUNTRY.NOT_FOUND" | "LOCALE_DATA/LANGUAGE.NOT_FOUND";
```

The union type of all valid error codes for this package.

### `LocaleDataError`

```ts
class LocaleDataError extends SuaveplanError<LocaleDataCode> {
  public constructor(
    code: LocaleDataCode,
    message: string,
    options?: SuaveplanErrorOptions
  );
}
```

**Parameters:**

- `code` — one of `LOCALE_DATA_CODES`; narrows the `.code` property type.
- `message` — human-readable description, suitable for logging.
- `options` — optional `{ cause?: unknown; context?: Record<string, unknown> }`.

**Throws:** Never (is the thrown value itself).

## Implementation Notes

The constructor is otherwise a no-op pass-through to `SuaveplanError` — the
`// biome-ignore lint/complexity/noUselessConstructor` comment is required because Biome would flag
the empty constructor. We keep it explicitly `public` to widen the inherited `protected` visibility
and to document the intended API surface. Error code strings are of the form
`"LOCALE_DATA/<CATEGORY>.<KEY>"` as produced by `defineCodes`.