@gravito/cosmos 3.2.1 → 4.0.0

package/README.md

@@ -6,13 +6,28 @@
 
 ## ✨ 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.
+- 🪐 **Galaxy-Ready Globalization**: Native integration with PlanetCore for universal translation support across all Satellites.
+- 🚀 **Performance-First**: Highly optimized translation resolution with internal caching and lazy loading.
+- 🛡️ **Type-Safe Keys**: End-to-end TypeScript support for translation keys using generics.
+- 🔄 **Request-Scoped State**: Clones i18n instances per request to maintain locale consistency without overhead.
+- 🌍 **Intl.PluralRules Support**: Native pluralization following international standards.
+- 📡 **Smart Auto-Detection**: Detects locale from Route Params, Query Strings, or `Accept-Language` headers.
+
+## 🌌 Role in Galaxy Architecture
+
+In the **Gravito Galaxy Architecture**, Cosmos acts as the **Universal Translator (Linguistic Base)**.
+
+- **Cross-Satellite Language**: Ensures that "Success" or "Error" messages are consistent and translated correctly, regardless of which Satellite generates the response.
+- **Linguistic Context**: Propagates the user's preferred language from the `Photon` Sensing Layer deep into the business logic of every Satellite.
+- **Dynamic Localization**: Works with `Atlas` or `Nebula` to load domain-specific translation files on demand, keeping the core Galaxy lean.
+
+```mermaid
+graph LR
+    User([User]) -- "Accept-Language: zh-TW" --> Photon[Photon Engine]
+    Photon --> Cosmos{Cosmos Orbit}
+    Cosmos -->|Translate| Sat[Satellite: Shop]
+    Sat -->|Response| User
+```
 
 ## 📦 Installation
 
