intor-translator 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -1,265 +1,383 @@
-import { LocaleNamespaceMessages, Locale, RichReplacement, FallbackLocalesMap, Replacement } from 'intor-types';
-
 /**
- * Represents the available locale namespaces from the message map.
+ * Represents a locale identifier, such as 'en', 'zh-TW', or 'fr-FR'.
  *
- * Extracts top-level keys from the entire localized message structure,
- * which are typically used as namespace identifiers (e.g., "common", "home", "dashboard").
+ * @example
+ * const locale: Locale = "en";
+ */
+type Locale = string;
+/**
+ * Represents a message namespace.
+ * Typically used to group related messages, such as 'common', 'auth', or 'dashboard'.
  *
- * @template Messages - The type of the locale message map.
+ * @example
+ * const namespace: Namespace = "dashboard";
  */
-type RawLocale<Messages extends LocaleNamespaceMessages> = keyof Messages & string;
+type Namespace = string;
 /**
- * Computes all possible nested key paths of a deeply nested object.
+ * Represents a single translatable message string.
  *
- * Example:
- * ```ts
- * {
- *   a: {
- *     b: {
- *       c: "hello";
- *     };
- *   };
- * }
- * ```
- * Will generate: `"a" | "a.b" | "a.b.c"`
+ * @example
+ * const message: Message = "Hello World";
+ */
+type Message = string;
+/**
+ * A recursive replacement object used for interpolating values in message templates.
  *
- * Useful for type-safe translation key autocompletion and validation.
+ * Each key maps to a value that can be a string, number, or another nested `Replacement`.
+ * This structure supports deep replacements such as `user.profile.link`.
  *
- * @template Messages - The message object to extract nested key paths from.
+ * @example
+ * const replacements: Replacement = {
+ *   name: "intor",
+ *   count: 5,
+ *   user: {
+ *     profile: {
+ *       link: "https://example.com/avatar.png"
+ *     }
+ *   }
+ * };
  */
-type NestedKeyPaths<Messages> = Messages extends object ? {
-    [Key in keyof Messages]: `${Key & string}` | `${Key & string}.${NestedKeyPaths<Messages[Key]>}`;
-}[keyof Messages] : never;
+type Replacement = {
+    [key: string]: string | number | Replacement;
+};
 
