@gravito/cosmos 3.1.0 → 3.2.0

package/src/runtime/detector.ts

@@ -0,0 +1,97 @@
+/**
+ * @file packages/cosmos/src/runtime/detector.ts
+ * @module @gravito/cosmos/runtime
+ * @description 運行環境檢測工具
+ */
+
+/**
+ * 運行環境類型
+ *
+ * @public
+ * @since 3.2.0
+ */
+export type RuntimeEnvironment = 'node' | 'edge' | 'unknown'
+
+/**
+ * 檢測當前運行環境
+ *
+ * 支援的環境:
+ * - Node.js (包含 Bun)
+ * - Cloudflare Workers
+ * - Vercel Edge Functions
+ * - Deno Deploy
+ * - 其他 Edge Runtime
+ *
+ * @returns 當前運行環境類型
+ * @public
+ * @since 3.2.0
+ *
+ * @example
+ * ```typescript
+ * import { detectRuntime } from '@gravito/cosmos/runtime'
+ *
+ * const runtime = detectRuntime()
+ * if (runtime === 'node') {
+ *   // 使用 Node.js 特定功能
+ * } else if (runtime === 'edge') {
+ *   // 使用 Edge Runtime 功能
+ * }
+ * ```
+ */
+export function detectRuntime(): RuntimeEnvironment {
+  // Cloudflare Workers
+  // 檢查 Cloudflare Workers 特有的全域物件
+  if (
+    typeof globalThis.caches !== 'undefined' &&
+    typeof (globalThis as any).WebSocketPair !== 'undefined'
+  ) {
+    return 'edge'
+  }
+
+  // Vercel Edge Functions
+  // 檢查 Vercel Edge Runtime 特有的全域變數
+  if (typeof (globalThis as any).EdgeRuntime !== 'undefined') {
+    return 'edge'
+  }
+
+  // Deno Deploy
+  // 檢查 Deno 特有的全域物件
+  if (typeof (globalThis as any).Deno !== 'undefined') {
+    return 'edge'
+  }
+
+  // Node.js (包含 Bun)
+  // 檢查 process 物件和 Node.js 版本
+  if (typeof process !== 'undefined' && process.versions?.node !== undefined) {
+    return 'node'
+  }
+
+  // Bun (當 process.versions.node 不存在時)
+  if (typeof process !== 'undefined' && (process.versions as any)?.bun !== undefined) {
+    return 'node' // Bun 相容 Node.js API
+  }
+
+  return 'unknown'
+}
+
+/**
+ * 檢查是否在 Node.js 環境
+ *
+ * @returns 是否為 Node.js 環境
+ * @public
+ * @since 3.2.0
+ */
+export function isNode(): boolean {
+  return detectRuntime() === 'node'
+}
+
+/**
+ * 檢查是否在 Edge Runtime 環境
+ *
+ * @returns 是否為 Edge Runtime 環境
+ * @public
+ * @since 3.2.0
+ */
+export function isEdge(): boolean {
+  return detectRuntime() === 'edge'
+}

package/src/runtime/path-utils.ts

