@jmruthers/pace-core 0.5.76 → 0.5.78

package/src/components/DataTable/utils/debugTools.ts

@@ -0,0 +1,609 @@
+/**
+ * @file Advanced Debugging Tools for DataTable Performance
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils/DebugTools
+ * @since 0.3.0
+ */
+
+import React from 'react';
+import type { 
+  DataRecord, 
+  PaginationMode,
+  ServerSideParams 
+} from '../types';
+import { createLogger } from '../../../utils/logger';
+
+/**
+ * Debug levels for controlling verbosity
+ */
+export enum DebugLevel {
+  NONE = 0,
+  ERROR = 1,
+  WARN = 2,
+  INFO = 3,
+  DEBUG = 4,
+  TRACE = 5,
+}
+
+/**
+ * Performance debug configuration
+ */
+export interface DebugConfig {
+  enabled: boolean;
+  level: DebugLevel;
+  logToConsole: boolean;
+  logToStorage: boolean;
+  maxLogEntries: number;
+  enablePerformanceMarks: boolean;
+  enableMemoryTracking: boolean;
+  enableRenderTracking: boolean;
+  enableNetworkTracking: boolean;
+}
+
+/**
+ * Default debug configuration
+ */
+export const DEFAULT_DEBUG_CONFIG: DebugConfig = {
+  enabled: import.meta.env.MODE === 'development',
+  level: DebugLevel.INFO,
+  logToConsole: true,
+  logToStorage: false,
+  maxLogEntries: 1000,
+  enablePerformanceMarks: true,
+  enableMemoryTracking: true,
+  enableRenderTracking: true,
+  enableNetworkTracking: true,
+};
+
+/**
+ * Debug log entry interface
+ */
+export interface DebugLogEntry {
+  timestamp: number;
+  level: DebugLevel;
+  category: string;
+  message: string;
+  data?: unknown;
+  stackTrace?: string;
+  performanceMarks?: string[];
+  memoryUsage?: number;
+}
+
+/**
+ * Performance timeline entry
+ */
+export interface PerformanceTimelineEntry {
+  id: string;
+  operation: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  metadata?: Record<string, unknown>;
+  children?: PerformanceTimelineEntry[];
+}
+
+/**
+ * Memory snapshot
+ */
+export interface MemorySnapshot {
+  timestamp: number;
+  heapUsed: number;
+  heapTotal: number;
+  external: number;
+  arrayBuffers?: number;
+}
+
+/**
+ * Render performance data
+ */
+export interface RenderPerformanceData {
+  componentName: string;
+  renderCount: number;
+  totalRenderTime: number;
+  averageRenderTime: number;
+  lastRenderTime: number;
+  propsChanges: number;
+}
+
+/**
+ * Advanced DataTable debugger
+ */
+export class DataTableDebugger {
+  private config: DebugConfig
+  private logger = createLogger('DataTableDebugger');
+  private logEntries: DebugLogEntry[] = [];
+  private performanceTimeline: Map<string, PerformanceTimelineEntry> = new Map();
+  private memorySnapshots: MemorySnapshot[] = [];
+  private renderPerformance: Map<string, RenderPerformanceData> = new Map();
+  private activeOperations: Set<string> = new Set();
+
+  constructor(config: Partial<DebugConfig> = {}) {
+    this.config = { ...DEFAULT_DEBUG_CONFIG, ...config };
+  }
+
+  /**
+   * Log a debug message
+   */
+  log(
+    level: DebugLevel, 
+    category: string, 
+    message: string, 
+    data?: unknown,
+    includeStackTrace: boolean = false
+  ): void {
+    if (!this.config.enabled || level > this.config.level) {
+      return;
+    }
+
+    const entry: DebugLogEntry = {
+      timestamp: Date.now(),
+      level,
+      category,
+      message,
+      data,
+      stackTrace: includeStackTrace ? new Error().stack : undefined,
+      memoryUsage: this.config.enableMemoryTracking ? this.getCurrentMemoryUsage() : undefined,
+    };
+
+    this.logEntries.push(entry);
+
+    // Maintain log size
+    if (this.logEntries.length > this.config.maxLogEntries) {
+      this.logEntries.shift();
+    }
+
+    // Console logging
+    if (this.config.logToConsole) {
+      this.logToConsole(entry);
+    }
+
+    // Storage logging
+    if (this.config.logToStorage) {
+      this.logToStorage(entry);
+    }
+  }
+
+  /**
+   * Start performance tracking for an operation
+   */
+  startOperation(operationId: string, operation: string, metadata?: Record<string, unknown>): void {
+    if (!this.config.enabled || !this.config.enableRenderTracking) return;
+
+    const entry: PerformanceTimelineEntry = {
+      id: operationId,
+      operation,
+      startTime: performance.now(),
+      metadata,
+      children: [],
+    };
+
+    this.performanceTimeline.set(operationId, entry);
+    this.activeOperations.add(operationId);
+
+    // Performance marks
+    if (this.config.enablePerformanceMarks) {
+      performance.mark(`${operationId}_start`);
+    }
+
+    this.log(DebugLevel.DEBUG, 'Performance', `Started operation: ${operation}`, { operationId, metadata });
+  }
+
+  /**
+   * End performance tracking for an operation
+   */
+  endOperation(operationId: string, metadata?: Record<string, unknown>): void {
+    if (!this.config.enabled || !this.config.enableRenderTracking) return;
+
+    const entry = this.performanceTimeline.get(operationId);
+    if (!entry) {
+      this.log(DebugLevel.WARN, 'Performance', `Operation not found: ${operationId}`);
+      return;
+    }
+
+    entry.endTime = performance.now();
+    entry.duration = entry.endTime - entry.startTime;
+    if (metadata) {
+      entry.metadata = { ...entry.metadata, ...metadata };
+    }
+
+    this.activeOperations.delete(operationId);
+
+    // Performance marks and measures
+    if (this.config.enablePerformanceMarks) {
+      performance.mark(`${operationId}_end`);
+      performance.measure(operationId, `${operationId}_start`, `${operationId}_end`);
+    }
+
+    this.log(DebugLevel.DEBUG, 'Performance', `Completed operation: ${entry.operation}`, {
+      operationId,
+      duration: entry.duration,
+      metadata: entry.metadata,
+    });
+  }
+
+  /**
+   * Track render performance
+   */
+  trackRender(componentName: string, renderTime: number, propsChanged: boolean = false): void {
+    if (!this.config.enabled || !this.config.enableRenderTracking) return;
+
+    const existing = this.renderPerformance.get(componentName) || {
+      componentName,
+      renderCount: 0,
+      totalRenderTime: 0,
+      averageRenderTime: 0,
+      lastRenderTime: 0,
+      propsChanges: 0,
+    };
+
+    existing.renderCount++;
+    existing.totalRenderTime += renderTime;
+    existing.averageRenderTime = existing.totalRenderTime / existing.renderCount;
+    existing.lastRenderTime = renderTime;
+    
+    if (propsChanged) {
+      existing.propsChanges++;
+    }
+
+    this.renderPerformance.set(componentName, existing);
+
+    this.log(DebugLevel.TRACE, 'Render', `Component rendered: ${componentName}`, {
+      renderTime,
+      propsChanged,
+      averageRenderTime: existing.averageRenderTime,
+    });
+  }
+
+  /**
+   * Take a memory snapshot
+   */
+  takeMemorySnapshot(label?: string): MemorySnapshot {
+    const snapshot: MemorySnapshot = {
+      timestamp: Date.now(),
+      heapUsed: 0,
+      heapTotal: 0,
+      external: 0,
+    };
+
+    if ('memory' in performance) {
+      interface PerformanceMemory {
+        usedJSHeapSize: number;
+        totalJSHeapSize: number;
+        jsHeapSizeLimit: number;
+      }
+      const memory = (performance as unknown as { memory: PerformanceMemory }).memory;
+      snapshot.heapUsed = memory.usedJSHeapSize;
+      snapshot.heapTotal = memory.totalJSHeapSize;
+      snapshot.external = memory.usedJSHeapSize;
+    }
+
+    this.memorySnapshots.push(snapshot);
+
+    // Keep last 100 snapshots
+    if (this.memorySnapshots.length > 100) {
+      this.memorySnapshots.shift();
+    }
+
+    this.log(DebugLevel.DEBUG, 'Memory', `Memory snapshot${label ? ` (${label})` : ''}`, snapshot);
+
+    return snapshot;
+  }
+
+  /**
+   * Analyze performance bottlenecks
+   */
+  analyzePerformance(): {
+    slowestOperations: PerformanceTimelineEntry[];
+    memoryTrends: { increasing: boolean; trend: number };
+    renderHotspots: RenderPerformanceData[];
+    recommendations: string[];
+  } {
+    const timeline = Array.from(this.performanceTimeline.values())
+      .filter(entry => entry.duration !== undefined)
+      .sort((a, b) => (b.duration || 0) - (a.duration || 0));
+
+    const slowestOperations = timeline.slice(0, 10);
+
+    // Memory trend analysis
+    const recentSnapshots = this.memorySnapshots.slice(-10);
+    const memoryTrend = recentSnapshots.length > 1 
+      ? (recentSnapshots[recentSnapshots.length - 1].heapUsed - recentSnapshots[0].heapUsed) / recentSnapshots.length
+      : 0;
+
+    // Render hotspots
+    const renderHotspots = Array.from(this.renderPerformance.values())
+      .sort((a, b) => b.averageRenderTime - a.averageRenderTime)
+      .slice(0, 5);
+
+    // Generate recommendations
+    const recommendations: string[] = [];
+    
+    if (slowestOperations.length > 0 && slowestOperations[0].duration! > 100) {
+      recommendations.push(`Consider optimizing ${slowestOperations[0].operation} (${slowestOperations[0].duration!.toFixed(2)}ms)`);
+    }
+    
+    if (memoryTrend > 1024 * 1024) { // 1MB increase per snapshot
+      recommendations.push('Memory usage is increasing rapidly - check for memory leaks');
+    }
+    
+    if (renderHotspots.length > 0 && renderHotspots[0].averageRenderTime > 16.67) { // 60fps threshold
+      recommendations.push(`${renderHotspots[0].componentName} is rendering slowly - consider memoization`);
+    }
+
+    return {
+      slowestOperations,
+      memoryTrends: {
+        increasing: memoryTrend > 0,
+        trend: memoryTrend,
+      },
+      renderHotspots,
+      recommendations,
+    };
+  }
+
+  /**
+   * Generate performance report
+   */
+  generateReport(): {
+    summary: {
+      totalOperations: number;
+      averageOperationTime: number;
+      totalRenders: number;
+      memorySnapshots: number;
+      logEntries: number;
+    };
+    performance: {
+      slowestOperations: PerformanceTimelineEntry[];
+      memoryTrends: { increasing: boolean; trend: number };
+      renderHotspots: RenderPerformanceData[];
+      recommendations: string[];
+    };
+    logs: DebugLogEntry[];
+    timeline: PerformanceTimelineEntry[];
+  } {
+    const completedOperations = Array.from(this.performanceTimeline.values())
+      .filter(op => op.duration !== undefined);
+
+    const averageOperationTime = completedOperations.length > 0
+      ? completedOperations.reduce((sum, op) => sum + (op.duration || 0), 0) / completedOperations.length
+      : 0;
+
+    const totalRenders = Array.from(this.renderPerformance.values())
+      .reduce((sum, data) => sum + data.renderCount, 0);
+
+    return {
+      summary: {
+        totalOperations: completedOperations.length,
+        averageOperationTime,
+        totalRenders,
+        memorySnapshots: this.memorySnapshots.length,
+        logEntries: this.logEntries.length,
+      },
+      performance: this.analyzePerformance(),
+      logs: this.logEntries.slice(-50), // Last 50 logs
+      timeline: Array.from(this.performanceTimeline.values()),
+    };
+  }
+
+  /**
+   * Export debug data
+   */
+  exportDebugData(): string {
+    const report = this.generateReport();
+    return JSON.stringify(report, null, 2);
+  }
+
+  /**
+   * Clear all debug data
+   */
+  clear(): void {
+    this.logEntries = [];
+    this.performanceTimeline.clear();
+    this.memorySnapshots = [];
+    this.renderPerformance.clear();
+    this.activeOperations.clear();
+  }
+
+  /**
+   * Get current memory usage
+   */
+  private getCurrentMemoryUsage(): number {
+    if ('memory' in performance) {
+      interface PerformanceMemory {
+        usedJSHeapSize: number;
+        totalJSHeapSize: number;
+        jsHeapSizeLimit: number;
+      }
+      const memory = (performance as unknown as { memory: PerformanceMemory }).memory;
+      return memory.usedJSHeapSize / (1024 * 1024); // MB
+    }
+    return 0;
+  }
+
+  /**
+   * Log to console with appropriate styling
+   */
+  private logToConsole(entry: DebugLogEntry): void {
+    const timestamp = new Date(entry.timestamp).toISOString();
+    const levelName = DebugLevel[entry.level];
+    const message = `[${timestamp}] [${levelName}] [${entry.category}] ${entry.message}`;
+
+    switch (entry.level) {
+      case DebugLevel.ERROR:
+        this.logger.error(message, entry.data);
+        break;
+      case DebugLevel.WARN:
+        this.logger.warn(message, entry.data);
+        break;
+      case DebugLevel.INFO:
+        this.logger.info(message, entry.data);
+        break;
+      case DebugLevel.DEBUG:
+      case DebugLevel.TRACE:
+        this.logger.debug(message, entry.data);
+        break;
+    }
+  }
+
+  /**
+   * Log to local storage
+   */
+  private logToStorage(entry: DebugLogEntry): void {
+    if (typeof window === 'undefined') return;
+    
+    try {
+      const stored = localStorage.getItem('datatable-debug-logs');
+      const logs = stored ? JSON.parse(stored) : [];
+      logs.push(entry);
+      
+      // Keep last 500 entries
+      if (logs.length > 500) {
+        logs.splice(0, logs.length - 500);
+      }
+      
+      localStorage.setItem('datatable-debug-logs', JSON.stringify(logs));
+    } catch (error) {
+        this.logger.warn('Failed to store debug log:', error);
+    }
+  }
+}
+
+/**
+ * Global debugger instance
+ */
+export const dataTableDebugger = new DataTableDebugger();
+
+/**
+ * Performance profiler decorator
+ */
+export function profile(operation: string) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (this: unknown, ...args: unknown[]) {
+      const operationId = `${target.constructor.name}.${propertyKey}_${Date.now()}`;
+      
+      dataTableDebugger.startOperation(operationId, operation, {
+        className: target.constructor.name,
+        methodName: propertyKey,
+        args: args.length,
+      });
+
+      try {
+        const result = await originalMethod.apply(this, args);
+        dataTableDebugger.endOperation(operationId, { success: true });
+        return result;
+      } catch (error) {
+        dataTableDebugger.endOperation(operationId, { success: false, error: error instanceof Error ? error.message : String(error) });
+        dataTableDebugger.log(DebugLevel.ERROR, 'Performance', `Operation failed: ${operation}`, error);
+        throw error;
+      }
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Memory monitoring utility
+ */
+export class MemoryMonitor {
+  private debuggerInstance: DataTableDebugger;
+  private intervalId: NodeJS.Timeout | null = null;
+
+  constructor(debuggerInstance: DataTableDebugger = dataTableDebugger) {
+    this.debuggerInstance = debuggerInstance;
+  }
+
+  start(interval: number = 5000): void {
+    this.stop(); // Stop any existing monitoring
+    
+    this.intervalId = setInterval(() => {
+      this.debuggerInstance.takeMemorySnapshot('periodic');
+    }, interval);
+  }
+
+  stop(): void {
+    if (this.intervalId) {
+      clearInterval(this.intervalId);
+      this.intervalId = null;
+    }
+  }
+}
+
+/**
+ * Performance monitoring React hook
+ */
+export function usePerformanceDebugger(componentName: string) {
+  const startTime = React.useRef<number>(0);
+
+  React.useEffect(() => {
+    startTime.current = performance.now();
+    
+    return () => {
+      const renderTime = performance.now() - startTime.current;
+      dataTableDebugger.trackRender(componentName, renderTime);
+    };
+  });
+
+  const trackOperation = React.useCallback((operation: string, fn: () => unknown) => {
+    const operationId = `${componentName}_${operation}_${Date.now()}`;
+    dataTableDebugger.startOperation(operationId, operation);
+    
+    try {
+      const result = fn();
+      dataTableDebugger.endOperation(operationId);
+      return result;
+    } catch (error) {
+      dataTableDebugger.endOperation(operationId, { error: error instanceof Error ? error.message : String(error) });
+      throw error;
+    }
+  }, [componentName]);
+
+  return {
+    trackOperation,
+    log: (level: DebugLevel, message: string, data?: unknown) => 
+      dataTableDebugger.log(level, componentName, message, data),
+  };
+}
+
+/**
+ * Development tools integration
+ */
+export function setupDevTools(): void {
+  if (typeof window === 'undefined' || import.meta.env.MODE !== 'development') {
+    return;
+  }
+
+  // Expose debugger to global scope for browser dev tools
+  interface WindowWithDataTableDebugger extends Window {
+    __DATATABLE_DEBUGGER__: typeof dataTableDebugger;
+    dataTableDebug: {
+      getReport: () => ReturnType<typeof dataTableDebugger.generateReport>;
+      exportData: () => ReturnType<typeof dataTableDebugger.exportDebugData>;
+      clearLogs: () => void;
+      takeSnapshot: (label?: string) => ReturnType<typeof dataTableDebugger.takeMemorySnapshot>;
+      analyze: () => ReturnType<typeof dataTableDebugger.analyzePerformance>;
+    };
+  }
+  
+  const windowWithDebugger = window as unknown as WindowWithDataTableDebugger;
+  windowWithDebugger.__DATATABLE_DEBUGGER__ = dataTableDebugger;
+
+  // Add console commands
+  windowWithDebugger.dataTableDebug = {
+    getReport: () => dataTableDebugger.generateReport(),
+    exportData: () => dataTableDebugger.exportDebugData(),
+    clearLogs: () => dataTableDebugger.clear(),
+    takeSnapshot: (label?: string) => dataTableDebugger.takeMemorySnapshot(label),
+    analyze: () => dataTableDebugger.analyzePerformance(),
+  };
+
+  createLogger('DataTableDebugTools').info('Debug Tools loaded. Use window.dataTableDebug for debugging.');
+}
+
+/**
+ * Initialize debugging tools
+ */
+setupDevTools();