@feugene/fint-i18n 0.2.3 → 0.3.0

package/dist/types/core/instance.d.ts

@@ -1,10 +1,20 @@
-import { type Ref } from 'vue';
+import { type WritableComputedRef } from 'vue';
 import { HookManager } from './hooks';
-import type { FintI18nOptions, Locale, MessageValue, TranslateOptions } from './types';
-export declare class FintI18n {
-    locale: Ref<Locale>;
+import type { FintI18nOptions, Locale, LocaleLoaderSource, MessageKey, MessageSchema, MessageValue, TranslateOptions } from './types';
+export declare class FintI18n<Schema extends MessageSchema = any> {
+    /**
+     * Текущая локаль. Чтение реактивно.
+     * Прямая запись в `.value` устарела: она делегирует в `setLocale()` —
+     * используйте `setLocale()` напрямую.
+     */
+    readonly locale: WritableComputedRef<Locale>;
     fallbackLocale: Locale;
-    readonly messages: Record<Locale, any>;
+    private readonly messagesStore;
+    /** Read-only представление словарей. Изменение — только через `mergeMessages()`. */
+    readonly messages: Readonly<Record<Locale, MessageSchema>>;
+    private readonly localeRef;
+    private readonly preloadFallback;
+    private readonly unloadUnusedBlocks;
     private compiledMessages;
     private readonly loaderRegistry;
     private loadingBlocks;
@@ -12,24 +22,46 @@ export declare class FintI18n {
     private blockUsageCounters;
     private patternExpansionCache;
     private pendingUsedBlockLoads;
-    private skipNextUsedBlockLoadLocale;
+    private localeEpoch;
+    private missingKeyReported;
+    private localeSetterWarned;
+    private readonly installedPlugins;
     hooks: HookManager;
     constructor(options: FintI18nOptions);
-    t: (key: string, params?: Record<string, any>, options?: TranslateOptions) => string;
+    /** Деинициализация: вызывает `uninstall` у установленных плагинов. */
+    dispose: () => void;
+    /**
+     * Зарегистрировать дополнительные лоадеры после создания инстанса
+     * (микрофронтенды, динамически подключаемые модули).
+     */
+    addLoaders: (source: LocaleLoaderSource) => void;
+    /** Локали, известные из зарегистрированных лоадеров. */
+    getKnownLocales: () => readonly Locale[];
+    t: (key: MessageKey<Schema>, params?: Record<string, any>, options?: TranslateOptions) => string;
+    private reportMissingKey;
+    private reportError;
     private resolve;
     private setCompiled;
+    /**
+     * Инвалидировать кэш компиляции для поддерева блока: сам блок и все
+     * вложенные ключи. Вызывается перед каждым merge, чтобы перезаписанные
+     * сообщения не отдавались из устаревшего кэша.
+     */
+    private invalidateCompiled;
     /**
      * Развернуть wildcard-паттерн в список конкретных имён блоков.
-     * Результат кэшируется по строке паттерна (набор лоадеров неизменен).
+     * Результат кэшируется по строке паттерна; кэш сбрасывается в addLoaders().
      * Не-паттерны возвращают пустой массив.
      */
     private expandPattern;
     loadBlock: (blockName: string, locale?: Locale) => Promise<void>;
+    private loadConcreteBlock;
     mergeMessages: (locale: Locale, blockName: string, messages: MessageValue) => void;
     private precompileBlock;
     isBlockLoaded: (blockName: string, locale?: Locale) => boolean;
     markBlockLoaded: (blockName: string, locale: Locale) => void;
     loadUsedBlocks: (locale: Locale) => Promise<void>;
+    private hasUnloadedUsedBlocks;
     setLocale: (newLocale: Locale) => Promise<void>;
     /**
      * Зарегистрировать использование блока.
@@ -48,5 +80,16 @@ export declare class FintI18n {
     unregisterUsage: (blockName: string) => void;
     private incrementUsage;
     private decrementUsage;
+    /**
+     * Выгрузить блок из памяти: удалить поддерево сообщений, инвалидировать
+     * кэш компиляции и сбросить отметку о загрузке (следующий `loadBlock`
+     * загрузит блок заново).
+     *
+     * Ограничение: если блок был загружен через родительский лоадер
+     * (например, `pages.articles` резолвится в `pages`), выгружать нужно
+     * по имени загруженного (родительского) блока.
+     */
+    unloadBlock: (blockName: string, locale?: Locale) => void;
+    private unloadBlockAllLocales;
 }
-export declare function createFintI18n(options: FintI18nOptions): FintI18n;
+export declare function createFintI18n<Schema extends MessageSchema = any>(options: FintI18nOptions): FintI18n<Schema>;

package/dist/types/core/loader-registry.d.ts

@@ -6,9 +6,15 @@ export interface ResolvedLocaleBlockLoaders {
 export declare function isBlockPattern(name: string): boolean;
 export declare class LocaleLoaderRegistry {
     private readonly loaders;
-    private readonly knownBlockNames;
+    private knownBlockNames;
     constructor(source?: LocaleLoaderSource);
+    /**
+     * Зарегистрировать дополнительные лоадеры после создания реестра
+     * (микрофронтенды, динамически подключаемые модули).
+     */
+    add(source: LocaleLoaderSource): void;
     getKnownBlockNames(): readonly string[];
+    getKnownLocales(): Locale[];
     /**
      * Развернуть wildcard-паттерн в список конкретных имён блоков.
      *

package/dist/types/core/types.d.ts

@@ -1,25 +1,58 @@
 import type { MessageFunction } from './compiler';
 import type { FintI18n } from './instance';
 export type Locale = string;
-export type LocaleBlockLoader = () => Promise<any>;
+export type LocaleBlockLoader = () => Promise<{
+    default: MessageValue;
+} | MessageValue>;
 export type LocaleBlockLoaders = LocaleBlockLoader | LocaleBlockLoader[];
 export type LocaleLoaderCollection = Record<Locale, Record<string, LocaleBlockLoaders>>;
 export type LocaleLoaderSource = LocaleLoaderCollection | LocaleLoaderCollection[];
 export interface FintI18nPlugin {
     name: string;
     install: (instance: FintI18n) => void;
+    /**
+     * Деинициализация плагина: снятие подписок, слушателей событий и т.п.
+     * Вызывается из `FintI18n.dispose()`.
+     */
+    uninstall?: (instance: FintI18n) => void;
 }
 export interface FintI18nOptions {
     locale: Locale;
     fallbackLocale?: Locale;
     loaders?: LocaleLoaderSource;
     plugins?: FintI18nPlugin[];
+    /**
+     * Грузить блоки также для `fallbackLocale` при каждом `loadBlock`.
+     * Без этого fallback срабатывает только по уже загруженным сообщениям.
+     */
+    preloadFallback?: boolean;
+    /**
+     * Выгружать блок из памяти (сообщения + кэш компиляции), когда счётчик
+     * его использований опускается до нуля (unmount последнего компонента,
+     * вызвавшего `useI18nScope` с этим блоком). По умолчанию выключено.
+     */
+    unloadUnusedBlocks?: boolean;
 }
 export type MessagePrimitive = string | number | boolean;
 export interface MessageSchema {
     [key: string]: MessagePrimitive | MessageFunction | MessageSchema;
 }
 export type MessageValue = MessagePrimitive | MessageFunction | MessageSchema;
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * Все листовые ключи схемы в dot-нотации:
+ * `{ common: { welcome: string } }` → `'common.welcome'`.
+ */
+export type MessageKeys<S> = S extends MessageSchema ? {
+    [K in keyof S & string]: S[K] extends MessageSchema ? `${K}.${MessageKeys<S[K]>}` : K;
+}[keyof S & string] : never;
+/**
+ * Тип ключа для `t()`: литеральные ключи схемы (автодополнение и проверка
+ * опечаток) плюс произвольная строка — для динамически конструируемых ключей
+ * и обратной совместимости (`string & {}` не сворачивает union в `string`).
+ */
+export type MessageKey<S> = IsAny<S> extends true ? string : MessageKeys<S> | (string & {});
 export interface TranslateOptions {
     fallbackLocale?: Locale;
 }
+export {};

package/dist/types/plugins/bridge.d.ts

@@ -1,10 +1,31 @@
-import type { FintI18n, FintI18nPlugin } from '@/core';
+import { type Ref } from 'vue';
+import type { FintI18n, FintI18nPlugin, Locale } from '../core';
+/**
+ * Минимальный структурный контракт vue-i18n:
+ * composer (locale — Ref) либо legacy-инстанс (locale — строка).
+ */
+export interface BridgeI18nTarget {
+    locale: Ref<Locale> | Locale;
+    t: (key: string, params?: Record<string, any>) => string;
+}
 export interface BridgeOptions {
-    i18n: any;
+    /** vue-i18n composer / legacy-инстанс; объекты с `.global` разворачиваются автоматически. */
+    i18n: BridgeI18nTarget | {
+        global: BridgeI18nTarget;
+    };
+    /**
+     * Чей перевод приоритетнее при конфликте:
+     * - `'fint'` (по умолчанию): vue-i18n опрашивается только если fint-i18n не нашёл ключ;
+     * - `'vue-i18n'`: перевод vue-i18n перекрывает найденный fint-i18n.
+     */
+    priority?: 'fint' | 'vue-i18n';
 }
 export declare class BridgePlugin implements FintI18nPlugin {
     name: string;
     private options;
+    private stopLocaleWatch?;
+    private hookUnsubscribers;
     constructor(options: BridgeOptions);
     install(fintI18n: FintI18n): void;
+    uninstall(): void;
 }

package/dist/types/plugins/hook-logger.d.ts

@@ -1,4 +1,4 @@
-import type { FintI18n, FintI18nPlugin } from '@/core';
+import type { FintI18n, FintI18nPlugin } from '../core';
 type LoggerFn = (message?: any, ...optionalParams: any[]) => void;
 export interface HookLoggerPluginOptions {
     logger?: LoggerFn;
@@ -7,8 +7,10 @@ export interface HookLoggerPluginOptions {
 export declare class HookLoggerPlugin implements FintI18nPlugin {
     name: string;
     private options;
+    private hookUnsubscribers;
     constructor(options?: HookLoggerPluginOptions);
     install(i18n: FintI18n): void;
+    uninstall(): void;
     private registerHook;
 }
 export {};

package/dist/types/plugins/persistence.d.ts

@@ -1,4 +1,4 @@
-import type { FintI18n, FintI18nPlugin } from '@/core';
+import type { FintI18n, FintI18nPlugin } from '../core';
 export interface PersistenceOptions {
     key?: string;
     storage?: Storage;
@@ -7,6 +7,9 @@ export interface PersistenceOptions {
 export declare class PersistencePlugin implements FintI18nPlugin {
     name: string;
     private options;
+    private offLocaleChange?;
+    private storageListener?;
     constructor(options?: PersistenceOptions);
     install(i18n: FintI18n): void;
+    uninstall(): void;
 }

package/dist/types/vue/directive.d.ts

@@ -1,5 +1,5 @@
-import type { Directive } from 'vue';
-import type { FintI18n } from '@/core';
+import { type Directive } from 'vue';
+import type { FintI18n } from '../core';
 export type VTDirectiveValue = string | {
     path: string;
     params?: Record<string, any>;
@@ -11,8 +11,11 @@ export interface VTDirectiveModifiers {
 /**
  * Create v-t directive.
  *
+ * Reactive: element text is re-rendered on locale change and when
+ * lazily loaded blocks arrive (via a per-element watchEffect).
+ *
  * Modifiers:
- * - `.once`: render only once
+ * - `.once`: render only once, no reactivity
  * - `.preserve`: keep current text if key not found
  */
 export declare function createVTDirective(i18n: FintI18n): Directive<HTMLElement, VTDirectiveValue>;

package/dist/types/vue/global-types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Opt-in глобальная аугментация типов Vue: `$t`, `$i18n` и директива `v-t`.
+ *
+ * Подключается явно — только если используется стандартная регистрация
+ * (`installI18n` с `globalInstall: true` и директивой под именем `t`):
+ *
+ * ```ts
+ * import '@feugene/fint-i18n/vue/global-types'
+ * ```
+ *
+ * Если глобальные свойства отключены или директива переименована,
+ * не импортируйте этот модуль — объявите собственный `declare module 'vue'`.
+ */
+import type { Directive } from 'vue';
+import type { FintI18n } from '../core';
+import type { VTDirectiveValue } from './directive';
+declare module '@vue/runtime-core' {
+    interface GlobalDirectives {
+        vT: Directive<HTMLElement, VTDirectiveValue>;
+    }
+    interface ComponentCustomProperties {
+        $t: FintI18n['t'];
+        $i18n: FintI18n;
+    }
+}
+declare module 'vue' {
+    interface GlobalDirectives {
+        vT: Directive<HTMLElement, VTDirectiveValue>;
+    }
+    interface ComponentCustomProperties {
+        $t: FintI18n['t'];
+        $i18n: FintI18n;
+    }
+}
+export {};

package/dist/types/vue/index.d.ts

@@ -2,24 +2,3 @@ export * from './scope';
 export * from './inject';
 export * from './directive';
 export * from './plugin';
-import type { FintI18n } from '@/core';
-import type { Directive } from 'vue';
-import type { VTDirectiveValue } from './directive';
-declare module '@vue/runtime-core' {
-    interface GlobalDirectives {
-        vT: Directive<HTMLElement, VTDirectiveValue>;
-    }
-    interface ComponentCustomProperties {
-        $t: FintI18n['t'];
-        $i18n: FintI18n;
-    }
-}
-declare module 'vue' {
-    interface GlobalDirectives {
-        vT: Directive<HTMLElement, VTDirectiveValue>;
-    }
-    interface ComponentCustomProperties {
-        $t: FintI18n['t'];
-        $i18n: FintI18n;
-    }
-}

package/dist/types/vue/inject.d.ts

@@ -1,4 +1,4 @@
 import { type InjectionKey } from 'vue';
-import type { FintI18n } from '@/core';
+import type { FintI18n, MessageSchema } from '../core';
 export declare const FINT_I18N_KEY: InjectionKey<FintI18n>;
-export declare function useFintI18n(): FintI18n;
+export declare function useFintI18n<Schema extends MessageSchema = any>(): FintI18n<Schema>;

package/dist/types/vue/plugin.d.ts

@@ -1,5 +1,5 @@
-import type { App } from 'vue';
-import type { FintI18n } from '@/core';
+import type { App, Plugin } from 'vue';
+import type { FintI18n } from '../core';
 export type GlobalInstallFn = (app: App, i18n: FintI18n) => void;
 export interface InstallI18nOptions {
     directive?: string | boolean;
@@ -12,3 +12,8 @@ export interface InstallI18nOptions {
     globalInstall?: boolean | GlobalInstallFn;
 }
 export declare function installI18n(app: App, i18n: FintI18n, options?: InstallI18nOptions): void;
+/**
+ * Стандартный Vue-плагин поверх `installI18n` — для конвенционального
+ * `app.use(createFintI18nPlugin(i18n))`.
+ */
+export declare function createFintI18nPlugin(i18n: FintI18n, options?: InstallI18nOptions): Plugin;

package/dist/types/vue/scope.d.ts

@@ -1,5 +1,28 @@
-export declare function useI18nScope(blocks: string | string[]): Promise<{
+import { type ComputedRef, type Ref } from 'vue';
+import type { Locale } from '../core';
+export interface UseI18nScopeOptions {
+    /**
+     * Префиксовать ключи именем блока: `t('login')` → `t('auth.login')`.
+     * Работает только с одиночным конкретным блоком (не паттерном).
+     */
+    prefix?: boolean;
+}
+export interface I18nScope {
     t: (key: string, params?: Record<string, any>) => string;
-    locale: import("vue").Ref<string, string>;
-    setLocale: (l: string) => Promise<void>;
-}>;
+    locale: ComputedRef<Locale>;
+    setLocale: (l: Locale) => Promise<void>;
+}
+export interface I18nScopeSync extends I18nScope {
+    /** Становится `true`, когда все блоки скоупа загружены. */
+    ready: Ref<boolean>;
+}
+/**
+ * Асинхронный скоуп блоков: дожидается загрузки.
+ * Требует `await` в `<script setup>` (т.е. `<Suspense>` выше по дереву).
+ */
+export declare function useI18nScope(blocks: string | string[], options?: UseI18nScopeOptions): Promise<I18nScope>;
+/**
+ * Синхронный вариант useI18nScope — не требует Suspense.
+ * Блоки загружаются в фоне; `ready` сигнализирует о готовности.
+ */
+export declare function useI18nScopeSync(blocks: string | string[], options?: UseI18nScopeOptions): I18nScopeSync;

package/dist/vue.js

@@ -1,56 +1,103 @@
-import { inject as e, onUnmounted as t } from "vue";
+import { n as e } from "./chunks/loader-registry-B_fUe8pM.js";
+import { computed as t, inject as n, onUnmounted as r, ref as i, shallowRef as a, watchEffect as o } from "vue";
 //#region src/vue/inject.ts
-var n = Symbol.for("FintI18n");
-function r() {
-	let t = e(n);
-	if (!t) throw Error("[fint-i18n] Instance not found. Did you call installI18n(app, i18n)?");
-	return t;
+var s = Symbol.for("FintI18n");
+function c() {
+	let e = n(s);
+	if (!e) throw Error("[fint-i18n] Instance not found. Did you call installI18n(app, i18n)?");
+	return e;
 }
 //#endregion
 //#region src/vue/scope.ts
-async function i(e) {
-	let n = r(), i = Array.isArray(e) ? e : [e];
-	t(() => {
-		i.forEach((e) => n.unregisterUsage(e));
+function l(n, i) {
+	let a = c(), o = Array.isArray(n) ? n : [n];
+	r(() => {
+		o.forEach((e) => a.unregisterUsage(e));
 	});
-	let a = i.map((e) => (n.registerUsage(e), n.loadBlock(e)));
-	return await Promise.all(a), {
-		t: (e, t) => n.t(e, t),
-		locale: n.locale,
-		setLocale: (e) => n.setLocale(e)
+	let s = o.map((e) => (a.registerUsage(e), a.loadBlock(e))), l = "";
+	return i.prefix && (o.length === 1 && !e(o[0]) ? l = `${o[0]}.` : console.warn("[fint-i18n] `prefix` option is ignored: it requires a single concrete block name")), {
+		loads: s,
+		scope: {
+			t: (e, t) => a.t(l + e, t),
+			locale: t(() => a.locale.value),
+			setLocale: (e) => a.setLocale(e)
+		}
+	};
+}
+async function u(e, t = {}) {
+	let { loads: n, scope: r } = l(e, t);
+	return await Promise.all(n), r;
+}
+function d(e, t = {}) {
+	let { loads: n, scope: r } = l(e, t), a = i(!1);
+	return Promise.all(n).then(() => {
+		a.value = !0;
+	}).catch((e) => {
+		console.error("[fint-i18n] Failed to load scope blocks:", e);
+	}), {
+		...r,
+		ready: a
 	};
 }
 //#endregion
 //#region src/vue/directive.ts
-function a(e) {
+var f = /* @__PURE__ */ new WeakMap();
+function p(e) {
 	return {
 		mounted(t, n) {
-			o(t, n, e);
+			if (n.modifiers.once) {
+				h(t, n, e);
+				return;
+			}
+			let r = a(n), i = o(() => h(t, r.value, e));
+			f.set(t, {
+				binding: r,
+				stop: i
+			});
 		},
 		updated(t, n) {
-			n.modifiers.once || o(t, n, e);
+			if (n.modifiers.once) return;
+			let r = f.get(t);
+			r ? r.binding.value = n : h(t, n, e);
+		},
+		unmounted(e) {
+			let t = f.get(e);
+			t && (t.stop(), f.delete(e));
+		},
+		getSSRProps(t) {
+			let n = m(t.value);
+			return n ? { textContent: e.t(n.key, n.params) } : {};
 		}
 	};
 }
-function o(e, t, n) {
-	let { value: r, modifiers: i } = t, a, o;
-	if (typeof r == "string") a = r;
-	else if (r && typeof r == "object") a = r.path, o = r.params;
-	else return;
-	let s = n.t(a, o);
-	s === a && i.preserve || (e.textContent = s);
+function m(e) {
+	return typeof e == "string" ? { key: e } : e && typeof e == "object" ? {
+		key: e.path,
+		params: e.params
+	} : null;
+}
+function h(e, t, n) {
+	let r = m(t.value);
+	if (!r) return;
+	let i = n.t(r.key, r.params);
+	i === r.key && t.modifiers.preserve || (e.textContent = i);
 }
 //#endregion
 //#region src/vue/plugin.ts
-function s(e, t) {
+function g(e, t) {
 	e.config.globalProperties.$t = t.t, e.config.globalProperties.$i18n = t;
 }
-function c(e, t, r = {}) {
-	e.provide(n, t);
-	let i = r.globalInstall ?? !0;
-	typeof i == "function" ? i(e, t) : i && s(e, t);
-	let o = r.directive === !1 ? null : typeof r.directive == "string" ? r.directive : "t";
-	o && e.directive(o, a(t));
+function _(e, t, n = {}) {
+	e.provide(s, t);
+	let r = n.globalInstall ?? !0;
+	typeof r == "function" ? r(e, t) : r && g(e, t);
+	let i = n.directive === !1 ? null : typeof n.directive == "string" ? n.directive : "t";
+	i && e.directive(i, p(t));
+}
+function v(e, t = {}) {
+	return { install(n) {
+		_(n, e, t);
+	} };
 }
 //#endregion
-export { n as FINT_I18N_KEY, a as createVTDirective, c as installI18n, r as useFintI18n, i as useI18nScope };
+export { s as FINT_I18N_KEY, v as createFintI18nPlugin, p as createVTDirective, _ as installI18n, c as useFintI18n, u as useI18nScope, d as useI18nScopeSync };

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@feugene/fint-i18n",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Lightweight Vue 3 i18n library with lazy-loading blocks and template caching",
-  "author": "feugene <feugene@example.com>",
+  "author": "Fureev Eugene<https://feugene.org>",
   "license": "MIT",
   "homepage": "https://github.com/efureev/fint-i18n#readme",
   "repository": {
@@ -22,24 +22,38 @@
   ],
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "LICENSE",
+    "README.md"
   ],
+  "engines": {
+    "node": ">=20"
+  },
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
     "./core": {
       "types": "./dist/types/core/index.d.ts",
-      "import": "./dist/core.js"
+      "import": "./dist/core.js",
+      "default": "./dist/core.js"
     },
     "./vue": {
       "types": "./dist/types/vue/index.d.ts",
-      "import": "./dist/vue.js"
+      "import": "./dist/vue.js",
+      "default": "./dist/vue.js"
+    },
+    "./vue/global-types": {
+      "types": "./dist/types/vue/global-types.d.ts",
+      "import": "./dist/vue-global-types.js",
+      "default": "./dist/vue-global-types.js"
     },
     "./plugins": {
       "types": "./dist/types/plugins/index.d.ts",
-      "import": "./dist/plugins.js"
+      "import": "./dist/plugins.js",
+      "default": "./dist/plugins.js"
     }
   },
   "sideEffects": false,