@gravito/cosmos 3.0.0 → 3.0.1

package/dist/index.d.cts

@@ -0,0 +1,274 @@
+import { GravitoMiddleware, GravitoOrbit, PlanetCore } from '@gravito/core';
+
+/**
+ * A map of translations where keys are translation keys and values
+ * are either the translated string or a nested map for grouping.
+ *
+ * @public
+ * @since 3.0.0
+ */
+type TranslationMap = {
+    [key: string]: string | TranslationMap;
+};
+/**
+ * Configuration for the I18n service.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface I18nConfig {
+    /** The fallback locale to use when the requested one is not found. */
+    defaultLocale: string;
+    /** List of locales officially supported by the application. */
+    supportedLocales: string[];
+    /**
+     * Optional record of translations indexed by locale.
+     * Keys are locale strings (e.g., 'en', 'zh-TW').
+     */
+    translations?: Record<string, TranslationMap>;
+}
+/**
+ * Interface for the I18n service providing translation capabilities.
+ *
+ * It allows for setting and getting the current locale, translating strings
+ * with optional replacements, and checking for key existence.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface I18nService {
+    /** The current active locale. */
+    locale: string;
+    /**
+     * Set the active locale for this service instance.
+     *
+     * @param locale - Valid locale string from supportedLocales.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the current active locale.
+     *
+     * @returns Current locale string.
+     */
+    getLocale(): string;
+    /**
+     * Translate a key into the current locale.
+     *
+     * @param key - The translation key (e.g., 'auth.login_success').
+     * @param replacements - Optional placeholders in the format `:key` replaced by values.
+     * @returns The translated string, or the key itself if not found.
+     *
+     * @example
+     * ```typescript
+     * i18n.t('messages.hello', { name: 'John' }); // "Hello John"
+     * ```
+     */
+    t(key: string, replacements?: Record<string, string | number>): string;
+    /**
+     * Check if a translation key exists for the current locale.
+     *
+     * @param key - The key to check.
+     * @returns True if the key exists, false otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Create a new request-scoped instance of the I18n service.
+     *
+     * @param locale - Optional initial locale for the new instance.
+     * @returns A new I18nService instance.
+     */
+    clone(locale?: string): I18nService;
+}
+/**
+ * Request-scoped I18n Instance
+ * Holds the state (locale) for a single request, but shares the heavy resources (translations)
+ */
+declare class I18nInstance implements I18nService {
+    readonly manager: I18nManager;
+    private _locale;
+    /**
+     * Create a new I18nInstance.
+     *
+     * @param manager - The I18nManager instance.
+     * @param initialLocale - The initial locale for this instance.
+     */
+    constructor(manager: I18nManager, initialLocale: string);
+    get locale(): string;
+    set locale(value: string);
+    /**
+     * Set the current locale.
+     *
+     * @param locale - The locale to set.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the current locale.
+     *
+     * @returns The current locale string.
+     */
+    getLocale(): string;
+    /**
+     * Translate a key.
+     *
+     * @param key - The translation key (e.g., 'messages.welcome').
+     * @param replacements - Optional replacements for parameters in the translation string.
+     * @returns The translated string, or the key if not found.
+     */
+    t(key: string, replacements?: Record<string, string | number>): string;
+    /**
+     * Check if a translation key exists.
+     *
+     * @param key - The translation key to check.
+     * @returns True if the key exists, false otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Clone the current instance with a potentially new locale.
+     *
+     * @param locale - Optional new locale for the cloned instance.
+     * @returns A new I18nInstance.
+     */
+    clone(locale?: string): I18nService;
+    /**
+     * Get the I18n configuration.
+     */
+    getConfig(): I18nConfig;
+    /**
+     * Get the translations.
+     */
+    get translations(): Record<string, TranslationMap>;
+}
+/**
+ * Global I18n Manager
+ * Holds shared configuration and translation resources
+ */
+declare class I18nManager implements I18nService {
+    private config;
+    translations: Record<string, TranslationMap>;
+    private globalInstance;
+    /**
+     * Create a new I18nManager.
+     *
+     * @param config - The I18n configuration.
+     */
+    constructor(config: I18nConfig);
+    get locale(): string;
+    set locale(value: string);
+    /**
+     * Set the global locale.
+     *
+     * @param locale - The locale to set.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the global locale.
+     *
+     * @returns The global locale string.
+     */
+    getLocale(): string;
+    /**
+     * Translate a key using the global locale.
+     *
+     * @param key - The translation key.
+     * @param replacements - Optional replacements.
+     * @returns The translated string.
+     */
+    t(key: string, replacements?: Record<string, string | number>): string;
+    /**
+     * Check if a translation key exists in the global locale.
+     *
+     * @param key - The translation key.
+     * @returns True if found.
+     */
+    has(key: string): boolean;
+    /**
+     * Clone the global instance.
+     *
+     * @param locale - Optional locale for the clone.
+     * @returns A new I18nInstance.
+     */
+    clone(locale?: string): I18nService;
+    /**
+     * Get the I18n configuration.
+     *
+     * @returns The configuration object.
+     */
+    getConfig(): I18nConfig;
+    /**
+     * Add a resource bundle for a specific locale.
+     *
+     * @param locale - The locale string.
+     * @param translations - The translations object.
+     */
+    addResource(locale: string, translations: TranslationMap): void;
+    /**
+     * Internal translation logic used by instances
+     */
+    translate(locale: string, key: string, replacements?: Record<string, string | number>): string;
+}
+/**
+ * Locale Middleware
+ *
+ * Detects locale from:
+ * 1. Route Parameter (e.g. /:locale/foo) - Recommended for SEO
+ * 2. Header (Accept-Language) - Recommended for APIs
+ */
+declare const localeMiddleware: (i18nManager: I18nService) => GravitoMiddleware;
+
+/**
+ * Load translations from a directory
+ * Structure:
+ * /lang
+ *   /en.json -> { "welcome": "Hello" }
+ *   /zh.json -> { "welcome": "Hello" }
+ *   /en/auth.json -> { "failed": "Login failed" } (Optional deep structure, maybe later)
+ *
+ * For now, we support flat JSON files per locale: en.json, zh.json
+ */
+declare function loadTranslations(directory: string): Promise<Record<string, Record<string, string>>>;
+
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** I18n service for translations */
+        i18n: I18nService;
+    }
+}
+/**
+ * OrbitCosmos provides internationalization (i18n) support for Gravito.
+ * It manages translations, locale switching, and provides a middleware for request-scoped locale detection.
+ *
+ * @example
+ * ```typescript
+ * const cosmos = new OrbitCosmos({
+ *   defaultLocale: 'en',
+ *   supportedLocales: ['en', 'zh-TW'],
+ *   translations: {
+ *     en: { welcome: 'Welcome!' },
+ *     'zh-TW': { welcome: '歡迎！' }
+ *   }
+ * });
+ * core.addOrbit(cosmos);
+ * ```
+ * @public
+ */
+declare class OrbitCosmos implements GravitoOrbit {
+    private config;
+    /**
+     * Create a new OrbitCosmos instance.
+     * @param config - The i18n configuration options.
+     */
+    constructor(config: I18nConfig);
+    /**
+     * Install the i18n service into PlanetCore.
+     * Registers the I18nManager and sets up the locale middleware.
+     *
+     * @param core - The PlanetCore instance.
+     */
+    install(core: PlanetCore): void;
+}
+/**
+ * @deprecated Use OrbitCosmos instead. Will be removed in v4.0.0.
+ */
+declare const I18nOrbit: typeof OrbitCosmos;
+
+export { type I18nConfig, I18nInstance, I18nManager, I18nOrbit, type I18nService, OrbitCosmos, type TranslationMap, loadTranslations, localeMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,274 @@
+import { GravitoMiddleware, GravitoOrbit, PlanetCore } from '@gravito/core';
+
+/**
+ * A map of translations where keys are translation keys and values
+ * are either the translated string or a nested map for grouping.
+ *
+ * @public
+ * @since 3.0.0
+ */
+type TranslationMap = {
+    [key: string]: string | TranslationMap;
+};
+/**
+ * Configuration for the I18n service.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface I18nConfig {
+    /** The fallback locale to use when the requested one is not found. */
+    defaultLocale: string;
+    /** List of locales officially supported by the application. */
+    supportedLocales: string[];
+    /**
+     * Optional record of translations indexed by locale.
+     * Keys are locale strings (e.g., 'en', 'zh-TW').
+     */
+    translations?: Record<string, TranslationMap>;
+}
+/**
+ * Interface for the I18n service providing translation capabilities.
+ *
+ * It allows for setting and getting the current locale, translating strings
+ * with optional replacements, and checking for key existence.
+ *
+ * @public
+ * @since 3.0.0
+ */
+interface I18nService {
+    /** The current active locale. */
+    locale: string;
+    /**
+     * Set the active locale for this service instance.
+     *
+     * @param locale - Valid locale string from supportedLocales.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the current active locale.
+     *
+     * @returns Current locale string.
+     */
+    getLocale(): string;
+    /**
+     * Translate a key into the current locale.
+     *
+     * @param key - The translation key (e.g., 'auth.login_success').
+     * @param replacements - Optional placeholders in the format `:key` replaced by values.
+     * @returns The translated string, or the key itself if not found.
+     *
+     * @example
+     * ```typescript
+     * i18n.t('messages.hello', { name: 'John' }); // "Hello John"
+     * ```
+     */
+    t(key: string, replacements?: Record<string, string | number>): string;
+    /**
+     * Check if a translation key exists for the current locale.
+     *
+     * @param key - The key to check.
+     * @returns True if the key exists, false otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Create a new request-scoped instance of the I18n service.
+     *
+     * @param locale - Optional initial locale for the new instance.
+     * @returns A new I18nService instance.
+     */
+    clone(locale?: string): I18nService;
+}
+/**
+ * Request-scoped I18n Instance
+ * Holds the state (locale) for a single request, but shares the heavy resources (translations)
+ */
+declare class I18nInstance implements I18nService {
+    readonly manager: I18nManager;
+    private _locale;
+    /**
+     * Create a new I18nInstance.
+     *
+     * @param manager - The I18nManager instance.
+     * @param initialLocale - The initial locale for this instance.
+     */
+    constructor(manager: I18nManager, initialLocale: string);
+    get locale(): string;
+    set locale(value: string);
+    /**
+     * Set the current locale.
+     *
+     * @param locale - The locale to set.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the current locale.
+     *
+     * @returns The current locale string.
+     */
+    getLocale(): string;
+    /**
+     * Translate a key.
+     *
+     * @param key - The translation key (e.g., 'messages.welcome').
+     * @param replacements - Optional replacements for parameters in the translation string.
+     * @returns The translated string, or the key if not found.
+     */
+    t(key: string, replacements?: Record<string, string | number>): string;
+    /**
+     * Check if a translation key exists.
+     *
+     * @param key - The translation key to check.
+     * @returns True if the key exists, false otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Clone the current instance with a potentially new locale.
+     *
+     * @param locale - Optional new locale for the cloned instance.
+     * @returns A new I18nInstance.
+     */
+    clone(locale?: string): I18nService;
+    /**
+     * Get the I18n configuration.
+     */
+    getConfig(): I18nConfig;
+    /**
+     * Get the translations.
+     */
+    get translations(): Record<string, TranslationMap>;
+}
+/**
+ * Global I18n Manager
+ * Holds shared configuration and translation resources
+ */
+declare class I18nManager implements I18nService {
+    private config;
+    translations: Record<string, TranslationMap>;
+    private globalInstance;
+    /**
+     * Create a new I18nManager.
+     *
+     * @param config - The I18n configuration.
+     */
+    constructor(config: I18nConfig);
+    get locale(): string;
+    set locale(value: string);
+    /**
+     * Set the global locale.
+     *
+     * @param locale - The locale to set.
+     */
+    setLocale(locale: string): void;
+    /**
+     * Get the global locale.
+     *
+     * @returns The global locale string.
+     */
+    getLocale(): string;
+    /**
+     * Translate a key using the global locale.
+     *
+     * @param key - The translation key.
+     * @param replacements - Optional replacements.
+     * @returns The translated string.
+     */
+    t(key: string, replacements?: Record<string, string | number>): string;
+    /**
+     * Check if a translation key exists in the global locale.
+     *
+     * @param key - The translation key.
+     * @returns True if found.
+     */
+    has(key: string): boolean;
+    /**
+     * Clone the global instance.
+     *
+     * @param locale - Optional locale for the clone.
+     * @returns A new I18nInstance.
+     */
+    clone(locale?: string): I18nService;
+    /**
+     * Get the I18n configuration.
+     *
+     * @returns The configuration object.
+     */
+    getConfig(): I18nConfig;
+    /**
+     * Add a resource bundle for a specific locale.
+     *
+     * @param locale - The locale string.
+     * @param translations - The translations object.
+     */
+    addResource(locale: string, translations: TranslationMap): void;
+    /**
+     * Internal translation logic used by instances
+     */
+    translate(locale: string, key: string, replacements?: Record<string, string | number>): string;
+}
+/**
+ * Locale Middleware
+ *
+ * Detects locale from:
+ * 1. Route Parameter (e.g. /:locale/foo) - Recommended for SEO
+ * 2. Header (Accept-Language) - Recommended for APIs
+ */
+declare const localeMiddleware: (i18nManager: I18nService) => GravitoMiddleware;
+
+/**
+ * Load translations from a directory
+ * Structure:
+ * /lang
+ *   /en.json -> { "welcome": "Hello" }
+ *   /zh.json -> { "welcome": "Hello" }
+ *   /en/auth.json -> { "failed": "Login failed" } (Optional deep structure, maybe later)
+ *
+ * For now, we support flat JSON files per locale: en.json, zh.json
+ */
+declare function loadTranslations(directory: string): Promise<Record<string, Record<string, string>>>;
+
+declare module '@gravito/core' {
+    interface GravitoVariables {
+        /** I18n service for translations */
+        i18n: I18nService;
+    }
+}
+/**
+ * OrbitCosmos provides internationalization (i18n) support for Gravito.
+ * It manages translations, locale switching, and provides a middleware for request-scoped locale detection.
+ *
+ * @example
+ * ```typescript
+ * const cosmos = new OrbitCosmos({
+ *   defaultLocale: 'en',
+ *   supportedLocales: ['en', 'zh-TW'],
+ *   translations: {
+ *     en: { welcome: 'Welcome!' },
+ *     'zh-TW': { welcome: '歡迎！' }
+ *   }
+ * });
+ * core.addOrbit(cosmos);
+ * ```
+ * @public
+ */
+declare class OrbitCosmos implements GravitoOrbit {
+    private config;
+    /**
+     * Create a new OrbitCosmos instance.
+     * @param config - The i18n configuration options.
+     */
+    constructor(config: I18nConfig);
+    /**
+     * Install the i18n service into PlanetCore.
+     * Registers the I18nManager and sets up the locale middleware.
+     *
+     * @param core - The PlanetCore instance.
+     */
+    install(core: PlanetCore): void;
+}
+/**
+ * @deprecated Use OrbitCosmos instead. Will be removed in v4.0.0.
+ */
+declare const I18nOrbit: typeof OrbitCosmos;
+
+export { type I18nConfig, I18nInstance, I18nManager, I18nOrbit, type I18nService, OrbitCosmos, type TranslationMap, loadTranslations, localeMiddleware };