@mirta/i18n 0.0.1 → 0.4.0

package/dist/index.d.mts

@@ -0,0 +1,353 @@
+/**
+ * Тип для локали (например, 'en-US', 'ru-RU'), обеспечивающий типобезопасность.
+ * Использует branded type для предотвращения случайного смешивания строк.
+ *
+ * @since 0.4.0
+ *
+ **/
+type Locale = Branded<string, 'Locale'>;
+/**
+ * Тип для языкового кода (например, 'en', 'ru'), выделенного из локали.
+ * Обеспечивает типобезопасность через branded type.
+ *
+ * @since 0.4.0
+ *
+ **/
+type Lang = Branded<string, 'Lang'>;
+/**
+ * Допустимые типы значений переменных в сообщениях локализации.
+ *
+ * @since 0.4.0
+ *
+ * @private
+ *
+ **/
+type MessageVariable = string | number | null | undefined;
+/**
+ * Базовый интерфейс для описания структуры сообщений и переменных локали.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface GenericShape {
+    /**
+     * Словарь локализованных сообщений.
+     * Ключ — идентификатор сообщения, значение — строка с текстом или шаблоном.
+     *
+     **/
+    messages: Record<string, string | undefined>;
+    /**
+     * Опциональные типы переменных для каждого сообщения.
+     * Позволяет строго типизировать переменные при вызове `t(...)`.
+     *
+     **/
+    variables: Record<string, Record<string, MessageVariable>>;
+}
+/**
+ * Извлекает тип переменных для указанного ключа сообщения.
+ * Если переменные для ключа определены — возвращает соответствующий тип,
+ * иначе — `never`.
+ *
+ * @template TShape - Интерфейс локали, совместимый с `GenericShape`
+ * @template K - Ключ сообщения
+ *
+ * @since 0.4.0
+ *
+ * @private
+ *
+ **/
+type VariablesOf<TShape extends GenericShape, K extends keyof TShape['messages']> = K extends keyof TShape['variables'] ? TShape['variables'][K] : never;
+/**
+ * Переводчик сообщений для текущей локали.
+ *
+ * Поддерживает два режима работы:
+ * - `t('ключ', { переменные })` — интерполированная строка
+ * - `t.plain('ключ', 'резервный текст')` — прямой доступ к сообщению.
+ *
+ * @template TShape - Интерфейс локализации, совместимый с `GenericShape`
+ *
+ * @example
+ * ```ts
+ * t('greeting', { name: 'Анна' })
+ * // → "Привет, Анна!"
+ * ```
+ * @example
+ * ```ts
+ * t.plain('unknown.key', 'По умолчанию')
+ * // → "По умолчанию" (если ключ не найден)
+ * ```
+ * @since 0.4.0
+ *
+ **/
+interface Translator<TShape extends GenericShape> {
+    /**
+     * Возвращает локализованное сообщение по ключу с подстановкой переменных.
+     * Ключ и структура переменных проверяются на этапе компиляции.
+     *
+     * @param key - Ключ сообщения
+     * @param variables - Данные для подстановки (если определены)
+     * @returns Локализованная строка с подставленными значениями
+     *
+     **/
+    <TMessageKey extends keyof TShape['messages']>(key: TMessageKey, variables?: VariablesOf<TShape, TMessageKey>): string;
+    /**
+     * Возвращает сообщение без интерполяции. Подходит для динамических ключей.
+     * Не требует строгой типизации переменных.
+     *
+     * @param key - Ключ сообщения
+     * @param fallbackValue - Текст, возвращаемый при отсутствии ключа
+     * @returns Значение сообщения или `fallbackValue`
+     *
+     **/
+    plain: (key: string, fallbackValue?: string) => string;
+}
+/**
+ * Интерфейс локализации, предоставляемый после инициализации.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface Localization<TShape extends GenericShape> {
+    /**
+     * Возвращает текущую активную локаль.
+     *
+     **/
+    getLocale: () => Locale;
+    /**
+     * Асинхронно устанавливает новую локаль.
+     * Если сообщения для указанной локали недоступны — используется fallback.
+     *
+     * @param locale - Локаль в виде строки (например, 'ru-RU')
+     *
+     **/
+    setLocaleAsync: (locale: string) => Promise<void>;
+    /**
+     * Переводчик сообщений для текущей локали.
+     *
+     **/
+    t: Translator<TShape>;
+}
+
+/**
+ * Опции для инициализации системы локализации.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface LocalizationOptions {
+    /**
+     * Рабочая директория, в которой ожидается папка `locales/`.
+     *
+     * По умолчанию `process.cwd()`
+     *
+     **/
+    cwd?: string;
+    /**
+     * Локаль по умолчанию, если системная недоступна или не поддерживается.
+     *
+     * По умолчанию `'en-US'`
+     *
+     **/
+    fallbackLocale?: string;
+    /**
+     * Определяет реакцию на ошибки при локализации.
+     *
+     * - `true` — выбрасывает ошибки,
+     * - `false` — использует fallback-поведение.
+     *
+     * По умолчанию `false`.
+     *
+     **/
+    strict?: boolean;
+}
+/**
+ * Инициализирует систему локализации, загружает сообщения для системной и fallback-локали.
+ *
+ * @template TShape - Интерфейс локали, описывающий структуру сообщений и переменных.
+ *                    Если не указан, применяется тип {@link GenericShape}, разрешающий использовать любые строки как ключи.
+ *                    Для включения строгой типизации передайте сгенерированный или явно определённый интерфейс `LocaleShape`.
+ *
+ * @param options - Опции инициализации локализации.
+ * @param options.cwd - Рабочая директория, откуда загружаются локали (по умолчанию: `process.cwd()`).
+ * @param options.fallbackLocale - Локаль по умолчанию, если другие не найдены (по умолчанию: `'en-US'`).
+ *
+ * @returns Промис, разрешающийся в объект `Localization<TShape>`, содержащий:
+ * - `getLocale()` — текущую локаль
+ * - `setLocaleAsync(locale)` — переключение локали
+ * - `t(key, vars)` — функция перевода
+ *
+ * @throws Ошибка, если не удалось загрузить fallback-локаль.
+ *
+ * @example
+ * ```ts
+ * // Без LocaleShape — нет строгой проверки ключей
+ * const { t } = await initLocalizationAsync()
+ * t('non.existing.key') // OK (нет ошибки на уровне типов)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // С интерфейсом — полная типизация
+ * const { t } = await initLocalizationAsync<MyLocaleShape>()
+ * t('non.existing.key') // Ошибка компиляции
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function initLocalizationAsync<TShape extends GenericShape = GenericShape>(options?: LocalizationOptions): Promise<Localization<TShape>>;
+
+/**
+ * Специализированный класс для обработки ошибок, связанных с работой локализации.
+ *
+ * Предоставляет структурированные и типизированные ошибки с использованием кодов, что упрощает
+ * программную обработку исключений в инструментах, работающих с пакетами.
+ *
+ * @example
+ * ```ts
+ * throw LocalizationError.get('fallback.LoadFailed', 'en-US')
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare class LocalizationError extends Error {
+    /**
+     * Код ошибки для программной идентификации.
+     *
+     * Позволяет точно определить причину ошибки в обработчиках `try/catch`.
+     *
+     **/
+    readonly code: string;
+    /**
+     * Приватный конструктор, используемый только внутри
+     * класса для создания экземпляров ошибки.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для идентификации.
+     * @param scope - Пространство имён или модуль, в котором возникла ошибка.
+     *                По умолчанию — {@link THIS_PACKAGE_NAME}.
+     *
+     **/
+    private constructor();
+    /** Карта кодов ошибок с соответствующими сообщениями. */
+    private static readonly codeMappings;
+    /**
+     * Фабричный метод для создания экземпляра ошибки по её коду.
+     *
+     * Автоматически подставляет сообщение из `codeMappings` и формирует ошибку с заданными параметрами.
+     *
+     * @template T - Ограниченный ключами `codeMappings` тип, гарантирующий корректность кода.
+     * @param code - Код ошибки (например, `'fallback.loadFailed'`).
+     * @param args - Аргументы, соответствующие параметрам функции сообщения из `codeMappings`.
+     * @returns Новый экземпляр {@link LocalizationError} с шаблонным сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = LocalizationError.get('fallback.loadFailed', 'en-US')
+     * ```
+     */
+    static get<T extends keyof typeof LocalizationError['codeMappings']>(code: T, ...args: Parameters<typeof LocalizationError['codeMappings'][T]>): LocalizationError;
+    /**
+     * Фабричный метод, аналогичный `get`, но с возможностью указать
+     * пользовательское пространство имён (scope).
+     *
+     * Полезно при использовании в других модулях, где нужно указать
+     * иной контекст ошибки.
+     *
+     * @template TKey - Тип кода ошибки, аналогично `get`.
+     *
+     * @param scope - Пространство имён ошибки (например, `'@mirta/store'`).
+     * @param code - Код ошибки.
+     * @param args - Аргументы для формирования сообщения.
+     *
+     * @returns Новый экземпляр {@link LocalizationError} с пользовательским
+     *          префиксом и шаблонным сообщением.
+     *
+     * @example
+     *
+     * ```ts
+     * const error = LocalizationError.getScoped('@mirta/cli', 'fallback.loadFailed', 'en-US')
+     * ```
+     **/
+    static getScoped<TKey extends keyof typeof LocalizationError['codeMappings']>(scope: string, code: TKey, ...args: Parameters<typeof LocalizationError['codeMappings'][TKey]>): LocalizationError;
+}
+
+/**
+ * Специализированный класс для обработки ошибок, связанных с работой локализации.
+ *
+ * Предоставляет структурированные и типизированные ошибки с использованием кодов, что упрощает
+ * программную обработку исключений в инструментах, работающих с пакетами.
+ *
+ * @example
+ * ```ts
+ * throw SourceError.get('file.accessDenied', '/path/to/file')
+ * ```
+ * @since 0.4.0
+ *
+ **/
+declare class SourceError extends Error {
+    /**
+     * Код ошибки для программной идентификации.
+     *
+     * Позволяет точно определить причину ошибки в обработчиках `try/catch`.
+     *
+     **/
+    readonly code: string;
+    /**
+     * Приватный конструктор, используемый только внутри
+     * класса для создания экземпляров ошибки.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для идентификации.
+     * @param scope - Пространство имён или модуль, в котором возникла ошибка.
+     *                По умолчанию — {@link THIS_PACKAGE_NAME}.
+     *
+     **/
+    private constructor();
+    /** Карта кодов ошибок с соответствующими сообщениями. */
+    private static readonly codeMappings;
+    static isFileError(error: unknown): error is SourceError;
+    static isParseError(error: unknown): error is SourceError;
+    /**
+     * Фабричный метод для создания экземпляра ошибки по её коду.
+     *
+     * Автоматически подставляет сообщение из `codeMappings` и формирует ошибку с заданными параметрами.
+     *
+     * @template T - Ограниченный ключами `codeMappings` тип, гарантирующий корректность кода.
+     * @param code - Код ошибки (например, `'alreadyDefined'`).
+     * @param args - Аргументы, соответствующие параметрам функции сообщения из `codeMappings`.
+     * @returns Новый экземпляр {@link SourceError} с шаблонным сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = SourceError.get('file.notFound', '/path/to/locale.json')
+     * ```
+     */
+    static get<T extends keyof typeof SourceError['codeMappings']>(code: T, ...args: Parameters<typeof SourceError['codeMappings'][T]>): SourceError;
+    /**
+     * Фабричный метод, аналогичный `get`, но с возможностью указать
+     * пользовательское пространство имён (scope).
+     *
+     * Полезно при использовании в других модулях, где нужно указать
+     * иной контекст ошибки.
+     *
+     * @template TKey - Тип кода ошибки, аналогично `get`.
+     *
+     * @param scope - Пространство имён ошибки (например, `'@mirta/store'`).
+     * @param code - Код ошибки.
+     * @param args - Аргументы для формирования сообщения.
+     *
+     * @returns Новый экземпляр {@link SourceError} с пользовательским
+     *          префиксом и шаблонным сообщением.
+     *
+     * @example
+     *
+     * ```ts
+     * const error = SourceError.getScoped('@mirta/bot-remote', 'file.accessDenied', '/path/to/file')
+     * ```
+     **/
+    static getScoped<TKey extends keyof typeof SourceError['codeMappings']>(scope: string, code: TKey, ...args: Parameters<typeof SourceError['codeMappings'][TKey]>): SourceError;
+}
+
+export { LocalizationError, SourceError, initLocalizationAsync };
+export type { GenericShape, Lang, Locale, Localization, MessageVariable };