i18n-typed-store 0.1.0 → 0.1.1

package/dist/context-Dp43aQ0V.d.mts

@@ -0,0 +1,91 @@
+/**
+ * Translation store structure.
+ * Manages translations for multiple namespace keys and locales.
+ *
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template M - Type of translation modules mapping (e.g., { common: { greeting: string }, errors: { notFound: string } })
+ */
+type TranslationStore<T extends Record<string, string>, L extends Record<string, string>, M extends {
+    [K in keyof T]: any;
+}> = {
+    /** Currently active locale */
+    currentLocale: keyof L;
+    /** Available locales */
+    locales: L;
+    /** Translations map (namespace keys) */
+    translationsMap: T;
+    /**
+     * Adds a listener for locale change events.
+     *
+     * @param listener - Function to call when locale changes
+     */
+    addChangeLocaleListener: (listener: (locale: keyof L) => void) => void;
+    /**
+     * Removes a locale change listener.
+     *
+     * @param listener - Listener function to remove
+     */
+    removeChangeLocaleListener: (listener: (locale: keyof L) => void) => void;
+    /**
+     * Changes the current locale and notifies all listeners.
+     *
+     * @param locale - New locale key
+     */
+    changeLocale: (locale: keyof L) => void;
+    /** Translations organized by namespace key */
+    translations: {
+        [K in keyof T]: {
+            /** Currently active translation for this namespace */
+            currentTranslation?: M[K];
+            /** Locale of the current translation */
+            currentLocale?: keyof L;
+            /** Translations for all locales for this namespace */
+            translations: Record<keyof L, {
+                /** Loaded translation data, undefined if not loaded yet */
+                namespace: M[K] | undefined;
+                /** Whether translation is currently being loaded */
+                isLoading: boolean;
+                /** Whether an error occurred during loading */
+                isError: boolean;
+                /** Promise for the ongoing loading operation */
+                loadingPromise?: Promise<void>;
+            }>;
+            /**
+             * Loads translation for a specific locale.
+             *
+             * @param locale - Locale key to load translation for
+             * @param fromCache - Whether to use cached translation if available (default: true)
+             * @returns Promise that resolves when translation is loaded
+             * @throws Error if loading fails
+             */
+            load: (locale: keyof L, fromCache?: boolean) => Promise<void>;
+        };
+    };
+};
+
+/**
+ * Context value for I18n typed store.
+ * Provides access to translation store, locale management, and loading state.
+ *
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template M - Type of translation modules mapping (e.g., { common: { greeting: string }, errors: { notFound: string } })
+ */
+interface II18nTypedStoreContext<T extends Record<string, string> = Record<string, string>, L extends Record<string, string> = Record<string, string>, M extends {
+    [K in keyof T]: any;
+} = {
+    [K in keyof T]: any;
+}> {
+    /** Translation store instance */
+    store: TranslationStore<T, L, M>;
+    /**
+     * Suspense mode for translation loading:
+     * - 'once' - suspend only on first load
+     * - 'first-load-locale' - suspend on first load for each locale
+     * - 'change-locale' - suspend on every locale change
+     */
+    suspenseMode: 'once' | 'first-load-locale' | 'change-locale';
+}
+
+export type { II18nTypedStoreContext as I, TranslationStore as T };

