@gravito/cosmos 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @gravito/cosmos
 
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies
+  - @gravito/core@1.2.1
+
 ## 3.0.0
 
 ### Patch Changes

package/README.md

@@ -1,8 +1,18 @@
-# @gravito/cosmos
+# @gravito/cosmos 🌌
 
-> Lightweight Internationalization (i18n) Orbit for Gravito.
+> Lightweight, high-performance Internationalization (i18n) Orbit for the Gravito framework.
 
-Provides simple JSON-based localization support for your Gravito application, with seamless integration into Photon context.
+`@gravito/cosmos` brings seamless localization support to your Gravito applications. It features request-scoped i18n instances, lazy loading of translation files, parameter replacement, and flexible locale detection.
+
+## ✨ Features
+
+- **🚀 Performance-First**: Highly optimized translation resolution with internal caching.
+- **🛡️ Type-Safe**: Support for type-safe translation keys using TypeScript generics.
+- **🔄 Request-Scoped**: Clones i18n instances per request to maintain locale state without resource duplication.
+- **📂 Lazy Loading**: Load translation files from the filesystem only when needed.
+- **🔗 Flexible Fallbacks**: Define custom fallback chains and missing key strategies.
+- **🌍 Pluralization**: Integrated support for `Intl.PluralRules` based pluralization.
+- **📡 Auto-Detection**: Detects locale from Route Params, Query Strings, or `Accept-Language` headers.
 
 ## 📦 Installation
 
@@ -12,55 +22,105 @@ bun add @gravito/cosmos
 
 ## 🚀 Quick Start
 
