i18n-typed-store 0.1.0 → 0.1.1

package/dist/react/index.d.mts

@@ -0,0 +1,296 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, FC } from 'react';
+import { I as II18nTypedStoreContext, T as TranslationStore } from '../context-Dp43aQ0V.mjs';
+
+/**
+ * React context for I18n typed store.
+ * Used internally by hooks to access the translation store.
+ */
+declare const I18nTypedStoreContext: react.Context<II18nTypedStoreContext<any, any, any> | null>;
+/**
+ * Provider component for I18n typed store.
+ * Wraps your application to provide translation store context to child components.
+ *
+ * @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
+ *
+ * @param props - Provider props
+ * @param props.store - Translation store instance
+ * @param props.children - React children
+ * @param props.suspenseMode - Suspense mode: 'once' | 'first-load-locale' | 'change-locale'
+ * @returns Provider component
+ *
+ * @example
+ * ```tsx
+ * const store = storeFactory.type<MyTranslations>();
+ *
+ * function App() {
+ *   return (
+ *     <I18nTypedStoreProvider store={store}>
+ *       <MyComponent />
+ *     </I18nTypedStoreProvider>
+ *   );
+ * }
+ * ```
+ */
+declare const I18nTypedStoreProvider: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K in keyof T]: any; }>({ store, children, suspenseMode, }: {
+    store: TranslationStore<T, L, M>;
+    children: ReactNode;
+    suspenseMode?: II18nTypedStoreContext<T, L, M>["suspenseMode"];
+}) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Safe component that catches errors during string extraction from translation objects.
+ * Useful for safely accessing nested translation keys that might throw errors.
+ *
+ * @param props - Component props
+ * @param props.children - Function that returns a string (called during render)
+ * @param props.errorComponent - Component to display if an error occurs (default: empty string)
+ * @param props.errorHandler - Optional error handler callback
+ * @returns Rendered string wrapped in a span or error component
+ *
+ * @example
+ * ```tsx
+ * <Safe
+ *   errorComponent={<span>N/A</span>}
+ *   errorHandler={(error) => console.error(error)}
+ * >
+ *   {() => translations.common.pages.main.title}
+ * </Safe>
+ * ```
+ */
+declare const Safe: FC<{
+    children: () => string;
+    errorComponent?: ReactNode;
+    errorHandler?: (error: unknown) => void;
+}>;
+
+/**
+ * Hook for accessing translations with automatic loading and locale change handling.
+ * Returns undefined if translation is not yet loaded.
+ *
+ * @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
+ * @template K - Namespace key from translations object
+ *
+ * @param namespace - Namespace key to load translations for
+ * @param fromCache - Whether to use cached translation if available (default: true)
+ * @returns Translation object for the specified namespace, or undefined if not loaded
+ *
+ * @example
+ * ```tsx
+ * const translations = useI18nTranslation('common');
+ * if (translations) {
+ *   console.log(translations.greeting);
+ * }
+ * ```
+ */
+declare const useI18nTranslation: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K_1 in keyof T]: any; }, K extends keyof T>(namespace: K, fromCache?: boolean) => M[K] | undefined;
+
+/**
+ * Hook for accessing translations with lazy loading and suspense support.
+ * Throws a promise if translation is not yet loaded (for React Suspense).
+ * Always returns a translation object (never undefined).
+ *
+ * @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
+ * @template K - Namespace key from translations object
+ *
+ * @param namespace - Namespace key to load translations for
+ * @param fromCache - Whether to use cached translation if available (default: true)
+ * @returns Translation object for the specified namespace (never undefined)
+ * @throws Promise if translation is not yet loaded (for React Suspense)
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const translations = useI18nTranslationLazy('common');
+ *   return <div>{translations.greeting}</div>;
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<Loading />}>
+ *       <MyComponent />
+ *     </Suspense>
+ *   );
+ * }
+ * ```
+ */
+declare const useI18nTranslationLazy: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K_1 in keyof T]: any; }, K extends keyof T>(namespace: K, fromCache?: boolean) => M[K];
+
+/**
+ * Hook for accessing the I18n typed store context.
+ * Must be used within an I18nTypedStoreProvider.
+ *
+ * @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
+ *
+ * @returns I18n typed store context value
+ * @throws Error if used outside of I18nTypedStoreProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { store, suspenseMode } = useI18nTypedStoreContext();
+ *   // Use store, suspenseMode
+ * }
+ * ```
+ */
+declare const useI18nTypedStoreContext: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K in keyof T]: any; }>() => II18nTypedStoreContext<T, L, M>;
+
+/**
+ * Hook for accessing and managing the current locale.
+ * Returns the current locale and a function to change it.
+ * Supports SSR/SSG by using useSyncExternalStore for proper hydration.
+ *
+ * @template T - Type of translations object
+ * @template L - Type of locales object
+ * @template M - Type of translation modules mapping
+ *
+ * @returns Object with current locale and setLocale function
+ *
+ * @example
+ * ```tsx
+ * function LocaleSwitcher() {
+ *   const { locale, setLocale } = useI18nLocale();
+ *   return (
+ *     <select value={locale} onChange={(e) => setLocale(e.target.value as keyof Locales)}>
+ *       <option value="en">English</option>
+ *       <option value="ru">Русский</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+declare const useI18nLocale: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K in keyof T]: any; }>() => {
+    locale: keyof L;
+    setLocale: (locale: keyof L) => void;
+};
+
+/**
+ * Request context interface for locale detection in SSR environments.
+ * Compatible with various SSR frameworks (Next.js, Remix, SvelteKit, etc.)
+ * and standard request objects that provide query, cookies, and headers.
+ */
+interface RequestContext {
+    query?: Record<string, string | string[]>;
+    cookies?: Record<string, string>;
+    headers?: Record<string, string | string[]> | Headers;
+}
+/**
+ * Options for getting locale from SSR request.
+ */
+interface GetLocaleFromRequestOptions {
+    /**
+     * Header name to read locale from (e.g., 'accept-language', 'x-locale')
+     * @default 'accept-language'
+     */
+    headerName?: string;
+    /**
+     * Cookie name to read locale from
+     */
+    cookieName?: string;
+    /**
+     * Query parameter name to read locale from (e.g., 'locale', 'lang')
+     */
+    queryParamName?: string;
+    /**
+     * Default locale to use if locale cannot be determined
+     */
+    defaultLocale: string;
+    /**
+     * Available locales to validate against
+     */
+    availableLocales: readonly string[];
+    /**
+     * Whether to parse Accept-Language header and find best match
+     * @default true
+     */
+    parseAcceptLanguage?: boolean;
+}
+/**
+ * Gets locale from SSR request context.
+ * Checks query params, cookies, and headers in that order.
+ * Works with any SSR framework that provides these standard request properties.
+ *
+ * @template L - Type of locales object
+ * @param context - SSR request context with query, cookies, and headers
+ * @param options - Options for locale detection
+ * @returns Detected locale key
+ *
+ * @example
+ * ```ts
+ * // Next.js example
+ * import type { GetServerSidePropsContext } from 'next';
+ *
+ * export async function getServerSideProps(context: GetServerSidePropsContext) {
+ *   const locale = getLocaleFromRequest(context, {
+ *     defaultLocale: 'en',
+ *     availableLocales: ['en', 'ru'],
+ *     cookieName: 'locale',
+ *     queryParamName: 'locale',
+ *   });
+ *
+ *   const store = storeFactory.type<MyTranslations>();
+ *   initializeStore(store, locale);
+ *
+ *   return { props: { locale } };
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Remix example
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const url = new URL(request.url);
+ *   const context: RequestContext = {
+ *     query: Object.fromEntries(url.searchParams),
+ *     headers: Object.fromEntries(request.headers),
+ *   };
+ *
+ *   const locale = getLocaleFromRequest(context, {
+ *     defaultLocale: 'en',
+ *     availableLocales: ['en', 'ru'],
+ *   });
+ *
+ *   return { locale };
+ * }
+ * ```
+ */
+declare function getLocaleFromRequest<L extends Record<string, string>>(context: RequestContext, options: GetLocaleFromRequestOptions): keyof L;
+/**
+ * Initializes translation store with a specific locale.
+ * Useful for SSR/SSG where you need to set the locale before rendering.
+ *
+ * @template T - Type of translations object
+ * @template L - Type of locales object
+ * @template M - Type of translation modules mapping
+ * @param store - Translation store instance
+ * @param locale - Locale to initialize with
+ *
+ * @example
+ * ```ts
+ * // In SSR handler
+ * const locale = getLocaleFromRequest(context, {
+ *   defaultLocale: 'en',
+ *   availableLocales: ['en', 'ru'],
+ * });
+ *
+ * const store = storeFactory.type<MyTranslations>();
+ * initializeStore(store, locale);
+ *
+ * // Preload translations if needed
+ * await store.common.load(locale);
+ * ```
+ */
+declare function initializeStore<T extends Record<string, string>, L extends Record<string, string>, M extends {
+    [K in keyof T]: any;
+}>(store: TranslationStore<T, L, M>, locale: keyof L): void;
+
+export { type GetLocaleFromRequestOptions, I18nTypedStoreContext, I18nTypedStoreProvider, type RequestContext, Safe, getLocaleFromRequest, initializeStore, useI18nLocale, useI18nTranslation, useI18nTranslationLazy, useI18nTypedStoreContext };

