@gravito/signal 3.0.3 → 3.0.4

package/doc/OPTIMIZATION_PLAN.md

@@ -0,0 +1,496 @@
+# @gravito/signal 優化改進計劃
+
+## 目前架構概覽
+
+`@gravito/signal` 是 Gravito 框架的郵件服務模組，提供以下核心功能：
+
+- **多傳輸層支援**：SMTP、AWS SES、Log、Memory
+- **多渲染引擎**：HTML、Template (Prism)、React、Vue
+- **開發模式**：內建郵件攔截與預覽 UI (`/__mail`)
+- **佇列整合**：透過 `@gravito/stream` 支援非同步發送
+- **國際化支援**：內建翻譯函式整合
+
+---
+
+## 第一階段：程式碼重構與 JSDoc 增強
+
+### 1.1 JSDoc 文檔優化
+
+**目標**：增強 AI 可讀性與開發者體驗
+
+| 檔案 | 優先級 | 改進內容 |
+|------|--------|----------|
+| `types.ts` | 高 | 補充 `@example`、`@see` 關聯說明 |
+| `Mailable.ts` | 高 | 增加完整使用範例、方法間的關聯說明 |
+| `OrbitSignal.ts` | 高 | 補充配置說明、錯誤處理說明 |
+| `transports/*.ts` | 中 | 增加配置範例、錯誤碼說明 |
+| `renderers/*.ts` | 中 | 補充渲染流程說明 |
+
+**具體改進項目**：
+
+```typescript
+// 範例：增強 Mailable 的 JSDoc
+/**
+ * Base class for all mailable messages.
+ *
+ * @description
+ * Mailable 提供流式 API 來建構郵件信封並使用多種引擎渲染內容。
+ * 支援 HTML、Prism 模板、React 與 Vue 組件渲染。
+ *
+ * @architecture
+ * ```
+ * Mailable
+ *   ├── Envelope (from, to, subject, etc.)
+ *   ├── Renderer (HtmlRenderer | TemplateRenderer | ReactRenderer | VueRenderer)
+ *   └── Queueable (佇列支援介面)
+ * ```
+ *
+ * @lifecycle
+ * 1. 建立 Mailable 子類別
+ * 2. 實作 build() 方法設定信封與內容
+ * 3. 呼叫 send() 或 queue() 發送
+ *
+ * @see {@link OrbitSignal} 郵件服務主類別
+ * @see {@link Renderer} 內容渲染器介面
+ * @see {@link Queueable} 佇列介面
+ */
+```
+
+### 1.2 stripHtml 方法重複問題
+
+**現狀**：`HtmlRenderer` 與 `TemplateRenderer` 各自實作相同的 `stripHtml` 方法
+
+**改進方案**：
+
+```typescript
+// 新增 src/utils/html.ts
+/**
+ * HTML 工具函式集合
+ *
+ * @module utils/html
+ * @since 3.1.0
+ */
+
+/**
+ * 將 HTML 內容轉換為純文字。
+ *
+ * @description
+ * 移除所有 HTML 標籤、樣式、腳本，並正規化空白字元。
+ * 用於產生郵件的純文字版本。
+ *
+ * @param html - 原始 HTML 字串
+ * @returns 純文字內容
+ *
+ * @example
+ * ```typescript
+ * const text = stripHtml('<h1>Hello</h1><p>World</p>')
+ * // Returns: 'Hello World'
+ * ```
+ */
+export function stripHtml(html: string): string {
+  return html
+    .replace(/<style(?:\s[^>]*)?>[\s\S]*?<\/style>/gi, '')
+    .replace(/<script(?:\s[^>]*)?>[\s\S]*?<\/script>/gi, '')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+```
+
+---
+
+## 第二階段：功能增強
+
+### 2.1 傳輸層錯誤處理增強
+
+**現狀**：傳輸層錯誤直接拋出，缺乏統一的錯誤類型
+
+**改進方案**：
+
+```typescript
+// 新增 src/errors.ts
+/**
+ * 郵件傳輸相關的錯誤類別
+ *
+ * @since 3.1.0
+ */
+export class MailTransportError extends Error {
+  constructor(
+    message: string,
+    public readonly code: MailErrorCode,
+    public readonly cause?: Error
+  ) {
+    super(message)
+    this.name = 'MailTransportError'
+  }
+}
+
+export enum MailErrorCode {
+  /** 連線失敗 */
+  CONNECTION_FAILED = 'CONNECTION_FAILED',
+  /** 認證失敗 */
+  AUTH_FAILED = 'AUTH_FAILED',
+  /** 收件人被拒 */
+  RECIPIENT_REJECTED = 'RECIPIENT_REJECTED',
+  /** 訊息被拒 */
+  MESSAGE_REJECTED = 'MESSAGE_REJECTED',
+  /** 速率限制 */
+  RATE_LIMIT = 'RATE_LIMIT',
+  /** 未知錯誤 */
+  UNKNOWN = 'UNKNOWN',
+}
+```
+
+### 2.2 重試機制
+
+**目標**：為傳輸層增加可配置的重試機制
+
+```typescript
+// Transport 介面擴展
+export interface TransportOptions {
+  /** 最大重試次數，預設 3 */
+  maxRetries?: number
+  /** 重試延遲（毫秒），預設 1000 */
+  retryDelay?: number
+  /** 指數退避乘數，預設 2 */
+  backoffMultiplier?: number
+}
+
+// 新增 BaseTransport 抽象類別
+export abstract class BaseTransport implements Transport {
+  protected options: Required<TransportOptions>
+
+  constructor(options?: TransportOptions) {
+    this.options = {
+      maxRetries: options?.maxRetries ?? 3,
+      retryDelay: options?.retryDelay ?? 1000,
+      backoffMultiplier: options?.backoffMultiplier ?? 2,
+    }
+  }
+
+  async send(message: Message): Promise<void> {
+    let lastError: Error | undefined
+    let delay = this.options.retryDelay
+
+    for (let attempt = 0; attempt <= this.options.maxRetries; attempt++) {
+      try {
+        return await this.doSend(message)
+      } catch (error) {
+        lastError = error as Error
+        if (attempt < this.options.maxRetries) {
+          await this.sleep(delay)
+          delay *= this.options.backoffMultiplier
+        }
+      }
+    }
+
+    throw new MailTransportError(
+      `發送失敗，已重試 ${this.options.maxRetries} 次`,
+      MailErrorCode.UNKNOWN,
+      lastError
+    )
+  }
+
+  protected abstract doSend(message: Message): Promise<void>
+
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+  }
+}
+```
+
+### 2.3 事件鉤子系統
+
+**目標**：提供郵件生命週期事件鉤子
+
+```typescript
+// 新增 src/events.ts
+export type MailEventType =
+  | 'beforeSend'
+  | 'afterSend'
+  | 'sendFailed'
+  | 'beforeRender'
+  | 'afterRender'
+
+export interface MailEvent {
+  type: MailEventType
+  mailable: Mailable
+  message?: Message
+  error?: Error
+  timestamp: Date
+}
+
+export type MailEventHandler = (event: MailEvent) => void | Promise<void>
+
+// OrbitSignal 擴展
+export class OrbitSignal implements GravitoOrbit {
+  private eventHandlers = new Map<MailEventType, MailEventHandler[]>()
+
+  /**
+   * 註冊事件處理器
+   *
+   * @example
+   * ```typescript
+   * mail.on('afterSend', async (event) => {
+   *   await analytics.track('email_sent', {
+   *     to: event.message?.to,
+   *     subject: event.message?.subject
+   *   })
+   * })
+   * ```
+   */
+  on(event: MailEventType, handler: MailEventHandler): this {
+    const handlers = this.eventHandlers.get(event) || []
+    handlers.push(handler)
+    this.eventHandlers.set(event, handlers)
+    return this
+  }
+
+  private async emit(event: MailEvent): Promise<void> {
+    const handlers = this.eventHandlers.get(event.type) || []
+    for (const handler of handlers) {
+      await handler(event)
+    }
+  }
+}
+```
+
+---
+
+## 第三階段：效能優化
+
+### 3.1 渲染器快取
+
+**目標**：快取已編譯的模板以提升效能
+
+```typescript
+// TemplateRenderer 增強
+export class TemplateRenderer implements Renderer {
+  private static engineCache = new Map<string, TemplateEngine>()
+
+  private getEngine(): TemplateEngine {
+    const cached = TemplateRenderer.engineCache.get(this.viewsDir)
+    if (cached) return cached
+
+    const engine = new TemplateEngine(this.viewsDir)
+    TemplateRenderer.engineCache.set(this.viewsDir, engine)
+    return engine
+  }
+
+  /**
+   * 清除模板引擎快取
+   *
+   * @description
+   * 在開發模式下，當模板檔案變更時呼叫此方法。
+   */
+  static clearCache(): void {
+    TemplateRenderer.engineCache.clear()
+  }
+}
+```
+
+### 3.2 連線池管理
+
+**目標**：為 SMTP 傳輸實作連線池
+
+```typescript
+// SmtpTransport 增強
+export interface SmtpConfig {
+  // ... 現有配置
+  /** 連線池大小，預設 5 */
+  poolSize?: number
+  /** 連線最大閒置時間（毫秒），預設 30000 */
+  maxIdleTime?: number
+}
+
+export class SmtpTransport implements Transport {
+  constructor(config: SmtpConfig) {
+    this.transporter = nodemailer.createTransport({
+      ...config,
+      pool: true,
+      maxConnections: config.poolSize ?? 5,
+      maxMessages: Infinity,
+      rateDelta: 1000,
+      rateLimit: 10,
+    })
+  }
+
+  /**
+   * 關閉連線池
+   *
+   * @description
+   * 在應用程式關閉時呼叫以釋放資源。
+   */
+  async close(): Promise<void> {
+    this.transporter.close()
+  }
+
+  /**
+   * 驗證 SMTP 連線
+   *
+   * @returns 連線是否成功
+   */
+  async verify(): Promise<boolean> {
+    try {
+      await this.transporter.verify()
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+```
+
+---
+
+## 第四階段：開發者體驗增強
+
+### 4.1 Dev UI 功能增強
+
+**目標**：增強開發郵件預覽 UI 的功能
+
+- [ ] 郵件搜尋功能
+- [ ] 標籤/分類過濾
+- [ ] 響應式預覽（桌面/平板/手機）
+- [ ] 郵件匯出功能（EML 格式）
+- [ ] 批次刪除功能
+- [ ] WebSocket 即時更新
+
+### 4.2 CLI 工具
+
+**目標**：提供郵件相關的 CLI 命令
+
+```bash
+# 發送測試郵件
+bun gravito mail:test --to test@example.com
+
+# 預覽 Mailable
+bun gravito mail:preview WelcomeEmail --data '{"name": "John"}'
+
+# 清空開發郵箱
+bun gravito mail:clear
+```
+
+### 4.3 型別安全增強
+
+**目標**：提升 TypeScript 型別推斷
+
+```typescript
+// 強型別 Mailable
+export abstract class TypedMailable<TData extends Record<string, unknown>> extends Mailable {
+  protected abstract data: TData
+
+  view<K extends keyof TData>(template: string, data: TData): this {
+    // 編譯時型別檢查
+    return super.view(template, data)
+  }
+}
+
+// 使用範例
+interface WelcomeData {
+  name: string
+  email: string
+  activationUrl: string
+}
+
+class WelcomeEmail extends TypedMailable<WelcomeData> {
+  protected data: WelcomeData
+
+  constructor(data: WelcomeData) {
+    super()
+    this.data = data
+  }
+
+  build() {
+    return this
+      .to(this.data.email)
+      .subject('歡迎加入！')
+      .view('welcome', this.data) // 型別安全
+  }
+}
+```
+
+---
+
+## 第五階段：測試與品質保證
+
+### 5.1 測試覆蓋率目標
+
+| 模組 | 目前覆蓋率 | 目標覆蓋率 |
+|------|-----------|-----------|
+| OrbitSignal | ~75% | 90% |
+| Mailable | ~70% | 90% |
+| Transports | ~60% | 85% |
+| Renderers | ~65% | 85% |
+| DevServer | ~50% | 80% |
+
+### 5.2 新增測試案例
+
+- [ ] 傳輸層重試機制測試
+- [ ] 事件鉤子系統測試
+- [ ] 連線池管理測試
+- [ ] 渲染器快取測試
+- [ ] 錯誤處理邊界情況測試
+- [ ] 國際化功能測試
+- [ ] 佇列整合測試
+
+### 5.3 效能基準測試
+
+```typescript
+// benchmarks/mail-sending.bench.ts
+import { bench, describe } from 'vitest'
+
+describe('Mail Sending Performance', () => {
+  bench('SmtpTransport - single message', async () => {
+    await transport.send(testMessage)
+  })
+
+  bench('SmtpTransport - 100 messages concurrent', async () => {
+    await Promise.all(
+      Array.from({ length: 100 }, () => transport.send(testMessage))
+    )
+  })
+
+  bench('TemplateRenderer - with cache', async () => {
+    await renderer.render(testData)
+  })
+})
+```
+
+---
+
+## 實施時程建議
+
+| 階段 | 內容 | 優先級 |
+|------|------|--------|
+| 第一階段 | JSDoc 增強、程式碼重構 | 高 |
+| 第二階段 | 錯誤處理、重試機制、事件系統 | 高 |
+| 第三階段 | 效能優化（快取、連線池） | 中 |
+| 第四階段 | 開發者體驗（Dev UI、CLI） | 中 |
+| 第五階段 | 測試與品質保證 | 高 |
+
+---
+
+## 破壞性變更注意事項
+
+以下改進可能導致破壞性變更，需要在下一個主版本（4.0）中實施：
+
+1. **Transport 介面變更**：增加 `close()` 方法
+2. **錯誤類型變更**：使用自定義錯誤類別
+3. **配置選項變更**：傳輸層配置擴展
+
+建議在 3.x 版本中以可選方式引入新功能，在 4.0 版本中設為預設行為。
+
+---
+
+## 參考資源
+
+- [Nodemailer 文檔](https://nodemailer.com/)
+- [AWS SES 最佳實踐](https://docs.aws.amazon.com/ses/latest/dg/best-practices.html)
+- [郵件傳送最佳實踐](https://postmarkapp.com/guides/best-practices-for-email-delivery)

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@gravito/signal",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "Powerful email framework for Gravito applications with Dev UI and multi-renderer support.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --external @gravito/core --external @gravito/stream --external @gravito/prism",
-    "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",
@@ -27,9 +29,9 @@
     "nodemailer": "^7.0.11"
   },
   "peerDependencies": {
-    "@gravito/core": "workspace:*",
-    "@gravito/stream": "workspace:*",
-    "@gravito/prism": "workspace:*",
+    "@gravito/core": "^1.6.1",
+    "@gravito/stream": "^2.0.2",
+    "@gravito/prism": "^3.1.1",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "vue": "^3.0.0"
@@ -49,13 +51,13 @@
     }
   },
   "devDependencies": {
-    "@gravito/prism": "workspace:*",
-    "@gravito/stream": "workspace:*",
+    "@gravito/prism": "^3.1.1",
+    "@gravito/stream": "^2.0.2",
     "@types/nodemailer": "^6.4.14",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vue/server-renderer": "^3.0.0",
-    "@gravito/core": "workspace:*",
+    "@gravito/core": "^1.6.1",
     "tsup": "8.5.1",
     "typescript": "^5.9.3",
     "vue": "^3.0.0",
@@ -70,4 +72,4 @@
     "url": "git+https://github.com/gravito-framework/gravito.git",
     "directory": "packages/signal"
   }
-}
+}

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(
+    `signal coverage ${rounded}% is below threshold ${threshold}%. Covered lines: ${hit}/${total}.`
+  )
+  process.exit(1)
+}
+
+console.log(`signal coverage ${rounded}% (${hit}/${total}) meets threshold ${threshold}%.`)