package/dist/context-Dp43aQ0V.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Translation store structure.
+ * Manages translations for multiple namespace keys and locales.
+ *
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template M - Type of translation modules mapping (e.g., { common: { greeting: string }, errors: { notFound: string } })
+ */
+type TranslationStore<T extends Record<string, string>, L extends Record<string, string>, M extends {
+    [K in keyof T]: any;
+}> = {
+    /** Currently active locale */
+    currentLocale: keyof L;
+    /** Available locales */
+    locales: L;
+    /** Translations map (namespace keys) */
+    translationsMap: T;
+    /**
+     * Adds a listener for locale change events.
+     *
+     * @param listener - Function to call when locale changes
+     */
+    addChangeLocaleListener: (listener: (locale: keyof L) => void) => void;
+    /**
+     * Removes a locale change listener.
+     *
+     * @param listener - Listener function to remove
+     */
+    removeChangeLocaleListener: (listener: (locale: keyof L) => void) => void;
+    /**
+     * Changes the current locale and notifies all listeners.
+     *
+     * @param locale - New locale key
+     */
+    changeLocale: (locale: keyof L) => void;
+    /** Translations organized by namespace key */
+    translations: {
+        [K in keyof T]: {
+            /** Currently active translation for this namespace */
+            currentTranslation?: M[K];
+            /** Locale of the current translation */
+            currentLocale?: keyof L;
+            /** Translations for all locales for this namespace */
+            translations: Record<keyof L, {
+                /** Loaded translation data, undefined if not loaded yet */
+                namespace: M[K] | undefined;
+                /** Whether translation is currently being loaded */
+                isLoading: boolean;
+                /** Whether an error occurred during loading */
+                isError: boolean;
+                /** Promise for the ongoing loading operation */
+                loadingPromise?: Promise<void>;
+            }>;
+            /**
+             * Loads translation for a specific locale.
+             *
+             * @param locale - Locale key to load translation for
+             * @param fromCache - Whether to use cached translation if available (default: true)
+             * @returns Promise that resolves when translation is loaded
+             * @throws Error if loading fails
+             */
+            load: (locale: keyof L, fromCache?: boolean) => Promise<void>;
+        };
+    };
+};
+
+/**
+ * Context value for I18n typed store.
+ * Provides access to translation store, locale management, and loading state.
+ *
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template M - Type of translation modules mapping (e.g., { common: { greeting: string }, errors: { notFound: string } })
+ */
+interface II18nTypedStoreContext<T extends Record<string, string> = Record<string, string>, L extends Record<string, string> = Record<string, string>, M extends {
+    [K in keyof T]: any;
+} = {
+    [K in keyof T]: any;
+}> {
+    /** Translation store instance */
+    store: TranslationStore<T, L, M>;
+    /**
+     * Suspense mode for translation loading:
+     * - 'once' - suspend only on first load
+     * - 'first-load-locale' - suspend on first load for each locale
+     * - 'change-locale' - suspend on every locale change
+     */
+    suspenseMode: 'once' | 'first-load-locale' | 'change-locale';
+}
+
+export type { II18nTypedStoreContext as I, TranslationStore as T };

package/dist/index.d.mts

@@ -1,56 +1,208 @@
+import { T as TranslationStore } from './context-Dp43aQ0V.mjs';
+export { I as II18nTypedStoreContext } from './context-Dp43aQ0V.mjs';
+
+/**
+ * Map of translation module loaders.
+ * Each namespace key maps to an object where each locale key maps to a loader function.
+ *
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template Module - Type of the raw module loaded from the module loader
+ */
+type TranslationModuleMap<T extends Record<string, string>, L extends Record<string, string>, Module = unknown> = Record<keyof T, Record<keyof L, () => Promise<Module>>>;
+
 /**
  * Creates a map of translation module loaders for all combinations of translations and locales.
+ * This map is used internally by the translation store to lazy-load translation modules.
+ *
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template Module - Type of the raw module loaded from the module loader
  *
  * @param translations - Object with translation keys
  * @param locales - Object with locale keys
- * @param loadModule - Function to load a translation module for a specific locale and translation
- * @returns Map where each translation key contains an object with loader functions for each locale
+ * @param loadModule - Function to load a translation module for a specific locale and namespace
+ * @returns Immutable map where each namespace key contains an object with loader functions for each locale
+ * @throws {TypeError} If translations or locales are empty objects
+ *
+ * @example
+ * ```ts
+ * const translations = { common: 'common', errors: 'errors' } as const;
+ * const locales = { en: 'en', ru: 'ru' } as const;
+ * const loadModule = async (locale, namespace) => import(`./${namespace}/${locale}.json`);
+ *
+ * const moduleMap = createTranslationModuleMap(translations, locales, loadModule);
+ * moduleMap.common.en() will load './common/en.json'
+ * moduleMap.errors.ru() will load './errors/ru.json'
+ * ```
  */
