@gravito/cosmos 3.0.1 → 3.2.0

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
+  }
+}

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
+  }
+}