@gravito/cosmos 3.1.0 → 3.2.1

package/tests/unit/hmr.test.ts

@@ -0,0 +1,255 @@
+/**
+ * @file packages/cosmos/tests/unit/hmr.test.ts
+ * @description 測試 HMR (熱重載) 功能
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { HMRWatcher } from '../../src/HMRWatcher'
+
+describe('HMRWatcher', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), 'gravito-hmr-test-'))
+  })
+
+  afterEach(async () => {
+    await rm(tmpDir, { force: true, recursive: true })
+  })
+
+  it('should detect file changes', async () => {
+    const filePath = join(tmpDir, 'zh-TW.json')
+    writeFileSync(filePath, JSON.stringify({ test: 'initial' }))
+
+    const changeEvents: Array<{ locale: string; type: string }> = []
+
+    const watcher = new HMRWatcher({
+      enabled: true,
+      watchDirs: [tmpDir],
+      debounce: 100,
+      verbose: false,
+    })
+
+    watcher.onChange((event) => {
+      changeEvents.push({
+        locale: event.locale,
+        type: event.type,
+      })
+    })
+
+    watcher.start()
+
+    // 等待監視器啟動
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    // 修改檔案
+    await writeFile(filePath, JSON.stringify({ test: 'updated' }))
+
+    // 等待防抖和事件處理
+    await new Promise((resolve) => setTimeout(resolve, 500))
+
+    watcher.stop()
+
+    expect(changeEvents.length).toBeGreaterThan(0)
+    expect(changeEvents[0].locale).toBe('zh-TW')
+  })
+
+  it('should not watch when disabled', async () => {
+    const watcher = new HMRWatcher({
+      enabled: false,
+      watchDirs: [tmpDir],
+    })
+
+    watcher.start()
+    expect(watcher.isActive()).toBe(false)
+  })
+
+  it('should filter by file extension', async () => {
+    const jsonFile = join(tmpDir, 'en.json')
+    const txtFile = join(tmpDir, 'en.txt')
+
+    writeFileSync(jsonFile, '{}')
+    writeFileSync(txtFile, 'text')
+
+    const changeEvents: string[] = []
+
+    const watcher = new HMRWatcher({
+      enabled: true,
+      watchDirs: [tmpDir],
+      extensions: ['.json'],
+      debounce: 100,
+      verbose: false,
+    })
+
+    watcher.onChange((event) => {
+      changeEvents.push(event.filePath)
+    })
+
+    watcher.start()
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    // 修改 JSON 檔案 (應該被檢測到)
+    await writeFile(jsonFile, '{"updated": true}')
+    await new Promise((resolve) => setTimeout(resolve, 300))
+
+    // 修改 TXT 檔案 (應該被忽略)
+    await writeFile(txtFile, 'updated text')
+    await new Promise((resolve) => setTimeout(resolve, 300))
+
+    watcher.stop()
+
+    // 只有 JSON 檔案的變更應該被檢測到
+    expect(changeEvents.some((path) => path.includes('.json'))).toBe(true)
+    expect(changeEvents.some((path) => path.includes('.txt'))).toBe(false)
+  })
+
+  it('should support multiple listeners', async () => {
+    const filePath = join(tmpDir, 'test.json')
+    writeFileSync(filePath, '{}')
+
+    let listener1Called = false
+    let listener2Called = false
+
+    const watcher = new HMRWatcher({
+      enabled: true,
+      watchDirs: [tmpDir],
+      debounce: 100,
+      verbose: false,
+    })
+
+    watcher.onChange(() => {
+      listener1Called = true
+    })
+
+    watcher.onChange(() => {
+      listener2Called = true
+    })
+
+    watcher.start()
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    await writeFile(filePath, '{"updated": true}')
+    await new Promise((resolve) => setTimeout(resolve, 300))
+
+    watcher.stop()
+
+    expect(listener1Called).toBe(true)
+    expect(listener2Called).toBe(true)
+  })
+
+  it('should allow removing listeners', async () => {
+    const filePath = join(tmpDir, 'test.json')
+    writeFileSync(filePath, '{}')
+
+    let callCount = 0
+    const listener = () => {
+      callCount++
+    }
+
+    const watcher = new HMRWatcher({
+      enabled: true,
+      watchDirs: [tmpDir],
+      debounce: 100,
+      verbose: false,
+    })
+
+    watcher.onChange(listener)
+    watcher.start()
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    // 第一次變更
+    await writeFile(filePath, '{"v": 1}')
+    await new Promise((resolve) => setTimeout(resolve, 300))
+
+    const initialCallCount = callCount
+    expect(initialCallCount).toBeGreaterThan(0)
+
+    // 移除監聽器
+    watcher.removeListener(listener)
+
+    // 第二次變更 (不應該觸發)
+    await writeFile(filePath, '{"v": 2}')
+    await new Promise((resolve) => setTimeout(resolve, 300))
+
+    watcher.stop()
+
+    // 移除後,callCount 應該不再增加
+    expect(callCount).toBe(initialCallCount)
+  })
+
+  it('should debounce rapid changes', async () => {
+    const filePath = join(tmpDir, 'rapid.json')
+    writeFileSync(filePath, '{}')
+
+    let callCount = 0
+
+    const watcher = new HMRWatcher({
+      enabled: true,
+      watchDirs: [tmpDir],
+      debounce: 200,
+      verbose: false,
+    })
+
+    watcher.onChange(() => {
+      callCount++
+    })
+
+    watcher.start()
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    // 快速連續修改多次
+    await writeFile(filePath, '{"v": 1}')
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    await writeFile(filePath, '{"v": 2}')
+    await new Promise((resolve) => setTimeout(resolve, 50))
+    await writeFile(filePath, '{"v": 3}')
+
+    // 等待防抖完成
+    await new Promise((resolve) => setTimeout(resolve, 400))
+
+    watcher.stop()
+
+    // 由於防抖,應該只觸發一次或少數幾次,而不是每次修改都觸發
+    expect(callCount).toBeLessThan(3)
+  })
+
+  it('should handle errors in listeners gracefully', async () => {
+    const filePath = join(tmpDir, 'error-test.json')
+    writeFileSync(filePath, '{}')
+
+    const errorListener = () => {
+      throw new Error('Listener error')
+    }
+
+    let goodListenerCalled = false
+    const goodListener = () => {
+      goodListenerCalled = true
+    }
+
+    const watcher = new HMRWatcher({
+      enabled: true,
+      watchDirs: [tmpDir],
+      debounce: 100,
+      verbose: false,
+    })
+
+    // 註冊會拋出錯誤的監聽器和正常的監聽器
+    watcher.onChange(errorListener)
+    watcher.onChange(goodListener)
+
+    watcher.start()
+    await new Promise((resolve) => setTimeout(resolve, 100))
+
+    await writeFile(filePath, '{"updated": true}')
+    await new Promise((resolve) => setTimeout(resolve, 300))
+
+    watcher.stop()
+
+    // 即使有監聽器出錯,其他監聽器仍應該被呼叫
+    expect(goodListenerCalled).toBe(true)
+  })
+})

package/tests/unit/loader.test.ts

@@ -1,44 +1,72 @@
-import { describe, expect, it, jest } from 'bun:test'
+import { describe, expect, it, mock, spyOn } from 'bun:test'
 import { mkdtempSync, writeFileSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { loadTranslations } from '../../src/loader'
+import { I18nManager } from '../../src/I18nService'
+import * as loader from '../../src/loader'
 
-describe('loadTranslations', () => {
-  it('loads json translation files from a directory', async () => {
-    const tmpDir = mkdtempSync(join(tmpdir(), 'gravito-i18n-'))
+describe('I18n Loading', () => {
+  describe('Loading Coalescing', () => {
+    it('should coalesce concurrent load requests', async () => {
+      const mockLoader = mock(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 50))
+        return { title: 'Loaded' }
+      })
 
-    try {
-      writeFileSync(join(tmpDir, 'en.json'), JSON.stringify({ hello: 'Hello' }))
-      writeFileSync(join(tmpDir, 'zh.json'), JSON.stringify({ hello: '你好' }))
+      const manager = new I18nManager({
+        defaultLocale: 'en',
+        supportedLocales: ['en'],
+        lazyLoad: {
+          baseDir: '/tmp',
+          loader: mockLoader,
+        },
+      })
 
-      const translations = await loadTranslations(tmpDir)
+      const p1 = manager.ensureLocale('en')
+      const p2 = manager.ensureLocale('en')
 
-      expect(translations.en.hello).toBe('Hello')
-      expect(translations.zh.hello).toBe('你好')
-    } finally {
-      await rm(tmpDir, { force: true, recursive: true })
-    }
+      await Promise.all([p1, p2])
+
+      expect(mockLoader).toHaveBeenCalledTimes(1)
+    })
   })
 
-  it('skips invalid json files and returns empty for missing dir', async () => {
-    const tmpDir = mkdtempSync(join(tmpdir(), 'gravito-i18n-invalid-'))
+  describe('loadTranslations', () => {
+    it('loads json translation files from a directory', async () => {
+      const tmpDir = mkdtempSync(join(tmpdir(), 'gravito-i18n-'))
+
+      try {
+        writeFileSync(join(tmpDir, 'en.json'), JSON.stringify({ hello: 'Hello' }))
+        writeFileSync(join(tmpDir, 'zh.json'), JSON.stringify({ hello: '你好' }))
+
+        const translations = await loader.loadTranslations(tmpDir)
+
+        expect(translations.en.hello).toBe('Hello')
+        expect(translations.zh.hello).toBe('你好')
+      } finally {
+        await rm(tmpDir, { force: true, recursive: true })
+      }
+    })
+
+    it('skips invalid json files and returns empty for missing dir', async () => {
+      const tmpDir = mkdtempSync(join(tmpdir(), 'gravito-i18n-invalid-'))
 
-    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
-    const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {})
+      const errorSpy = spyOn(console, 'error').mockImplementation(() => {})
+      const warnSpy = spyOn(console, 'warn').mockImplementation(() => {})
 
-    try {
-      writeFileSync(join(tmpDir, 'en.json'), '{invalid json}')
-      const translations = await loadTranslations(tmpDir)
-      expect(translations.en).toBeUndefined()
+      try {
+        writeFileSync(join(tmpDir, 'en.json'), '{invalid json}')
+        const translations = await loader.loadTranslations(tmpDir)
+        expect(translations.en).toBeUndefined()
 
-      const missing = await loadTranslations(join(tmpDir, 'missing'))
-      expect(missing).toEqual({})
-    } finally {
-      errorSpy.mockRestore()
-      warnSpy.mockRestore()
-      await rm(tmpDir, { force: true, recursive: true })
-    }
+        const missing = await loader.loadTranslations(join(tmpDir, 'missing'))
+        expect(missing).toEqual({})
+      } finally {
+        errorSpy.mockRestore()
+        warnSpy.mockRestore()
+        await rm(tmpDir, { force: true, recursive: true })
+      }
+    })
   })
 })

package/tests/unit/loaders.test.ts

@@ -0,0 +1,332 @@
+/**
+ * @file packages/cosmos/tests/unit/loaders.test.ts
+ * @description 測試新的 TranslationLoader 實現
+ */
+
+import { afterEach, beforeEach, describe, expect, it, mock } from 'bun:test'
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { TranslationMap } from '../../src/I18nService'
+import { ChainedLoader } from '../../src/loaders/ChainedLoader'
+import { FileSystemLoader } from '../../src/loaders/FileSystemLoader'
+import { RemoteLoader } from '../../src/loaders/RemoteLoader'
+
+describe('TranslationLoaders', () => {
+  describe('FileSystemLoader', () => {
+    let tmpDir: string
+
+    beforeEach(() => {
+      tmpDir = mkdtempSync(join(tmpdir(), 'gravito-cosmos-test-'))
+    })
+
+    afterEach(async () => {
+      await rm(tmpDir, { force: true, recursive: true })
+    })
+
+    it('should load translation from filesystem', async () => {
+      writeFileSync(
+        join(tmpDir, 'zh-TW.json'),
+        JSON.stringify({ welcome: '歡迎', auth: { login: '登入' } })
+      )
+
+      const loader = new FileSystemLoader({ baseDir: tmpDir })
+      const translations = await loader.load('zh-TW')
+
+      expect(translations).not.toBeNull()
+      expect(translations?.welcome).toBe('歡迎')
+      expect((translations?.auth as TranslationMap)?.login).toBe('登入')
+    })
+
+    it('should return null for missing locale', async () => {
+      const loader = new FileSystemLoader({ baseDir: tmpDir })
+      const translations = await loader.load('non-existent')
+
+      expect(translations).toBeNull()
+    })
+
+    it('should support custom extension', async () => {
+      writeFileSync(join(tmpDir, 'en.txt'), JSON.stringify({ hello: 'Hello' }))
+
+      const loader = new FileSystemLoader({
+        baseDir: tmpDir,
+        extension: '.txt',
+      })
+      const translations = await loader.load('en')
+
+      expect(translations).not.toBeNull()
+      expect(translations?.hello).toBe('Hello')
+    })
+
+    it('should support fallback loader', async () => {
+      const fallbackLoader = {
+        name: 'FallbackLoader',
+        load: async () => ({ fallback: 'Fallback Value' }),
+      }
+
+      const loader = new FileSystemLoader({ baseDir: tmpDir }).fallback(fallbackLoader)
+      const translations = await loader.load('missing')
+
+      expect(translations).not.toBeNull()
+      expect(translations?.fallback).toBe('Fallback Value')
+    })
+  })
+
+  describe('RemoteLoader', () => {
+    it('should load translation from remote API', async () => {
+      // Mock fetch
+      const mockFetch = mock((url: string) => {
+        if (url.includes('zh-TW')) {
+          return Promise.resolve({
+            ok: true,
+            status: 200,
+            headers: new Map([['ETag', '"abc123"']]),
+            json: async () => ({ remote: '遠端翻譯' }),
+          })
+        }
+        return Promise.resolve({
+          ok: false,
+          status: 404,
+        })
+      })
+
+      globalThis.fetch = mockFetch as any
+
+      const loader = new RemoteLoader({
+        url: 'https://api.example.com/i18n/:locale',
+      })
+      const translations = await loader.load('zh-TW')
+
+      expect(translations).not.toBeNull()
+      expect(translations?.remote).toBe('遠端翻譯')
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+    })
+
+    it('should return null on HTTP error', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: false,
+          status: 500,
+        })
+      ) as any
+
+      const loader = new RemoteLoader({
+        url: 'https://api.example.com/i18n/:locale',
+        retries: 0, // 不重試以加快測試
+      })
+      const translations = await loader.load('en')
+
+      expect(translations).toBeNull()
+    })
+
+    it('should support ETag caching', async () => {
+      let callCount = 0
+      globalThis.fetch = mock((_url: string, options?: any) => {
+        callCount++
+        const ifNoneMatch = options?.headers?.['If-None-Match']
+
+        // 第一次請求
+        if (!ifNoneMatch) {
+          return Promise.resolve({
+            ok: true,
+            status: 200,
+            headers: new Map([['ETag', '"v1"']]),
+            json: async () => ({ version: '1.0' }),
+          })
+        }
+
+        // 第二次請求帶 ETag,返回 304
+        return Promise.resolve({
+          ok: true,
+          status: 304,
+          headers: new Map([['ETag', '"v1"']]),
+        })
+      }) 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')
+
+      // 第二次載入 (應該使用快取)
+      const translations2 = await loader.load('en')
+      expect(translations2?.version).toBe('1.0')
+      expect(callCount).toBe(2)
+    })
+
+    it('should retry on failure', async () => {
+      let attemptCount = 0
+      globalThis.fetch = mock(() => {
+        attemptCount++
+        // 前兩次失敗,第三次成功
+        if (attemptCount < 3) {
+          return Promise.reject(new Error('Network error'))
+        }
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Map(),
+          json: async () => ({ retry: 'success' }),
+        })
+      }) as any
+
+      const loader = new RemoteLoader({
+        url: 'https://api.example.com/i18n/:locale',
+        retries: 3,
+        retryDelay: 10, // 短延遲以加快測試
+      })
+      const translations = await loader.load('en')
+
+      expect(translations).not.toBeNull()
+      expect(translations?.retry).toBe('success')
+      expect(attemptCount).toBe(3)
+    })
+
+    it('should support custom headers', async () => {
+      let receivedHeaders: Record<string, string> = {}
+
+      globalThis.fetch = mock((_url: string, options?: any) => {
+        receivedHeaders = options?.headers || {}
+        return Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Map(),
+          json: async () => ({}),
+        })
+      }) as any
+
+      const loader = new RemoteLoader({
+        url: 'https://api.example.com/i18n/:locale',
+        headers: {
+          Authorization: 'Bearer token123',
+          'X-Custom': 'value',
+        },
+      })
+      await loader.load('en')
+
+      expect(receivedHeaders.Authorization).toBe('Bearer token123')
+      expect(receivedHeaders['X-Custom']).toBe('value')
+    })
+
+    it('should support fallback loader when all retries fail', async () => {
+      globalThis.fetch = mock(() => Promise.reject(new Error('Network error'))) as any
+
+      const fallbackLoader = {
+        name: 'FallbackLoader',
+        load: async () => ({ fallback: 'value' }),
+      }
+
+      const loader = new RemoteLoader({
+        url: 'https://api.example.com/i18n/:locale',
+        retries: 0,
+      }).fallback(fallbackLoader)
+
+      const translations = await loader.load('en')
+      expect(translations).not.toBeNull()
+      expect(translations?.fallback).toBe('value')
+    })
+
+    it('should clear ETag and translation cache', async () => {
+      globalThis.fetch = mock(() =>
+        Promise.resolve({
+          ok: true,
+          status: 200,
+          headers: new Map([['ETag', '"test"']]),
+          json: async () => ({ cached: true }),
+        })
+      ) as any
+
+      const loader = new RemoteLoader({
+        url: 'https://api.example.com/i18n/:locale',
+        etagCache: true,
+      })
+
+      await loader.load('en')
+      loader.clearCache()
+
+      // clearCache 被呼叫後，內部快取應該已清除
+      // 這主要是為了覆蓋 clearCache 方法
+      expect(loader.name).toBe('RemoteLoader')
+    })
+  })
+
+  describe('ChainedLoader', () => {
+    it('should try loaders in sequence', async () => {
+      const loader1 = {
+        name: 'Loader1',
+        load: async () => null, // 失敗
+      }
+
+      const loader2 = {
+        name: 'Loader2',
+        load: async () => ({ source: 'loader2' }), // 成功
+      }
+
+      const loader3 = {
+        name: 'Loader3',
+        load: async () => ({ source: 'loader3' }), // 不應該被呼叫
+      }
+
+      const chained = new ChainedLoader([loader1, loader2, loader3])
+      const translations = await chained.load('en')
+
+      expect(translations).not.toBeNull()
+      expect(translations?.source).toBe('loader2')
+    })
+
+    it('should return null if all loaders fail', async () => {
+      const loader1 = {
+        name: 'Loader1',
+        load: async () => null,
+      }
+
+      const loader2 = {
+        name: 'Loader2',
+        load: async () => null,
+      }
+
+      const chained = new ChainedLoader([loader1, loader2])
+      const translations = await chained.load('en')
+
+      expect(translations).toBeNull()
+    })
+
+    it('should support append and prepend', async () => {
+      const loader1 = { name: 'L1', load: async () => ({ order: '1' }) }
+      const loader2 = { name: 'L2', load: async () => null }
+      const loader3 = { name: 'L3', load: async () => null }
+
+      const chained = new ChainedLoader([loader2])
+      chained.prepend(loader3) // [loader3, loader2]
+      chained.append(loader1) // [loader3, loader2, loader1]
+
+      const loaders = chained.getLoaders()
+      expect(loaders[0].name).toBe('L3')
+      expect(loaders[1].name).toBe('L2')
+      expect(loaders[2].name).toBe('L1')
+    })
+
+    it('should support fallback loader', async () => {
+      const mainLoader = {
+        name: 'MainLoader',
+        load: async () => null,
+      }
+
+      const fallbackLoader = {
+        name: 'FallbackLoader',
+        load: async () => ({ fallback: 'used' }),
+      }
+
+      const chained = new ChainedLoader([mainLoader]).fallback(fallbackLoader)
+      const translations = await chained.load('en')
+
+      expect(translations).not.toBeNull()
+      expect(translations?.fallback).toBe('used')
+    })
+  })
+})