@gravito/cosmos 3.1.0 → 3.2.0

package/src/loaders/ChainedLoader.ts

@@ -0,0 +1,117 @@
+/**
+ * @file packages/cosmos/src/loaders/ChainedLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description 組合多個載入器的鏈式載入器實現
+ */
+
+import type { TranslationMap } from '../I18nService'
+import type { TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * 鏈式翻譯載入器
+ *
+ * 組合多個載入器,實現降級策略
+ * 當第一個載入器失敗時,自動嘗試下一個載入器
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * import { ChainedLoader, FileSystemLoader, RemoteLoader } from '@gravito/cosmos'
+ *
+ * const loader = new ChainedLoader([
+ *   new FileSystemLoader({ baseDir: './lang' }),
+ *   new RemoteLoader({ url: 'https://api.example.com/i18n/:locale' }),
+ *   new MemoryLoader({ fallbackTranslations })
+ * ])
+ *
+ * // 載入順序: FileSystem -> Remote -> Memory
+ * const translations = await loader.load('zh-TW')
+ * ```
+ */
+export class ChainedLoader implements TranslationLoaderChain {
+  public readonly name: string
+  private loaders: TranslationLoader[]
+  private fallbackLoader?: TranslationLoader
+
+  /**
+   * 建立鏈式載入器實例
+   *
+   * @param loaders - 載入器陣列,按照優先順序排列
+   * @param name - 載入器名稱 (可選)
+   */
+  constructor(loaders: TranslationLoader[], name?: string) {
+    this.name = name || 'ChainedLoader'
+    this.loaders = loaders
+  }
+
+  /**
+   * 載入指定語言的翻譯資源
+   *
+   * 按順序嘗試每個載入器,直到成功載入或所有載入器都失敗
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源,所有載入器都失敗則返回 null
+   */
+  async load(locale: string): Promise<TranslationMap | null> {
+    // 嘗試每個載入器
+    for (const loader of this.loaders) {
+      try {
+        const result = await loader.load(locale)
+        if (result) {
+          return result
+        }
+      } catch (_error) {}
+    }
+
+    // 所有載入器都失敗,嘗試備用載入器
+    if (this.fallbackLoader) {
+      return this.fallbackLoader.load(locale)
+    }
+
+    return null
+  }
+
+  /**
+   * 設定備用載入器
+   *
+   * @param loader - 備用載入器
+   * @returns 當前實例,支援鏈式調用
+   */
+  fallback(loader: TranslationLoader): TranslationLoaderChain {
+    this.fallbackLoader = loader
+    return this
+  }
+
+  /**
+   * 在鏈的末尾新增載入器
+   *
+   * @param loader - 要新增的載入器
+   * @returns 當前實例,支援鏈式調用
+   */
+  append(loader: TranslationLoader): ChainedLoader {
+    this.loaders.push(loader)
+    return this
+  }
+
+  /**
+   * 在鏈的開頭插入載入器
+   *
+   * @param loader - 要插入的載入器
+   * @returns 當前實例,支援鏈式調用
+   */
+  prepend(loader: TranslationLoader): ChainedLoader {
+    this.loaders.unshift(loader)
+    return this
+  }
+
+  /**
+   * 取得載入器陣列
+   *
+   * @returns 載入器陣列的複本
+   */
+  getLoaders(): readonly TranslationLoader[] {
+    return [...this.loaders]
+  }
+}

package/src/loaders/CloudflareKVLoader.ts

@@ -0,0 +1,194 @@
+/**
+ * @file packages/cosmos/src/loaders/CloudflareKVLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description Cloudflare Workers KV 載入器
+ */
+
+/**
+ * Cloudflare Workers KV Namespace 類型聲明
+ * @see https://developers.cloudflare.com/workers/runtime-apis/kv/
+ */
+declare global {
+  interface KVNamespace {
+    get(key: string, type?: 'text'): Promise<string | null>
+    get(key: string, type: 'json'): Promise<any>
+    get(key: string, type: 'arrayBuffer'): Promise<ArrayBuffer | null>
+    get(key: string, type: 'stream'): Promise<ReadableStream | null>
+    put(key: string, value: string | ArrayBuffer | ArrayBufferView | ReadableStream): Promise<void>
+    delete(key: string): Promise<void>
+  }
+}
+
+import type { TranslationMap } from '../I18nService'
+import type { KVStorage } from './EdgeKVLoader'
+import { EdgeKVLoader } from './EdgeKVLoader'
+import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * Cloudflare Workers KV 適配器
+ *
+ * 將 Cloudflare KV Namespace 適配到 KVStorage 介面
+ *
+ * @internal
+ * @since 3.2.0
+ */
+export class CloudflareKVAdapter implements KVStorage {
+  constructor(private namespace: KVNamespace) {}
+
+  async get(key: string): Promise<string | null> {
+    return this.namespace.get(key, 'text')
+  }
+
+  async put(key: string, value: string): Promise<void> {
+    await this.namespace.put(key, value)
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.namespace.delete(key)
+  }
+}
+
+/**
+ * Cloudflare KV 載入器配置
+ *
+ * @public
+ * @since 3.2.0
+ */
+export interface CloudflareKVLoaderConfig extends LoaderConfig {
+  /**
+   * Cloudflare KV Namespace
+   *
+   * 在 wrangler.toml 中定義的 KV binding
+   *
+   * @example
+   * ```toml
+   * # wrangler.toml
+   * [[kv_namespaces]]
+   * binding = "I18N_KV"
+   * id = "your-namespace-id"
+   * ```
+   */
+  namespace: KVNamespace
+
+  /**
+   * Key 前綴
+   *
+   * @default 'i18n'
+   */
+  prefix?: string
+
+  /**
+   * Key 模板
+   *
+   * @default ':prefix::locale'
+   */
+  keyTemplate?: string
+}
+
+/**
+ * Cloudflare Workers KV 載入器
+ *
+ * 從 Cloudflare Workers KV 載入翻譯資源
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * // worker.ts
+ * import { OrbitCosmos, CloudflareKVLoader } from '@gravito/cosmos/edge'
+ *
+ * export interface Env {
+ *   I18N_KV: KVNamespace
+ * }
+ *
+ * export default {
+ *   async fetch(request: Request, env: Env) {
+ *     const cosmos = new OrbitCosmos({
+ *       defaultLocale: 'en',
+ *       supportedLocales: ['en', 'zh-TW'],
+ *       loaders: [
+ *         new CloudflareKVLoader({
+ *           namespace: env.I18N_KV,
+ *           prefix: 'translations'
+ *         })
+ *       ]
+ *     })
+ *
+ *     // ... rest of your worker
+ *   }
+ * }
+ * ```
+ *
+ * ## 上傳翻譯到 KV
+ *
+ * 使用 wrangler 命令上傳翻譯檔案:
+ *
+ * ```bash
+ * # 上傳單個語言
+ * wrangler kv:key put --binding I18N_KV "i18n:zh-TW" "$(cat lang/zh-TW.json)"
+ *
+ * # 批次上傳
+ * for file in lang/*.json; do
+ *   locale=$(basename "$file" .json)
+ *   wrangler kv:key put --binding I18N_KV "i18n:$locale" "$(cat $file)"
+ * done
+ * ```
+ *
+ * ## 特點
+ *
+ * - **全球邊緣快取**: 翻譯資料快取在全球邊緣節點
+ * - **低延遲**: 通常 <100ms 讀取時間
+ * - **高可用性**: Cloudflare 的全球網路
+ * - **動態更新**: 可以動態更新翻譯而無需重新部署
+ */
+export class CloudflareKVLoader implements TranslationLoaderChain {
+  private loader: EdgeKVLoader
+
+  /**
+   * 建立 Cloudflare KV 載入器實例
+   *
+   * @param config - 載入器配置
+   */
+  constructor(config: CloudflareKVLoaderConfig) {
+    const adapter = new CloudflareKVAdapter(config.namespace)
+    this.loader = new EdgeKVLoader({
+      storage: adapter,
+      prefix: config.prefix,
+      keyTemplate: config.keyTemplate,
+      name: config.name || 'CloudflareKVLoader',
+    })
+  }
+
+  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
+  }
+
+  /**
+   * 儲存翻譯資源到 Cloudflare KV
+   *
+   * @param locale - 語言代碼
+   * @param translations - 翻譯資源
+   */
+  async put(locale: string, translations: TranslationMap): Promise<void> {
+    return this.loader.put(locale, translations)
+  }
+
+  /**
+   * 從 Cloudflare KV 刪除翻譯資源
+   *
+   * @param locale - 語言代碼
+   */
+  async delete(locale: string): Promise<void> {
+    return this.loader.delete(locale)
+  }
+}

