@gravito/cosmos 3.1.0 → 3.2.0

package/src/HMRWatcher.ts

@@ -0,0 +1,305 @@
+/**
+ * @file packages/cosmos/src/HMRWatcher.ts
+ * @module @gravito/cosmos/hmr
+ * @description 翻譯檔案的熱重載 (Hot Module Replacement) 監視器
+ *
+ * ⚠️ **Node.js Only**
+ *
+ * HMR 功能依賴 Node.js 的 fs.watch，無法在 Edge Runtime 使用
+ *
+ * Edge Runtime 環境請使用 RemoteLoader 的 ETag 快取機制
+ *
+ * @since 3.1.0
+ * @platform node
+ */
+
+import type { FSWatcher } from 'node:fs'
+import { watch } from 'node:fs'
+import { join } from 'node:path'
+import { detectRuntime } from './runtime/detector'
+
+/**
+ * HMR 配置
+ *
+ * @public
+ * @since 3.1.0
+ */
+export interface HMRConfig {
+  /**
+   * 是否啟用 HMR
+   *
+   * 建議僅在開發模式啟用
+   *
+   * @default false
+   */
+  enabled: boolean
+
+  /**
+   * 要監視的目錄路徑陣列
+   *
+   * @example ['/app/lang', '/app/i18n']
+   */
+  watchDirs: string[]
+
+  /**
+   * 防抖延遲 (毫秒)
+   *
+   * 避免短時間內多次觸發重新載入
+   *
+   * @default 300
+   */
+  debounce?: number
+
+  /**
+   * 要監視的檔案副檔名
+   *
+   * @default ['.json']
+   */
+  extensions?: string[]
+
+  /**
+   * 是否在檔案變更時顯示日誌
+   *
+   * @default true
+   */
+  verbose?: boolean
+}
+
+/**
+ * 翻譯檔案變更事件
+ *
+ * @public
+ * @since 3.1.0
+ */
+export interface TranslationChangeEvent {
+  /** 變更的檔案路徑 */
+  filePath: string
+  /** 受影響的語言代碼 */
+  locale: string
+  /** 變更類型 */
+  type: 'change' | 'rename'
+}
+
+/**
+ * 變更監聽器函數
+ *
+ * @public
+ * @since 3.1.0
+ */
+export type ChangeListener = (event: TranslationChangeEvent) => void | Promise<void>
+
+/**
+ * HMR 監視器
+ *
+ * 監視翻譯檔案的變更,並在檔案變更時觸發回調
+ * 支援防抖、多目錄監視、副檔名篩選等功能
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const watcher = new HMRWatcher({
+ *   enabled: true,
+ *   watchDirs: ['./lang'],
+ *   debounce: 300,
+ *   verbose: true
+ * })
+ *
+ * watcher.onChange(async ({ locale, filePath }) => {
+ *   console.log(`Reloading ${locale} from ${filePath}`)
+ *   await i18nManager.reloadLocale(locale)
+ * })
+ *
+ * watcher.start()
+ * ```
+ */
+export class HMRWatcher {
+  private config: Required<HMRConfig>
+  private watchers: FSWatcher[] = []
+  private listeners: ChangeListener[] = []
+  private debounceTimers = new Map<string, NodeJS.Timeout>()
+  private isWatching = false
+
+  /**
+   * 建立 HMR 監視器實例
+   *
+   * @param config - HMR 配置
+   */
+  constructor(config: HMRConfig) {
+    // 運行時檢查 - Edge 環境靜默失敗
+    const runtime = detectRuntime()
+    if (runtime === 'edge') {
+      if (config.verbose ?? true) {
+        console.warn(
+          '[HMRWatcher] HMR is not supported in Edge Runtime. ' +
+            'Consider using RemoteLoader with ETag caching instead.'
+        )
+      }
+      // 靜默處理，不拋出錯誤
+      this.config = {
+        enabled: false, // 強制停用
+        watchDirs: [],
+        debounce: 300,
+        extensions: ['.json'],
+        verbose: false,
+      }
+      return
+    }
+
+    this.config = {
+      enabled: config.enabled,
+      watchDirs: config.watchDirs,
+      debounce: config.debounce ?? 300,
+      extensions: config.extensions ?? ['.json'],
+      verbose: config.verbose ?? true,
+    }
+  }
+
+  /**
+   * 註冊變更監聽器
+   *
+   * @param listener - 監聽器函數
+   * @returns 當前實例,支援鏈式調用
+   */
+  onChange(listener: ChangeListener): HMRWatcher {
+    this.listeners.push(listener)
+    return this
+  }
+
+  /**
+   * 移除變更監聽器
+   *
+   * @param listener - 要移除的監聽器函數
+   */
+  removeListener(listener: ChangeListener): void {
+    const index = this.listeners.indexOf(listener)
+    if (index > -1) {
+      this.listeners.splice(index, 1)
+    }
+  }
+
+  /**
+   * 開始監視
+   */
+  start(): void {
+    if (!this.config.enabled) {
+      return
+    }
+
+    if (this.isWatching) {
+      console.warn('[HMRWatcher] Already watching')
+      return
+    }
+
+    for (const dir of this.config.watchDirs) {
+      try {
+        const watcher = watch(dir, { recursive: false }, (eventType, filename) => {
+          if (!filename) {
+            return
+          }
+
+          // 檢查副檔名
+          const hasValidExtension = this.config.extensions.some((ext) => filename.endsWith(ext))
+          if (!hasValidExtension) {
+            return
+          }
+
+          // 提取語言代碼 (假設檔案名稱為 {locale}.json)
+          const locale = filename.replace(/\.[^/.]+$/, '')
+          const filePath = join(dir, filename)
+
+          this.handleChange({
+            filePath,
+            locale,
+            type: eventType === 'rename' ? 'rename' : 'change',
+          })
+        })
+
+        this.watchers.push(watcher)
+
+        if (this.config.verbose) {
+          console.log(`[HMRWatcher] Watching directory: ${dir}`)
+        }
+      } catch (error) {
+        console.error(`[HMRWatcher] Failed to watch directory: ${dir}`, error)
+      }
+    }
+
+    this.isWatching = true
+  }
+
+  /**
+   * 停止監視
+   */
+  stop(): void {
+    for (const watcher of this.watchers) {
+      watcher.close()
+    }
+
+    this.watchers = []
+    this.isWatching = false
+
+    // 清除所有防抖計時器
+    for (const timer of this.debounceTimers.values()) {
+      clearTimeout(timer)
+    }
+    this.debounceTimers.clear()
+
+    if (this.config.verbose) {
+      console.log('[HMRWatcher] Stopped watching')
+    }
+  }
+
+  /**
+   * 處理檔案變更事件
+   *
+   * @param event - 變更事件
+   */
+  private handleChange(event: TranslationChangeEvent): void {
+    const key = `${event.locale}:${event.type}`
+
+    // 清除舊的計時器
+    if (this.debounceTimers.has(key)) {
+      clearTimeout(this.debounceTimers.get(key)!)
+    }
+
+    // 設定新的防抖計時器
+    const timer = setTimeout(async () => {
+      this.debounceTimers.delete(key)
+
+      if (this.config.verbose) {
+        console.log(`[HMRWatcher] File ${event.type}: ${event.filePath} (${event.locale})`)
+      }
+
+      // 通知所有監聽器
+      for (const listener of this.listeners) {
+        try {
+          await listener(event)
+        } catch (error) {
+          console.error('[HMRWatcher] Error in change listener:', error)
+        }
+      }
+    }, this.config.debounce)
+
+    this.debounceTimers.set(key, timer)
+  }
+
+  /**
+   * 檢查是否正在監視
+   *
+   * @returns 是否正在監視
+   */
+  isActive(): boolean {
+    return this.isWatching
+  }
+
+  /**
+   * 取得監視的目錄列表
+   *
+   * @returns 目錄路徑陣列
+   */
+  getWatchDirs(): readonly string[] {
+    return [...this.config.watchDirs]
+  }
+}

