@sc4rfurryx/proteusjs 1.0.0

package/src/utils/debounce.ts

@@ -0,0 +1,259 @@
+/**
+ * Debounce and throttle utilities for ProteusJS
+ * Optimizes performance by controlling function execution frequency
+ */
+
+export interface DebounceOptions {
+  leading?: boolean;
+  trailing?: boolean;
+  maxWait?: number;
+}
+
+export interface ThrottleOptions {
+  leading?: boolean;
+  trailing?: boolean;
+}
+
+/**
+ * Debounce function execution
+ */
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  wait: number,
+  options: DebounceOptions = {}
+): T & { cancel: () => void; flush: () => ReturnType<T> | undefined } {
+  const { leading = false, trailing = true, maxWait } = options;
+
+  let timeoutId: number | null = null;
+  let maxTimeoutId: number | null = null;
+  let lastCallTime: number | undefined;
+  let lastInvokeTime = 0;
+  let lastArgs: Parameters<T> | undefined;
+  let lastThis: unknown;
+  let result: ReturnType<T> | undefined;
+
+  function invokeFunc(time: number): ReturnType<T> {
+    const args = lastArgs!;
+    const thisArg = lastThis;
+
+    lastArgs = undefined;
+    lastThis = undefined;
+    lastInvokeTime = time;
+    result = func.apply(thisArg, args) as ReturnType<T>;
+    return result!;
+  }
+
+  function leadingEdge(time: number): ReturnType<T> {
+    lastInvokeTime = time;
+    timeoutId = window.setTimeout(timerExpired, wait);
+    return leading ? invokeFunc(time) : result!;
+  }
+
+  function remainingWait(time: number): number {
+    const timeSinceLastCall = time - lastCallTime!;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    const timeWaiting = wait - timeSinceLastCall;
+    
+    return maxWait !== undefined
+      ? Math.min(timeWaiting, maxWait - timeSinceLastInvoke)
+      : timeWaiting;
+  }
+
+  function shouldInvoke(time: number): boolean {
+    const timeSinceLastCall = time - lastCallTime!;
+    const timeSinceLastInvoke = time - lastInvokeTime;
+    
+    return (
+      lastCallTime === undefined ||
+      timeSinceLastCall >= wait ||
+      timeSinceLastCall < 0 ||
+      (maxWait !== undefined && timeSinceLastInvoke >= maxWait)
+    );
+  }
+
+  function timerExpired(): ReturnType<T> | undefined {
+    const time = Date.now();
+    if (shouldInvoke(time)) {
+      return trailingEdge(time);
+    }
+    timeoutId = window.setTimeout(timerExpired, remainingWait(time));
+    return undefined;
+  }
+
+  function trailingEdge(time: number): ReturnType<T> | undefined {
+    timeoutId = null;
+    
+    if (trailing && lastArgs) {
+      return invokeFunc(time);
+    }
+    lastArgs = undefined;
+    lastThis = undefined;
+    return result;
+  }
+
+  function cancel(): void {
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    if (maxTimeoutId !== null) {
+      clearTimeout(maxTimeoutId);
+      maxTimeoutId = null;
+    }
+    lastInvokeTime = 0;
+    lastArgs = undefined;
+    lastCallTime = undefined;
+    lastThis = undefined;
+  }
+
+  function flush(): ReturnType<T> | undefined {
+    return timeoutId === null ? result : trailingEdge(Date.now());
+  }
+
+  function debounced(this: unknown, ...args: Parameters<T>): ReturnType<T> | undefined {
+    const time = Date.now();
+    const isInvoking = shouldInvoke(time);
+    
+    lastArgs = args;
+    lastThis = this;
+    lastCallTime = time;
+    
+    if (isInvoking) {
+      if (timeoutId === null) {
+        return leadingEdge(lastCallTime);
+      }
+      if (maxWait !== undefined) {
+        timeoutId = window.setTimeout(timerExpired, wait);
+        return invokeFunc(lastCallTime);
+      }
+    }
+    if (timeoutId === null) {
+      timeoutId = window.setTimeout(timerExpired, wait);
+    }
+    return result;
+  }
+
+  debounced.cancel = cancel;
+  debounced.flush = flush;
+  
+  return debounced as T & { cancel: () => void; flush: () => ReturnType<T> | undefined };
+}
+
+/**
+ * Throttle function execution
+ */
+export function throttle<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  wait: number,
+  options: ThrottleOptions = {}
+): T & { cancel: () => void; flush: () => ReturnType<T> | undefined } {
+  const { leading = true, trailing = true } = options;
+  return debounce(func, wait, { leading, trailing, maxWait: wait });
+}
+
+/**
+ * Request animation frame based throttle
+ */
+export function rafThrottle<T extends (...args: unknown[]) => unknown>(
+  func: T
+): T & { cancel: () => void } {
+  let rafId: number | null = null;
+  let lastArgs: Parameters<T> | undefined;
+  let lastThis: unknown;
+
+  function throttled(this: unknown, ...args: Parameters<T>): void {
+    lastArgs = args;
+    lastThis = this;
+    
+    if (rafId === null) {
+      rafId = requestAnimationFrame(() => {
+        rafId = null;
+        if (lastArgs) {
+          func.apply(lastThis, lastArgs);
+          lastArgs = undefined;
+          lastThis = undefined;
+        }
+      });
+    }
+  }
+
+  function cancel(): void {
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    lastArgs = undefined;
+    lastThis = undefined;
+  }
+
+  throttled.cancel = cancel;
+  
+  return throttled as T & { cancel: () => void };
+}
+
+/**
+ * Idle callback based debounce
+ */
+export function idleDebounce<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  timeout: number = 5000
+): T & { cancel: () => void } {
+  let idleId: number | null = null;
+  let timeoutId: number | null = null;
+  let lastArgs: Parameters<T> | undefined;
+  let lastThis: unknown;
+
+  function debounced(this: unknown, ...args: Parameters<T>): void {
+    lastArgs = args;
+    lastThis = this;
+    
+    // Cancel previous calls
+    if (idleId !== null) {
+      cancelIdleCallback(idleId);
+      idleId = null;
+    }
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+
+    // Try to use idle callback
+    if (typeof requestIdleCallback !== 'undefined') {
+      idleId = requestIdleCallback(() => {
+        idleId = null;
+        if (lastArgs) {
+          func.apply(lastThis, lastArgs);
+          lastArgs = undefined;
+          lastThis = undefined;
+        }
+      }, { timeout });
+    } else {
+      // Fallback to setTimeout
+      timeoutId = window.setTimeout(() => {
+        timeoutId = null;
+        if (lastArgs) {
+          func.apply(lastThis, lastArgs);
+          lastArgs = undefined;
+          lastThis = undefined;
+        }
+      }, 16); // ~60fps fallback
+    }
+  }
+
+  function cancel(): void {
+    if (idleId !== null) {
+      cancelIdleCallback(idleId);
+      idleId = null;
+    }
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+      timeoutId = null;
+    }
+    lastArgs = undefined;
+    lastThis = undefined;
+  }
+
+  debounced.cancel = cancel;
+  
+  return debounced as T & { cancel: () => void };
+}

