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

locale-data-error

(no submodules)

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

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

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

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

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

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

LocaleDataError

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.