@gravito/cosmos 3.1.0 → 3.2.0

package/src/loaders/MemoryLoader.ts

@@ -0,0 +1,161 @@
+/**
+ * @file packages/cosmos/src/loaders/MemoryLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description 從記憶體載入翻譯資源的實現
+ */
+
+import type { TranslationMap } from '../I18nService'
+import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * 記憶體載入器配置
+ *
+ * @public
+ * @since 3.2.0
+ */
+export interface MemoryLoaderConfig extends LoaderConfig {
+  /**
+   * 預先載入的翻譯資源
+   *
+   * Key 為語言代碼,Value 為翻譯 Map
+   */
+  translations: Record<string, TranslationMap>
+}
+
+/**
+ * 記憶體翻譯載入器
+ *
+ * 從記憶體載入預先打包的翻譯資源
+ * 適用於 Edge Runtime 環境或靜態翻譯場景
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * import { MemoryLoader } from '@gravito/cosmos'
+ * import en from './lang/en.json'
+ * import zhTW from './lang/zh-TW.json'
+ *
+ * const loader = new MemoryLoader({
+ *   translations: {
+ *     en,
+ *     'zh-TW': zhTW
+ *   }
+ * })
+ *
+ * const translations = await loader.load('zh-TW')
+ * ```
+ *
+ * ## 適用場景
+ *
+ * - **靜態翻譯**: Build-time 打包的翻譯資源
+ * - **Edge Runtime**: 無檔案系統的邊緣環境
+ * - **測試環境**: 快速的測試資料載入
+ * - **小型應用**: 翻譯量較少的應用(<100KB)
+ *
+ * ## 優缺點
+ *
+ * **優點**:
+ * - 極快的載入速度(記憶體讀取)
+ * - 無需網路請求
+ * - Edge Runtime 相容
+ *
+ * **缺點**:
+ * - 增加 Bundle Size
+ * - 無法動態更新翻譯
+ * - 不適合大量翻譯
+ */
+export class MemoryLoader implements TranslationLoaderChain {
+  public readonly name: string
+  private translations: Record<string, TranslationMap>
+  private fallbackLoader?: TranslationLoader
+
+  /**
+   * 建立記憶體載入器實例
+   *
+   * @param config - 載入器配置
+   */
+  constructor(config: MemoryLoaderConfig) {
+    this.name = config.name || 'MemoryLoader'
+    this.translations = config.translations
+  }
+
+  /**
+   * 載入指定語言的翻譯資源
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源,如果不存在則嘗試使用 fallback loader
+   */
+  async load(locale: string): Promise<TranslationMap | null> {
+    const translations = this.translations[locale]
+
+    if (translations) {
+      return translations
+    }
+
+    // 嘗試使用備用載入器
+    if (this.fallbackLoader) {
+      return this.fallbackLoader.load(locale)
+    }
+
+    return null
+  }
+
+  /**
+   * 設定備用載入器
+   *
+   * @param loader - 備用載入器
+   * @returns 當前實例,支援鏈式調用
+   */
+  fallback(loader: TranslationLoader): TranslationLoaderChain {
+    this.fallbackLoader = loader
+    return this
+  }
+
+  /**
+   * 新增或更新語言的翻譯資源
+   *
+   * @param locale - 語言代碼
+   * @param translations - 翻譯資源
+   *
+   * @example
+   * ```typescript
+   * loader.addTranslations('fr', { hello: 'Bonjour' })
+   * ```
+   */
+  addTranslations(locale: string, translations: TranslationMap): void {
+    this.translations[locale] = {
+      ...(this.translations[locale] || {}),
+      ...translations,
+    }
+  }
+
+  /**
+   * 移除語言的翻譯資源
+   *
+   * @param locale - 語言代碼
+   */
+  removeTranslations(locale: string): void {
+    delete this.translations[locale]
+  }
+
+  /**
+   * 取得所有已載入的語言列表
+   *
+   * @returns 語言代碼陣列
+   */
+  getLoadedLocales(): string[] {
+    return Object.keys(this.translations)
+  }
+
+  /**
+   * 檢查是否已載入指定語言
+   *
+   * @param locale - 語言代碼
+   * @returns 是否已載入
+   */
+  hasLocale(locale: string): boolean {
+    return locale in this.translations
+  }
+}

package/src/loaders/RemoteLoader.ts