@@ -88,6 +103,14 @@ app.get('/items', (c) => {
 });
 ```
 
+## 📚 Documentation
+
+Detailed guides and references for the Galaxy Architecture:
+
+- [🏗️ **Architecture Overview**](./README.md) — Linguistic base and request-scoped state.
+- [🌍 **Localization Strategy**](./doc/LOCALIZATION_STRATEGY.md) — **NEW**: Managing translations across isolated Satellites.
+- [🔗 **Integration with Orbits**](#-quick-start) — Using i18n in Signal and Flare.
+
 ## 📚 Core Concepts
 
 ### I18nManager

package/build.ts

@@ -1,6 +1,8 @@
 import { spawn } from 'bun'
 
-console.log('Building @gravito/cosmos...')
+const isDtsOnly = process.argv.includes('--dts-only')
+
+console.log(isDtsOnly ? 'Building @gravito/cosmos DTS...' : 'Building @gravito/cosmos...')
 
 // Clean dist
 await Bun.$`rm -rf dist`
@@ -8,12 +10,14 @@ await Bun.$`rm -rf dist`
 // Use tsup for multi-format build
 const tsup = spawn(
   [
-    'npx',
+    'bunx',
     'tsup',
     'src/index.ts',
     '--format',
-    'esm,cjs',
-    '--dts',
+    isDtsOnly ? 'esm' : 'esm,cjs',
+    ...(isDtsOnly ? ['--dts', '--dts-only'] : ['--dts']),
+    '--tsconfig',
+    'tsconfig.build.json',
     '--external',
     '@gravito/core,@gravito/photon',
     '--outDir',
@@ -27,9 +31,11 @@ const tsup = spawn(
 
 const tsupCode = await tsup.exited
 if (tsupCode !== 0) {
-  console.error('❌ tsup build failed')
+  console.error('\u274c tsup build failed')
   process.exit(1)
 }
 
-console.log('✅ Build complete!')
+// Type declaration generation is now handled by tsup --dts
+
+console.log('\u2705 Build complete!')
 process.exit(0)

package/doc/LOCALIZATION_STRATEGY.md

@@ -0,0 +1,89 @@
+# Localization Strategy Guide
+
+In a distributed **Galaxy Architecture**, maintaining consistent translations across isolated Satellites is a challenge. `@gravito/cosmos` provides the infrastructure to manage globalization at scale.
+
+## 1. Request-Scoped Locales
+
+Cosmos automatically detects and sets the current locale for every incoming request. This state is maintained throughout the request lifecycle.
+
+```typescript
+// The 'i18n' instance in context is pre-configured for the current user
+app.get('/welcome', (c) => {
+  const t = c.get('i18n').t;
+  return c.text(t('messages.welcome'));
+});
+```
+
+## 2. Distributed Translation Files
+
+Instead of one giant translation file, each **Satellite** should manage its own linguistic assets.
+
+```
+satellites/catalog/
+└── lang/
+    ├── en.json
+    └── zh-TW.json
+```
+
+Register satellite-specific translations during the `BOOT` phase:
+
+```typescript
+// CatalogSatellite.ts
+async boot(core: PlanetCore) {
+  const cosmos = core.container.resolve('cosmos');
+  cosmos.addTranslations('catalog', path.join(__dirname, '../lang'));
+}
+```
+
+## 3. Translation Namespacing
+
+To avoid collisions between Satellites, use namespaces when resolving keys.
+
+```typescript
+// Explicit namespace
+t('catalog::products.not_found');
+
+// Fallback to global if namespace not found
+t('common::errors.validation_failed');
+```
+
+## 4. Parameter Replacement & Pluralization
+
+Cosmos follows the standard `:param` syntax for replacements and leverages `Intl.PluralRules` for complex pluralization logic.
+
+```json
+{
+  "items_count": "Found :count {zero: items|one: item|other: items}"
+}
+```
+
+```typescript
+t('items_count', { count: 5 }); // Found 5 items
+```
+
+## 5. Dynamic Fallback Chains
+
+Configure fallback languages based on regional requirements.
+
+```typescript
+new OrbitCosmos({
+  fallback: {
+    fallbackChain: {
+      'zh-HK': ['zh-TW', 'en'],
+      'fr-CA': ['fr', 'en']
+    }
+  }
+})
+```
+
+## 6. Integration with Signal (Mail)
+
+When sending emails via `@gravito/signal`, the `Mailable` class automatically uses the current locale context provided by Cosmos.
+
+```typescript
+export class WelcomeEmail extends Mailable {
+  build() {
+    return this.subject(this.t('emails.welcome_subject'));
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/cosmos",
-  "version": "3.2.1",
+  "version": "4.0.0",
   "description": "Internationalization orbit for Gravito framework",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -26,9 +26,10 @@
   },
   "scripts": {
     "build": "bun run build.ts",
+    "build:dts": "bun run build.ts --dts-only",
     "test": "bun test --timeout=10000",
-    "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
-    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && bun run --bun scripts/check-coverage.ts",
+    "test:coverage": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && COVERAGE_THRESHOLD=65 bun run --bun scripts/check-coverage.ts",
+    "test:ci": "bun test --timeout=10000 --coverage --coverage-reporter=lcov --coverage-dir coverage && COVERAGE_THRESHOLD=65 bun run --bun scripts/check-coverage.ts",
     "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck",
     "test:unit": "bun test tests/ --timeout=10000",
     "test:integration": "test $(find tests -name '*.integration.test.ts' 2>/dev/null | wc -l) -gt 0 && find tests -name '*.integration.test.ts' -print0 | xargs -0 bun test --timeout=10000 || echo 'No integration tests found'"
@@ -42,10 +43,11 @@
   "author": "Carl Lee <carllee0520@gmail.com>",
   "license": "MIT",
   "peerDependencies": {
-    "@gravito/core": "^1.6.1",
-    "@gravito/photon": "^1.0.1"
+    "@gravito/core": "^3.0.0",
+    "@gravito/photon": "^2.0.0"
   },
   "devDependencies": {
+    "@gravito/core": "workspace:*",
     "bun-types": "latest",
     "mitata": "^1.0.34",
     "tsup": "^8.5.1",

package/src/HMRWatcher.ts

@@ -141,7 +141,7 @@ export class HMRWatcher {
         enabled: false, // 強制停用
         watchDirs: [],
         debounce: 300,
-        extensions: ['.json'],
+        extensions: ['.json', '.json5'],
         verbose: false,
       }
       return
@@ -151,7 +151,7 @@ export class HMRWatcher {
       enabled: config.enabled,
       watchDirs: config.watchDirs,
       debounce: config.debounce ?? 300,
-      extensions: config.extensions ?? ['.json'],
+      extensions: config.extensions ?? ['.json', '.json5'],
       verbose: config.verbose ?? true,
     }
   }

package/src/I18nService.ts

@@ -7,6 +7,8 @@
 import type { GravitoMiddleware } from '@gravito/core'
 import { LRUCache } from 'lru-cache'
 import { type HMRConfig, HMRWatcher } from './HMRWatcher'
+import { CosmosError } from './errors/CosmosError'
+import { CosmosErrorCodes } from './errors/codes'
 import { loadLocale } from './loader'
 import type { TranslationLoader } from './loaders/TranslationLoader'
 
@@ -816,7 +818,9 @@ export class I18nManager<Schema = TranslationMap> implements I18nService<Schema>
       case 'empty':
         return ''
       case 'throw':
-        throw new Error(`Missing translation: ${key}`)
+        throw new CosmosError(500, CosmosErrorCodes.MISSING_TRANSLATION, {
+          message: `Missing translation: ${key}`,
+        })
       default:
         return key
     }

package/src/errors/CosmosError.ts

@@ -0,0 +1,20 @@
+import { SystemException, type ExceptionOptions } from '@gravito/core'
+import type { CosmosErrorCode } from './codes'
+
+/**
+ * Base error class for @gravito/cosmos i18n operations.
+ * Extends SystemException as cosmos is a general system utility (not a domain/auth module).
+ *
+ * @public
+ */
+export class CosmosError extends SystemException {
+  constructor(
+    status: number,
+    code: CosmosErrorCode,
+    options: ExceptionOptions = {}
+  ) {
+    super(status, code, options)
+    this.name = 'CosmosError'
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}

package/src/errors/codes.ts

@@ -0,0 +1,30 @@
+/**
+ * Structured error codes for @gravito/cosmos i18n operations.
+ * Follows the dot-separated namespace convention used across Gravito.
+ *
+ * @public
+ */
+export const CosmosErrorCodes = {
+  // Translation errors
+  MISSING_TRANSLATION: 'cosmos.missing_translation',
+
+  // Loader errors
+  LOADER_FAILED: 'cosmos.loader_failed',
+  UNSUPPORTED_FORMAT: 'cosmos.unsupported_format',
+
+  // Filesystem loader errors
+  FILE_NOT_FOUND: 'cosmos.file_not_found',
+  FILE_READ_FAILED: 'cosmos.file_read_failed',
+
+  // Remote loader errors
+  HTTP_ERROR: 'cosmos.http_error',
+
+  // Runtime errors
+  EDGE_RUNTIME_UNSUPPORTED: 'cosmos.edge_runtime_unsupported',
+
+  // KV storage errors
+  KV_PUT_UNSUPPORTED: 'cosmos.kv_put_unsupported',
+  KV_DELETE_UNSUPPORTED: 'cosmos.kv_delete_unsupported',
+} as const
+
+export type CosmosErrorCode = (typeof CosmosErrorCodes)[keyof typeof CosmosErrorCodes]

package/src/errors/index.ts

@@ -0,0 +1,2 @@
+export { CosmosError } from './CosmosError'
+export { CosmosErrorCodes, type CosmosErrorCode } from './codes'

package/src/index.ts

@@ -84,6 +84,7 @@ export * from './loaders/ChainedLoader'
 export * from './loaders/CloudflareKVLoader'
 export * from './loaders/EdgeKVLoader'
 export * from './loaders/FileSystemLoader'
+export * from './loaders/Json5Loader'
 export * from './loaders/MemoryLoader'
 export * from './loaders/RemoteLoader'
 // Loaders
@@ -93,3 +94,6 @@ export * from './loaders/VercelKVLoader'
 // Runtime utilities
 export * from './runtime/detector'
 export * from './runtime/path-utils'
+
+// Errors
+export * from './errors'

package/src/loader.ts

@@ -21,14 +21,59 @@
 
 import { readdir, readFile } from 'node:fs/promises'
 import { join, parse } from 'node:path'
+import { CosmosError } from './errors/CosmosError'
+import { CosmosErrorCodes } from './errors/codes'
+
+/**
+ * 偵測 Bun 運行時是否原生支援 JSON5 解析
+ *
+ * @returns 是否具備 Bun 原生 JSON5 能力
+ */
+function hasBunJson5(): boolean {
+  return (
+    typeof globalThis.Bun !== 'undefined' &&
+    typeof (globalThis.Bun as Record<string, unknown>).JSON5 === 'object'
+  )
+}
+
+/**
+ * 解析 JSON5 格式字串（降級到 json5 npm 套件）
+ *
+ * @param content - 要解析的 JSON5 字串
+ * @returns 解析結果
+ */
+async function parseJson5(content: string): Promise<unknown> {
+  if (hasBunJson5()) {
+    const bunJson5 = (globalThis.Bun as Record<string, unknown>).JSON5 as {
+      parse: (text: string) => unknown
+    }
+    return bunJson5.parse(content)
+  }
+
+  // 使用變數作為路徑以避免靜態型別解析（json5 為可選 peer dependency）
+  try {
+    const pkgName = 'json5'
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json5Module = await (import(pkgName) as Promise<any>)
+    const json5 = json5Module.default ?? json5Module
+    return (json5 as { parse: (text: string) => unknown }).parse(content)
+  } catch {
+    throw new CosmosError(500, CosmosErrorCodes.UNSUPPORTED_FORMAT, {
+      message:
+        '[Cosmos] JSON5 parsing requires either Bun v1.2+ or the `json5` npm package. ' +
+        'Please install it: bun add json5',
+    })
+  }
+}
 
 /**
  * 從目錄載入所有翻譯檔案
  *
- * 掃描指定目錄中的所有 JSON 檔案並載入為翻譯資源
+ * 掃描指定目錄中的所有 JSON 與 JSON5 檔案並載入為翻譯資源
+ * 若同一語言同時存在 `.json` 與 `.json5`，以 `.json5` 優先
  * 檔案名稱(不含副檔名)將作為語言代碼
  *
- * @deprecated 自 v3.1.0 起,建議使用 FileSystemLoader
+ * @deprecated 自 v3.1.0 起,建議使用 FileSystemLoader 或 Json5Loader
  * @param directory - 翻譯目錄的絕對路徑
  * @returns 語言代碼到翻譯資源的對應表
  * @public
@@ -37,7 +82,7 @@ import { join, parse } from 'node:path'
  * ```
  * /lang
  *   /en.json    -> { "welcome": "Hello" }
- *   /zh-TW.json -> { "welcome": "你好" }
+ *   /zh-TW.json5 -> { "welcome": "你好" }  // 支援 JSON5
  * ```
  */
 export async function loadTranslations(
@@ -48,13 +93,29 @@ export async function loadTranslations(
   try {
     const files = await readdir(directory)
 
+    // 收集所有支援格式的翻譯檔案，以 locale 為鍵，避免重複處理
+    const localeFiles = new Map<string, string>()
+
     for (const file of files) {
-      if (!file.endsWith('.json')) {
+      if (!file.endsWith('.json') && !file.endsWith('.json5')) {
         continue
       }
 
-      const locale = parse(file).name // 'en' from 'en.json'
-      const translationsForLocale = await loadLocale(directory, locale)
+      const locale = parse(file).name
+      const existing = localeFiles.get(locale)
+
+      // json5 優先：若同一 locale 已有 .json，json5 可覆蓋；反之不覆蓋
+      if (!existing || file.endsWith('.json5')) {
+        localeFiles.set(locale, file)
+      }
+    }
+
+    for (const [locale, file] of localeFiles) {
+      const translationsForLocale = await loadLocale(
+        directory,
+        locale,
+        parse(file).ext as '.json' | '.json5'
+      )
       if (translationsForLocale) {
         translations[locale] = translationsForLocale
       }
@@ -71,21 +132,26 @@ export async function loadTranslations(
 /**
  * 載入指定語言的翻譯資源
  *
- * 期望在指定目錄中找到 `{locale}.json` 格式的檔案
+ * 期望在指定目錄中找到 `{locale}.json` 或 `{locale}.json5` 格式的檔案
  *
- * @deprecated 自 v3.1.0 起,建議使用 FileSystemLoader
+ * @deprecated 自 v3.1.0 起,建議使用 FileSystemLoader 或 Json5Loader
  * @param directory - 包含翻譯檔案的目錄
  * @param locale - 要載入的語言代碼
+ * @param extension - 檔案副檔名，預設 `.json`，可傳入 `.json5`
  * @returns 翻譯資源,載入失敗則返回 null
  * @public
  */
 export async function loadLocale(
   directory: string,
-  locale: string
+  locale: string,
+  extension: '.json' | '.json5' = '.json'
 ): Promise<Record<string, string> | null> {
-  const filePath = join(directory, `${locale}.json`)
+  const filePath = join(directory, `${locale}${extension}`)
   try {
     const content = await readFile(filePath, 'utf-8')
+    if (extension === '.json5') {
+      return (await parseJson5(content)) as Record<string, string>
+    }
     return JSON.parse(content)
   } catch {
     return null

package/src/loaders/EdgeKVLoader.ts

@@ -5,6 +5,8 @@
  */
 
 import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
 import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
 
 /**
@@ -219,7 +221,9 @@ export class EdgeKVLoader implements TranslationLoaderChain {
    */
   async put(locale: string, translations: TranslationMap): Promise<void> {
     if (!this.storage.put) {
-      throw new Error('[EdgeKVLoader] Storage does not support put operation')
+      throw new CosmosError(500, CosmosErrorCodes.KV_PUT_UNSUPPORTED, {
+        message: '[EdgeKVLoader] Storage does not support put operation',
+      })
     }
 
     const key = this.buildKey(locale)
@@ -239,7 +243,9 @@ export class EdgeKVLoader implements TranslationLoaderChain {
    */
   async delete(locale: string): Promise<void> {
     if (!this.storage.delete) {
-      throw new Error('[EdgeKVLoader] Storage does not support delete operation')
+      throw new CosmosError(500, CosmosErrorCodes.KV_DELETE_UNSUPPORTED, {
+        message: '[EdgeKVLoader] Storage does not support delete operation',
+      })
     }
 
     const key = this.buildKey(locale)

package/src/loaders/FileSystemLoader.ts

@@ -1,7 +1,7 @@
 /**
  * @file packages/cosmos/src/loaders/FileSystemLoader.ts
  * @module @gravito/cosmos/loaders
- * @description 從檔案系統載入翻譯資源的實現
+ * @description 從檔案系統載入翻譯資源的實現，支援 JSON 與 JSON5 格式
  *
  * ⚠️ **Node.js Only**
  *
@@ -19,9 +19,25 @@
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
 import { detectRuntime } from '../runtime/detector'
 import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
 
+/**
+ * 偵測 Bun 運行時是否原生支援 JSON5 解析
+ *
+ * Bun v1.2+ 提供 `Bun.JSON5` 全域物件
+ *
+ * @returns 是否具備 Bun 原生 JSON5 能力
+ */
+function hasBunJson5(): boolean {
+  return (
+    typeof globalThis.Bun !== 'undefined' &&
+    typeof (globalThis.Bun as Record<string, unknown>).JSON5 === 'object'
+  )
+}
+
 /**
  * 檔案系統載入器配置
  *
@@ -39,6 +55,8 @@ export interface FileSystemLoaderConfig extends LoaderConfig {
   /**
    * 檔案副檔名
    *
+   * 支援 `.json` 與 `.json5` 兩種格式
+   *
    * @default '.json'
    */
   extension?: string
@@ -80,10 +98,11 @@ export class FileSystemLoader implements TranslationLoaderChain {
     // 運行時檢查
     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.'
-      )
+      throw new CosmosError(500, CosmosErrorCodes.EDGE_RUNTIME_UNSUPPORTED, {
+        message:
+          '[FileSystemLoader] This loader requires Node.js and cannot run in Edge Runtime. ' +
+          'Use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.',
+      })
     }
 
     this.name = config.name || 'FileSystemLoader'
@@ -94,6 +113,8 @@ export class FileSystemLoader implements TranslationLoaderChain {
   /**
    * 載入指定語言的翻譯資源
    *
+   * 根據 extension 自動判斷使用 JSON 或 JSON5 解析器
+   *
    * @param locale - 語言代碼
    * @returns 翻譯資源,載入失敗則返回 null
    */
@@ -101,7 +122,10 @@ export class FileSystemLoader implements TranslationLoaderChain {
     try {
       const filePath = join(this.baseDir, `${locale}${this.extension}`)
       const content = await readFile(filePath, 'utf-8')
-      const translations = JSON.parse(content) as TranslationMap
+      const translations =
+        this.extension === '.json5'
+          ? await this.parseJson5(content)
+          : (JSON.parse(content) as TranslationMap)
       return translations
     } catch (_error) {
       // 如果有備用載入器,嘗試使用備用載入器
@@ -112,6 +136,42 @@ export class FileSystemLoader implements TranslationLoaderChain {
     }
   }
 
+  /**
+   * 解析 JSON5 內容
+   *
+   * 優先使用 Bun 原生 JSON5 解析器（Bun v1.2+），
+   * 若不可用則嘗試動態載入 `json5` npm 套件作為降級方案
+   *
+   * @param content - 要解析的 JSON5 字串
+   * @returns 解析後的翻譯資源
+   * @throws {Error} 若 Bun 原生與 json5 套件均不可用時
+   */
+  private async parseJson5(content: string): Promise<TranslationMap> {
+    // 優先使用 Bun 原生 JSON5 解析器
+    if (hasBunJson5()) {
+      const bunJson5 = (globalThis.Bun as Record<string, unknown>).JSON5 as {
+        parse: (text: string) => unknown
+      }
+      return bunJson5.parse(content) as TranslationMap
+    }
+
+    // 降級方案：動態載入 json5 npm 套件
+    // 使用變數作為路徑以避免靜態型別解析（json5 為可選 peer dependency）
+    try {
+      const pkgName = 'json5'
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const json5Module = await (import(pkgName) as Promise<any>)
+      const json5 = json5Module.default ?? json5Module
+      return (json5 as { parse: (text: string) => unknown }).parse(content) as TranslationMap
+    } catch {
+      throw new CosmosError(500, CosmosErrorCodes.UNSUPPORTED_FORMAT, {
+        message:
+          '[FileSystemLoader] JSON5 parsing requires either Bun v1.2+ (native support) ' +
+          'or the `json5` npm package. Please install it: bun add json5',
+      })
+    }
+  }
+
   /**
    * 設定備用載入器
    *

package/src/loaders/Json5Loader.ts

@@ -0,0 +1,256 @@
+/**
+ * @file packages/cosmos/src/loaders/Json5Loader.ts
+ * @module @gravito/cosmos/loaders
+ * @description 支援 JSON5 格式翻譯檔案的混合載入器
+ *
+ * ⚠️ **Node.js Only**
+ *
+ * 此載入器依賴 Node.js 的 fs 模組，無法在 Edge Runtime 使用
+ *
+ * 支援混合載入 `.json5` 與 `.json` 格式的翻譯檔案，
+ * 可配置載入優先級以彈性應對不同場景
+ *
+ * @since 3.2.0
+ * @platform node
+ */
+
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
+import { detectRuntime } from '../runtime/detector'
+import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
+
+/**
+ * Json5Loader 優先級策略
+ *
+ * - `json5-first`: 優先嘗試 `.json5`，失敗後退到 `.json`
+ * - `json-first`: 優先嘗試 `.json`，失敗後退到 `.json5`
+ * - `json5-only`: 只載入 `.json5`，不降級
+ * - `json-only`: 只載入 `.json`，不降級
+ *
+ * @public
+ * @since 3.2.0
+ */
+export type Json5LoaderPriority = 'json5-first' | 'json-first' | 'json5-only' | 'json-only'
+
+/**
+ * Json5Loader 配置
+ *
+ * @public
+ * @since 3.2.0
+ */
+export interface Json5LoaderConfig extends LoaderConfig {
+  /**
+   * 翻譯檔案所在的基礎目錄
+   *
+   * @example '/app/lang'
+   */
+  baseDir: string
+
+  /**
+   * 載入優先級策略
+   *
+   * @default 'json5-first'
+   */
+  priority?: Json5LoaderPriority
+}
+
+/**
+ * 偵測 Bun 運行時是否原生支援 JSON5 解析
+ *
+ * Bun v1.2+ 提供 `Bun.JSON5` 全域物件
+ *
+ * @returns 是否具備 Bun 原生 JSON5 能力
+ */
+function hasBunJson5(): boolean {
+  return (
+    typeof globalThis.Bun !== 'undefined' &&
+    typeof (globalThis.Bun as Record<string, unknown>).JSON5 === 'object'
+  )
+}
+
+/**
+ * 解析 JSON5 格式字串
+ *
+ * 優先使用 Bun 原生 JSON5 解析器（Bun v1.2+），
+ * 降級至 `json5` npm 套件
+ *
+ * @param content - 要解析的 JSON5 字串
+ * @returns 解析結果
+ * @throws {Error} 若兩種方式均不可用
+ */
+async function parseJson5Content(content: string): Promise<unknown> {
+  if (hasBunJson5()) {
+    const bunJson5 = (globalThis.Bun as Record<string, unknown>).JSON5 as {
+      parse: (text: string) => unknown
+    }
+    return bunJson5.parse(content)
+  }
+
+  // 使用變數作為路徑以避免靜態型別解析（json5 為可選 peer dependency）
+  try {
+    const pkgName = 'json5'
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const json5Module = await (import(pkgName) as Promise<any>)
+    const json5 = json5Module.default ?? json5Module
+    return (json5 as { parse: (text: string) => unknown }).parse(content)
+  } catch {
+    throw new CosmosError(500, CosmosErrorCodes.UNSUPPORTED_FORMAT, {
+      message:
+        '[Json5Loader] JSON5 parsing requires either Bun v1.2+ (native support) ' +
+        'or the `json5` npm package. Please install it: bun add json5',
+    })
+  }
+}
+
+/**
+ * JSON5 混合翻譯載入器
+ *
+ * 支援混合載入 `.json5` 與 `.json` 格式的翻譯檔案。
+ * 透過優先級配置彈性控制載入策略，並支援 fallback 降級鏈。
+ *
+ * @public
+ * @since 3.2.0
+ *
+ * @example json5-first 優先（預設）
+ * ```typescript
+ * const loader = new Json5Loader({
+ *   baseDir: '/app/lang',
+ *   priority: 'json5-first'
+ * })
+ * // 嘗試 zh-TW.json5，若不存在則退回 zh-TW.json
+ * const translations = await loader.load('zh-TW')
+ * ```
+ *
+ * @example 搭配 fallback 鏈
+ * ```typescript
+ * const loader = new Json5Loader({ baseDir: '/app/lang' })
+ *   .fallback(new MemoryLoader({ en: { welcome: 'Hello' } }))
+ *
+ * const translations = await loader.load('en')
+ * ```
+ */
+export class Json5Loader implements TranslationLoaderChain {
+  public readonly name: string
+  private readonly baseDir: string
+  private readonly priority: Json5LoaderPriority
+  private fallbackLoader?: TranslationLoader
+
+  /**
+   * 建立 Json5Loader 實例
+   *
+   * @param config - 載入器配置
+   * @throws {Error} 如果在 Edge Runtime 環境中使用
+   */
+  constructor(config: Json5LoaderConfig) {
+    // 運行時檢查
+    const runtime = detectRuntime()
+    if (runtime === 'edge') {
+      throw new CosmosError(500, CosmosErrorCodes.EDGE_RUNTIME_UNSUPPORTED, {
+        message:
+          '[Json5Loader] This loader requires Node.js and cannot run in Edge Runtime. ' +
+          'Use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.',
+      })
+    }
+
+    this.name = config.name ?? 'Json5Loader'
+    this.baseDir = config.baseDir
+    this.priority = config.priority ?? 'json5-first'
+  }
+
+  /**
+   * 載入指定語言的翻譯資源
+   *
+   * 根據優先級策略嘗試不同副檔名的檔案
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源，所有嘗試均失敗則返回 null
+   */
+  async load(locale: string): Promise<TranslationMap | null> {
+    const result = await this.loadByPriority(locale)
+
+    if (result !== null) {
+      return result
+    }
+
+    // 嘗試外部 fallback 載入器
+    if (this.fallbackLoader) {
+      return this.fallbackLoader.load(locale)
+    }
+
+    return null
+  }
+
+  /**
+   * 設定備用載入器
+   *
+   * @param loader - 備用載入器
+   * @returns 當前實例，支援鏈式調用
+   */
+  fallback(loader: TranslationLoader): TranslationLoaderChain {
+    this.fallbackLoader = loader
+    return this
+  }
+
+  /**
+   * 取得當前優先級策略
+   *
+   * @returns 優先級策略字串
+   */
+  getPriority(): Json5LoaderPriority {
+    return this.priority
+  }
+
+  /**
+   * 根據優先級策略依序嘗試載入翻譯檔案
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源，或 null
+   */
+  private async loadByPriority(locale: string): Promise<TranslationMap | null> {
+    switch (this.priority) {
+      case 'json5-first':
+        return (await this.tryLoadJson5(locale)) ?? (await this.tryLoadJson(locale))
+      case 'json-first':
+        return (await this.tryLoadJson(locale)) ?? (await this.tryLoadJson5(locale))
+      case 'json5-only':
+        return this.tryLoadJson5(locale)
+      case 'json-only':
+        return this.tryLoadJson(locale)
+    }
+  }
+
+  /**
+   * 嘗試載入 `.json5` 格式的翻譯檔案
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源，或 null
+   */
+  private async tryLoadJson5(locale: string): Promise<TranslationMap | null> {
+    try {
+      const filePath = join(this.baseDir, `${locale}.json5`)
+      const content = await readFile(filePath, 'utf-8')
+      return (await parseJson5Content(content)) as TranslationMap
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * 嘗試載入 `.json` 格式的翻譯檔案
+   *
+   * @param locale - 語言代碼
+   * @returns 翻譯資源，或 null
+   */
+  private async tryLoadJson(locale: string): Promise<TranslationMap | null> {
+    try {
+      const filePath = join(this.baseDir, `${locale}.json`)
+      const content = await readFile(filePath, 'utf-8')
+      return JSON.parse(content) as TranslationMap
+    } catch {
+      return null
+    }
+  }
+}

package/src/loaders/RemoteLoader.ts

@@ -5,6 +5,8 @@
  */
 
 import type { TranslationMap } from '../I18nService'
+import { CosmosError } from '../errors/CosmosError'
+import { CosmosErrorCodes } from '../errors/codes'
 import type { LoaderConfig, TranslationLoader, TranslationLoaderChain } from './TranslationLoader'
 
 /**
@@ -124,16 +126,12 @@ export class RemoteLoader implements TranslationLoaderChain {
    * @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
-
+      } catch {
         // 如果不是最後一次嘗試,等待後重試
         if (attempt < this.retries) {
           const delay = this.retryDelay * 2 ** attempt
@@ -160,6 +158,7 @@ export class RemoteLoader implements TranslationLoaderChain {
     const url = this.url.replace(':locale', locale)
     const controller = new AbortController()
     const timeoutId = setTimeout(() => controller.abort(), this.timeout)
+    timeoutId.unref?.()
 
     try {
       const headers: Record<string, string> = { ...this.headers }
@@ -181,11 +180,17 @@ export class RemoteLoader implements TranslationLoaderChain {
         if (cached) {
           return cached
         }
+
+        // ETag 與本地翻譯快取脫鉤時，丟棄 stale ETag 後重新抓取完整內容。
+        this.etagMap.delete(locale)
+        return this.fetchWithTimeout(locale)
       }
 
       // 處理錯誤狀態碼
       if (!response.ok) {
-        throw new Error(`HTTP error! status: ${response.status}`)
+        throw new CosmosError(response.status, CosmosErrorCodes.HTTP_ERROR, {
+          message: `HTTP error! status: ${response.status}`,
+        })
       }
 
       const data = (await response.json()) as TranslationMap

package/tests/contract/cosmos-errors.contract.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'bun:test'
+import { GravitoException, SystemException } from '@gravito/core'
+import { CosmosError } from '../../src/errors/CosmosError'
+import { CosmosErrorCodes } from '../../src/errors/codes'
+
+describe('CosmosError contract', () => {
+  it('satisfies GravitoException contract', () => {
+    const err = new CosmosError(500, CosmosErrorCodes.MISSING_TRANSLATION, {
+      message: 'Missing translation: common.welcome',
+    })
+
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(GravitoException)
+    expect(err).toBeInstanceOf(SystemException)
+    expect(err).toBeInstanceOf(CosmosError)
+
+    expect(err.code).toBe('cosmos.missing_translation')
+    expect(err.status).toBe(500)
+    expect(typeof err.code).toBe('string')
+    expect(typeof err.status).toBe('number')
+    expect(err.name).toBe('CosmosError')
+    expect(err.name).not.toBe('Error')
+  })
+
+  it('extends SystemException (not DomainException or AuthException)', () => {
+    const err = new CosmosError(500, CosmosErrorCodes.LOADER_FAILED)
+    expect(err).toBeInstanceOf(SystemException)
+  })
+
+  it('preserves message', () => {
+    const err = new CosmosError(500, CosmosErrorCodes.MISSING_TRANSLATION, {
+      message: 'Missing translation: test.key',
+    })
+    expect(err.message).toBe('Missing translation: test.key')
+  })
+
+  it('preserves cause', () => {
+    const cause = new Error('original error')
+    const err = new CosmosError(500, CosmosErrorCodes.LOADER_FAILED, { cause })
+    expect(err.cause).toBe(cause)
+  })
+
+  it('instanceof chain holds for all error codes', () => {
+    const codes = Object.values(CosmosErrorCodes)
+    for (const code of codes) {
+      const err = new CosmosError(500, code)
+      expect(err).toBeInstanceOf(CosmosError)
+      expect(err).toBeInstanceOf(SystemException)
+      expect(err).toBeInstanceOf(GravitoException)
+      expect(err).toBeInstanceOf(Error)
+      expect(err.code).toBe(code)
+    }
+  })
+
+  it('all error codes are cosmos.* namespaced', () => {
+    const codes = Object.values(CosmosErrorCodes)
+    for (const code of codes) {
+      expect(code).toMatch(/^cosmos\./)
+    }
+  })
+
+  it('CosmosErrorCodes covers expected domains', () => {
+    expect(CosmosErrorCodes.MISSING_TRANSLATION).toBe('cosmos.missing_translation')
+    expect(CosmosErrorCodes.LOADER_FAILED).toBe('cosmos.loader_failed')
+    expect(CosmosErrorCodes.UNSUPPORTED_FORMAT).toBe('cosmos.unsupported_format')
+    expect(CosmosErrorCodes.FILE_NOT_FOUND).toBe('cosmos.file_not_found')
+    expect(CosmosErrorCodes.FILE_READ_FAILED).toBe('cosmos.file_read_failed')
+    expect(CosmosErrorCodes.HTTP_ERROR).toBe('cosmos.http_error')
+    expect(CosmosErrorCodes.EDGE_RUNTIME_UNSUPPORTED).toBe('cosmos.edge_runtime_unsupported')
+    expect(CosmosErrorCodes.KV_PUT_UNSUPPORTED).toBe('cosmos.kv_put_unsupported')
+    expect(CosmosErrorCodes.KV_DELETE_UNSUPPORTED).toBe('cosmos.kv_delete_unsupported')
+  })
+})

package/tests/unit/loaders.test.ts

@@ -159,6 +159,52 @@ describe('TranslationLoaders', () => {
       expect(callCount).toBe(2)
     })
 
+    it('should refetch when server returns 304 but translation cache is missing', async () => {
+      let callCount = 0
+      globalThis.fetch = mock((_url: string, options?: any) => {
+        callCount++
+        const ifNoneMatch = options?.headers?.['If-None-Match']
+
+        if (!ifNoneMatch && callCount === 1) {
+          return Promise.resolve({
+            ok: true,
+            status: 200,
+            headers: new Map([['ETag', '"v1"']]),
+            json: async () => ({ version: '1.0' }),
+          })
+        }
+
+        if (callCount === 2) {
+          return Promise.resolve({
+            ok: true,
+            status: 304,
+            headers: new Map([['ETag', '"v1"']]),
+          })
+        }
+
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Map([['ETag', '"v2"']]),
+          json: async () => ({ version: '2.0' }),
+        })
+      }) as any
+
+      const loader = new RemoteLoader({
+        url: 'https://api.example.com/i18n/:locale',
+        etagCache: true,
+      })
+
+      const translations1 = await loader.load('en')
+      expect(translations1?.version).toBe('1.0')
+
+      ;(loader as any).translationCache.clear()
+
+      const translations2 = await loader.load('en')
+      expect(translations2?.version).toBe('2.0')
+      expect(callCount).toBe(3)
+    })
+
     it('should retry on failure', async () => {
       let attemptCount = 0
       globalThis.fetch = mock(() => {
@@ -213,6 +259,39 @@ describe('TranslationLoaders', () => {
       expect(receivedHeaders['X-Custom']).toBe('value')
     })
 
+    it('should unref request timeout timers', async () => {
+      const originalSetTimeout = global.setTimeout
+      const handle = {
+        unrefCalled: false,
+        unref() {
+          this.unrefCalled = true
+        },
+      }
+
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Map(),
+          json: async () => ({}),
+        })
+      ) as any
+
+      global.setTimeout = ((_fn: () => void) => handle as any) as unknown as typeof setTimeout
+
+      try {
+        const loader = new RemoteLoader({
+          url: 'https://api.example.com/i18n/:locale',
+          timeout: 100,
+        })
+        await loader.load('en')
+
+        expect(handle.unrefCalled).toBe(true)
+      } finally {
+        global.setTimeout = originalSetTimeout
+      }
+    })
+
     it('should support fallback loader when all retries fail', async () => {
       globalThis.fetch = mock(() => Promise.reject(new Error('Network error'))) as any
 

package/tsconfig.build.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": false,
+    "emitDeclarationOnly": true,
+    "declaration": true,
+    "declarationMap": false,
+    "outDir": "./dist",
+    "rootDir": "src",
+    "skipLibCheck": true,
+    "baseUrl": ".",
+    "jsx": "react-jsx",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "types": ["bun-types"],
+    "paths": {
+      "@gravito/cosmos": ["./src/index.ts"],
+      "@gravito/core": ["../../packages/core/dist/index.d.ts"],
+      "@gravito/core/*": ["../../packages/core/dist/*"],
+      "@gravito/*": ["../../packages/*/dist/index.d.ts"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "exclude": ["node_modules", "dist", "tests", "**/*.test.ts", "**/*.test.tsx"]
+}

package/tsconfig.json

@@ -2,11 +2,6 @@
   "extends": "../../tsconfig.json",
   "compilerOptions": {
     "outDir": "./dist",
-    "baseUrl": ".",
-    "paths": {
-      "@gravito/core": ["../../packages/core/src/index.ts"],
-      "@gravito/*": ["../../packages/*/src/index.ts"]
-    },
     "types": ["bun-types"]
   },
   "include": ["src/**/*"],