first commit

docs/localization/i18n/locale-data/src/errors/locale-data-error.md

@@ -0,0 +1,100 @@
+# 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`.