@gravito/cosmos 2.0.0 → 3.0.1

package/dist/index.js

@@ -1,40 +1,87 @@
 // src/I18nService.ts
-class I18nInstance {
-  manager;
-  _locale;
+var I18nInstance = class _I18nInstance {
+  /**
+   * Create a new I18nInstance.
+   *
+   * @param manager - The I18nManager instance.
+   * @param initialLocale - The initial locale for this instance.
+   */
   constructor(manager, initialLocale) {
     this.manager = manager;
     this._locale = initialLocale;
   }
+  _locale;
   get locale() {
     return this._locale;
   }
   set locale(value) {
     this.setLocale(value);
   }
+  /**
+   * Set the current locale.
+   *
+   * @param locale - The locale to set.
+   */
   setLocale(locale) {
     if (this.manager.getConfig().supportedLocales.includes(locale)) {
       this._locale = locale;
     }
   }
+  /**
+   * Get the current locale.
+   *
+   * @returns The current locale string.
+   */
   getLocale() {
     return this._locale;
   }
+  /**
+   * 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, replacements) {
     return this.manager.translate(this._locale, key, replacements);
   }
+  /**
+   * Check if a translation key exists.
+   *
+   * @param key - The translation key to check.
+   * @returns True if the key exists, false otherwise.
+   */
   has(key) {
     return this.t(key) !== key;
   }
+  /**
+   * Clone the current instance with a potentially new locale.
+   *
+   * @param locale - Optional new locale for the cloned instance.
+   * @returns A new I18nInstance.
+   */
   clone(locale) {
-    return new I18nInstance(this.manager, locale || this._locale);
+    return new _I18nInstance(this.manager, locale || this._locale);
   }
-}
-
-class I18nManager {
-  config;
-  translations = {};
-  globalInstance;
+  /**
+   * Get the I18n configuration.
+   */
+  getConfig() {
+    return this.manager.getConfig();
+  }
+  /**
+   * Get the translations.
+   */
+  get translations() {
+    return this.manager.translations;
+  }
+};
+var I18nManager = class {
+  /**
+   * Create a new I18nManager.
+   *
+   * @param config - The I18n configuration.
+   */
   constructor(config) {
     this.config = config;
     if (config.translations) {
@@ -42,36 +89,84 @@ class I18nManager {
     }
     this.globalInstance = new I18nInstance(this, config.defaultLocale);
   }
+  translations = {};
+  // Default instance for global usage (e.g. CLI or background jobs)
+  globalInstance;
+  // --- I18nService Implementation (Delegates to global instance) ---
   get locale() {
     return this.globalInstance.locale;
   }
   set locale(value) {
     this.globalInstance.locale = value;
   }
+  /**
+   * Set the global locale.
+   *
+   * @param locale - The locale to set.
+   */
   setLocale(locale) {
     this.globalInstance.setLocale(locale);
   }
+  /**
+   * Get the global locale.
+   *
+   * @returns The global locale string.
+   */
   getLocale() {
     return this.globalInstance.getLocale();
   }
+  /**
+   * Translate a key using the global locale.
+   *
+   * @param key - The translation key.
+   * @param replacements - Optional replacements.
+   * @returns The translated string.
+   */
   t(key, replacements) {
     return this.globalInstance.t(key, replacements);
   }
+  /**
+   * Check if a translation key exists in the global locale.
+   *
+   * @param key - The translation key.
+   * @returns True if found.
+   */
   has(key) {
     return this.globalInstance.has(key);
   }
+  /**
+   * Clone the global instance.
+   *
+   * @param locale - Optional locale for the clone.
+   * @returns A new I18nInstance.
+   */
   clone(locale) {
     return new I18nInstance(this, locale || this.config.defaultLocale);
   }
+  // --- Manager Internal API ---
+  /**
+   * Get the I18n configuration.
+   *
+   * @returns The configuration object.
+   */
   getConfig() {
     return this.config;
   }
+  /**
+   * Add a resource bundle for a specific locale.
+   *
+   * @param locale - The locale string.
+   * @param translations - The translations object.
+   */
   addResource(locale, translations) {
     this.translations[locale] = {
       ...this.translations[locale] || {},
       ...translations
     };
   }
+  /**
+   * Internal translation logic used by instances
+   */
   translate(locale, key, replacements) {
     const keys = key.split(".");
     let value = this.translations[locale];
@@ -79,33 +174,34 @@ class I18nManager {
       if (value && typeof value === "object" && k in value) {
         value = value[k];
       } else {
-        value = undefined;
+        value = void 0;
         break;
       }
     }
-    if (value === undefined && locale !== this.config.defaultLocale) {
+    if (value === void 0 && locale !== this.config.defaultLocale) {
       let fallbackValue = this.translations[this.config.defaultLocale];
       for (const k of keys) {
         if (fallbackValue && typeof fallbackValue === "object" && k in fallbackValue) {
           fallbackValue = fallbackValue[k];
         } else {
-          fallbackValue = undefined;
+          fallbackValue = void 0;
           break;
         }
       }
       value = fallbackValue;
     }
-    if (value === undefined || typeof value !== "string") {
+    if (value === void 0 || typeof value !== "string") {
       return key;
     }
-    if (replacements) {
-      for (const [search, replace] of Object.entries(replacements)) {
-        value = value.replace(new RegExp(`:${search}`, "g"), String(replace));
-      }
+    if (replacements && Object.keys(replacements).length > 0) {
+      value = value.replace(REPLACEMENT_REGEX, (match, key2) => {
+        return replacements[key2] !== void 0 ? String(replacements[key2]) : match;
+      });
     }
     return value;
   }
-}
+};
+var REPLACEMENT_REGEX = /:([a-zA-Z0-9_]+)/g;
 var localeMiddleware = (i18nManager) => {
   return async (c, next) => {
     let locale = c.req.param("locale") || c.req.query("lang");
@@ -117,12 +213,13 @@ var localeMiddleware = (i18nManager) => {
     }
     const i18n = i18nManager.clone(locale);
     c.set("i18n", i18n);
-    await next();
+    return await next();
   };
 };
+
 // src/loader.ts
-import { readdir, readFile } from "node:fs/promises";
-import { join, parse } from "node:path";
+import { readdir, readFile } from "fs/promises";
+import { join, parse } from "path";
 async function loadTranslations(directory) {
   const translations = {};
   try {
@@ -140,29 +237,41 @@ async function loadTranslations(directory) {
       }
     }
   } catch (_e) {
-    console.warn(`[Orbit-I18n] Could not load translations from ${directory}. Directory might not exist.`);
+    console.warn(
+      `[Orbit-I18n] Could not load translations from ${directory}. Directory might not exist.`
+    );
   }
   return translations;
 }
 
 // src/index.ts
-class OrbitCosmos {
-  config;
+var OrbitCosmos = class {
+  /**
+   * Create a new OrbitCosmos instance.
+   * @param config - The i18n configuration options.
+   */
   constructor(config) {
     this.config = config;
   }
+  /**
+   * Install the i18n service into PlanetCore.
+   * Registers the I18nManager and sets up the locale middleware.
+   *
+   * @param core - The PlanetCore instance.
+   */
   install(core) {
     const i18nManager = new I18nManager(this.config);
+    core.container.instance("i18n", i18nManager);
     core.adapter.use("*", localeMiddleware(i18nManager));
     core.logger.info(`[OrbitCosmos] I18n initialized with locale: ${this.config.defaultLocale}`);
   }
-}
+};
 var I18nOrbit = OrbitCosmos;
 export {
-  localeMiddleware,
-  loadTranslations,
-  OrbitCosmos,
-  I18nOrbit,
+  I18nInstance,
   I18nManager,
-  I18nInstance
+  I18nOrbit,
+  OrbitCosmos,
+  loadTranslations,
+  localeMiddleware
 };

package/package.json

@@ -1,11 +1,21 @@
 {
   "name": "@gravito/cosmos",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "Internationalization orbit for Gravito framework",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
   "scripts": {
-    "build": "bun build ./src/index.ts --outdir ./dist --target node --external @gravito/core --external @gravito/photon",
+    "build": "bun run build.ts",
     "test": "bun test",
     "test:coverage": "bun test --coverage --coverage-threshold=80",
     "test:ci": "bun test --coverage --coverage-threshold=80",
@@ -24,7 +34,9 @@
     "@gravito/photon": "workspace:*"
   },
   "devDependencies": {
-    "bun-types": "latest"
+    "bun-types": "latest",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
   },
   "publishConfig": {
     "access": "public"
@@ -35,4 +47,4 @@
     "url": "git+https://github.com/gravito-framework/gravito.git",
     "directory": "packages/cosmos"
   }
-}
+}

package/src/I18nService.ts

@@ -1,24 +1,84 @@
-import type { MiddlewareHandler } from '@gravito/photon'
+import type { GravitoMiddleware } 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
+ */
 export type TranslationMap = {
   [key: string]: string | TranslationMap
 }
 
+/**
+ * Configuration for the I18n service.
+ *
+ * @public
+ * @since 3.0.0
+ */
 export 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[]
-  // Path to translation files, or a Record of translations
-  // If undefined, it will look into `resources/lang` by default (conceptually, handled by loader)
+  /**
+   * 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
+ */
 export 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 request-scoped instance
+  /**
+   * 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
 }
 
@@ -36,7 +96,7 @@ export class I18nInstance implements I18nService {
    * @param initialLocale - The initial locale for this instance.
    */
   constructor(
-    private manager: I18nManager,
+    public readonly manager: I18nManager,
     initialLocale: string
   ) {
     this._locale = initialLocale
@@ -100,6 +160,20 @@ export class I18nInstance implements I18nService {
   clone(locale?: string): I18nService {
     return new I18nInstance(this.manager, locale || this._locale)
   }
+
+  /**
+   * Get the I18n configuration.
+   */
+  getConfig(): I18nConfig {
+    return this.manager.getConfig()
+  }
+
+  /**
+   * Get the translations.
+   */
+  get translations(): Record<string, TranslationMap> {
+    return this.manager.translations
+  }
 }
 
 /**
@@ -107,7 +181,7 @@ export class I18nInstance implements I18nService {
  * Holds shared configuration and translation resources
  */
 export class I18nManager implements I18nService {
-  private translations: Record<string, TranslationMap> = {}
+  public translations: Record<string, TranslationMap> = {}
   // Default instance for global usage (e.g. CLI or background jobs)
   private globalInstance: I18nInstance
 
@@ -211,12 +285,12 @@ export class I18nManager implements I18nService {
    */
   translate(locale: string, key: string, replacements?: Record<string, string | number>): string {
     const keys = key.split('.')
-    let value: any = this.translations[locale]
+    let value: string | TranslationMap | undefined = this.translations[locale]
 
     // 1. Try current locale
     for (const k of keys) {
       if (value && typeof value === 'object' && k in value) {
-        value = value[k]
+        value = (value as TranslationMap)[k]
       } else {
         value = undefined
         break
@@ -225,10 +299,11 @@ export class I18nManager implements I18nService {
 
     // 2. If not found, try fallback (defaultLocale)
     if (value === undefined && locale !== this.config.defaultLocale) {
-      let fallbackValue: any = this.translations[this.config.defaultLocale]
+      let fallbackValue: string | TranslationMap | undefined =
+        this.translations[this.config.defaultLocale]
       for (const k of keys) {
         if (fallbackValue && typeof fallbackValue === 'object' && k in fallbackValue) {
-          fallbackValue = fallbackValue[k]
+          fallbackValue = (fallbackValue as TranslationMap)[k]
         } else {
           fallbackValue = undefined
           break
@@ -242,16 +317,20 @@ export class I18nManager implements I18nService {
     }
 
     // 3. Replacements
-    if (replacements) {
-      for (const [search, replace] of Object.entries(replacements)) {
-        value = value.replace(new RegExp(`:${search}`, 'g'), String(replace))
-      }
+    if (replacements && Object.keys(replacements).length > 0) {
+      value = value.replace(REPLACEMENT_REGEX, (match, key) => {
+        return (replacements as Record<string, unknown>)[key] !== undefined
+          ? String((replacements as Record<string, unknown>)[key])
+          : match
+      })
     }
 
     return value
   }
 }
 
+const REPLACEMENT_REGEX = /:([a-zA-Z0-9_]+)/g
+
 /**
  * Locale Middleware
  *
@@ -259,7 +338,7 @@ export class I18nManager implements I18nService {
  * 1. Route Parameter (e.g. /:locale/foo) - Recommended for SEO
  * 2. Header (Accept-Language) - Recommended for APIs
  */
-export const localeMiddleware = (i18nManager: I18nService): MiddlewareHandler => {
+export const localeMiddleware = (i18nManager: I18nService): GravitoMiddleware => {
   return async (c, next) => {
     // Determine initial locale
     // Priority: 1. Route Param 2. Query ?lang= 3. Header 4. Default
@@ -279,6 +358,6 @@ export const localeMiddleware = (i18nManager: I18nService): MiddlewareHandler =>
     // Inject into context
     c.set('i18n', i18n)
 
-    await next()
+    return await next()
   }
 }

package/src/index.ts

@@ -2,24 +2,48 @@ import type { GravitoMiddleware, GravitoOrbit, PlanetCore } from '@gravito/core'
 import { type I18nConfig, I18nManager, type I18nService, localeMiddleware } from './I18nService'
 
 declare module '@gravito/core' {
-  interface Variables {
+  interface GravitoVariables {
+    /** I18n service for translations */
     i18n: I18nService
   }
 }
 
 /**
- * OrbitCosmos - Internationalization Orbit
+ * OrbitCosmos provides internationalization (i18n) support for Gravito.
+ * It manages translations, locale switching, and provides a middleware for request-scoped locale detection.
  *
- * Provides i18n functionality for Gravito applications.
+ * @example
+ * ```typescript
+ * const cosmos = new OrbitCosmos({
+ *   defaultLocale: 'en',
+ *   supportedLocales: ['en', 'zh-TW'],
+ *   translations: {
+ *     en: { welcome: 'Welcome!' },
+ *     'zh-TW': { welcome: '歡迎！' }
+ *   }
+ * });
+ * core.addOrbit(cosmos);
+ * ```
+ * @public
  */
 export class OrbitCosmos implements GravitoOrbit {
+  /**
+   * Create a new OrbitCosmos instance.
+   * @param config - The i18n configuration options.
+   */
   constructor(private 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 {
     const i18nManager = new I18nManager(this.config)
 
-    // Register globally if needed (for CLI/Jobs)
-    // core.services.set('i18n', i18nManager);
+    // Register globally for CLI/Jobs using the container
+    core.container.instance('i18n', i18nManager)
 
     // Inject locale middleware into every request
     // This middleware handles cloning the i18n instance per request
@@ -29,7 +53,9 @@ export class OrbitCosmos implements GravitoOrbit {
   }
 }
 
-/** @deprecated Use OrbitCosmos instead */
+/**
+ * @deprecated Use OrbitCosmos instead. Will be removed in v4.0.0.
+ */
 export const I18nOrbit = OrbitCosmos
 
 export * from './I18nService'

package/tests/manager.test.ts

@@ -30,7 +30,6 @@ describe('Orbit I18n Manager', () => {
       en: {
         title: 'Hello',
         auth: {
-          // @ts-expect-error
           failed: 'Failed Login',
         } as any,
       },

package/tests/service.test.ts

@@ -90,8 +90,12 @@ describe('localeMiddleware', () => {
 
 describe('OrbitCosmos', () => {
   it('installs locale middleware and logs initialization', () => {
+    const instances = new Map<string, unknown>()
     const core = {
       adapter: { use: jest.fn() },
+      container: {
+        instance: (key: string, value: unknown) => instances.set(key, value),
+      },
       logger: { info: jest.fn() },
     }
     const orbit = new OrbitCosmos({
@@ -104,6 +108,7 @@ describe('OrbitCosmos', () => {
 
     expect(core.adapter.use).toHaveBeenCalledWith('*', expect.any(Function))
     expect(core.logger.info).toHaveBeenCalledWith('[OrbitCosmos] I18n initialized with locale: en')
+    expect(instances.get('i18n')).toBeDefined()
     expect(I18nOrbit).toBe(OrbitCosmos)
   })
 })