intor 2.2.13 → 2.2.15

package/dist/server/index.d.ts

@@ -1,377 +0,0 @@
-import { Level, NormalizerConfig, FormatterConfig, LoggerPreset } from 'logry/edge';
-import { Locale, LocaleMessages, FallbackLocalesMap, NestedMessage, ScopedLeafKeys, LocalizedLeafKeys, Replacement, TranslateHandlers, LocalizedNodeKeys } from 'intor-translator';
-import Keyv from 'keyv';
-import { Logger } from 'logry';
-
-type CookieRawOptions = {
-    /** Enable cookie usage (read/write) - default: true */
-    enabled?: boolean;
-    /** Allow the system to automatically set cookies - default: true */
-    autoSetCookie?: boolean;
-    /** default: "intor.i18n.locale" */
-    name?: string;
-    /** default: null */
-    domain?: string | null;
-    /** default: "/" */
-    path?: string;
-    /** default: 60 * 60 * 24 * 365 (365 days) */
-    maxAge?: number;
-    /** default: false */
-    httpOnly?: boolean;
-    /** default: process.env.NODE_ENV !== "development" */
-    secure?: boolean;
-    /** default: lax */
-    sameSite?: "lax" | "strict" | "none";
-};
-type CookieResolvedOptions = Required<Omit<CookieRawOptions, "domain">> & {
-    domain: string | null;
-};
-
-/**
- * ```ts
- * {
- *  default: ["ui", "meta"],
- *  "/auth": ["auth", "admin"],
- * }
- * // When pathname is "/" => namespaces: ["ui", "meta"]
- * // When pathname is "/auth" => namespaces: ["ui", "meta", "auth", "admin"]
- * ```
- */
-type RouteNamespaces = {
-    [key: string]: string[];
-} | {
-    [key: string]: string[];
-    default: string[];
-};
-interface RemoteHeaders {
-    authorization?: string;
-    "x-api-key"?: string;
-    [key: string]: string | undefined;
-}
-type BaseLoaderOptions = {
-    rootDir?: string;
-    namespaces?: string[];
-    routeNamespaces?: RouteNamespaces;
-    concurrency?: number;
-};
-type LocalLoader = BaseLoaderOptions & {
-    type: "local";
-};
-type RemoteLoader = BaseLoaderOptions & {
-    type: "remote";
-    remoteUrl: string;
-    remoteHeaders?: RemoteHeaders;
-    fullReload?: boolean;
-};
-type LoaderOptions = LocalLoader | RemoteLoader;
-
-type LoggerOptions = {
-    level?: Level;
-    normalizerConfig?: NormalizerConfig;
-    formatterConfig?: FormatterConfig;
-    preset?: LoggerPreset;
-};
-
-declare const routingPrefix: readonly ["none", "all", "except-default"];
-declare const routingFirstVisitLocaleSource: readonly ["default", "browser"];
-type RoutingRawOptions = {
-    /** default: "none" */
-    prefix?: (typeof routingPrefix)[number];
-    firstVisit?: {
-        /** default: "browser" */
-        localeSource?: (typeof routingFirstVisitLocaleSource)[number];
-        /** default: true */
-        redirect?: boolean;
-    };
-    /** default: "" */
-    basePath?: string;
-};
-type RoutingResolvedOptions = Required<RoutingRawOptions>;
-
-type CacheRawOptions = {
-    /** default: process.env.NODE_ENV === "production" */
-    enabled?: boolean;
-    /** default: 60\*60\*1000 (1 hour) */
-    ttl?: number;
-};
-type CacheResolvedOptions = Required<CacheRawOptions>;
-
-type TranslatorOptions = {
-    loadingMessage?: string;
-    placeholder?: string;
-};
-
-type IntorResolvedConfig = ({
-    loader: LoaderOptions;
-    supportedLocales: readonly Locale[];
-} | {
-    loader?: undefined;
-    supportedLocales: readonly Locale[];
-}) & {
-    readonly id: string;
-    readonly messages?: LocaleMessages;
-    readonly defaultLocale: Locale;
-    readonly fallbackLocales: FallbackLocalesMap;
-    readonly translator?: TranslatorOptions;
-    readonly cookie: CookieResolvedOptions;
-    readonly routing: RoutingResolvedOptions;
-    readonly logger?: LoggerOptions;
-    readonly cache: CacheResolvedOptions;
-};
-
-declare const PREFIX_PLACEHOLDER = "{locale}";
-
-/**
- * Conditional type for generated types.
- * - Returns `Then` if `IntorGeneratedTypes` exists, otherwise `Else`.
- */
-type IfGen<Then, Else = never> = IntorGeneratedTypes extends void ? Else : Then;
-/**
- * Union of all configuration keys.
- * - Defaults to `string` if `IntorGeneratedTypes` does not exist.
- */
-type GenConfigKeys = IfGen<keyof IntorGeneratedTypes, string>;
-/**
- * Configuration shape for a given config key.
- * - If `IntorGeneratedTypes` is not defined, falls back to default shape.
- * Otherwise, picks `Locales` and `Messages` according to the key.
- */
-type GenConfig<CK extends GenConfigKeys = "__default__"> = IntorGeneratedTypes extends void ? {
-    Locales: string;
-    Messages: LocaleMessages;
-} : CK extends keyof IntorGeneratedTypes ? {
-    Locales: IntorGeneratedTypes[CK]["Locales"];
-    Messages: {
-        [K in IntorGeneratedTypes[CK]["Locales"]]: IntorGeneratedTypes[CK]["Messages"][typeof PREFIX_PLACEHOLDER];
-    };
-} : never;
-/** Extracts messages for a given config key */
-type GenMessages<CK extends GenConfigKeys = "__default__"> = GenConfig<CK>["Messages"];
-/** Extracts locales for a given config key */
-type GenLocale<CK extends GenConfigKeys = "__default__"> = GenConfig<CK>["Locales"];
-
-interface I18nContext {
-    locale: GenLocale;
-    pathname: string;
-}
-type GetI18nContext = (config: IntorResolvedConfig) => Promise<I18nContext>;
-interface IntorResult {
-    config: IntorResolvedConfig;
-    initialLocale: Locale;
-    pathname: string;
-    messages: LocaleMessages;
-}
-
-/**
- * Represents a collection of localized messages.
- *
- * - Each key is a namespace or message identifier, and the value is a
- * `NestedMessage` object that can contain nested message structures.
- *
- * @example
- * ```ts
- * const messages: Messages = {
- *   ui: {
- *     greeting: "Hello",
- *     farewell: "Goodbye"
- *   },
- *   errors: {
- *     network: "Network error occurred"
- *   }
- * };
- * ```
- */
-type Messages = Record<string, NestedMessage>;
-/**
- * A function that reads messages from a given file path.
- *
- * - This function is expected to return a `Promise` that resolves to a `Messages` object.
- * - It can be implemented to support different file formats such as JSON, YAML, or others.
- *
- * @param filePath - The path to the message file to read.
- * @returns A Promise that resolves to a `Messages` object.
- *
- * @example
- * ```ts
- * const reader: MessagesReader = async (filePath) => {
- *   const content = await fs.promises.readFile(filePath, "utf-8");
- *   return JSON.parse(content) as Messages;
- * };
- * ```
- */
-type MessagesReader = (filePath: string) => Promise<Messages>;
-
-type LoadMessagesOptions = {
-    config: IntorResolvedConfig;
-    locale: Locale;
-    pathname?: string;
-    extraOptions?: {
-        exts?: string[];
-        messagesReader?: MessagesReader;
-    };
-    allowCacheWrite?: boolean;
-};
-type LoadMessagesResult<C extends GenConfigKeys = "__default__"> = Promise<GenMessages<C> | undefined>;
-
-/**
- * Load messages for a given locale and pathname.
- *
- * - Resolve namespaces based on config and pathname.
- * - Support both **local local** and **remote API** loaders.
- * - Apply fallback locales if needed.
- * - Cache messages if enabled (handled by underlying loader, not this function directly).
- */
-declare const loadMessages: <C extends GenConfigKeys = "__default__">({ config, locale, pathname, extraOptions: { exts, messagesReader }, allowCacheWrite, }: LoadMessagesOptions) => LoadMessagesResult<C>;
-
-/**
- * Global messages pool (cross-module + hot-reload safe)
- */
-type MessagesPool = Keyv<LocaleMessages>;
-declare global {
-    var __INTOR_MESSAGES_POOL__: MessagesPool | undefined;
-}
-/**
- * Optional: clear all cache
- * Useful in tests or dynamic reloads.
- */
-declare function clearMessagesPool(): void;
-
-interface LoadLocalMessagesOptions {
-    pool?: MessagesPool;
-    rootDir?: string;
-    locale: string;
-    fallbackLocales?: string[];
-    namespaces?: string[];
-    extraOptions?: {
-        concurrency?: number;
-        cacheOptions?: CacheResolvedOptions;
-        loggerOptions?: LoggerOptions & {
-            id?: string;
-        };
-        exts?: string[];
-        messagesReader?: MessagesReader;
-    };
-    allowCacheWrite?: boolean;
-}
-
-/**
- * Load local messages from the file system.
- *
- * - Load messages for a target locale with optional fallback locales.
- * - Support filtering by specific namespaces.
- * - Cache messages if enabled.
- * - Limit concurrent file reads for performance.
- */
-declare const loadLocalMessages: ({ pool, rootDir, locale, fallbackLocales, namespaces, extraOptions: { concurrency, cacheOptions, loggerOptions, exts, messagesReader, }, allowCacheWrite, }: LoadLocalMessagesOptions) => Promise<LocaleMessages | undefined>;
-
-interface LoadRemoteMessagesOptions {
-    pool?: MessagesPool;
-    rootDir?: string;
-    locale: string;
-    fallbackLocales: string[];
-    namespaces?: string[];
-    remoteUrl: string;
-    remoteHeaders?: RemoteHeaders;
-    extraOptions?: {
-        cacheOptions?: CacheResolvedOptions;
-        loggerOptions?: LoggerOptions & {
-            id?: string;
-        };
-    };
-    allowCacheWrite?: boolean;
-}
-
-/**
- * Load locale messages from a remote API.
- *
- * - Fetch messages for a target locale with optional fallback locales.
- * - Cache messages if enabled.
- */
-declare const loadRemoteMessages: ({ pool, rootDir, remoteUrl, remoteHeaders, locale, fallbackLocales, namespaces, extraOptions: { cacheOptions, loggerOptions, }, allowCacheWrite, }: LoadRemoteMessagesOptions) => Promise<LocaleMessages | undefined>;
-
-/**
- * Entry point for initializing Intor.
- *
- * 1. Resolve context via adapter or fallback values.
- * 2. Load messages if loader is enabled.
- * 3. Merge static messages with loaded messages.
- */
-declare const intor: (config: IntorResolvedConfig, i18nContext: GetI18nContext | Partial<I18nContext>, loadMessagesOptions?: {
-    exts?: string[];
-    messagesReader?: MessagesReader;
-}) => Promise<IntorResult>;
-
-/** Base properties shared by all translator instances. */
-interface TranslatorBaseProps<M = unknown> {
-    /** `messages`: The message object containing all translations. */
-    messages: M;
-    /** Current locale in use. */
-    locale: Locale<M>;
-}
-/** Properties specific to client-side translator behavior. */
-interface TranslatorClientProps<M = unknown> {
-    /** `isLoading`: Indicates whether translations are currently loading. */
-    isLoading: boolean;
-    /** `setLocale`: Function to update the current locale. */
-    setLocale: (locale: Locale<M>) => void;
-}
-/**
- * Conditional key type for TranslatorInstance.
- * - Resolves to `ScopedLeafKeys` if a pre-key `PK` is provided,
- * otherwise resolves to `LocalizedLeafKeys`.
- */
-type Key<M, PK> = IfGen<PK extends string ? ScopedLeafKeys<M, PK> : LocalizedLeafKeys<M>, string>;
-/**
- * Translator instance type.
- * Combines base props, client props, and core translation methods.
- */
-type TranslatorInstance<M, PK extends string | undefined = undefined> = {
-    /** Check if a given key exists in the messages. */
-    hasKey: (key?: Key<M, PK>, targetLocale?: Locale<M>) => boolean;
-    /** Translate a given key into its string representation. */
-    t: <Result = string>(key?: Key<M, PK>, replacements?: Replacement) => Result;
-} & TranslatorBaseProps<M> & TranslatorClientProps<M>;
-
-/**
- * Create a translator instance for a specific locale and pathname
- *
- * - Loads messages using the provided config, locale, and pathname.
- * - Initializes a translator with `t`, `hasKey`, and optional scoped methods.
- * - Supports optional `preKey` to create a scoped translator for nested keys.
- */
-declare function getTranslator<CK extends GenConfigKeys = "__default__">(options: {
-    config: IntorResolvedConfig;
-    locale: GenLocale;
-    pathname?: string;
-    handlers?: TranslateHandlers;
-    extraOptions?: {
-        exts?: string[];
-        messagesReader?: MessagesReader;
-    };
-}): Promise<TranslatorInstance<GenMessages<CK>>>;
-declare function getTranslator<CK extends GenConfigKeys = "__default__", PK extends string = LocalizedNodeKeys<GenMessages<CK>>>(options: {
-    config: IntorResolvedConfig;
-    locale: GenLocale;
-    pathname?: string;
-    handlers?: TranslateHandlers;
-    extraOptions?: {
-        exts?: string[];
-        messagesReader?: MessagesReader;
-    };
-    preKey?: PK;
-}): Promise<TranslatorInstance<GenMessages<CK>, PK>>;
-
-/**
- * Global logger pool (cross-module + hot-reload safe)
- */
-type LoggerPool = Map<string, Logger>;
-declare global {
-    var __INTOR_LOGGER_POOL__: LoggerPool | undefined;
-}
-/**
- * Optional: clear all cache
- * Useful in tests or dynamic reloads.
- */
-declare function clearLoggerPool(): void;
-
-export { type I18nContext, type IntorResult, type LoadLocalMessagesOptions, type LoadRemoteMessagesOptions, type Messages, type MessagesReader, clearLoggerPool, clearMessagesPool, getTranslator, intor, loadLocalMessages, loadMessages, loadRemoteMessages };