---
title: Справочник API
description: Спецификация I18nErrorBase, setErrorMessage и связанных типов.
---

## `I18nErrorBase` [#i18n-error-base]

Базовый класс для расширения `Error`. `message` разрешается по `lang`.

```ts
import { I18nErrorBase } from "i18n-error-base";

class MyError extends I18nErrorBase<{ code: string }> {}
```

### Параметры типа [#type-params]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `TMeta` | `ErrorMeta \| undefined` | `ErrorMeta \| undefined` | Тип `meta`. Если не используется, укажите `undefined`. |

### Статические свойства [#static-props]

| Prop | Type | Default | Description |
| ---- | ---- | ------- | ----------- |
| `prefix?` | `string` | `undefined` | Добавляется в начало разрешённого сообщения. |

### Свойства экземпляра [#instance-props]

| Prop | Type | Description |
| ---- | ---- | ----------- |
| `meta` | `TMeta` | Вспомогательные данные из конструктора. Доступны для чтения и записи. |
| `message` | `string` | Сообщение, разрешённое по `lang`. Перечисляемое. |
| `cause` | `unknown` | Причина из `ErrorOptions`. Стандартное свойство `Error`. |

### Конструктор [#constructor]

Если `TMeta` исключает `undefined`, `meta` обязателен.

```ts
new MyError(meta, message, options?)
```

Если `TMeta` равен `undefined`, `meta` можно опускать.

```ts
new MyError(message, options?)
new MyError(meta, message, options?)
```

| Параметр | Тип | Описание |
| ------------ | -- | ---- |
| `meta` | `TMeta` | Вспомогательные данные для генерации сообщений. |
| `message` | `string \| MessageFactory<TMeta>` | Сообщение по умолчанию для языков без регистрации. Функции принимают `meta`. |
| `options` | `ErrorOptions` | Опции, совместимые со 2-м аргументом `Error` (например `{ cause }`). |

### Порядок разрешения [#resolution-order]

1. Получает `lang` из `getGlobalConfig()` (`"en"`, если не задан)
2. Выполняет зарегистрированную функцию для этого класса и языка с `meta`
3. Если регистрации нет, использует сообщение по умолчанию
4. Если задан `static prefix`, добавляет его в начало

:::note
Регистрации относятся к классу. Родительские не наследуются. Регистрируйте каждый класс.
:::

## `setErrorMessage` [#set-error-message]

Регистрирует фабричные функции сообщений по языкам.

```ts
import { setErrorMessage } from "i18n-error-base";

setErrorMessage(MyError, (meta) => `...: ${meta.code}`, "ja");
```

| Параметр | Тип | Описание |
| ------------ | -- | ---- |
| `reference` | `I18nErrorBaseConstructor` | Класс, наследующий `I18nErrorBase`. Остальные — ошибка типа. |
| `message` | `string \| (meta) => string` | Регистрируемое сообщение. `meta` выводится из целевого класса. |
| `lang` | `string \| Iterable<string>` | Целевой язык. Один код или итерируемый объект (например, массив). |

Повторная регистрация того же класса и языка перезаписывает.

## Типы [#types]

### `ErrorMeta` [#error-meta]

```ts
type ErrorMeta = {
  readonly [prop: string]: unknown;
};
```

Ограничение по умолчанию для `TMeta`. Объект только для чтения с произвольными свойствами.

### `ErrorOptions` [#error-options]

```ts
type ErrorOptions =
  ConstructorParameters<typeof Error> extends [
    message?: unknown,
    options?: (infer TOptions) | undefined,
  ]
    ? TOptions
    : { readonly cause?: unknown };
```

Тип из 2-го аргумента `Error`. Позволяет передать `cause`.

### `MessageFactory<TMeta>` [#message-factory]

```ts
interface MessageFactory<TMeta extends ErrorMeta | undefined = ErrorMeta | undefined> {
  (meta: TMeta): string;
}
```

Функция, создающая сообщение из `meta`. Используется и для сообщений по умолчанию, и для зарегистрированных.

### `I18nErrorBaseParams<TMeta>` [#i18n-error-base-params]

Перегрузки аргументов конструктора.

```ts
type I18nErrorBaseParams<TMeta extends ErrorMeta | undefined = ErrorMeta | undefined> =
  [TMeta] extends [undefined]
    ?
        | [message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined]
        | [meta: undefined, message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined]
    : [meta: TMeta, message: string | MessageFactory<TMeta>, options?: ErrorOptions | undefined];
```

Сокращённая форма без `meta` допустима только когда `TMeta` равен `undefined`.

### `I18nErrorBaseConstructor` [#i18n-error-base-constructor]

```ts
interface I18nErrorBaseConstructor {
  new (...args: any): I18nErrorBase;
}
```

Тип 1-го аргумента `setErrorMessage`.

## Примечания [#notes]

- `lang` по умолчанию — `"en"`. Переключайте через `setGlobalConfig({ lang })`
- Без нормализации кодов и цепочки запаса (например `en-US` → `en`). Нерегистрированные языки дают сообщение по умолчанию