package/src/utils/performance.ts

@@ -0,0 +1,371 @@
+/**
+ * Performance utilities for ProteusJS
+ * Provides timing, measurement, and optimization tools
+ */
+
+export interface TimingMark {
+  name: string;
+  startTime: number;
+  endTime?: number;
+  duration?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PerformanceBudget {
+  responseTime: number; // Maximum response time in ms
+  frameRate: number;    // Minimum frame rate
+  memoryUsage: number;  // Maximum memory usage in MB
+}
+
+export class PerformanceTracker {
+  private marks: Map<string, TimingMark> = new Map();
+  private measurements: TimingMark[] = [];
+  private budget: PerformanceBudget;
+  private warningThreshold: number = 0.8; // 80% of budget
+
+  constructor(budget?: Partial<PerformanceBudget>) {
+    this.budget = {
+      responseTime: 60,  // 60ms default
+      frameRate: 60,     // 60fps default
+      memoryUsage: 100,  // 100MB default
+      ...budget
+    };
+  }
+
+  /**
+   * Start timing a performance mark
+   */
+  public mark(name: string, metadata?: Record<string, unknown>): void {
+    const mark: TimingMark = {
+      name,
+      startTime: performance.now(),
+      ...(metadata && { metadata })
+    };
+    
+    this.marks.set(name, mark);
+    
+    // Use Performance API if available
+    if (typeof performance.mark === 'function') {
+      performance.mark(`proteus-${name}-start`);
+    }
+  }
+
+  /**
+   * End timing a performance mark
+   */
+  public measure(name: string): TimingMark | null {
+    const mark = this.marks.get(name);
+    if (!mark) {
+      console.warn(`ProteusJS: Performance mark "${name}" not found`);
+      return null;
+    }
+
+    const endTime = performance.now();
+    const duration = endTime - mark.startTime;
+    
+    const measurement: TimingMark = {
+      ...mark,
+      endTime,
+      duration
+    };
+
+    this.measurements.push(measurement);
+    this.marks.delete(name);
+
+    // Use Performance API if available
+    if (typeof performance.mark === 'function' && typeof performance.measure === 'function') {
+      performance.mark(`proteus-${name}-end`);
+      performance.measure(`proteus-${name}`, `proteus-${name}-start`, `proteus-${name}-end`);
+    }
+
+    // Check against budget
+    this.checkBudget(measurement);
+
+    return measurement;
+  }
+
+  /**
+   * Get all measurements
+   */
+  public getMeasurements(): TimingMark[] {
+    return [...this.measurements];
+  }
+
+  /**
+   * Get measurements by name pattern
+   */
+  public getMeasurementsByPattern(pattern: RegExp): TimingMark[] {
+    return this.measurements.filter(m => pattern.test(m.name));
+  }
+
+  /**
+   * Get average duration for measurements with the same name
+   */
+  public getAverageDuration(name: string): number {
+    const matching = this.measurements.filter(m => m.name === name && m.duration !== undefined);
+    if (matching.length === 0) return 0;
+    
+    const total = matching.reduce((sum, m) => sum + (m.duration || 0), 0);
+    return total / matching.length;
+  }
+
+  /**
+   * Get performance statistics
+   */
+  public getStats(): Record<string, unknown> {
+    const stats: Record<string, unknown> = {
+      totalMeasurements: this.measurements.length,
+      activeMeasurements: this.marks.size,
+      budget: this.budget,
+      violations: this.getBudgetViolations()
+    };
+
+    // Group by name
+    const byName: Record<string, { count: number; avgDuration: number; maxDuration: number }> = {};
+    
+    this.measurements.forEach(m => {
+      if (m.duration === undefined) return;
+      
+      if (!byName[m.name]) {
+        byName[m.name] = { count: 0, avgDuration: 0, maxDuration: 0 };
+      }
+      
+      byName[m.name]!.count++;
+      byName[m.name]!.maxDuration = Math.max(byName[m.name]!.maxDuration, m.duration);
+    });
+
+    // Calculate averages
+    Object.keys(byName).forEach(name => {
+      byName[name]!.avgDuration = this.getAverageDuration(name);
+    });
+
+    stats['byName'] = byName;
+    return stats;
+  }
+
+  /**
+   * Clear all measurements
+   */
+  public clear(): void {
+    this.measurements.length = 0;
+    this.marks.clear();
+  }
+
+  /**
+   * Update performance budget
+   */
+  public updateBudget(budget: Partial<PerformanceBudget>): void {
+    this.budget = { ...this.budget, ...budget };
+  }
+
+  /**
+   * Check measurement against budget
+   */
+  private checkBudget(measurement: TimingMark): void {
+    if (measurement.duration === undefined) return;
+
+    const warningThreshold = this.budget.responseTime * this.warningThreshold;
+    const errorThreshold = this.budget.responseTime;
+
+    if (measurement.duration > errorThreshold) {
+      console.error(
+        `ProteusJS: Performance budget exceeded for "${measurement.name}": ${measurement.duration.toFixed(2)}ms > ${errorThreshold}ms`
+      );
+    } else if (measurement.duration > warningThreshold) {
+      console.warn(
+        `ProteusJS: Performance warning for "${measurement.name}": ${measurement.duration.toFixed(2)}ms > ${warningThreshold.toFixed(2)}ms`
+      );
+    }
+  }
+
+  /**
+   * Get budget violations
+   */
+  private getBudgetViolations(): TimingMark[] {
+    return this.measurements.filter(m => 
+      m.duration !== undefined && m.duration > this.budget.responseTime
+    );
+  }
+}
+
+/**
+ * Global performance tracker instance
+ */
+export const performanceTracker = new PerformanceTracker();
+
+/**
+ * Decorator for automatic performance tracking
+ */
+export function trackPerformance(name?: string): (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor {
+  return function (target: unknown, propertyKey: string, descriptor: PropertyDescriptor): PropertyDescriptor {
+    const originalMethod = descriptor.value;
+    const trackingName = name || `${(target as { constructor: { name: string } }).constructor.name}.${propertyKey}`;
+
+    descriptor.value = function (...args: unknown[]): unknown {
+      performanceTracker.mark(trackingName);
+      
+      try {
+        const result = originalMethod.apply(this, args);
+        
+        // Handle async methods
+        if (result && typeof result.then === 'function') {
+          return result.finally(() => {
+            performanceTracker.measure(trackingName);
+          });
+        }
+        
+        performanceTracker.measure(trackingName);
+        return result;
+      } catch (error) {
+        performanceTracker.measure(trackingName);
+        throw error;
+      }
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Measure function execution time
+ */
+export function measureTime<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  name?: string
+): T {
+  const measureName = name || func.name || 'anonymous';
+
+  return ((...args: unknown[]) => {
+    performanceTracker.mark(measureName);
+    
+    try {
+      const result = func(...args);
+      
+      // Handle async functions
+      if (result && typeof (result as { then?: unknown }).then === 'function') {
+        return (result as Promise<unknown>).finally(() => {
+          performanceTracker.measure(measureName);
+        });
+      }
+      
+      performanceTracker.measure(measureName);
+      return result;
+    } catch (error) {
+      performanceTracker.measure(measureName);
+      throw error;
+    }
+  }) as T;
+}
+
+/**
+ * Create a performance-aware wrapper for frequently called functions
+ */
+export function createPerformanceWrapper<T extends (...args: unknown[]) => unknown>(
+  func: T,
+  options: {
+    name?: string;
+    sampleRate?: number; // 0-1, percentage of calls to measure
+    budget?: number; // ms
+  } = {}
+): T {
+  const { name = func.name || 'wrapped', sampleRate = 0.1, budget = 16 } = options;
+  let callCount = 0;
+  let totalTime = 0;
+  let maxTime = 0;
+
+  return ((...args: unknown[]) => {
+    callCount++;
+    const shouldMeasure = Math.random() < sampleRate;
+    
+    if (shouldMeasure) {
+      const startTime = performance.now();
+      
+      try {
+        const result = func(...args);
+        
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        
+        totalTime += duration;
+        maxTime = Math.max(maxTime, duration);
+        
+        if (duration > budget) {
+          console.warn(
+            `ProteusJS: Performance budget exceeded in ${name}: ${duration.toFixed(2)}ms > ${budget}ms`
+          );
+        }
+        
+        return result;
+      } catch (error) {
+        const endTime = performance.now();
+        const duration = endTime - startTime;
+        totalTime += duration;
+        maxTime = Math.max(maxTime, duration);
+        throw error;
+      }
+    } else {
+      return func(...args);
+    }
+  }) as T;
+}
+
+/**
+ * Get browser performance information
+ */
+export function getBrowserPerformanceInfo(): object {
+  const info: any = {
+    timing: {},
+    memory: {},
+    navigation: {}
+  };
+
+  // Navigation timing (using modern API)
+  try {
+    const navigationEntries = performance.getEntriesByType('navigation') as PerformanceNavigationTiming[];
+    if (navigationEntries.length > 0) {
+      const nav = navigationEntries[0]!;
+      info.timing = {
+        domContentLoaded: nav.domContentLoadedEventEnd - nav.domContentLoadedEventStart,
+        loadComplete: nav.loadEventEnd - nav.loadEventStart,
+        domInteractive: nav.domInteractive - nav.fetchStart
+      };
+    }
+  } catch (error) {
+    // Modern browsers should support performance.getEntriesByType
+    // If not available, we'll just skip the timing information
+    console.warn('ProteusJS: Performance timing API not available', error);
+  }
+
+  // Memory info
+  if ('memory' in performance) {
+    const memory = (performance as any).memory;
+    info.memory = {
+      usedJSHeapSize: memory.usedJSHeapSize,
+      totalJSHeapSize: memory.totalJSHeapSize,
+      jsHeapSizeLimit: memory.jsHeapSizeLimit
+    };
+  }
+
+  // Navigation info (using modern API)
+  try {
+    const navigationEntries = performance.getEntriesByType('navigation') as PerformanceNavigationTiming[];
+    if (navigationEntries.length > 0) {
+      const nav = navigationEntries[0]!;
+      info.navigation = {
+        type: nav.type === 'navigate' ? 0 : nav.type === 'reload' ? 1 : nav.type === 'back_forward' ? 2 : 255,
+        redirectCount: nav.redirectCount || 0
+      };
+    }
+  } catch (error) {
+    // Fallback for older browsers (deprecated APIs)
+    const perfAny = performance as any;
+    if (perfAny.navigation) {
+      info.navigation = {
+        type: perfAny.navigation.type,
+        redirectCount: perfAny.navigation.redirectCount
+      };
+    }
+  }
+
+  return info;
+}