-1.  **Register the Orbit**:
-    ```typescript
-    import { PlanetCore } from '@gravito/core';
-    import { OrbitI18n } from '@gravito/cosmos';
-
-    const core = new PlanetCore();
-
-    core.boot({
-      orbits: [OrbitI18n],
-      config: {
-        i18n: {
-          defaultLocale: 'en',
-          fallbackLocale: 'en',
-          path: './lang' // Path to your locale JSON files
-        }
-      }
-    });
-    ```
-
-2.  **Create Locale Files**:
-    Create `./lang/en.json` and `./lang/zh-TW.json`:
-    ```json
-    // en.json
-    {
-      "welcome": "Welcome, {name}!"
+### 1. Register the Orbit
+
+Add `OrbitCosmos` to your PlanetCore configuration:
+
+```typescript
+import { PlanetCore } from '@gravito/core';
+import { OrbitCosmos } from '@gravito/cosmos';
+
+const core = new PlanetCore({
+  config: {
+    // Optional static translations
+    translations: {
+      en: { welcome: 'Welcome, :name!' },
+      'zh-TW': { welcome: '歡迎，:name！' }
     }
-    ```
+  }
+});
+
+core.addOrbit(new OrbitCosmos({
+  defaultLocale: 'en',
+  supportedLocales: ['en', 'zh-TW'],
+  // Optional: configure lazy loading from a directory
+  lazyLoad: {
+    baseDir: './lang'
+  }
+}));
+
+await core.bootstrap();
+```
 
-3.  **Use in Routes**:
-    ```typescript
-    app.get('/', (c) => {
-      const t = c.get('t');
-      return c.text(t('welcome', { name: 'Carl' }));
-    });
-    ```
+### 2. Create Locale Files (If using lazy loading)
+
+Create `./lang/en.json`:
+```json
+{
+  "auth": {
+    "login_success": "Welcome back!",
+    "failed": "Invalid credentials."
+  },
+  "items": {
+    "count": {
+      "zero": "No items found",
+      "one": "Found :count item",
+      "other": "Found :count items"
+    }
+  }
+}
+```
 
-## ✨ Features
+### 3. Use in Routes
 
--   **Context Injection**: Automatically injects `t()` helper into Photon context.
--   **Parameter Replacement**: Supports `{key}` style parameter replacement.
--   **Locale Detection**: Automatically detects locale from `Accept-Language` header or query parameter `?lang=`.
--   **Fallback**: gracefully falls back to default locale if key is missing.
+The `i18n` service is automatically injected into the context:
 
-## 📚 API
+```typescript
+app.get('/hello', (c) => {
+  const t = c.get('i18n').t;
+  return c.text(t('welcome', { name: 'Carl' }));
+});
 
-### `t(key: string, params?: Record<string, any>): string`
+// Pluralization
+app.get('/items', (c) => {
+  const i18n = c.get('i18n');
+  return c.text(i18n.t('items.count', { count: 5 })); // "Found 5 items"
+});
+```
 
-Main translation helper function.
+## 📚 Core Concepts
+
+### I18nManager
+The central hub that holds shared configuration and translation resources. It handles the heavy lifting of loading files and resolving keys.
+
+### I18nInstance
+A lightweight, request-scoped object that holds the current locale. It delegates to the `I18nManager` for translations.
+
+### Locale Detectors
+Built-in detectors allow automatic locale selection:
+- `RouteParamDetector`: Looks for `:locale` in route parameters.
+- `QueryDetector`: Looks for `?lang=` in the URL.
+- `HeaderDetector`: Uses the `Accept-Language` header.
+
+## 🛠️ Configuration
+
+```typescript
+export interface I18nConfig {
+  defaultLocale: string;
+  supportedLocales: string[];
+  translations?: Record<string, TranslationMap>;
+  lazyLoad?: {
+    baseDir: string;
+    preload?: string[];
+  };
+  fallback?: {
+    fallbackChain?: Record<string, string[]>;
+    onMissingKey?: 'key' | 'empty' | 'throw' | ((key: string, locale: string) => string);
+    warnOnMissing?: boolean;
+  };
+}
+```
 
 ## License
 
-MIT
+MIT © Carl Lee

package/README.zh-TW.md

@@ -1,46 +1,126 @@
-# @gravito/cosmos
+# @gravito/cosmos 🌌
 
-> Gravito 的輕量 i18n 模組，提供 JSON 檔案式在地化。
+> 為 Gravito 框架設計的輕量級、高效能國際化 (i18n) 擴展。
 
-## 安裝
+`@gravito/cosmos` 為您的 Gravito 應用程式提供無縫的在地化支援。具備請求級別的 i18n 實例、翻譯檔案懶加載、參數替換以及靈活的語言偵測功能。
+
+## ✨ 特性
+
+- **🚀 效能優先**：高度優化的翻譯查找與內部快取機制。
+- **🛡️ 類型安全**：支援 TypeScript 泛型，提供類型安全的翻譯鍵值。
+- **🔄 請求級別實例**：為每個請求克隆輕量實例，保持語言狀態而不重複佔用資源。
+- **📂 懶加載**：僅在需要時從檔案系統載入翻譯檔案。
+- **🔗 靈活的回退機制**：可自定義回退鏈與缺失鍵值的處理策略。
+- **🌍 複數支援**：整合 `Intl.PluralRules` 的複數處理。
+- **📡 自動偵測**：支援從路由參數、查詢字串或 `Accept-Language` 標頭偵測語言。
+
+## 📦 安裝
 
 ```bash
 bun add @gravito/cosmos
 ```
 
-## 快速開始
+## 🚀 快速開始
 
-```typescript
-import { PlanetCore } from '@gravito/core'
-import { OrbitI18n } from '@gravito/cosmos'
+### 1. 註冊 Orbit
 
-const core = new PlanetCore()
+將 `OrbitCosmos` 加入您的 PlanetCore 配置中：
 
-core.boot({
-  orbits: [OrbitI18n],
+```typescript
+import { PlanetCore } from '@gravito/core';
+import { OrbitCosmos } from '@gravito/cosmos';
+
+const core = new PlanetCore({
   config: {
-    i18n: {
-      defaultLocale: 'en',
-      fallbackLocale: 'en',
-      path: './lang'
+    // 可選的靜態翻譯
+    translations: {
+      en: { welcome: 'Welcome, :name!' },
+      'zh-TW': { welcome: '歡迎，:name！' }
     }
   }
-})
+});
+
+core.addOrbit(new OrbitCosmos({
+  defaultLocale: 'en',
+  supportedLocales: ['en', 'zh-TW'],
+  // 可選：配置語言檔案目錄
+  lazyLoad: {
+    baseDir: './lang'
+  }
+}));
+
+await core.bootstrap();
 ```
 
-建立 `./lang/en.json`:
+### 2. 建立語言檔案 (若使用懶加載)
 
+建立 `./lang/en.json`:
 ```json
 {
-  "welcome": "Welcome, {name}!"
+  "auth": {
+    "login_success": "Welcome back!",
+    "failed": "Invalid credentials."
+  },
+  "items": {
+    "count": {
+      "zero": "No items found",
+      "one": "Found :count item",
+      "other": "Found :count items"
+    }
+  }
 }
 ```
 
-在路由中使用：
+### 3. 在路由中使用
+
+`i18n` 服務會自動注入到上下文 (Context) 中：
 
 ```typescript
-app.get('/', (c) => {
-  const t = c.get('t')
-  return c.text(t('welcome', { name: 'Carl' }))
-})
+app.get('/hello', (c) => {
+  const t = c.get('i18n').t;
+  return c.text(t('welcome', { name: 'Carl' }));
+});
+
+// 複數處理
+app.get('/items', (c) => {
+  const i18n = c.get('i18n');
+  return c.text(i18n.t('items.count', { count: 5 })); // "Found 5 items"
+});
 ```
+
+## 📚 核心概念
+
+### I18nManager
+核心管理中心，持有共享配置與翻譯資源。負責載入檔案、處理翻譯邏輯、回退策略與快取。
+
+### I18nInstance
+輕量級的請求範圍物件，持有當前的語言狀態。實際翻譯邏輯委託給 `I18nManager` 執行。
+
+### 語言偵測器 (Locale Detectors)
+內建多種偵測器：
+- `RouteParamDetector`：從路由參數 `:locale` 獲取。
+- `QueryDetector`：從 URL 查詢字串 `?lang=` 獲取。
+- `HeaderDetector`：從 `Accept-Language` HTTP 標頭獲取。
+
+## 🛠️ 配置選項
+
+```typescript
+export interface I18nConfig {
+  defaultLocale: string;
+  supportedLocales: string[];
+  translations?: Record<string, TranslationMap>;
+  lazyLoad?: {
+    baseDir: string;
+    preload?: string[];
+  };
+  fallback?: {
+    fallbackChain?: Record<string, string[]>;
+    onMissingKey?: 'key' | 'empty' | 'throw' | ((key: string, locale: string) => string);
+    warnOnMissing?: boolean;
+  };
+}
+```
+
+## License
+
+MIT © Carl Lee

package/build.ts

@@ -0,0 +1,35 @@
+import { spawn } from 'bun'
+
+console.log('Building @gravito/cosmos...')
+
+// Clean dist
+await Bun.$`rm -rf dist`
+
+// Use tsup for multi-format build
+const tsup = spawn(
+  [
+    'npx',
+    'tsup',
+    'src/index.ts',
+    '--format',
+    'esm,cjs',
+    '--dts',
+    '--external',
+    '@gravito/core,@gravito/photon',
+    '--outDir',
+    'dist',
+  ],
+  {
+    stdout: 'inherit',
+    stderr: 'inherit',
+  }
+)
+
+const tsupCode = await tsup.exited
+if (tsupCode !== 0) {
+  console.error('❌ tsup build failed')
+  process.exit(1)
+}
+
+console.log('✅ Build complete!')
+process.exit(0)

package/docs/plans/01-performance.md

@@ -0,0 +1,187 @@
+# Phase 1: 效能優化計劃
+
+> 優先級: P0 | 預估影響: 高
+
+## 現況分析
+
+### 當前瓶頸
+
+1. **翻譯查找無快取**
+   - 每次 `translate()` 都重新遍歷嵌套鍵
+   - 點號分割 (`key.split('.')`) 在熱路徑重複執行
+
+2. **參數替換效率**
+   - 正則表達式每次重新編譯
+   - 多次字串替換操作
+
+3. **檔案加載同步阻塞**
+   - `loadTranslations()` 同步讀取所有檔案
+   - 大型翻譯檔案影響啟動時間
+
+## 優化方案
+
+### 1.1 翻譯查找快取
+
+**目標**: 將重複查找的翻譯結果快取
+
+```typescript
+// 現況
+translate(locale: string, key: string) {
+  const keys = key.split('.')
+  let value = this.translations[locale]
+  for (const k of keys) {
+    value = value?.[k]
+  }
+  return value
+}
+
+// 優化後
+private cache = new Map<string, string>()
+
+translate(locale: string, key: string) {
+  const cacheKey = `${locale}:${key}`
+
+  if (this.cache.has(cacheKey)) {
+    return this.cache.get(cacheKey)
+  }
+
+  const result = this.resolveKey(locale, key)
+  this.cache.set(cacheKey, result)
+  return result
+}
+```
+
+**評估指標**:
+- [ ] 快取命中率 > 80%
+- [ ] 熱路徑查找時間減少 50%+
+
+### 1.2 預編譯正則表達式
+
+**目標**: 避免重複編譯正則
+
+```typescript
+// 現況 - 每次呼叫都編譯
+for (const [param, val] of Object.entries(replacements)) {
+  result = result.replace(new RegExp(`:${param}`, 'g'), String(val))
+}
+
+// 優化後 - 預編譯快取
+private regexCache = new Map<string, RegExp>()
+
+private getParamRegex(param: string): RegExp {
+  if (!this.regexCache.has(param)) {
+    this.regexCache.set(param, new RegExp(`:${param}`, 'g'))
+  }
+  return this.regexCache.get(param)!
+}
+```
+
+### 1.3 懶加載翻譯資源
+
+**目標**: 按需加載語言包，減少初始載入時間
+
+```typescript
+interface LazyLoadConfig {
+  baseDir: string
+  preload?: string[]  // 預載入的語言
+}
+
+class I18nManager {
+  private loadedLocales = new Set<string>()
+
+  async ensureLocale(locale: string): Promise<void> {
+    if (this.loadedLocales.has(locale)) return
+
+    const translations = await this.loadLocale(locale)
+    this.addResource(locale, translations)
+    this.loadedLocales.add(locale)
+  }
+
+  private async loadLocale(locale: string): Promise<TranslationMap> {
+    const path = `${this.config.baseDir}/${locale}.json`
+    return Bun.file(path).json()
+  }
+}
+```
+
+**評估指標**:
+- [ ] 初始載入時間減少 40%+
+- [ ] 記憶體佔用按需增長
+
+### 1.4 快取失效策略
+
+**目標**: 確保快取正確性
+
+```typescript
+class I18nManager {
+  addResource(locale: string, translations: TranslationMap) {
+    this.translations[locale] = {
+      ...this.translations[locale],
+      ...translations
+    }
+    this.invalidateCache(locale)
+  }
+
+  private invalidateCache(locale?: string) {
+    if (locale) {
+      // 精確失效
+      for (const key of this.cache.keys()) {
+        if (key.startsWith(`${locale}:`)) {
+          this.cache.delete(key)
+        }
+      }
+    } else {
+      // 全部失效
+      this.cache.clear()
+    }
+  }
+}
+```
+
+## 實施步驟
+
+### Step 1: 基準測試建立
+```bash
+# 建立效能測試套件
+bun test:perf
+```
+
+- [x] 建立翻譯查找基準測試
+- [x] 建立參數替換基準測試
+- [x] 建立檔案加載基準測試
+
+### Step 2: 實施快取機制
+- [x] 實作 `TranslationCache` 類別 (Implemented as Map in I18nManager)
+- [x] 整合至 `I18nManager`
+- [x] 單元測試覆蓋
+
+### Step 3: 正則預編譯
+- [x] 實作 `RegexCache` (Implemented as constant REPLACEMENT_REGEX)
+- [x] 替換現有實作
+- [x] 效能驗證
+
+### Step 4: 懶加載機制
+- [x] 設計 `LazyLoadConfig` 介面
+- [x] 實作 `ensureLocale()` 方法
+- [x] 整合至中間件
+
+### Step 5: 效能驗證
+- [x] 執行基準測試比對
+- [x] 記憶體使用分析
+- [x] 真實場景壓測
+
+## 風險評估
+
+| 風險 | 機率 | 影響 | 緩解措施 |
+|------|------|------|----------|
+| 快取記憶體爆增 | 中 | 中 | 設定快取上限，使用 LRU |
+| 快取失效遺漏 | 低 | 高 | 完善單元測試 |
+| 懶加載競態條件 | 中 | 中 | 使用 Promise 鎖 |
+
+## 成功標準
+
+- [x] 翻譯查找效能提升 50%+
+- [x] 初始載入時間減少 40%+
+- [x] 無記憶體洩漏
+- [x] 所有現有測試通過
+- [x] 新增效能測試套件