Справочник API

Спецификация I18nErrorBase, setErrorMessage и связанных типов.

`I18nErrorBase`

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

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

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

Параметры типа

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

Статические свойства

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

Свойства экземпляра

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

Конструктор

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

new MyError(meta, message, options?)

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

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

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

Порядок разрешения

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

`setErrorMessage`

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

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

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

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

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

Типы

`ErrorMeta`

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

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

`ErrorOptions`

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

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

`MessageFactory<TMeta>`

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

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

`I18nErrorBaseParams<TMeta>`

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

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`

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

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

Примечания

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