@@ -0,0 +1,235 @@
+/**
+ * @file packages/cosmos/src/loaders/RemoteLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description 從遠端 HTTP API 載入翻譯資源的實現
+ */
+
+import type { TranslationMap } from '../I18nService'
+import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * 遠端載入器配置
+ *
+ * @public
+ * @since 3.1.0
+ */
+export interface RemoteLoaderConfig extends LoaderConfig {
+  /**
+   * 遠端 API 的 URL 模板
+   *
+   * 使用 `:locale` 作為語言代碼的佔位符
+   *
+   * @example 'https://cms.example.com/i18n/:locale'
+   */
+  url: string
+
+  /**
+   * HTTP 請求標頭
+   *
+   * @example { 'Authorization': 'Bearer token', 'Accept': 'application/json' }
+   */
+  headers?: Record<string, string>
+
+  /**
+   * 請求超時時間 (毫秒)
+   *
+   * @default 10000 (10 秒)
+   */
+  timeout?: number
+
+  /**
+   * 重試次數
+   *
+   * @default 3
+   */
+  retries?: number
+
+  /**
+   * 重試延遲 (毫秒)
+   *
+   * 使用指數退避策略: delay * (2 ^ attempt)
+   *
+   * @default 1000 (1 秒)
+   */
+  retryDelay?: number
+
+  /**
+   * 是否啟用 ETag 快取
+   *
+   * 啟用後,會在後續請求中發送 If-None-Match 標頭
+   * 如果伺服器返回 304 Not Modified,則使用快取的翻譯
+   *
+   * @default true
+   */
+  etagCache?: boolean
+}
+
+/**
+ * 遠端翻譯載入器
+ *
+ * 從遠端 HTTP API 載入翻譯資源
+ * 支援 ETag 快取、重試機制、超時處理
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const loader = new RemoteLoader({
+ *   url: 'https://api.example.com/i18n/:locale',
+ *   headers: { 'Authorization': 'Bearer your-token' },
+ *   timeout: 5000,
+ *   retries: 3,
+ *   etagCache: true
+ * })
+ *
+ * const translations = await loader.load('zh-TW')
+ * // GET https://api.example.com/i18n/zh-TW
+ * ```
+ */
+export class RemoteLoader implements TranslationLoaderChain {
+  public readonly name: string
+  private url: string
+  private headers: Record<string, string>
+  private timeout: number
+  private retries: number
+  private retryDelay: number
+  private etagCache: boolean
+  private fallbackLoader?: TranslationLoader
+
+  /** ETag 快取:locale -> etag */
+  private etagMap = new Map<string, string>()
+  /** 翻譯快取:locale -> translations (用於 ETag 304 回應) */
+  private translationCache = new Map<string, TranslationMap>()
+
+  /**
+   * 建立遠端載入器實例
+   *
+   * @param config - 載入器配置
+   */
+  constructor(config: RemoteLoaderConfig) {
+    this.name = config.name || 'RemoteLoader'
+    this.url = config.url
+    this.headers = config.headers || {}
+    this.timeout = config.timeout ?? 10000
+    this.retries = config.retries ?? 3
+    this.retryDelay = config.retryDelay ?? 1000
+    this.etagCache = config.etagCache ?? true
+  }
+
+  /**
+   * 載入指定語言的翻譯資源
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源,載入失敗則返回 null
+   */
+  async load(locale: string): Promise<TranslationMap | null> {
+    let _lastError: Error | null = null
+
+    // 重試邏輯
+    for (let attempt = 0; attempt <= this.retries; attempt++) {
+      try {
+        const result = await this.fetchWithTimeout(locale)
+        return result
+      } catch (error) {
+        _lastError = error as Error
+
+        // 如果不是最後一次嘗試,等待後重試
+        if (attempt < this.retries) {
+          const delay = this.retryDelay * 2 ** attempt
+          await this.sleep(delay)
+        }
+      }
+    }
+
+    // 所有重試都失敗,嘗試備用載入器
+    if (this.fallbackLoader) {
+      return this.fallbackLoader.load(locale)
+    }
+
+    return null
+  }
+
+  /**
+   * 發送 HTTP 請求並處理 ETag 快取
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源
+   */
+  private async fetchWithTimeout(locale: string): Promise<TranslationMap | null> {
+    const url = this.url.replace(':locale', locale)
+    const controller = new AbortController()
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout)
+
+    try {
+      const headers: Record<string, string> = { ...this.headers }
+
+      // 如果啟用 ETag 快取且有快取的 ETag,加入 If-None-Match 標頭
+      if (this.etagCache && this.etagMap.has(locale)) {
+        headers['If-None-Match'] = this.etagMap.get(locale)!
+      }
+
+      const response = await fetch(url, {
+        method: 'GET',
+        headers,
+        signal: controller.signal,
+      })
+
+      // 處理 304 Not Modified
+      if (response.status === 304) {
+        const cached = this.translationCache.get(locale)
+        if (cached) {
+          return cached
+        }
+      }
+
+      // 處理錯誤狀態碼
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`)
+      }
+
+      const data = (await response.json()) as TranslationMap
+
+      // 儲存 ETag 和翻譯快取
+      if (this.etagCache) {
+        const etag = response.headers.get('ETag')
+        if (etag) {
+          this.etagMap.set(locale, etag)
+          this.translationCache.set(locale, data)
+        }
+      }
+
+      return data
+    } finally {
+      clearTimeout(timeoutId)
+    }
+  }
+
+  /**
+   * 延遲函數
+   *
+   * @param ms - 延遲時間 (毫秒)
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+
+  /**
+   * 設定備用載入器
+   *
+   * @param loader - 備用載入器
+   * @returns 當前實例,支援鏈式調用
+   */
+  fallback(loader: TranslationLoader): TranslationLoaderChain {
+    this.fallbackLoader = loader
+    return this
+  }
+
+  /**
+   * 清除 ETag 和翻譯快取
+   */
+  clearCache(): void {
+    this.etagMap.clear()
+    this.translationCache.clear()
+  }
+}

package/src/loaders/TranslationLoader.ts

@@ -0,0 +1,98 @@
+/**
+ * @file packages/cosmos/src/loaders/TranslationLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description 抽象的翻譯載入器介面,支援多種翻譯來源
+ */
+
+import type { TranslationMap } from '../I18nService'
+
+/**
+ * 翻譯載入器介面
+ *
+ * 定義統一的載入介面,支援多種實現:
+ * - FileSystemLoader: 從檔案系統載入
+ * - RemoteLoader: 從 HTTP API 載入
+ * - DatabaseLoader: 從資料庫載入
+ * - EdgeLoader: Edge Runtime 相容的載入器
+ *
+ * @public
+ * @since 3.1.0
+ */
+export interface TranslationLoader {
+  /**
+   * 載入器名稱,用於識別和除錯
+   */
+  readonly name: string
+
+  /**
+   * 載入指定語言的翻譯資源
+   *
+   * @param locale - 要載入的語言代碼 (如 'en', 'zh-TW')
+   * @returns 翻譯資源,如果載入失敗則返回 null
+   *
+   * @example
+   * ```typescript
+   * const translations = await loader.load('zh-TW')
+   * if (translations) {
+   *   console.log(translations.welcome) // "歡迎"
+   * }
+   * ```
+   */
+  load(locale: string): Promise<TranslationMap | null>
+}
+
+/**
+ * 支援鏈式組合的翻譯載入器介面
+ *
+ * 允許多個載入器組合,實現降級策略:
+ * 主要載入器失敗時,自動嘗試備用載入器
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const loader = new FileSystemLoader(config)
+ *   .fallback(new RemoteLoader(remoteConfig))
+ *   .fallback(new MemoryLoader(fallbackTranslations))
+ *
+ * // 載入順序: FileSystem -> Remote -> Memory
+ * const translations = await loader.load('zh-TW')
+ * ```
+ */
+export interface TranslationLoaderChain extends TranslationLoader {
+  /**
+   * 設定備用載入器
+   *
+   * 當當前載入器失敗時,會嘗試使用備用載入器
+   *
+   * @param loader - 備用載入器
+   * @returns 鏈式載入器實例,支援繼續串接
+   */
+  fallback(loader: TranslationLoader): TranslationLoaderChain
+}
+
+/**
+ * 載入器配置的基礎介面
+ *
+ * 所有載入器都應該接受的通用配置選項
+ *
+ * @public
+ * @since 3.1.0
+ */
+export interface LoaderConfig {
+  /**
+   * 載入器名稱 (可選)
+   */
+  name?: string
+
+  /**
+   * 快取策略 (可選)
+   */
+  cache?: {
+    /** 是否啟用快取 */
+    enabled: boolean
+    /** 快取過期時間 (毫秒) */
+    ttl?: number
+  }
+}

package/src/loaders/VercelKVLoader.ts

@@ -0,0 +1,192 @@
+/**
+ * @file packages/cosmos/src/loaders/VercelKVLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description Vercel KV 載入器
+ */
+
+import type { TranslationMap } from '../I18nService'
+import type { KVStorage } from './EdgeKVLoader'
+import { EdgeKVLoader } from './EdgeKVLoader'
+import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * Vercel KV 適配器
+ *
+ * 將 @vercel/kv 適配到 KVStorage 介面
+ *
+ * @internal
+ * @since 3.2.0
+ */
+export class VercelKVAdapter implements KVStorage {
+  constructor(private kv: any) {} // @vercel/kv 型別
+
+  async get(key: string): Promise<string | null> {
+    return this.kv.get(key)
+  }
+
+  async put(key: string, value: string): Promise<void> {
+    await this.kv.set(key, value)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.kv.del(key)
+  }
+}
+
+/**
+ * Vercel KV 載入器配置
+ *
+ * @public
+ * @since 3.2.0
+ */
+export interface VercelKVLoaderConfig extends LoaderConfig {
+  /**
+   * Vercel KV 實例
+   *
+   * 從 @vercel/kv 導入
+   *
+   * @example
+   * ```typescript
+   * import { kv } from '@vercel/kv'
+   *
+   * const loader = new VercelKVLoader({ kv })
+   * ```
+   */
+  kv: any // @vercel/kv
+
+  /**
+   * Key 前綴
+   *
+   * @default 'i18n'
+   */
+  prefix?: string
+
+  /**
+   * Key 模板
+   *
+   * @default ':prefix::locale'
+   */
+  keyTemplate?: string
+}
+
+/**
+ * Vercel KV 載入器
+ *
+ * 從 Vercel KV (基於 Redis) 載入翻譯資源
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * // app/api/route.ts (Vercel Edge Function)
+ * import { OrbitCosmos, VercelKVLoader } from '@gravito/cosmos/edge'
+ * import { kv } from '@vercel/kv'
+ *
+ * const cosmos = new OrbitCosmos({
+ *   defaultLocale: 'en',
+ *   supportedLocales: ['en', 'zh-TW'],
+ *   loaders: [
+ *     new VercelKVLoader({
+ *       kv,
+ *       prefix: 'i18n'
+ *     })
+ *   ]
+ * })
+ *
+ * export async function GET() {
+ *   const i18n = cosmos.clone('zh-TW')
+ *   await i18n.ensureLocale('zh-TW')
+ *   return new Response(i18n.t('welcome'))
+ * }
+ * ```
+ *
+ * ## 上傳翻譯到 Vercel KV
+ *
+ * 使用 Vercel CLI 或 API 上傳翻譯:
+ *
+ * ```typescript
+ * // scripts/upload-translations.ts
+ * import { kv } from '@vercel/kv'
+ * import { readFileSync } from 'fs'
+ *
+ * const locales = ['en', 'zh-TW', 'ja']
+ *
+ * for (const locale of locales) {
+ *   const translations = JSON.parse(
+ *     readFileSync(`./lang/${locale}.json`, 'utf-8')
+ *   )
+ *   await kv.set(`i18n:${locale}`, JSON.stringify(translations))
+ *   console.log(`Uploaded ${locale}`)
+ * }
+ * ```
+ *
+ * ## 特點
+ *
+ * - **基於 Redis**: 高效能的記憶體資料庫
+ * - **全球複製**: 資料複製到多個區域
+ * - **低延遲**: Edge 環境快速存取
+ * - **動態更新**: 即時更新翻譯
+ * - **TTL 支援**: 可設定過期時間
+ *
+ * ## 環境變數
+ *
+ * 需要在 Vercel 專案中設定:
+ *
+ * ```env
+ * KV_URL=your-kv-url
+ * KV_REST_API_URL=your-api-url
+ * KV_REST_API_TOKEN=your-api-token
+ * KV_REST_API_READ_ONLY_TOKEN=your-read-only-token
+ * ```
+ */
+export class VercelKVLoader implements TranslationLoaderChain {
+  private loader: EdgeKVLoader
+
+  /**
+   * 建立 Vercel KV 載入器實例
+   *
+   * @param config - 載入器配置
+   */
+  constructor(config: VercelKVLoaderConfig) {
+    const adapter = new VercelKVAdapter(config.kv)
+    this.loader = new EdgeKVLoader({
+      storage: adapter,
+      prefix: config.prefix,
+      keyTemplate: config.keyTemplate,
+      name: config.name || 'VercelKVLoader',
+    })
+  }
+
+  get name(): string {
+    return this.loader.name
+  }
+
+  async load(locale: string): Promise<TranslationMap | null> {
+    return this.loader.load(locale)
+  }
+
+  fallback(loader: TranslationLoader): TranslationLoaderChain {
+    this.loader.fallback(loader)
+    return this
+  }
+
+  /**
+   * 儲存翻譯資源到 Vercel KV
+   *
+   * @param locale - 語言代碼
+   * @param translations - 翻譯資源
+   */
+  async put(locale: string, translations: TranslationMap): Promise<void> {
+    return this.loader.put(locale, translations)
+  }
+
+  /**
+   * 從 Vercel KV 刪除翻譯資源
+   *
+   * @param locale - 語言代碼
+   */
+  async delete(locale: string): Promise<void> {
+    return this.loader.delete(locale)
+  }
+}