@@ -0,0 +1,169 @@
+/**
+ * @file packages/cosmos/src/runtime/path-utils.ts
+ * @module @gravito/cosmos/runtime
+ * @description Edge-compatible path 工具函數
+ *
+ * 提供與 Node.js path 模組相似的功能,但不依賴 Node.js API
+ * 適用於 Edge Runtime 環境
+ */
+
+/**
+ * Edge-compatible path 工具集
+ *
+ * @public
+ * @since 3.2.0
+ */
+export const pathUtils = {
+  /**
+   * 將多個路徑片段連接成一個路徑
+   *
+   * @param parts - 路徑片段
+   * @returns 連接後的路徑
+   *
+   * @example
+   * ```typescript
+   * pathUtils.join('foo', 'bar', 'baz.txt') // 'foo/bar/baz.txt'
+   * pathUtils.join('/foo', '/bar/') // '/foo/bar'
+   * pathUtils.join('', 'foo', '', 'bar') // 'foo/bar'
+   * ```
+   */
+  join(...parts: string[]): string {
+    return parts
+      .filter(Boolean) // 移除空字串
+      .join('/')
+      .replace(/\/+/g, '/') // 將多個斜線替換為單個斜線
+      .replace(/\/$/, '') // 移除尾部斜線
+      .replace(/^\/+/, '/') // 確保開頭只有一個斜線(如果有的話)
+  },
+
+  /**
+   * 返回路徑的最後一部分
+   *
+   * @param path - 路徑
+   * @param ext - 要移除的副檔名(可選)
+   * @returns 路徑的基本名稱
+   *
+   * @example
+   * ```typescript
+   * pathUtils.basename('/foo/bar/baz.txt') // 'baz.txt'
+   * pathUtils.basename('/foo/bar/baz.txt', '.txt') // 'baz'
+   * pathUtils.basename('/foo/bar/') // 'bar'
+   * ```
+   */
+  basename(path: string, ext?: string): string {
+    // 移除尾部斜線
+    const normalized = path.replace(/\/$/, '')
+    // 取得最後一個片段
+    const base = normalized.split('/').pop() || ''
+
+    if (ext && base.endsWith(ext)) {
+      return base.slice(0, -ext.length)
+    }
+    return base
+  },
+
+  /**
+   * 返回路徑的目錄部分
+   *
+   * @param path - 路徑
+   * @returns 目錄路徑
+   *
+   * @example
+   * ```typescript
+   * pathUtils.dirname('/foo/bar/baz.txt') // '/foo/bar'
+   * pathUtils.dirname('/foo') // '/'
+   * pathUtils.dirname('foo/bar') // 'foo'
+   * ```
+   */
+  dirname(path: string): string {
+    const parts = path.split('/')
+    parts.pop() // 移除最後一個片段
+    const result = parts.join('/')
+    return result || (path.startsWith('/') ? '/' : '.')
+  },
+
+  /**
+   * 返回路徑的副檔名
+   *
+   * @param path - 路徑
+   * @returns 副檔名(包含點號)
+   *
+   * @example
+   * ```typescript
+   * pathUtils.extname('index.html') // '.html'
+   * pathUtils.extname('index.coffee.md') // '.md'
+   * pathUtils.extname('index.') // '.'
+   * pathUtils.extname('index') // ''
+   * ```
+   */
+  extname(path: string): string {
+    const match = path.match(/\.[^./]*$/)
+    return match ? match[0] : ''
+  },
+
+  /**
+   * 檢查路徑是否為絕對路徑
+   *
+   * @param path - 路徑
+   * @returns 是否為絕對路徑
+   *
+   * @example
+   * ```typescript
+   * pathUtils.isAbsolute('/foo/bar') // true
+   * pathUtils.isAbsolute('foo/bar') // false
+   * pathUtils.isAbsolute('C:/foo/bar') // true (Windows)
+   * ```
+   */
+  isAbsolute(path: string): boolean {
+    // Unix-style absolute path
+    if (path.startsWith('/')) {
+      return true
+    }
+    // Windows-style absolute path (C:/, D:/, etc.)
+    if (/^[a-zA-Z]:[\\/]/.test(path)) {
+      return true
+    }
+    return false
+  },
+
+  /**
+   * 正規化路徑
+   *
+   * 解析 `.` 和 `..` 片段
+   *
+   * @param path - 路徑
+   * @returns 正規化後的路徑
+   *
+   * @example
+   * ```typescript
+   * pathUtils.normalize('/foo/bar//baz/./qux/../quux') // '/foo/bar/baz/quux'
+   * pathUtils.normalize('foo/../bar') // 'bar'
+   * ```
+   */
+  normalize(path: string): string {
+    const isAbs = this.isAbsolute(path)
+    const parts = path.split('/').filter(Boolean)
+    const result: string[] = []
+
+    for (const part of parts) {
+      if (part === '.') {
+      } else if (part === '..') {
+        // 返回上一級目錄
+        if (result.length > 0 && result[result.length - 1] !== '..') {
+          result.pop()
+        } else if (!isAbs) {
+          // 相對路徑可以保留 ..
+          result.push('..')
+        }
+      } else {
+        result.push(part)
+      }
+    }
+
+    let normalized = result.join('/')
+    if (isAbs) {
+      normalized = `/${normalized}`
+    }
+    return normalized || (isAbs ? '/' : '.')
+  },
+}

package/tests/unit/detector.test.ts

@@ -1,10 +1,5 @@
 import { describe, expect, it, jest } from 'bun:test'