-declare const createTranslationModuleMap: <T extends Record<string, string>, L extends Record<string, string>, Module = unknown>(translations: T, locales: L, loadModule: (locale: keyof L, translation: keyof T) => Promise<Module>) => Record<keyof T, Record<keyof L, () => Promise<Module>>>;
+declare const createTranslationModuleMap: <T extends Record<string, string>, L extends Record<string, string>, Module = unknown>(translations: T, locales: L, loadModule: (locale: keyof L, namespace: keyof T) => Promise<Module>) => TranslationModuleMap<T, L, Module>;
 
 /**
- * Creates a translation store with typed translations for different locales.
+ * Options for creating a translation store.
  *
- * @param translations - Object with translation keys
- * @param locales - Object with locale keys
- * @param loadModule - Function to load a translation module
- * @param extractTranslation - Function to extract translation data from the loaded module.
- *   Receives three parameters: (module, locale, translation) allowing for locale-specific
- *   or translation-specific extraction logic.
- * @returns Object with a type() method for creating a typed translation store
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template Module - Type of the raw module loaded from the module loader
+ */
+interface CreateTranslationStoreOptions<T extends Record<string, string>, L extends Record<string, string>, Module = unknown> {
+    /** Object with translation keys */
+    translations: T;
+    /** Object with locale keys */
+    locales: L;
+    /** Function to load a translation module for a specific locale and namespace */
+    loadModule: (locale: keyof L, namespace: keyof T) => Promise<Module>;
+    /**
+     * Function to extract translation data from the loaded module.
+     * Receives three parameters: (module, locale, namespace) allowing for locale-specific
+     * or namespace-specific extraction logic.
+     */
+    extractTranslation: (module: Module, locale: keyof L, namespace: keyof T) => unknown | Promise<unknown>;
+    /**
+     * Whether to delete translations for other locales after loading a new one.
+     * Useful for memory-constrained environments.
+     * @default false
+     */
+    deleteOtherLocalesAfterLoad?: boolean;
+    /**
+     * Whether to load translations from cache by default.
+     * If false, will always reload even if translation is already cached.
+     * @default true
+     */
+    loadFromCache?: boolean;
+    /** Default locale key to use */
+    defaultLocale: keyof L;
+    /**
+     * Whether to use fallback locale for missing translations.
+     * When enabled, translations will be merged with fallback locale translations.
+     * @default false
+     */
+    useFallback?: boolean;
+    /**
+     * Fallback locale key to use when useFallback is true.
+     * If not provided, defaultLocale will be used as fallback.
+     * @default defaultLocale
+     */
+    fallbackLocale?: keyof L;
+    /**
+     * Event name for locale change events.
+     * @default 'change-locale'
+     */
+    changeLocaleEventName?: string;
+}
+
+/**
+ * Creates a translation store factory with typed translations for different locales.
+ * The store supports lazy loading, caching, error handling, and fallback locale merging.
+ *
+ * @template T - Type of translations object (e.g., { common: 'common', errors: 'errors' })
+ * @template L - Type of locales object (e.g., { en: 'en', ru: 'ru' })
+ * @template Module - Type of the raw module loaded from the module loader
+ *
+ * @param options - Configuration options for the translation store
+ * @returns Object with a `type()` method for creating a typed translation store
+ * @throws {TypeError} If required options are invalid
+ *
+ * @example
+ * ```ts
+ * const translations = { common: 'common', errors: 'errors' } as const;
+ * const locales = { en: 'en', ru: 'ru' } as const;
+ *
+ * const storeFactory = createTranslationStore({
+ *   translations,
+ *   locales,
+ *   loadModule: async (locale, namespace) => import(`./${namespace}/${locale}.json`),
+ *   extractTranslation: (module) => module.default || module,
+ *   defaultLocale: 'en',
+ *   useFallback: true,
+ *   fallbackLocale: 'en',
+ * });
+ *
+ * const store = storeFactory.type<{
+ *   common: { greeting: string };
+ *   errors: { notFound: string };
+ * }>();
+ * ```
  */