package/src/loaders/EdgeKVLoader.ts

@@ -0,0 +1,248 @@
+/**
+ * @file packages/cosmos/src/loaders/EdgeKVLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description 通用 Edge KV 儲存載入器
+ */
+
+import type { TranslationMap } from '../I18nService'
+import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * KV 儲存介面(通用抽象)
+ *
+ * 定義通用的 KV 儲存操作介面
+ * 可以被不同的 KV 儲存後端實現
+ *
+ * @public
+ * @since 3.2.0
+ */
+export interface KVStorage {
+  /**
+   * 從 KV 儲存讀取值
+   *
+   * @param key - 鍵
+   * @returns 值,如果不存在則返回 null
+   */
+  get(key: string): Promise<string | null>
+
+  /**
+   * 寫入值到 KV 儲存(可選)
+   *
+   * @param key - 鍵
+   * @param value - 值
+   */
+  put?(key: string, value: string): Promise<void>
+
+  /**
+   * 從 KV 儲存刪除值(可選)
+   *
+   * @param key - 鍵
+   */
+  delete?(key: string): Promise<void>
+}
+
+/**
+ * Edge KV 載入器配置
+ *
+ * @public
+ * @since 3.2.0
+ */
+export interface EdgeKVLoaderConfig extends LoaderConfig {
+  /**
+   * KV 儲存實例
+   */
+  storage: KVStorage
+
+  /**
+   * Key 前綴
+   *
+   * @default 'i18n'
+   */
+  prefix?: string
+
+  /**
+   * Key 模板
+   *
+   * 可用的佔位符:
+   * - `:prefix` - Key 前綴
+   * - `:locale` - 語言代碼
+   *
+   * @default ':prefix::locale'
+   *
+   * @example
+   * ```typescript
+   * // 使用冒號分隔
+   * keyTemplate: ':prefix::locale' // 'i18n:zh-TW'
+   *
+   * // 使用斜線分隔
+   * keyTemplate: ':prefix/:locale.json' // 'i18n/zh-TW.json'
+   *
+   * // 僅使用語言代碼
+   * keyTemplate: ':locale' // 'zh-TW'
+   * ```
+   */
+  keyTemplate?: string
+}
+
+/**
+ * 通用 Edge KV 載入器
+ *
+ * 支援任何符合 KVStorage 介面的儲存後端
+ * 適用於 Edge Runtime 環境的 KV 儲存
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * // 自訂 KV 儲存實現
+ * const customStorage: KVStorage = {
+ *   async get(key: string) {
+ *     // 從你的 KV 儲存讀取
+ *     return await myKV.get(key)
+ *   }
+ * }
+ *
+ * const loader = new EdgeKVLoader({
+ *   storage: customStorage,
+ *   prefix: 'translations',
+ *   keyTemplate: ':prefix/:locale.json'
+ * })
+ *
+ * const translations = await loader.load('zh-TW')
+ * // 讀取 key: 'translations/zh-TW.json'
+ * ```
+ *
+ * ## 適用場景
+ *
+ * - **Cloudflare Workers KV**: 使用 CloudflareKVLoader
+ * - **Vercel KV**: 使用 VercelKVLoader
+ * - **自訂 KV 儲存**: 實現 KVStorage 介面
+ *
+ * ## 優缺點
+ *
+ * **優點**:
+ * - Edge Runtime 原生支援
+ * - 低延遲讀取(邊緣快取)
+ * - 支援動態更新
+ *
+ * **缺點**:
+ * - 需要額外的儲存服務
+ * - 可能有額外成本
+ * - 需要預先上傳翻譯到 KV
+ */
+export class EdgeKVLoader implements TranslationLoaderChain {
+  public readonly name: string
+  private storage: KVStorage
+  private prefix: string
+  private keyTemplate: string
+  private fallbackLoader?: TranslationLoader
+
+  /**
+   * 建立 Edge KV 載入器實例
+   *
+   * @param config - 載入器配置
+   */
+  constructor(config: EdgeKVLoaderConfig) {
+    this.name = config.name || 'EdgeKVLoader'
+    this.storage = config.storage
+    this.prefix = config.prefix || 'i18n'
+    this.keyTemplate = config.keyTemplate || ':prefix::locale'
+  }
+
+  /**
+   * 載入指定語言的翻譯資源
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源,載入失敗則返回 null 或嘗試 fallback
+   */
+  async load(locale: string): Promise<TranslationMap | null> {
+    try {
+      const key = this.buildKey(locale)
+      const value = await this.storage.get(key)
+
+      if (!value) {
+        return this.tryFallback(locale)
+      }
+
+      return JSON.parse(value) as TranslationMap
+    } catch (error) {
+      console.error(`[EdgeKVLoader] Failed to load ${locale}:`, error)
+      return this.tryFallback(locale)
+    }
+  }
+
+  /**
+   * 建立 KV 儲存的 key
+   *
+   * @param locale - 語言代碼
+   * @returns KV key
+   */
+  private buildKey(locale: string): string {
+    return this.keyTemplate.replace(':prefix', this.prefix).replace(':locale', locale)
+  }
+
+  /**
+   * 嘗試使用備用載入器
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源或 null
+   */
+  private async tryFallback(locale: string): Promise<TranslationMap | null> {
+    if (this.fallbackLoader) {
+      return this.fallbackLoader.load(locale)
+    }
+    return null
+  }
+
+  /**
+   * 設定備用載入器
+   *
+   * @param loader - 備用載入器
+   * @returns 當前實例,支援鏈式調用
+   */
+  fallback(loader: TranslationLoader): TranslationLoaderChain {
+    this.fallbackLoader = loader
+    return this
+  }
+
+  /**
+   * 儲存翻譯資源到 KV 儲存(如果儲存支援 put 操作)
+   *
+   * @param locale - 語言代碼
+   * @param translations - 翻譯資源
+   *
+   * @example
+   * ```typescript
+   * await loader.put('zh-TW', { hello: '你好' })
+   * ```
+   */
+  async put(locale: string, translations: TranslationMap): Promise<void> {
+    if (!this.storage.put) {
+      throw new Error('[EdgeKVLoader] Storage does not support put operation')
+    }
+
+    const key = this.buildKey(locale)
+    const value = JSON.stringify(translations)
+    await this.storage.put(key, value)
+  }
+
+  /**
+   * 從 KV 儲存刪除翻譯資源(如果儲存支援 delete 操作)
+   *
+   * @param locale - 語言代碼
+   *
+   * @example
+   * ```typescript
+   * await loader.delete('zh-TW')
+   * ```
+   */
+  async delete(locale: string): Promise<void> {
+    if (!this.storage.delete) {
+      throw new Error('[EdgeKVLoader] Storage does not support delete operation')
+    }
+
+    const key = this.buildKey(locale)
+    await this.storage.delete(key)
+  }
+}