package/src/I18nService.ts

@@ -5,7 +5,10 @@
  */
 
 import type { GravitoMiddleware } from '@gravito/core'
+import { LRUCache } from 'lru-cache'
+import { type HMRConfig, HMRWatcher } from './HMRWatcher'
 import { loadLocale } from './loader'
+import type { TranslationLoader } from './loaders/TranslationLoader'
 
 /**
  * Interface for locale detectors used to determine the user's preferred locale from a request context.
@@ -60,6 +63,13 @@ export interface LazyLoadConfig {
   baseDir: string
   /** Optional list of locales to preload on startup. */
   preload?: string[]
+  /**
+   * Custom loader function for testing or specialized loading strategies.
+   * If not provided, defaults to the filesystem loader.
+   *
+   * @deprecated 自 v3.1.0 起建議使用 loaders 陣列
+   */
+  loader?: (baseDir: string, locale: string) => Promise<Record<string, string> | null>
 }
 
 /**
@@ -109,6 +119,50 @@ export interface I18nConfig {
    * Configuration for fallback strategies and missing key handling.
    */
   fallback?: FallbackConfig
+  /**
+   * 翻譯載入器陣列
+   *
+   * 支援多個載入器的鏈式組合,實現降級策略
+   * 當第一個載入器失敗時,會自動嘗試下一個載入器
+   *
+   * @since 3.1.0
+   *
+   * @example
+   * ```typescript
+   * import { FileSystemLoader, RemoteLoader } from '@gravito/cosmos'
+   *
+   * const config: I18nConfig = {
+   *   defaultLocale: 'zh-TW',
+   *   supportedLocales: ['zh-TW', 'en'],
+   *   loaders: [
+   *     new FileSystemLoader({ baseDir: './lang' }),
+   *     new RemoteLoader({ url: 'https://api.example.com/i18n/:locale' })
+   *   ]
+   * }
+   * ```
+   */
+  loaders?: TranslationLoader[]
+  /**
+   * HMR (熱重載) 配置
+   *
+   * 在開發模式下啟用,可以在翻譯檔案變更時自動重新載入
+   *
+   * @since 3.1.0
+   *
+   * @example
+   * ```typescript
+   * const config: I18nConfig = {
+   *   defaultLocale: 'zh-TW',
+   *   supportedLocales: ['zh-TW', 'en'],
+   *   hmr: {
+   *     enabled: process.env.NODE_ENV === 'development',
+   *     watchDirs: ['./lang'],
+   *     debounce: 300
+   *   }
+   * }
+   * ```
+   */
+  hmr?: HMRConfig
 }
 
 /**
@@ -418,17 +472,21 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
   /** Map of translation bundles indexed by locale. */
   public translations: Record<string, TranslationMap> = {}
   /** Internal cache for resolved translation strings. */
