zyflow 0.6.4

package/src/utils/error-logger.ts

@@ -0,0 +1,399 @@
+/**
+ * Error Logger Implementation
+ * Captures, persists, and manages error logs
+ * @module utils/error-logger
+ */
+
+import { ErrorContext, ErrorCode, ErrorSeverity, ErrorType } from '@/types/errors'
+
+// =============================================
+// Constants
+// =============================================
+
+const MAX_IN_MEMORY_LOGS = 50
+const MAX_LOCAL_STORAGE_LOGS = 500
+const LOCAL_STORAGE_KEY = 'zyflow_error_logs'
+const LOCAL_STORAGE_CHUNK_SIZE = 50
+const LOCAL_STORAGE_PREFIX = 'zyflow_error_logs_'
+
+// =============================================
+// Error Logger Class
+// =============================================
+
+export class ErrorLogger {
+  private logs: ErrorContext[] = []
+  private initialized = false
+
+  constructor() {
+    this.initialize()
+  }
+
+  /**
+   * Initialize error logger and load from localStorage
+   */
+  private initialize(): void {
+    if (this.initialized) return
+
+    try {
+      this.loadFromLocalStorage()
+      this.initialized = true
+    } catch (error) {
+      console.warn('Failed to initialize error logger', error)
+      this.initialized = true
+    }
+  }
+
+  /**
+   * Log an error with context
+   */
+  log(error: ErrorContext): ErrorContext {
+    const timestamp = Date.now()
+    const contextWithTimestamp: ErrorContext = {
+      ...error,
+      timestamp: error.timestamp || timestamp,
+    }
+
+    // Add to in-memory log
+    this.logs.unshift(contextWithTimestamp)
+
+    // Maintain max in-memory size
+    if (this.logs.length > MAX_IN_MEMORY_LOGS) {
+      this.logs = this.logs.slice(0, MAX_IN_MEMORY_LOGS)
+    }
+
+    // Persist to localStorage
+    try {
+      this.persistToLocalStorage()
+    } catch (error) {
+      console.warn('Failed to persist error log to localStorage', error)
+    }
+
+    return contextWithTimestamp
+  }
+
+  /**
+   * Get error history
+   */
+  getHistory(limit: number = 20): ErrorContext[] {
+    return this.logs.slice(0, limit)
+  }
+
+  /**
+   * Get all errors
+   */
+  getAllErrors(): ErrorContext[] {
+    return [...this.logs]
+  }
+
+  /**
+   * Get errors by type
+   */
+  getErrorsByType(type: ErrorType, limit: number = 20): ErrorContext[] {
+    return this.logs.filter((log) => log.type === type).slice(0, limit)
+  }
+
+  /**
+   * Get errors by severity
+   */
+  getErrorsBySeverity(severity: ErrorSeverity, limit: number = 20): ErrorContext[] {
+    return this.logs.filter((log) => log.severity === severity).slice(0, limit)
+  }
+
+  /**
+   * Get errors by code
+   */
+  getErrorsByCode(code: ErrorCode, limit: number = 20): ErrorContext[] {
+    return this.logs.filter((log) => log.code === code).slice(0, limit)
+  }
+
+  /**
+   * Get errors by component
+   */
+  getErrorsByComponent(component: string, limit: number = 20): ErrorContext[] {
+    return this.logs.filter((log) => log.component === component).slice(0, limit)
+  }
+
+  /**
+   * Get error statistics
+   */
+  getStatistics(): {
+    total: number
+    byType: Record<ErrorType, number>
+    bySeverity: Record<ErrorSeverity, number>
+    byCode: Record<string, number>
+  } {
+    const stats = {
+      total: this.logs.length,
+      byType: {} as Record<ErrorType, number>,
+      bySeverity: {} as Record<ErrorSeverity, number>,
+      byCode: {} as Record<string, number>,
+    }
+
+    this.logs.forEach((log) => {
+      // Count by type
+      stats.byType[log.type] = (stats.byType[log.type] || 0) + 1
+
+      // Count by severity
+      stats.bySeverity[log.severity] = (stats.bySeverity[log.severity] || 0) + 1
+
+      // Count by code
+      stats.byCode[log.code] = (stats.byCode[log.code] || 0) + 1
+    })
+
+    return stats
+  }
+
+  /**
+   * Clear all errors
+   */
+  clear(): void {
+    this.logs = []
+    try {
+      this.clearLocalStorage()
+    } catch (error) {
+      console.warn('Failed to clear localStorage', error)
+    }
+  }
+
+  /**
+   * Clear errors older than specified milliseconds
+   */
+  clearOlderThan(milliseconds: number): number {
+    const cutoffTime = Date.now() - milliseconds
+    const beforeCount = this.logs.length
+
+    this.logs = this.logs.filter((log) => log.timestamp > cutoffTime)
+
+    const deletedCount = beforeCount - this.logs.length
+
+    if (deletedCount > 0) {
+      try {
+        this.persistToLocalStorage()
+      } catch (error) {
+        console.warn('Failed to persist after clearing old logs', error)
+      }
+    }
+
+    return deletedCount
+  }
+
+  /**
+   * Export error logs as JSON
+   */
+  export(): {
+    version: string
+    exportedAt: number
+    errors: ErrorContext[]
+  } {
+    return {
+      version: '1.0.0',
+      exportedAt: Date.now(),
+      errors: [...this.logs],
+    }
+  }
+
+  /**
+   * Export error logs as CSV
+   */
+  exportAsCSV(): string {
+    if (this.logs.length === 0) {
+      return 'No errors to export'
+    }
+
+    const headers = [
+      'Timestamp',
+      'Code',
+      'Severity',
+      'Type',
+      'Message',
+      'Component',
+      'Function',
+      'User Action',
+    ]
+
+    const rows = this.logs.map((log) => [
+      new Date(log.timestamp).toISOString(),
+      log.code,
+      log.severity,
+      log.type,
+      `"${log.message.replace(/"/g, '""')}"`,
+      log.component || '',
+      log.function || '',
+      log.userAction || '',
+    ])
+
+    return [headers, ...rows].map((row) => row.join(',')).join('\n')
+  }
+
+  /**
+   * Search errors by message or component
+   */
+  search(
+    query: string,
+    options: {
+      searchMessage?: boolean
+      searchComponent?: boolean
+      searchFunction?: boolean
+      caseSensitive?: boolean
+      limit?: number
+    } = {}
+  ): ErrorContext[] {
+    const {
+      searchMessage = true,
+      searchComponent = true,
+      searchFunction = true,
+      caseSensitive = false,
+      limit = 20,
+    } = options
+
+    const pattern = caseSensitive ? query : query.toLowerCase()
+
+    return this.logs
+      .filter((log) => {
+        if (searchMessage && this.matchesPattern(log.message, pattern, caseSensitive)) return true
+        if (searchComponent && this.matchesPattern(log.component || '', pattern, caseSensitive)) return true
+        if (searchFunction && this.matchesPattern(log.function || '', pattern, caseSensitive)) return true
+        return false
+      })
+      .slice(0, limit)
+  }
+
+  /**
+   * Get error frequency for trend analysis
+   */
+  getFrequency(
+    timewindowMs: number = 3600000 // 1 hour
+  ): {
+    window: string
+    count: number
+    errors: Array<{
+      code: string
+      count: number
+    }>
+  } {
+    const cutoffTime = Date.now() - timewindowMs
+    const recentErrors = this.logs.filter((log) => log.timestamp > cutoffTime)
+
+    const byCode: Record<string, number> = {}
+    recentErrors.forEach((log) => {
+      byCode[log.code] = (byCode[log.code] || 0) + 1
+    })
+
+    return {
+      window: `${Math.round(timewindowMs / 1000)}s`,
+      count: recentErrors.length,
+      errors: Object.entries(byCode)
+        .map(([code, count]) => ({ code, count }))
+        .sort((a, b) => b.count - a.count),
+    }
+  }
+
+  /**
+   * Persist logs to localStorage
+   */
+  private persistToLocalStorage(): void {
+    try {
+      if (typeof window === 'undefined' || !window.localStorage) return
+
+      // Clear old chunks first
+      this.clearLocalStorage()
+
+      // Split logs into chunks for localStorage limits
+      const allLogs = this.logs
+      const chunks = []
+
+      for (let i = 0; i < allLogs.length; i += LOCAL_STORAGE_CHUNK_SIZE) {
+        chunks.push(allLogs.slice(i, i + LOCAL_STORAGE_CHUNK_SIZE))
+      }
+
+      // Store chunks
+      chunks.forEach((chunk, index) => {
+        const key = `${LOCAL_STORAGE_PREFIX}${index}`
+        localStorage.setItem(key, JSON.stringify(chunk))
+      })
+
+      // Store chunk count
+      localStorage.setItem(`${LOCAL_STORAGE_KEY}_chunks`, JSON.stringify(chunks.length))
+    } catch (error) {
+      // Silently fail if localStorage is full or unavailable
+      console.warn('Failed to persist error logs', error)
+    }
+  }
+
+  /**
+   * Load logs from localStorage
+   */
+  private loadFromLocalStorage(): void {
+    try {
+      if (typeof window === 'undefined' || !window.localStorage) return
+
+      const chunksStr = localStorage.getItem(`${LOCAL_STORAGE_KEY}_chunks`)
+      if (!chunksStr) return
+
+      const chunkCount = JSON.parse(chunksStr) as number
+      const allLogs: ErrorContext[] = []
+
+      for (let i = 0; i < chunkCount; i++) {
+        const key = `${LOCAL_STORAGE_PREFIX}${i}`
+        const chunkStr = localStorage.getItem(key)
+        if (chunkStr) {
+          const chunk = JSON.parse(chunkStr) as ErrorContext[]
+          allLogs.push(...chunk)
+        }
+      }
+
+      // Limit to max size
+      this.logs = allLogs.slice(0, MAX_LOCAL_STORAGE_LOGS)
+    } catch (error) {
+      console.warn('Failed to load error logs from localStorage', error)
+    }
+  }
+
+  /**
+   * Clear localStorage
+   */
+  private clearLocalStorage(): void {
+    try {
+      if (typeof window === 'undefined' || !window.localStorage) return
+
+      const chunksStr = localStorage.getItem(`${LOCAL_STORAGE_KEY}_chunks`)
+      if (chunksStr) {
+        const chunkCount = JSON.parse(chunksStr) as number
+        for (let i = 0; i < chunkCount; i++) {
+          localStorage.removeItem(`${LOCAL_STORAGE_PREFIX}${i}`)
+        }
+        localStorage.removeItem(`${LOCAL_STORAGE_KEY}_chunks`)
+      }
+    } catch (error) {
+      console.warn('Failed to clear localStorage', error)
+    }
+  }
+
+  /**
+   * Check if pattern matches text
+   */
+  private matchesPattern(text: string, pattern: string, caseSensitive: boolean): boolean {
+    const searchText = caseSensitive ? text : text.toLowerCase()
+    return searchText.includes(pattern)
+  }
+}
+
+// =============================================
+// Singleton Instance
+// =============================================
+
+let loggerInstance: ErrorLogger | null = null
+
+export function getErrorLogger(): ErrorLogger {
+  if (!loggerInstance) {
+    loggerInstance = new ErrorLogger()
+  }
+  return loggerInstance
+}
+
+/**
+ * Quick logging function
+ */
+export function logError(context: ErrorContext): ErrorContext {
+  return getErrorLogger().log(context)
+}

