@jmruthers/pace-core 0.5.118 → 0.5.120

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

@@ -1,609 +0,0 @@
-/**
- * @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();