-declare const createTranslationStore: <T extends Record<string, string>, L extends Record<string, string>, Module = unknown>(translations: T, locales: L, loadModule: (locale: keyof L, translation: keyof T) => Promise<Module>, extractTranslation: (module: Module, locale: keyof L, translation: keyof T) => unknown) => {
+declare const createTranslationStore: <T extends Record<string, string>, L extends Record<string, string>, Module = unknown>({ translations, locales, loadModule, extractTranslation, deleteOtherLocalesAfterLoad, loadFromCache, defaultLocale, useFallback, fallbackLocale, changeLocaleEventName, }: CreateTranslationStoreOptions<T, L, Module>) => {
     /**
      * Creates a typed translation store.
+     * The store provides methods to load and access translations for each locale.
+     * When useFallback is enabled, translations are automatically merged with fallback locale.
      *
-     * @template M - Type of translation object where each key corresponds to a key from translations
+     * @template M - Type of translation modules mapping where each key corresponds to a key from translations
      * @returns Store with methods to load translations for each locale
+     *
+     * @example
+     * ```ts
+     * const store = storeFactory.type<{
+     *   common: { greeting: string; goodbye: string };
+     *   errors: { notFound: string; unauthorized: string };
+     * }>();
+     *
+     * await store.common.load('ru');
+     * // If useFallback is true and 'ru' translation is missing some keys,
+     * // they will be filled from fallback locale (e.g., 'en')
+     * const greeting = store.common.translations.ru.namespace?.greeting;
+     * ```
      */
-    type: <M extends { [K in keyof T]: any; }>() => { [K in keyof T]: {
-        translation?: M[K];
-        load: (locale: keyof L) => Promise<void>;
-    }; };
+    type: <M extends { [K in keyof T]: any; }>() => TranslationStore<T, L, M>;
 };
 
 /**
  * Plural form variants for different plural categories.
  * Based on Unicode CLDR plural rules: zero, one, two, few, many, other.
+ *
+ * @see https://unicode-org.github.io/cldr-staging/charts/latest/supplemental/language_plural_rules.html
+ *
+ * @example
+ * ```ts
+ * const variants: PluralVariants = {
+ *   one: 'item',
+ *   other: 'items'
+ * };
+ * ```
  */
 type PluralVariants = {
+    /** Used for count = 0 (in some languages) */
     zero?: string;
+    /** Used for count = 1 (in most languages) */
     one?: string;
+    /** Used for count = 2 (in some languages like Welsh) */
     two?: string;
+    /** Used for small numbers (e.g., 3-10 in Russian) */
     few?: string;
+    /** Used for large numbers or fractional values */
     many?: string;
-    other?: string;
+    /** Default/fallback variant - MUST be provided for correct pluralization */
+    other: string;
 };
+/**
+ * Valid plural category names according to CLDR.
+ */
+type PluralCategory = keyof PluralVariants;
+
+/**
+ * Options for creating a plural selector.
+ */
+interface CreatePluralSelectorOptions {
+    /**
+     * Whether to throw an error if 'other' variant is missing.
+     * @default false
+     */
+    strict?: boolean;
+}
 
 /**
  * Creates a plural selector function for a specific locale.
- * The returned function selects the appropriate plural form based on the count.
+ * The returned function selects the appropriate plural form based on the count
+ * using Unicode CLDR plural rules.
  *
- * @param locale - Locale string (e.g., 'en', 'ru', 'fr')
+ * @param locale - Locale string (e.g., 'en', 'ru', 'fr', 'uk-UA')
+ * @param options - Configuration options
  * @returns Function that takes a count and plural variants, returns the matching variant
+ * @throws {TypeError} If locale is not a valid string
+ * @throws {Error} If strict mode is enabled and 'other' variant is missing
  *
  * @example
  * ```ts
@@ -58,7 +210,34 @@ type PluralVariants = {
  * selectPlural(1, { one: 'item', other: 'items' }); // => 'item'
  * selectPlural(5, { one: 'item', other: 'items' }); // => 'items'
  * ```
+ *
+ * @example
+ * ```ts
+ * const selectPlural = createPluralSelector('ru');
+ * selectPlural(1, { one: 'элемент', few: 'элемента', many: 'элементов', other: 'элементов' }); // => 'элемент'
+ * selectPlural(2, { one: 'элемент', few: 'элемента', many: 'элементов', other: 'элементов' }); // => 'элемента'
+ * selectPlural(5, { one: 'элемент', few: 'элемента', many: 'элементов', other: 'элементов' }); // => 'элементов'
+ * ```
+ */
+declare const createPluralSelector: (locale: string, options?: CreatePluralSelectorOptions) => ((count: number, variants: PluralVariants) => string);
+
+/**
+ * Event listener function type.
+ *
+ * @template T - Type of event arguments array
+ */
+type Listener<T extends any[] = any[]> = (...args: T) => void;
+/**
+ * Event map type that maps event names to their argument types.
+ *
+ * @example
+ * ```ts
+ * type MyEvents = {
+ *   'user-login': [userId: string, timestamp: number];
+ *   'user-logout': [userId: string];
+ * };
+ * ```
  */
-declare const createPluralSelector: (locale: string) => (count: number, variants: PluralVariants) => string;
+type EventMap = Record<PropertyKey, any[]>;
 
-export { createPluralSelector, createTranslationModuleMap, createTranslationStore };
+export { type CreatePluralSelectorOptions, type CreateTranslationStoreOptions, type EventMap, type Listener, type PluralCategory, type PluralVariants, type TranslationModuleMap, TranslationStore, createPluralSelector, createTranslationModuleMap, createTranslationStore };