package/src/loaders/FileSystemLoader.ts

@@ -0,0 +1,125 @@
+/**
+ * @file packages/cosmos/src/loaders/FileSystemLoader.ts
+ * @module @gravito/cosmos/loaders
+ * @description 從檔案系統載入翻譯資源的實現
+ *
+ * ⚠️ **Node.js Only**
+ *
+ * 此載入器依賴 Node.js 的 fs 模組，無法在 Edge Runtime 使用
+ *
+ * Edge Runtime 替代方案:
+ * - MemoryLoader: 靜態翻譯
+ * - RemoteLoader: HTTP API
+ * - EdgeKVLoader: KV 儲存
+ *
+ * @since 3.1.0
+ * @platform node
+ */
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { TranslationMap } from '../I18nService'
+import { detectRuntime } from '../runtime/detector'
+import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * 檔案系統載入器配置
+ *
+ * @public
+ * @since 3.1.0
+ */
+export interface FileSystemLoaderConfig extends LoaderConfig {
+  /**
+   * 翻譯檔案所在的基礎目錄
+   *
+   * @example '/app/lang'
+   */
+  baseDir: string
+
+  /**
+   * 檔案副檔名
+   *
+   * @default '.json'
+   */
+  extension?: string
+}
+
+/**
+ * 檔案系統翻譯載入器
+ *
+ * 從本地檔案系統載入 JSON 格式的翻譯檔案
+ * 預設尋找 `{baseDir}/{locale}.json` 格式的檔案
+ *
+ * @public
+ * @since 3.1.0
+ *
+ * @example
+ * ```typescript
+ * const loader = new FileSystemLoader({
+ *   baseDir: '/app/lang',
+ *   name: 'fs-loader'
+ * })
+ *
+ * const translations = await loader.load('zh-TW')
+ * // 載入 /app/lang/zh-TW.json
+ * ```
+ */
+export class FileSystemLoader implements TranslationLoaderChain {
+  public readonly name: string
+  private baseDir: string
+  private extension: string
+  private fallbackLoader?: TranslationLoader
+
+  /**
+   * 建立檔案系統載入器實例
+   *
+   * @param config - 載入器配置
+   * @throws {Error} 如果在 Edge Runtime 環境中使用
+   */
+  constructor(config: FileSystemLoaderConfig) {
+    // 運行時檢查
+    const runtime = detectRuntime()
+    if (runtime === 'edge') {
+      throw new Error(
+        '[FileSystemLoader] This loader requires Node.js and cannot run in Edge Runtime. ' +
+          'Use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.'
+      )
+    }
+
+    this.name = config.name || 'FileSystemLoader'
+    this.baseDir = config.baseDir
+    this.extension = config.extension || '.json'
+  }
+
+  /**
+   * 載入指定語言的翻譯資源
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源,載入失敗則返回 null
+   */
+  async load(locale: string): Promise<TranslationMap | null> {
+    try {
+      const filePath = join(this.baseDir, `${locale}${this.extension}`)
+      const content = await readFile(filePath, 'utf-8')
+      const translations = JSON.parse(content) as TranslationMap
+      return translations
+    } catch (_error) {
+      // 如果有備用載入器,嘗試使用備用載入器
+      if (this.fallbackLoader) {
+        return this.fallbackLoader.load(locale)
+      }
+      return null
+    }
+  }
+
+  /**
+   * 設定備用載入器
+   *
+   * @param loader - 備用載入器
+   * @returns 當前實例,支援鏈式調用
+   */
+  fallback(loader: TranslationLoader): TranslationLoaderChain {
+    this.fallbackLoader = loader
+    return this
+  }
+}