package/dist/react/index.d.ts

@@ -0,0 +1,296 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode, FC } from 'react';
+import { I as II18nTypedStoreContext, T as TranslationStore } from '../context-Dp43aQ0V.js';
+
+/**
+ * React context for I18n typed store.
+ * Used internally by hooks to access the translation store.
+ */
+declare const I18nTypedStoreContext: react.Context<II18nTypedStoreContext<any, any, any> | null>;
+/**
+ * Provider component for I18n typed store.
+ * Wraps your application to provide translation store context to child components.
+ *
+ * @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
+ *
+ * @param props - Provider props
+ * @param props.store - Translation store instance
+ * @param props.children - React children
+ * @param props.suspenseMode - Suspense mode: 'once' | 'first-load-locale' | 'change-locale'
+ * @returns Provider component
+ *
+ * @example
+ * ```tsx
+ * const store = storeFactory.type<MyTranslations>();
+ *
+ * function App() {
+ *   return (
+ *     <I18nTypedStoreProvider store={store}>
+ *       <MyComponent />
+ *     </I18nTypedStoreProvider>
+ *   );
+ * }
+ * ```
+ */
+declare const I18nTypedStoreProvider: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K in keyof T]: any; }>({ store, children, suspenseMode, }: {
+    store: TranslationStore<T, L, M>;
+    children: ReactNode;
+    suspenseMode?: II18nTypedStoreContext<T, L, M>["suspenseMode"];
+}) => react_jsx_runtime.JSX.Element;
+
+/**
+ * Safe component that catches errors during string extraction from translation objects.
+ * Useful for safely accessing nested translation keys that might throw errors.
+ *
+ * @param props - Component props
+ * @param props.children - Function that returns a string (called during render)
+ * @param props.errorComponent - Component to display if an error occurs (default: empty string)
+ * @param props.errorHandler - Optional error handler callback
+ * @returns Rendered string wrapped in a span or error component
+ *
+ * @example
+ * ```tsx
+ * <Safe
+ *   errorComponent={<span>N/A</span>}
+ *   errorHandler={(error) => console.error(error)}
+ * >
+ *   {() => translations.common.pages.main.title}
+ * </Safe>
+ * ```
+ */
+declare const Safe: FC<{
+    children: () => string;
+    errorComponent?: ReactNode;
+    errorHandler?: (error: unknown) => void;
+}>;
+
+/**
+ * Hook for accessing translations with automatic loading and locale change handling.
+ * Returns undefined if translation is not yet loaded.
+ *
+ * @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
+ * @template K - Namespace key from translations object
+ *
+ * @param namespace - Namespace key to load translations for
+ * @param fromCache - Whether to use cached translation if available (default: true)
+ * @returns Translation object for the specified namespace, or undefined if not loaded
+ *
+ * @example
+ * ```tsx
+ * const translations = useI18nTranslation('common');
+ * if (translations) {
+ *   console.log(translations.greeting);
+ * }
+ * ```
+ */
+declare const useI18nTranslation: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K_1 in keyof T]: any; }, K extends keyof T>(namespace: K, fromCache?: boolean) => M[K] | undefined;
+
+/**
+ * Hook for accessing translations with lazy loading and suspense support.
+ * Throws a promise if translation is not yet loaded (for React Suspense).
+ * Always returns a translation object (never undefined).
+ *
+ * @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
+ * @template K - Namespace key from translations object
+ *
+ * @param namespace - Namespace key to load translations for
+ * @param fromCache - Whether to use cached translation if available (default: true)
+ * @returns Translation object for the specified namespace (never undefined)
+ * @throws Promise if translation is not yet loaded (for React Suspense)
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const translations = useI18nTranslationLazy('common');
+ *   return <div>{translations.greeting}</div>;
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<Loading />}>
+ *       <MyComponent />
+ *     </Suspense>
+ *   );
+ * }
+ * ```
+ */
+declare const useI18nTranslationLazy: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K_1 in keyof T]: any; }, K extends keyof T>(namespace: K, fromCache?: boolean) => M[K];
+
+/**
+ * Hook for accessing the I18n typed store context.
+ * Must be used within an I18nTypedStoreProvider.
+ *
+ * @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
+ *
+ * @returns I18n typed store context value
+ * @throws Error if used outside of I18nTypedStoreProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { store, suspenseMode } = useI18nTypedStoreContext();
+ *   // Use store, suspenseMode
+ * }
+ * ```
+ */
+declare const useI18nTypedStoreContext: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K in keyof T]: any; }>() => II18nTypedStoreContext<T, L, M>;
+
+/**
+ * Hook for accessing and managing the current locale.
+ * Returns the current locale and a function to change it.
+ * Supports SSR/SSG by using useSyncExternalStore for proper hydration.
+ *
+ * @template T - Type of translations object
+ * @template L - Type of locales object
+ * @template M - Type of translation modules mapping
+ *
+ * @returns Object with current locale and setLocale function
+ *
+ * @example
+ * ```tsx
+ * function LocaleSwitcher() {
+ *   const { locale, setLocale } = useI18nLocale();
+ *   return (
+ *     <select value={locale} onChange={(e) => setLocale(e.target.value as keyof Locales)}>
+ *       <option value="en">English</option>
+ *       <option value="ru">Русский</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ */
+declare const useI18nLocale: <T extends Record<string, string>, L extends Record<string, string>, M extends { [K in keyof T]: any; }>() => {
+    locale: keyof L;
+    setLocale: (locale: keyof L) => void;
+};
+
+/**
+ * Request context interface for locale detection in SSR environments.
+ * Compatible with various SSR frameworks (Next.js, Remix, SvelteKit, etc.)
+ * and standard request objects that provide query, cookies, and headers.
+ */
+interface RequestContext {
+    query?: Record<string, string | string[]>;
+    cookies?: Record<string, string>;
+    headers?: Record<string, string | string[]> | Headers;
+}
+/**
+ * Options for getting locale from SSR request.
+ */
+interface GetLocaleFromRequestOptions {
+    /**
+     * Header name to read locale from (e.g., 'accept-language', 'x-locale')
+     * @default 'accept-language'
+     */
+    headerName?: string;
+    /**
+     * Cookie name to read locale from
+     */
+    cookieName?: string;
+    /**
+     * Query parameter name to read locale from (e.g., 'locale', 'lang')
+     */
+    queryParamName?: string;
+    /**
+     * Default locale to use if locale cannot be determined
+     */
+    defaultLocale: string;
+    /**
+     * Available locales to validate against
+     */
+    availableLocales: readonly string[];
+    /**
+     * Whether to parse Accept-Language header and find best match
+     * @default true
+     */
+    parseAcceptLanguage?: boolean;
+}
+/**
+ * Gets locale from SSR request context.
+ * Checks query params, cookies, and headers in that order.
+ * Works with any SSR framework that provides these standard request properties.
+ *
+ * @template L - Type of locales object
+ * @param context - SSR request context with query, cookies, and headers
+ * @param options - Options for locale detection
+ * @returns Detected locale key
+ *
+ * @example
+ * ```ts
+ * // Next.js example
+ * import type { GetServerSidePropsContext } from 'next';
+ *
+ * export async function getServerSideProps(context: GetServerSidePropsContext) {
+ *   const locale = getLocaleFromRequest(context, {
+ *     defaultLocale: 'en',
+ *     availableLocales: ['en', 'ru'],
+ *     cookieName: 'locale',
+ *     queryParamName: 'locale',
+ *   });
+ *
+ *   const store = storeFactory.type<MyTranslations>();
+ *   initializeStore(store, locale);
+ *
+ *   return { props: { locale } };
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Remix example
+ * export async function loader({ request }: LoaderFunctionArgs) {
+ *   const url = new URL(request.url);
+ *   const context: RequestContext = {
+ *     query: Object.fromEntries(url.searchParams),
+ *     headers: Object.fromEntries(request.headers),
+ *   };
+ *
+ *   const locale = getLocaleFromRequest(context, {
+ *     defaultLocale: 'en',
+ *     availableLocales: ['en', 'ru'],
+ *   });
+ *
+ *   return { locale };
+ * }
+ * ```
+ */
+declare function getLocaleFromRequest<L extends Record<string, string>>(context: RequestContext, options: GetLocaleFromRequestOptions): keyof L;
+/**
+ * Initializes translation store with a specific locale.
+ * Useful for SSR/SSG where you need to set the locale before rendering.
+ *
+ * @template T - Type of translations object
+ * @template L - Type of locales object
+ * @template M - Type of translation modules mapping
+ * @param store - Translation store instance
+ * @param locale - Locale to initialize with
+ *
+ * @example
+ * ```ts
+ * // In SSR handler
+ * const locale = getLocaleFromRequest(context, {
+ *   defaultLocale: 'en',
+ *   availableLocales: ['en', 'ru'],
+ * });
+ *
+ * const store = storeFactory.type<MyTranslations>();
+ * initializeStore(store, locale);
+ *
+ * // Preload translations if needed
+ * await store.common.load(locale);
+ * ```
+ */
+declare function initializeStore<T extends Record<string, string>, L extends Record<string, string>, M extends {
+    [K in keyof T]: any;
+}>(store: TranslationStore<T, L, M>, locale: keyof L): void;
+
+export { type GetLocaleFromRequestOptions, I18nTypedStoreContext, I18nTypedStoreProvider, type RequestContext, Safe, getLocaleFromRequest, initializeStore, useI18nLocale, useI18nTranslation, useI18nTranslationLazy, useI18nTypedStoreContext };