@gravito/cosmos 3.1.0 → 3.2.0

package/MIGRATION.md

@@ -0,0 +1,331 @@
+# Migration Guide: Cosmos v1.x → v2.0
+
+## Overview
+
+Cosmos v2.0 introduces Edge Runtime support while maintaining full backward compatibility with v1.x. This guide helps you migrate to v2.0 and leverage new features.
+
+## Breaking Changes
+
+**None!** v2.0 is fully backward compatible with v1.x.
+
+All existing code will continue to work without modifications.
+
+## What's New in v2.0
+
+### Edge Runtime Support
+
+Cosmos now runs in Edge Runtime environments:
+- ✅ Cloudflare Workers
+- ✅ Vercel Edge Functions
+- ✅ Deno Deploy
+- ✅ Node.js (existing support)
+
+### New Loaders
+
+- **MemoryLoader**: Static translations for Edge environments
+- **EdgeKVLoader**: Generic KV storage abstraction
+- **CloudflareKVLoader**: Cloudflare Workers KV
+- **VercelKVLoader**: Vercel KV
+
+### Runtime Detection
+
+- `detectRuntime()`: Auto-detect execution environment
+- `isNode()`, `isEdge()`: Helper functions
+
+## Migration Paths
+
+### For Node.js Projects
+
+**No changes required!** Your existing code works as-is.
+
+```typescript
+// ✅ This still works
+import { OrbitCosmos } from '@gravito/cosmos'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  lazyLoad: {
+    baseDir: './lang'
+  }
+})
+```
+
+### For Edge Runtime Projects
+
+#### Option 1: Static Translations (Recommended for <100KB)
+
+```typescript
+// Before: Not possible
+// After: Use MemoryLoader
+import { OrbitCosmos, MemoryLoader } from '@gravito/cosmos/edge'
+import en from './lang/en.json'
+import zhTW from './lang/zh-TW.json'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new MemoryLoader({
+      translations: { en, 'zh-TW': zhTW }
+    })
+  ]
+})
+```
+
+#### Option 2: Remote API (Recommended for dynamic content)
+
+```typescript
+import { OrbitCosmos, RemoteLoader } from '@gravito/cosmos/edge'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new RemoteLoader({
+      url: 'https://api.example.com/i18n/:locale',
+      etagCache: true,
+      retries: 3
+    })
+  ]
+})
+```
+
+#### Option 3: KV Storage (Recommended for Cloudflare/Vercel)
+
+**Cloudflare Workers:**
+
+```typescript
+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: 'zh-TW',
+      supportedLocales: ['zh-TW', 'en'],
+      loaders: [
+        new CloudflareKVLoader({
+          namespace: env.I18N_KV
+        })
+      ]
+    })
+
+    // ... use cosmos
+  }
+}
+```
+
+**Vercel Edge Functions:**
+
+```typescript
+import { OrbitCosmos, VercelKVLoader } from '@gravito/cosmos/edge'
+import { kv } from '@vercel/kv'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new VercelKVLoader({ kv })
+  ]
+})
+```
+
+## Best Practices
+
+### 1. Use Fallback Chains
+
+Combine loaders for reliability:
+
+```typescript
+import { MemoryLoader, RemoteLoader, CloudflareKVLoader } from '@gravito/cosmos/edge'
+
+const cosmos = new OrbitCosmos({
+  loaders: [
+    new CloudflareKVLoader({ namespace: env.I18N_KV })
+      .fallback(new RemoteLoader({ url: env.I18N_API }))
+      .fallback(new MemoryLoader({ translations: fallbackData }))
+  ]
+})
+```
+
+### 2. Choose the Right Loader
+
+| Scenario | Recommended Loader | Reason |
+|----------|-------------------|--------|
+| Small static translations (<100KB) | MemoryLoader | Fastest, no network |
+| Dynamic CMS translations | RemoteLoader | Real-time updates |
+| Cloudflare Workers | CloudflareKVLoader | Edge-optimized |
+| Vercel Edge | VercelKVLoader | Edge-optimized |
+| Node.js server | FileSystemLoader | Native fs access |
+
+### 3. Optimize Bundle Size
+
+Edge environments have size limits:
+
+```typescript
+// ✅ Good: Import only what you need
+import { OrbitCosmos, MemoryLoader } from '@gravito/cosmos/edge'
+
+// ❌ Avoid: Importing Node.js-only features in Edge
+import { FileSystemLoader } from '@gravito/cosmos/node'
+```
+
+## Deprecated Features
+
+### lazyLoad.loader (Still works, but deprecated)
+
+```typescript
+// ⚠️ Deprecated
+{
+  lazyLoad: {
+    baseDir: './lang',
+    loader: customLoaderFn
+  }
+}
+
+// ✅ Recommended
+{
+  loaders: [
+    new FileSystemLoader({ baseDir: './lang' })
+  ]
+}
+```
+
+## Troubleshooting
+
+### Error: "FileSystemLoader requires Node.js"
+
+**Cause**: Using FileSystemLoader in Edge Runtime
+
+**Solution**: Use MemoryLoader, RemoteLoader, or EdgeKVLoader
+
+```typescript
+// ❌ Wrong
+import { FileSystemLoader } from '@gravito/cosmos/edge'
+
+// ✅ Correct
+import { MemoryLoader } from '@gravito/cosmos/edge'
+```
+
+### Warning: "HMR is not supported in Edge Runtime"
+
+**Cause**: HMRWatcher is Node.js-only
+
+**Solution**: Use RemoteLoader with ETag caching for dynamic updates
+
+```typescript
+// Edge Runtime alternative to HMR
+new RemoteLoader({
+  url: 'https://api.example.com/i18n/:locale',
+  etagCache: true // Automatically refetches when content changes
+})
+```
+
+### Translations not loading
+
+**Debug steps:**
+
+1. Check loader configuration
+2. Verify translations are uploaded (for KV loaders)
+3. Check network requests (for RemoteLoader)
+4. Enable verbose logging
+
+```typescript
+const loader = new RemoteLoader({
+  url: 'https://api.example.com/i18n/:locale',
+  // Add console.log in load method for debugging
+})
+
+console.log('Testing load:', await loader.load('en'))
+```
+
+## Examples
+
+### Cloudflare Workers Complete Example
+
+```typescript
+import { OrbitCosmos, CloudflareKVLoader, MemoryLoader } from '@gravito/cosmos/edge'
+
+export interface Env {
+  I18N_KV: KVNamespace
+}
+
+// Fallback translations
+const fallback = {
+  en: { error: 'An error occurred' },
+  'zh-TW': { error: '發生錯誤' }
+}
+
+export default {
+  async fetch(request: Request, env: Env) {
+    const cosmos = new OrbitCosmos({
+      defaultLocale: 'zh-TW',
+      supportedLocales: ['zh-TW', 'en'],
+      loaders: [
+        new CloudflareKVLoader({ namespace: env.I18N_KV })
+          .fallback(new MemoryLoader({ translations: fallback }))
+      ]
+    })
+
+    const i18n = cosmos.clone('zh-TW')
+    await i18n.ensureLocale('zh-TW')
+
+    return new Response(i18n.t('welcome'))
+  }
+}
+```
+
+### Vercel Edge Functions Complete Example
+
+```typescript
+import { OrbitCosmos, VercelKVLoader } from '@gravito/cosmos/edge'
+import { kv } from '@vercel/kv'
+
+const cosmos = new OrbitCosmos({
+  defaultLocale: 'zh-TW',
+  supportedLocales: ['zh-TW', 'en'],
+  loaders: [
+    new VercelKVLoader({ kv, prefix: 'i18n' })
+  ]
+})
+
+export async function GET(request: Request) {
+  const url = new URL(request.url)
+  const locale = url.searchParams.get('lang') || 'zh-TW'
+
+  const i18n = cosmos.clone(locale)
+  await i18n.ensureLocale(locale)
+
+  return new Response(JSON.stringify({
+    message: i18n.t('welcome'),
+    locale: i18n.getLocale()
+  }))
+}
+```
+
+## FAQ
+
+**Q: Do I need to update my code for v2.0?**
+A: No, v2.0 is fully backward compatible.
+
+**Q: Can I use FileSystemLoader in Edge Runtime?**
+A: No, use MemoryLoader, RemoteLoader, or EdgeKVLoader instead.
+
+**Q: How do I upload translations to KV storage?**
+A: See the CloudflareKVLoader and VercelKVLoader documentation for upload scripts.
+
+**Q: What's the performance difference between loaders?**
+A: MemoryLoader (fastest) > KV Loaders (fast) > RemoteLoader (depends on network)
+
+**Q: Can I mix Node.js and Edge loaders?**
+A: In Node.js, yes. In Edge, only Edge-compatible loaders work.
+
+## Support
+
+- Documentation: [README.md](./README.md)
+- Architecture: [docs/architecture/cosmos.md](../../docs/architecture/cosmos.md)
+- Issues: [GitHub Issues](https://github.com/gravito-framework/gravito/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gravito/cosmos",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Internationalization orbit for Gravito framework",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -12,14 +12,26 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./edge": {
+      "types": "./dist/index.edge.d.ts",
+      "import": "./dist/index.edge.js",
+      "require": "./dist/index.edge.cjs"
+    },
+    "./node": {
+      "types": "./dist/index.node.d.ts",
+      "import": "./dist/index.node.js",
+      "require": "./dist/index.node.cjs"
     }
   },
   "scripts": {
     "build": "bun run build.ts",
-    "test": "bun test",
-    "test:coverage": "bun test --coverage --coverage-threshold=80",
-    "test:ci": "bun test --coverage --coverage-threshold=80",
-    "typecheck": "bun tsc -p tsconfig.json --noEmit --skipLibCheck"
+    "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",
+    "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'"
   },
   "keywords": [
     "gravito",
@@ -47,5 +59,8 @@
     "type": "git",
     "url": "git+https://github.com/gravito-framework/gravito.git",
     "directory": "packages/cosmos"
+  },
+  "dependencies": {
+    "lru-cache": "^11.2.5"
   }
 }