-import {
-  DefaultDetectors,
-  type I18nService,
-  type LocaleDetector,
-  localeMiddleware,
-} from '../../src/I18nService'
+import { DefaultDetectors, type I18nService, localeMiddleware } from '../../src/I18nService'
 
 describe('Locale Detectors', () => {
   const mockContext = (params: any = {}) => ({

package/tests/unit/edge-kv-loader.test.ts

@@ -0,0 +1,202 @@
+/**
+ * @file packages/cosmos/tests/unit/edge-kv-loader.test.ts
+ * @description EdgeKVLoader 單元測試
+ */
+
+import { describe, expect, it, mock } from 'bun:test'
+import type { KVStorage } from '../../src/loaders/EdgeKVLoader'
+import { EdgeKVLoader } from '../../src/loaders/EdgeKVLoader'
+
+describe('EdgeKVLoader', () => {
+  it('should load translations from KV storage', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async (key: string) => {
+        if (key === 'i18n:en') {
+          return JSON.stringify({ hello: 'Hello' })
+        }
+        return null
+      }),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    const result = await loader.load('en')
+    expect(result).toEqual({ hello: 'Hello' })
+    expect(mockStorage.get).toHaveBeenCalledWith('i18n:en')
+  })
+
+  it('should return null for missing locale', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => null),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    const result = await loader.load('missing')
+    expect(result).toBeNull()
+  })
+
+  it('should handle JSON parse errors', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => 'invalid json'),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    const result = await loader.load('en')
+    expect(result).toBeNull()
+  })
+
+  it('should support custom prefix', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async (key: string) => {
+        if (key === 'translations:en') {
+          return JSON.stringify({ hello: 'Hello' })
+        }
+        return null
+      }),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+      prefix: 'translations',
+    })
+
+    const result = await loader.load('en')
+    expect(result).toEqual({ hello: 'Hello' })
+    expect(mockStorage.get).toHaveBeenCalledWith('translations:en')
+  })
+
+  it('should support custom key template', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async (key: string) => {
+        if (key === 'translations/en.json') {
+          return JSON.stringify({ hello: 'Hello' })
+        }
+        return null
+      }),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+      prefix: 'translations',
+      keyTemplate: ':prefix/:locale.json',
+    })
+
+    const result = await loader.load('en')
+    expect(result).toEqual({ hello: 'Hello' })
+    expect(mockStorage.get).toHaveBeenCalledWith('translations/en.json')
+  })
+
+  it('should support fallback loader', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => null),
+    }
+
+    const fallbackLoader = {
+      name: 'Fallback',
+      load: mock(async () => ({ hello: 'Fallback' })),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    }).fallback(fallbackLoader)
+
+    const result = await loader.load('en')
+    expect(result).toEqual({ hello: 'Fallback' })
+    expect(fallbackLoader.load).toHaveBeenCalledWith('en')
+  })
+
+  it('should support put operation', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => null),
+      put: mock(async () => {}),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    await loader.put('en', { hello: 'Hello' })
+
+    expect(mockStorage.put).toHaveBeenCalledWith('i18n:en', JSON.stringify({ hello: 'Hello' }))
+  })
+
+  it('should throw error if storage does not support put', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => null),
+      // No put method
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    await expect(loader.put('en', { hello: 'Hello' })).rejects.toThrow(
+      'Storage does not support put operation'
+    )
+  })
+
+  it('should support delete operation', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => null),
+      delete: mock(async () => {}),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    await loader.delete('en')
+
+    expect(mockStorage.delete).toHaveBeenCalledWith('i18n:en')
+  })
+
+  it('should throw error if storage does not support delete', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => null),
+      // No delete method
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    await expect(loader.delete('en')).rejects.toThrow('Storage does not support delete operation')
+  })
+
+  it('should handle nested translations', async () => {
+    const mockStorage: KVStorage = {
+      get: mock(async () => {
+        return JSON.stringify({
+          auth: {
+            login: 'Login',
+            errors: {
+              invalid: 'Invalid credentials',
+            },
+          },
+        })
+      }),
+    }
+
+    const loader = new EdgeKVLoader({
+      storage: mockStorage,
+    })
+
+    const result = await loader.load('en')
+    expect(result).toEqual({
+      auth: {
+        login: 'Login',
+        errors: {
+          invalid: 'Invalid credentials',
+        },
+      },
+    })
+  })
+})