-type TranslatorHandlers = {
-    /**
-     * A custom formatter function to format translation messages.
-     * You can use this to integrate ICU libraries like `intl-messageformat`.
-     */
-    messageFormatter?: MessageFormatter;
-    /**
-     * Handler for loading state of the translation message.
-     * Useful when translations are loaded asynchronously.
-     */
-    loadingMessageHandler?: LoadingMessageHandler;
-    /**
-     * Handler for placeholders in translation messages.
-     * Useful for handling missing or fallback placeholders.
-     */
-    placeholderHandler?: PlaceholderHandler;
+/** Represents primitive types supported in rich replacements. */
+type RichPrimitive = string | number | boolean | Date;
+/** Represents serializable objects that provide a custom string representation. */
+type RichSerializable = {
+    toString(): string;
 };
+/** A formatter function that takes a string chunk and returns any formatted output. */
+type RichFormatterFunction = (value: unknown, ...args: unknown[]) => unknown;
+/**
+ * Possible value types for rich replacements.
+ * Can be a primitive, serializable object, formatter function, or null/undefined.
+ */
+type ReplacementValue = RichPrimitive | RichSerializable | RichFormatterFunction | null | undefined;
 /**
- * Custom formatter for translation messages.
+ * A recursive replacement object that supports rich replacement values,
+ * allowing complex nested interpolation structures.
  *
- * This function receives the raw message and context to produce a formatted result.
- * You can use this to integrate ICU-style formatting or other complex message processing.
+ * @example
+ * const replacements: RichReplacement = {
+ *   name: "Alice",
+ *   age: 30,
+ *   isActive: true,
+ *   birthday: new Date("1993-04-25"),
+ *   formatter: (value, ...args) => `<b>${value}</b>`,
+ *   nested: {
+ *     score: 100,
+ *     note: null,
+ *   },
+ * };
+ */
+type RichReplacement = {
+    [key: string]: ReplacementValue;
+};
+
+/**
+ * A nested message structure or a simple string message.
+ * Used to represent either a plain message or an object containing more nested messages.
  *
- * @template Result - The type of the formatted result.
+ * @example
+ * const greeting: NestedMessage = "Hello";
  *
- * @param ctx - The context object containing information for formatting.
- * @param ctx.message - The raw message string to format.
- * @param ctx.locale - The currently active locale string (e.g. 'en-US').
- * @param ctx.key - The translation key associated with this message.
- * @param ctx.replacements - Optional replacement values for variables inside the message.
+ * const userMessages: NestedMessage = {
+ *   profile: {
+ *     greeting: "Hello, user!",
+ *     farewell: "Goodbye!"
+ *   }
+ * };
+ */
+type NestedMessage = Message | {
+    [key: string]: NestedMessage;
+};
+/**
+ * A record of messages where keys are strings, and values can be strings or nested message objects.
+ * Supports deep message trees like `errors.form.required`.
  *
- * @returns The formatted message, usually a string but can be any type.
+ * @example
+ * const messages: MessageRecord = {
+ *   greeting: "Hello",
+ *   user: {
+ *     profile: {
+ *       name: "Your Name"
+ *     }
+ *   }
+ * };
  */
-type MessageFormatter<Result = unknown> = (ctx: TranslatorHandlerContext & {
-    message: string;
-}) => Result;
+type MessageRecord = Record<string, NestedMessage>;
 /**
- * Handler function called when translation message is loading.
+ * A record of messages grouped by namespace.
+ * Each namespace contains its own `MessageRecord` structure.
  *
- * @template Result - The type of the loading handler result.
+ * @example
+ * const namespaceMessages: NamespaceMessages = {
+ *   common: {
+ *     hello: "Hello",
+ *     goodbye: "Goodbye"
+ *   },
+ *   auth: {
+ *     login: {
+ *       success: "Login successful"
+ *     }
+ *   }
+ * };
+ */
+type NamespaceMessages = Record<Namespace, NestedMessage>;
+/**
+ * Messages grouped by locale and then by namespace.
+ * Used to structure all available messages for multiple locales and namespaces.
  *
- * @param ctx - The context object containing locale, key, and replacements.
- * @returns Result to display during loading (e.g. a placeholder string or React element).
+ * @example
+ * const messages: LocaleNamespaceMessages = {
+ *   en: {
+ *     common: {
+ *       welcome: "Welcome"
+ *     },
+ *     auth: {
+ *       login: {
+ *         success: "Login successful"
+ *       }
+ *     }
+ *   },
+ *   "zh-TW": {
+ *     common: {
+ *       welcome: "歡迎"
+ *     }
+ *   }
+ * };
  */
-type LoadingMessageHandler<Result = unknown> = (ctx: TranslatorHandlerContext) => Result;
+type LocaleNamespaceMessages = Record<Locale, NamespaceMessages>;
 /**
- * Handler function for placeholders in translation messages.
+ * Merges messages from all locales into a single unified structure.
  *
- * @template Result - The type of the placeholder handler result.
+ * @example
+ * const messages = {
+ *   en: { auth: { login: "Login" } },
+ *   zh: { auth: { logout: "登出" } },
+ * };
  *
- * @param ctx - The context object containing locale, key, and replacements.
- * @returns Result to display for placeholders (e.g. a default string or React element).
+ * type Result = UnionLocaleMessages<typeof messages>;
+ * // Result: { auth: { login: "Login" } } | { auth: { logout: "登出" } }
  */
-type PlaceholderHandler<Result = unknown> = (ctx: TranslatorHandlerContext) => Result;
+type UnionLocaleMessages<M extends LocaleNamespaceMessages> = M[LocaleKey<M>];
+
 /**
- * Context object passed to translation handlers.
- * Contains necessary information for formatting or handling translation messages.
+ * Extracts the locale keys from the messages object as string literals.
+ *
+ * @example
+ * type Locales = LocaleKey<{
+ *   en: {};
+ *   "zh-TW": {};
+ * }>;
+ * // Locales is "en" | "zh-TW"
  */
-type TranslatorHandlerContext = {
-    locale: Locale;
-    key: string;
-    replacements?: RichReplacement;
-};
-
+type LocaleKey<M extends LocaleNamespaceMessages> = keyof M & string;
 /**
- * - Options for creating a translator instance.
+ * A map that defines fallback locales for each base locale.
+ *
+ * When a message is missing for a given locale, the system will attempt to find the message
+ * by falling back to the locales listed here, in the specified order.
  *
  * @example
- * ```ts
- * const options: TranslatorOptions = {
- *   locale: 'en',
- *   messages: {
- *     en: { common: { hello: "Hello" } },
- *     zh: { common: { hello: "你好" } },
- *   },
- *   fallbackLocales: { zh: ['en'] },
- *   handlers: {
- *     messageFormatter: ({ message }) => message.toUpperCase(),
- *   },
+ * const fallbacks: FallbackLocalesMap = {
+ *   "en-AU": ["en-GB", "en"],
+ *   "zh-TW": ["zh-HK", "zh"]
  * };
- * ```
  */
-type TranslatorOptions<Messages extends LocaleNamespaceMessages> = {
-    /**
-     * - The message definitions to be used by the translator.
-     * - These should be pre-loaded and structured by locale and namespace.
-     */
-    messages: Readonly<Messages>;
-    /**
-     * - The current active locale, e.g., "en" or "zh-TW".
-     */
-    locale: RawLocale<Messages>;
-    /**
-     * - Optional fallback locale(s) to use when a message is missing in the primary locale.
-     */
-    fallbackLocales?: FallbackLocalesMap;
-    /**
-     * - Whether the translator is currently in a loading state.
-     * - Useful for SSR or async loading scenarios.
-     */
-    isLoading?: boolean;
-    /**
-     * - The message string to return while in loading state.
-     * - Will be overridden if you provide a `loadingMessageHandler` in handlers.
-     */
-    loadingMessage?: string;
-    /**
-     * - A fallback string to show when the message key is missing.
-     * - Will be overridden if you provide a `placeholderHandler` in handlers.
-     */
-    placeholder?: string;
-    /**
-     * - Optional handlers to customize translation behavior (formatting, placeholders, etc).
-     */
-    handlers?: TranslatorHandlers;
-};
-
-type GetLocale<Messages extends LocaleNamespaceMessages> = () => RawLocale<Messages>;
-
-type GetMessages<Messages extends LocaleNamespaceMessages> = () => Readonly<Messages>;
-
-type HasKey<Messages extends LocaleNamespaceMessages> = {
-    <Locale extends RawLocale<Messages>>(key: NestedKeyPaths<Messages[Locale]>, locale?: Locale): boolean;
-    (key: string, locale?: Locale): boolean;
-};
-type LooseHasKey = (key?: string, locale?: Locale) => boolean;
-
-type Translate<Messages extends LocaleNamespaceMessages> = {
-    <Locale extends RawLocale<Messages>>(key: NestedKeyPaths<Messages[Locale]>, replacements?: Replacement | RichReplacement): string;
-    (key: string, replacements?: Replacement | RichReplacement): string;
-};
-type LooseTranslate = (key?: string, replacements?: Replacement | RichReplacement) => string;
-
-type Scoped<Messages extends LocaleNamespaceMessages> = <Locale extends RawLocale<Messages>>(preKey?: NestedKeyPaths<Messages[Locale]>) => {
-    t: LooseTranslate;
-    hasKey: LooseHasKey;
-};
-
-type SetLocale<Messages extends LocaleNamespaceMessages> = (newLocale: RawLocale<Messages>) => void;
+type FallbackLocalesMap<L extends string = string> = Partial<Record<L, L[]>>;
 
 /**
- * The main Translator interface providing all core i18n methods.
+ * Gets all dot-separated keys (including non-leaf nodes) from a nested object.
  *
- * This interface is the foundation of the `intor` i18n engine, giving access
- * to all translation utilities and state management.
+ * @example
+ * NodeKeys<{ a: { b: { c: string }, d: string } }> → "a" | "a.b" | "a.b.c" | "a.d"
+ */
+type NodeKeys<M> = M extends object ? {
+    [K in keyof M]: K extends string ? `${K}` | `${K}.${NodeKeys<M[K]>}` : never;
+}[keyof M] : never;
+/**
+ * Default maximum recursive depth for nested key type computations,
+ * balancing type safety and compiler performance.
+ */
+type DefaultDepth = 15;
+/** Countdown tuple for limiting recursive depth (up to 10 levels). */
+type Prev = [
+    never,
+    0,
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10,
+    11,
+    12,
+    13,
+    14,
+    15,
+    16,
+    17,
+    18,
+    19,
+    20
+];
+/**
+ * Gets dot-separated keys to string leaf nodes in a nested object.
  *
- * @typeParam Messages - The full shape of all available locale messages.
- *                       Defaults to `LocaleNamespaceMessages`.
+ * @example
+ * LeafKeys<{ a: { b: "x", c: { d: "y" } } }> → "a.b" | "a.c.d"
  */
-type Translator<Messages extends LocaleNamespaceMessages = LocaleNamespaceMessages> = {
-    /**
-     * Get the current active locale.
-     *
-     * @returns The current locale string (e.g., "en", "zh-TW").
-     */
-    getLocale: GetLocale<Messages>;
-    /**
-     * Set the current locale.
-     *
-     * @param locale - The new locale to switch to.
-     */
-    setLocale: SetLocale<Messages>;
-    /**
-     * Get all messages for the current locale.
-     *
-     * @returns The messages object containing all translation namespaces and keys.
-     */
-    getMessages: GetMessages<Messages>;
-    /**
-     * Translate a message by its key with optional replacements.
-     *
-     * This function is fully type-safe, ensuring that translation keys are valid
-     * according to the loaded locale messages.
-     *
-     * You can use autocompletion and strict checking for nested message keys
-     * by providing the locale type.
-     *
-     * @example
-     * ```ts
-     * t("home.welcome.title"); // Fully typed with key autocompletion
-     * t("dashboard.stats.count", { count: 5 });
-     * ```
-     *
-     * @param key - A dot-separated translation key (e.g., `"common.hello"`).
-     * @param replacements - Optional values to replace placeholders in the message.
-     * @returns The translated message string.
-     */
-    t: Translate<Messages>;
-    /**
-     * Check whether a strongly-typed translation key exists in the loaded messages.
-     *
-     * This method ensures the key path is valid according to the message schema
-     * for a given locale.
-     *
-     * @example
-     * ```ts
-     * hasKey("home.welcome.title"); // true or false
-     * hasKey("dashboard.stats.count", "zh");
-     * ```
-     *
-     * @param key - A dot-separated message key defined in the locale messages.
-     * @param locale - Optional locale to check against. If omitted, defaults to current locale.
-     * @returns A boolean indicating whether the key exists.
-     */
-    hasKey: HasKey<Messages>;
-    /**
-     * Create a scoped translator bound to a specific namespace.
-     *
-     * Useful for modular translation logic (e.g., per-page or per-component).
-     *
-     * @param namespace - The namespace to scope to (e.g., "auth").
-     * @returns A new translator with scoped `t()` and helpers.
-     */
-    scoped: Scoped<Messages>;
-};
+type LeafKeys<M, D extends number = DefaultDepth> = [D] extends [never] ? never : M extends object ? {
+    [K in keyof M]: M[K] extends string ? `${K & string}` : M[K] extends object ? `${K & string}.${LeafKeys<M[K], Prev[D]>}` : never;
+}[keyof M] : never;
+/**
+ * Gets string leaf keys from all locale messages combined.
+ *
+ * @example
+ * UnionLocaleLeafKeys<{ en: { a: { b: "x" } }, zh: { a: { c: "y" } } }> → "a.b" | "a.c"
+ */
+type UnionLocaleLeafKeys<M extends LocaleNamespaceMessages, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends NamespaceMessages ? LeafKeys<UnionLocaleMessages<M>, D> : never;
+/**
+ * Resolves the type at a dot-separated key in a nested object.
+ *
+ * @example
+ * ResolvePathType<{ a: { b: { c: string } } }, "a.b.c"> → string
+ * ResolvePathType<{ a: { b: { c: "hello" } } }, "a.b.c"> → "hello"
+ */
+type ResolvePathType<T, P extends string> = P extends `${infer Head}.${infer Tail}` ? Head extends keyof T ? ResolvePathType<T[Head], Tail> : never : P extends keyof T ? T[P] : never;
+/**
+ * Extracts leaf keys under a scoped path (K) from all locales combined.
+ *
+ * @example
+ * type Messages = {
+ *   en: { auth: { login: { success: string } } },
+ *   zh: { auth: { login: { success: string; failed: string } } }
+ * };
+ * ScopedLeafKeys<Messages, "auth.login"> → "success" | "failed"
+ */
+type ScopedLeafKeys<M extends LocaleNamespaceMessages, K extends string, D extends number = DefaultDepth> = UnionLocaleMessages<M> extends infer ResolvedLocaleMessages ? ResolvedLocaleMessages extends object ? LeafKeys<ResolvePathType<ResolvedLocaleMessages, K>, D> : never : never;
 
 /**
- * Factory function to create a translator instance.
+ * A ref object holding all localized messages by locale.
  *
- * This function sets up a full-featured translator object based on the provided options,
- * including locale management, message retrieval, key existence checking, translation,
- * and scoped translations with prefixes.
+ * @example
+ * const messagesRef: MessagesRef<AllMessages> = {
+ *   current: {
+ *     en: { home: { title: "Welcome" } },
+ *     zh: { home: { title: "歡迎" } }
+ *   }
+ * };
+ */
+type MessagesRef<M extends LocaleNamespaceMessages> = {
+    current: Readonly<M>;
+};
+/**
+ * A ref object holding the currently selected locale.
  *
- * @template Messages - The shape of the locale namespace messages supported by this translator.
+ * @example
+ * const localeRef: LocaleRef<AllMessages> = {
+ *   current: "en"
+ * };
+ */
+type LocaleRef<M extends LocaleNamespaceMessages> = {
+    current: LocaleKey<M>;
+};
+/**
+ * A ref object indicating whether translation is loading.
  *
- * @param translatorOptions - Configuration options including initial locale and messages.
- * @returns A translator instance exposing locale control and translation methods.
+ * @example
+ * const isLoadingRef: IsLoadingRef = {
+ *   current: true
+ * };
  */
-declare function createTranslator<Messages extends LocaleNamespaceMessages>(translatorOptions: TranslatorOptions<Messages>): Translator<Messages>;
+type IsLoadingRef = {
+    current: boolean;
+};
+
+/** Config options for translation behavior. */
+type TranslateConfig = {
+    fallbackLocales?: FallbackLocalesMap;
+    loadingMessage?: string;
+    placeholder?: string;
+    handlers?: TranslateHandlers;
+};
+/** Optional handler functions for customizing translation behavior. */
+type TranslateHandlers = {
+    formatMessage?: FormatMessage;
+    onLoading?: OnLoading;
+    onMissing?: OnMissing;
+};
+/** Format a resolved message before returning it. */
+type FormatMessage<Result = unknown> = (ctx: TranslateContext & {
+    message: string;
+}) => Result;
+/** Called when translation is still loading. */
+type OnLoading<Result = unknown> = (ctx: TranslateContext) => Result;
+/** Called when no message is found for the given key. */
+type OnMissing<Result = unknown> = (ctx: TranslateContext) => Result;
+/**
+ * Context passed to translation-related functions.
+ * @example
+ * {
+ *   locale: "en",
+ *   key: "home.title",
+ *   replacements: { name: "Yiming" }
+ * }
+ */
+type TranslateContext = {
+    locale: Locale;
+    key: string;
+    replacements?: Replacement | RichReplacement;
+};
+
+interface BaseTranslatorOptions<M extends LocaleNamespaceMessages> {
+    messages: Readonly<M>;
+    locale: LocaleKey<M>;
+}
+
+declare class BaseTranslator<M extends LocaleNamespaceMessages> {
+    protected options: BaseTranslatorOptions<M>;
+    protected messagesRef: MessagesRef<M>;
+    protected localeRef: LocaleRef<M>;
+    constructor(options: BaseTranslatorOptions<M>);
+    /** Get all message data. */
+    get messages(): M;
+    /** Replace messages with new ones. */
+    setMessages(messages: M): void;
+    /** Get the current active locale. */
+    get locale(): LocaleKey<M>;
+    /** Change the active locale if available. */
+    setLocale(newLocale: LocaleKey<M>): boolean;
+    /** Check if a key exists in the specified locale or current locale. */
+    hasKey: (key: UnionLocaleLeafKeys<M>, targetLocale?: LocaleKey<M>) => boolean;
+}
+
+interface CoreTranslatorOptions<M extends LocaleNamespaceMessages> extends BaseTranslatorOptions<M>, TranslateConfig {
+}
+
+declare class CoreTranslator<M extends LocaleNamespaceMessages> extends BaseTranslator<M> {
+    protected options: CoreTranslatorOptions<M>;
+    protected isLoadingRef: IsLoadingRef;
+    constructor(options: CoreTranslatorOptions<M>);
+    /** Get the current loading state. */
+    get isLoading(): boolean;
+    /** Set the loading state. */
+    setLoading(state: boolean): void;
+    t: <Result = string>(key: UnionLocaleLeafKeys<M>, replacements?: Replacement | RichReplacement) => Result;
+}
+
+declare class ScopeTranslator<M extends LocaleNamespaceMessages> extends CoreTranslator<M> {
+    constructor(options: CoreTranslatorOptions<M>);
+    scoped: <K extends NodeKeys<UnionLocaleMessages<M>> & string, ScopedKeys extends ScopedLeafKeys<M, K> & string>(preKey: K) => {
+        hasKey: (key?: ScopedKeys | undefined, targetLocale?: string) => boolean;
+        t: (key?: ScopedKeys | undefined, replacements?: Replacement | RichReplacement) => string;
+    };
+}
 
-export { type LoadingMessageHandler, type MessageFormatter, type PlaceholderHandler, type Translator, type TranslatorHandlers, createTranslator };
+export { type FallbackLocalesMap, type FormatMessage, type IsLoadingRef, type LeafKeys, type Locale, type LocaleKey, type LocaleNamespaceMessages, type LocaleRef, type Message, type MessageRecord, type MessagesRef, type Namespace, type NamespaceMessages, type NestedMessage, type NodeKeys, type OnLoading, type OnMissing, type Replacement, type RichReplacement, type ScopedLeafKeys, type TranslateConfig, type TranslateContext, type TranslateHandlers, ScopeTranslator as Translator, type UnionLocaleLeafKeys, type UnionLocaleMessages };