package/scripts/check-coverage.ts

@@ -0,0 +1,64 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const lcovPath = process.argv[2] ?? 'coverage/lcov.info'
+const threshold = Number.parseFloat(process.env.COVERAGE_THRESHOLD ?? '80')
+
+const root = resolve(process.cwd())
+const srcRoot = `${resolve(root, 'src')}/`
+
+// 檢查 lcov.info 是否存在
+if (!existsSync(lcovPath)) {
+  console.error(`Coverage file not found: ${lcovPath}`)
+  process.exit(1)
+}
+
+let content: string
+try {
+  content = readFileSync(lcovPath, 'utf-8')
+} catch (error) {
+  console.error(`Failed to read coverage file: ${error}`)
+  process.exit(1)
+}
+
+const lines = content.split('\n')
+
+let currentFile: string | null = null
+let total = 0
+let hit = 0
+
+for (const line of lines) {
+  if (line.startsWith('SF:')) {
+    const filePath = line.slice(3).trim()
+    const abs = resolve(root, filePath)
+    currentFile = abs.startsWith(srcRoot) ? abs : null
+    continue
+  }
+
+  if (!currentFile) {
+    continue
+  }
+
+  if (line.startsWith('DA:')) {
+    const parts = line.slice(3).split(',')
+    if (parts.length >= 2) {
+      total += 1
+      const count = Number.parseInt(parts[1] ?? '0', 10)
+      if (count > 0) {
+        hit += 1
+      }
+    }
+  }
+}
+
+const percent = total === 0 ? 0 : (hit / total) * 100
+const rounded = Math.round(percent * 100) / 100
+
+if (rounded < threshold) {
+  console.error(
+    `cosmos coverage ${rounded}% is below threshold ${threshold}%. Covered lines: ${hit}/${total}.`
+  )
+  process.exit(1)
+}
+
+console.log(`cosmos coverage ${rounded}% (${hit}/${total}) meets threshold ${threshold}%.`)