package/src/utils/error-statistics.ts

@@ -0,0 +1,305 @@
+/**
+ * Error Statistics and Analytics Utilities
+ * Calculates error metrics, trends, and distributions
+ * @module utils/error-statistics
+ */
+
+import { ErrorContext, ErrorSeverity, ErrorType } from '@/types/errors'
+
+// =============================================
+// Types
+// =============================================
+
+export interface ErrorStats {
+  total: number
+  byType: Record<ErrorType, number>
+  bySeverity: Record<ErrorSeverity, number>
+  byCode: Record<string, number>
+  topErrors: Array<{ code: string; count: number; message: string }>
+  recoveryRate: number
+  avgRecoveryTime: number
+}
+
+export interface ErrorTrendPoint {
+  timestamp: number
+  count: number
+  critical: number
+  error: number
+  warning: number
+  info: number
+}
+
+export interface ErrorTrend {
+  period: '1h' | '24h' | '7d'
+  points: ErrorTrendPoint[]
+  totalErrors: number
+  trend: 'increasing' | 'decreasing' | 'stable'
+}
+
+// =============================================
+// Statistics Calculation
+// =============================================
+
+/**
+ * Calculate error statistics from error list
+ */
+export function calculateErrorStats(errors: ErrorContext[]): ErrorStats {
+  const stats: ErrorStats = {
+    total: errors.length,
+    byType: {
+      [ErrorType.NETWORK]: 0,
+      [ErrorType.COMPONENT]: 0,
+      [ErrorType.VALIDATION]: 0,
+      [ErrorType.STATE]: 0,
+      [ErrorType.TASK]: 0,
+      [ErrorType.SSE]: 0,
+    },
+    bySeverity: {
+      [ErrorSeverity.INFO]: 0,
+      [ErrorSeverity.WARNING]: 0,
+      [ErrorSeverity.ERROR]: 0,
+      [ErrorSeverity.CRITICAL]: 0,
+    },
+    byCode: {},
+    topErrors: [],
+    recoveryRate: 0,
+    avgRecoveryTime: 0,
+  }
+
+  // Count by type, severity, and code
+  errors.forEach((error) => {
+    stats.byType[error.type]++
+    stats.bySeverity[error.severity]++
+    stats.byCode[error.code] = (stats.byCode[error.code] || 0) + 1
+  })
+
+  // Calculate top errors
+  stats.topErrors = Object.entries(stats.byCode)
+    .map(([code, count]) => ({
+      code,
+      count,
+      message: errors.find((e) => e.code === code)?.message || 'Unknown error',
+    }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 5)
+
+  // Calculate recovery rate
+  const recoverableErrors = errors.filter((e) => e.recoverable)
+  stats.recoveryRate =
+    errors.length > 0 ? (recoverableErrors.length / errors.length) * 100 : 0
+
+  // Calculate average recovery time
+  const recoveryTimes = errors
+    .filter((e) => e.recoveryTime && e.recoveryTime > 0)
+    .map((e) => e.recoveryTime || 0)
+  stats.avgRecoveryTime =
+    recoveryTimes.length > 0
+      ? recoveryTimes.reduce((a, b) => a + b, 0) / recoveryTimes.length
+      : 0
+
+  return stats
+}
+
+// =============================================
+// Trend Analysis
+// =============================================
+
+/**
+ * Calculate error trend over time period
+ */
+export function calculateErrorTrend(
+  errors: ErrorContext[],
+  period: '1h' | '24h' | '7d' = '24h'
+): ErrorTrend {
+  const now = Date.now()
+  const periodMs = getPeriodMs(period)
+  const cutoffTime = now - periodMs
+
+  // Filter errors within period
+  const periodErrors = errors.filter((e) => e.timestamp >= cutoffTime)
+
+  // Create time buckets
+  const bucketSize = getBucketSize(period)
+  const buckets = new Map<number, ErrorTrendPoint>()
+
+  // Initialize buckets
+  for (let i = 0; i < Math.ceil(periodMs / bucketSize); i++) {
+    const bucketTime = now - (Math.ceil(periodMs / bucketSize) - i) * bucketSize
+    buckets.set(bucketTime, {
+      timestamp: bucketTime,
+      count: 0,
+      critical: 0,
+      error: 0,
+      warning: 0,
+      info: 0,
+    })
+  }
+
+  // Aggregate errors into buckets
+  periodErrors.forEach((error) => {
+    const bucketIndex = Math.floor((now - error.timestamp) / bucketSize)
+    const bucketTime = now - bucketIndex * bucketSize
+    const bucket = buckets.get(bucketTime)
+
+    if (bucket) {
+      bucket.count++
+      if (error.severity === ErrorSeverity.CRITICAL) bucket.critical++
+      else if (error.severity === ErrorSeverity.ERROR) bucket.error++
+      else if (error.severity === ErrorSeverity.WARNING) bucket.warning++
+      else bucket.info++
+    }
+  })
+
+  const points = Array.from(buckets.values()).sort(
+    (a, b) => a.timestamp - b.timestamp
+  )
+
+  // Calculate trend
+  const firstHalf = points.slice(0, Math.floor(points.length / 2))
+  const secondHalf = points.slice(Math.floor(points.length / 2))
+  const firstAvg =
+    firstHalf.reduce((sum, p) => sum + p.count, 0) / firstHalf.length
+  const secondAvg =
+    secondHalf.reduce((sum, p) => sum + p.count, 0) / secondHalf.length
+
+  let trend: 'increasing' | 'decreasing' | 'stable' = 'stable'
+  if (secondAvg > firstAvg * 1.1) trend = 'increasing'
+  else if (secondAvg < firstAvg * 0.9) trend = 'decreasing'
+
+  return {
+    period,
+    points,
+    totalErrors: periodErrors.length,
+    trend,
+  }
+}
+
+/**
+ * Group errors by time period (hourly, daily, weekly)
+ */
+export function groupErrorsByTime(
+  errors: ErrorContext[],
+  period: 'hour' | 'day' | 'week' = 'hour'
+): Map<string, ErrorContext[]> {
+  const grouped = new Map<string, ErrorContext[]>()
+
+  errors.forEach((error) => {
+    const timeKey = formatTimeKey(error.timestamp, period)
+    if (!grouped.has(timeKey)) {
+      grouped.set(timeKey, [])
+    }
+    grouped.get(timeKey)?.push(error)
+  })
+
+  return grouped
+}
+
+/**
+ * Calculate error frequency over time
+ */
+export function calculateErrorFrequency(
+  errors: ErrorContext[]
+): Map<string, number> {
+  const frequency = new Map<string, number>()
+
+  errors.forEach((error) => {
+    const count = frequency.get(error.code) || 0
+    frequency.set(error.code, count + 1)
+  })
+
+  return frequency
+}
+
+/**
+ * Get most common error patterns
+ */
+export function getErrorPatterns(
+  errors: ErrorContext[]
+): Array<{ pattern: string; count: number; examples: ErrorContext[] }> {
+  const patterns = new Map<string, ErrorContext[]>()
+
+  errors.forEach((error) => {
+    const pattern = `${error.type}:${error.component}`
+    if (!patterns.has(pattern)) {
+      patterns.set(pattern, [])
+    }
+    patterns.get(pattern)?.push(error)
+  })
+
+  return Array.from(patterns.entries())
+    .map(([pattern, examples]) => ({
+      pattern,
+      count: examples.length,
+      examples: examples.slice(0, 3),
+    }))
+    .sort((a, b) => b.count - a.count)
+}
+
+// =============================================
+// Helper Functions
+// =============================================
+
+function getPeriodMs(period: '1h' | '24h' | '7d'): number {
+  switch (period) {
+    case '1h':
+      return 60 * 60 * 1000
+    case '24h':
+      return 24 * 60 * 60 * 1000
+    case '7d':
+      return 7 * 24 * 60 * 60 * 1000
+  }
+}
+
+function getBucketSize(period: '1h' | '24h' | '7d'): number {
+  switch (period) {
+    case '1h':
+      return 5 * 60 * 1000 // 5 min buckets
+    case '24h':
+      return 60 * 60 * 1000 // 1 hour buckets
+    case '7d':
+      return 6 * 60 * 60 * 1000 // 6 hour buckets
+  }
+}
+
+function formatTimeKey(timestamp: number, period: 'hour' | 'day' | 'week'): string {
+  const date = new Date(timestamp)
+
+  switch (period) {
+    case 'hour':
+      return date.toISOString().slice(0, 13) + ':00'
+    case 'day':
+      return date.toISOString().slice(0, 10)
+    case 'week': {
+      const weekStart = new Date(date)
+      weekStart.setDate(date.getDate() - date.getDay())
+      return weekStart.toISOString().slice(0, 10)
+    }
+  }
+}
+
+/**
+ * Format relative time (e.g., "5 minutes ago")
+ */
+export function formatRelativeTime(timestamp: number): string {
+  const now = Date.now()
+  const diff = now - timestamp
+  const seconds = Math.floor(diff / 1000)
+  const minutes = Math.floor(seconds / 60)
+  const hours = Math.floor(minutes / 60)
+  const days = Math.floor(hours / 24)
+
+  if (seconds < 60) return 'just now'
+  if (minutes < 60) return `${minutes} minute${minutes > 1 ? 's' : ''} ago`
+  if (hours < 24) return `${hours} hour${hours > 1 ? 's' : ''} ago`
+  if (days < 7) return `${days} day${days > 1 ? 's' : ''} ago`
+
+  return new Date(timestamp).toLocaleDateString()
+}
+
+/**
+ * Format duration in milliseconds (e.g., "5.2s" or "250ms")
+ */
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  return `${(ms / 1000).toFixed(1)}s`
+}