-  private cache = new Map<string, string>()
+  private cache: LRUCache<string, string>
   /** Cache for Intl.PluralRules instances. */
   private pluralRules = new Map<string, Intl.PluralRules>()
   /** Set of locales that have been successfully loaded. */
   private loadedLocales = new Set<string>()
+  /** Map of pending locale load promises for coalescing. */
+  private loadingPromises = new Map<string, Promise<void>>()
   /** Counter for cache hits. */
   private cacheHits = 0
   /** Counter for cache misses. */
   private cacheMisses = 0
   /** Default instance for global/CLI usage. */
   private globalInstance: I18nInstance<Schema>
+  /** HMR watcher for development mode. */
+  private hmrWatcher?: HMRWatcher
 
   /**
    * Create a new I18nManager.
@@ -439,7 +497,20 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
     if (config.translations) {
       this.translations = config.translations
     }
+    this.cache = new LRUCache<string, string>({
+      max: 10000,
+      ttl: 1000 * 60 * 60, // 1 hour
+    })
     this.globalInstance = new I18nInstance(this, config.defaultLocale)
+
+    // 初始化 HMR
+    if (config.hmr?.enabled) {
+      this.hmrWatcher = new HMRWatcher(config.hmr)
+      this.hmrWatcher.onChange(async ({ locale }) => {
+        await this.reloadLocale(locale)
+      })
+      this.hmrWatcher.start()
+    }
   }
 
   // --- I18nService Implementation (Delegates to global instance) ---
@@ -550,17 +621,48 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
    * @param locale - Locale to load.
    */
   async ensureLocale(locale: string): Promise<void> {
-    // If already loaded or no lazy load config, skip
-    if (this.loadedLocales.has(locale) || !this.config.lazyLoad) {
+    // If already loaded, skip
+    if (this.loadedLocales.has(locale)) {
       return
     }
 
-    // Attempt to load
-    const translations = await loadLocale(this.config.lazyLoad.baseDir, locale)
-    if (translations) {
-      this.addResource(locale, translations)
-      this.loadedLocales.add(locale)
+    // Check for pending load promise to coalesce requests
+    if (this.loadingPromises.has(locale)) {
+      return this.loadingPromises.get(locale)
     }
+
+    // Create a new load promise
+    const loadPromise = (async () => {
+      try {
+        let translations: TranslationMap | null = null
+
+        // 優先使用新的 loaders 配置
+        if (this.config.loaders && this.config.loaders.length > 0) {
+          // 嘗試每個載入器,直到成功載入
+          for (const loader of this.config.loaders) {
+            translations = await loader.load(locale)
+            if (translations) {
+              break
+            }
+          }
+        }
+        // 向後相容:使用舊的 lazyLoad 配置
+        else if (this.config.lazyLoad) {
+          const loaderFn = this.config.lazyLoad.loader || loadLocale
+          translations = await loaderFn(this.config.lazyLoad.baseDir, locale)
+        }
+
+        if (translations) {
+          this.addResource(locale, translations)
+          this.loadedLocales.add(locale)
+        }
+      } finally {
+        this.loadingPromises.delete(locale)
+      }
+    })()
+
+    this.loadingPromises.set(locale, loadPromise)
+    return loadPromise
   }
 
   // --- Manager Internal API ---
@@ -601,6 +703,11 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
    */
   private invalidateCache(locale?: string) {
     if (locale) {
+      // LRUCache doesn't support iterating keys efficiently in all versions,
+      // but newer versions (v7+) are Map-like.
+      // However, iterating over cache to delete by prefix is expensive.
+      // For now, we clear everything for simplicity and correctness, or we assume keys are iterable.
+      // lru-cache v11 (installed) supports keys().
       for (const key of this.cache.keys()) {
         if (key.startsWith(`${locale}:`)) {
           this.cache.delete(key)
@@ -611,6 +718,37 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
     }
   }
 
+  /**
+   * 重新載入指定語言的翻譯資源
+   *
+   * 會清除該語言的快取並重新從載入器載入
+   * 主要用於 HMR 和手動重新載入場景
+   *
+   * @param locale - 要重新載入的語言代碼
+   * @returns Promise that resolves when reloading is complete
+   * @public
+   * @since 3.1.0
+   *
+   * @example
+   * ```typescript
+   * // 手動重新載入某個語言
+   * await i18nManager.reloadLocale('zh-TW')
+   *
+   * // HMR 自動觸發重新載入
+   * hmrWatcher.onChange(({ locale }) => {
+   *   i18nManager.reloadLocale(locale)
+   * })
+   * ```
+   */
+  async reloadLocale(locale: string): Promise<void> {
+    // 清除已載入標記
+    this.loadedLocales.delete(locale)
+    // 清除快取
+    this.invalidateCache(locale)
+    // 重新載入
+    return this.ensureLocale(locale)
+  }
+
   /**
    * Get the plural form for a locale and count.
    */
@@ -646,7 +784,9 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
 
     for (const fallbackLocale of chain) {
       // Avoid infinite recursion if fallback points to itself
-      if (fallbackLocale === locale) continue
+      if (fallbackLocale === locale) {
+        continue
+      }
 
       const value = this.resolveKey(fallbackLocale, key)
       if (value !== undefined) {

package/src/index.edge.ts

@@ -0,0 +1,35 @@
+/**
+ * @file packages/cosmos/src/index.edge.ts
+ * @module @gravito/cosmos/edge
+ * @description Edge Runtime 入口點
+ *
+ * 此入口點不包含 Node.js 特定功能:
+ * - 不導出 FileSystemLoader (依賴 node:fs)
+ * - 不導出 HMRWatcher (依賴 node:fs)
+ * - 不導出舊的 loader.ts (依賴 node:fs)
+ *
+ * Edge Runtime 環境包括:
+ * - Cloudflare Workers
+ * - Vercel Edge Functions
+ * - Deno Deploy
+ * - 其他邊緣運行環境
+ *
+ * @since 3.2.0
+ * @platform edge
+ */
+
+// Core services
+export * from './I18nService'
+export { I18nOrbit, OrbitCosmos } from './index'
+export * from './loaders/ChainedLoader'
+export * from './loaders/CloudflareKVLoader'
+export * from './loaders/EdgeKVLoader'
+export * from './loaders/MemoryLoader'
+export * from './loaders/RemoteLoader'
+// Edge-compatible loaders
+export * from './loaders/TranslationLoader'
+export * from './loaders/VercelKVLoader'
+
+// Runtime utilities
+export * from './runtime/detector'
+export * from './runtime/path-utils'

package/src/index.node.ts

@@ -0,0 +1,20 @@
+/**
+ * @file packages/cosmos/src/index.node.ts
+ * @module @gravito/cosmos/node
+ * @description Node.js 專用入口點
+ *
+ * 包含完整功能，包括 Node.js 特定功能:
+ * - FileSystemLoader
+ * - HMRWatcher
+ * - 舊的 loader.ts (向後相容)
+ *
+ * @since 3.2.0
+ * @platform node
+ */
+
+export * from './HMRWatcher'
+// Re-export everything from main index
+export * from './index'
+export * from './loader'
+// Ensure all Node.js features are explicitly available
+export * from './loaders/FileSystemLoader'

package/src/index.ts

@@ -77,5 +77,19 @@ export class OrbitCosmos implements GravitoOrbit {
  */
 export const I18nOrbit = OrbitCosmos
 
+export * from './HMRWatcher'
 export * from './I18nService'
 export * from './loader'
+export * from './loaders/ChainedLoader'
+export * from './loaders/CloudflareKVLoader'
+export * from './loaders/EdgeKVLoader'
+export * from './loaders/FileSystemLoader'
+export * from './loaders/MemoryLoader'
+export * from './loaders/RemoteLoader'
+// Loaders
+export * from './loaders/TranslationLoader'
+export * from './loaders/VercelKVLoader'
+
+// Runtime utilities
+export * from './runtime/detector'
+export * from './runtime/path-utils'

package/src/loader.ts

@@ -1,17 +1,37 @@
 /**
  * @file packages/cosmos/src/loader.ts
  * @module @gravito/cosmos/loader
- * @description Utilities for loading translation files from the filesystem.
+ * @description 載入翻譯檔案的工具函數 (向後相容層)
+ *
+ * @deprecated 自 v3.1.0 起建議使用 FileSystemLoader 類別
+ * 這些函數將在 v4.0.0 中移除
+ *
+ * @example
+ * ```typescript
+ * // 舊寫法 (deprecated)
+ * import { loadLocale } from '@gravito/cosmos/loader'
+ * const translations = await loadLocale('/lang', 'zh-TW')
+ *
+ * // 新寫法 (推薦)
+ * import { FileSystemLoader } from '@gravito/cosmos'
+ * const loader = new FileSystemLoader({ baseDir: '/lang' })
+ * const translations = await loader.load('zh-TW')
+ * ```
  */
 
 import { readdir, readFile } from 'node:fs/promises'
 import { join, parse } from 'node:path'
 
 /**
- * Load translations from a directory.
+ * 從目錄載入所有翻譯檔案
  *
- * Scans the specified directory for JSON files and loads them as translation bundles.
- * The filename (without extension) is used as the locale key.
+ * 掃描指定目錄中的所有 JSON 檔案並載入為翻譯資源
+ * 檔案名稱(不含副檔名)將作為語言代碼
+ *
+ * @deprecated 自 v3.1.0 起,建議使用 FileSystemLoader
+ * @param directory - 翻譯目錄的絕對路徑
+ * @returns 語言代碼到翻譯資源的對應表
+ * @public
  *
  * @example
  * ```
@@ -19,10 +39,6 @@ import { join, parse } from 'node:path'
  *   /en.json    -> { "welcome": "Hello" }
  *   /zh-TW.json -> { "welcome": "你好" }
  * ```
- *
- * @param directory - The absolute path to the translations directory.
- * @returns A promise that resolves to a map of locale -> translations.
- * @public
  */
 export async function loadTranslations(
   directory: string
@@ -45,7 +61,7 @@ export async function loadTranslations(
     }
   } catch (_e) {
     console.warn(
-      `[Orbit-I18n] Could not load translations from ${directory}. Directory might not exist.`
+      `[Cosmos] Could not load translations from ${directory}. Directory might not exist.`
     )
   }
 
@@ -53,13 +69,14 @@ export async function loadTranslations(
 }
 
 /**
- * Load translations for a specific locale from a directory.
+ * 載入指定語言的翻譯資源
  *
- * Expects a file named `{locale}.json` in the given directory.
+ * 期望在指定目錄中找到 `{locale}.json` 格式的檔案
  *
- * @param directory - The directory containing translation files.
- * @param locale - The locale string to load.
- * @returns A promise that resolves to the translations map, or null if the file could not be read.
+ * @deprecated 自 v3.1.0 起,建議使用 FileSystemLoader
+ * @param directory - 包含翻譯檔案的目錄
+ * @param locale - 要載入的語言代碼
+ * @returns 翻譯資源,載入失敗則返回 null
  * @public
  */
 export async function loadLocale(