traceperf 0.1.5 → 0.2.1

package/dist/core/optimized-performance-monitor.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Optimized Performance Monitoring Library
+ *
+ * This implementation incorporates all optimizations from benchmarking:
+ * 1. Tiered tracking modes for performance vs. detail balance
+ * 2. Context preservation for object methods
+ * 3. Async/Promise support
+ * 4. Browser/Node.js environment detection
+ * 5. Memory usage tracking optimizations
+ * 6. Module registration capability
+ * 7. Enhanced visualization
+ */
+export declare const TrackingModes: {
+    PERFORMANCE: string;
+    BALANCED: string;
+    DETAILED: string;
+    DEBUG: string;
+};
+/**
+ * Get current memory usage with environment detection
+ * @returns Memory usage in bytes
+ */
+export declare const getMemoryUsage: () => number;
+/**
+ * Get high-resolution timestamp with environment detection
+ * @returns Timestamp in nanoseconds
+ */
+export declare const getTimestamp: () => number;
+/**
+ * Calculate time difference between two timestamps
+ * @param startTime Starting timestamp in nanoseconds
+ * @returns Duration in nanoseconds
+ */
+export declare const getDuration: (startTime: number) => number;
+/**
+ * Interface for execution tracking options
+ */
+export interface ExecutionTrackerOptions {
+    trackingMode?: string;
+    silent?: boolean;
+    showMemoryUsage?: boolean;
+    enableNestedTracking?: boolean;
+    threshold?: number;
+}
+/**
+ * Interface for timer options
+ */
+export interface TimerOptions {
+    trackMemory?: boolean;
+    captureArgs?: boolean;
+    args?: any[];
+}
+/**
+ * Interface for execution data
+ */
+export interface ExecutionData {
+    id: string;
+    label: string;
+    startTime: number;
+    endTime: number;
+    duration: number;
+    parentId: string | null;
+    children: string[];
+    args?: string[];
+    complete: boolean;
+    memoryAtStart?: number;
+    memoryAtEnd?: number;
+    memoryDelta?: number;
+    result?: any;
+    error?: Error | null;
+}
+/**
+ * Optimized tracker for individual function executions
+ */
+export declare class OptimizedExecutionTracker {
+    private executionTree;
+    private currentExecutionId;
+    private activeExecutions;
+    showMemoryUsage: boolean;
+    enableNestedTracking: boolean;
+    silent: boolean;
+    trackingMode: string;
+    defaultThreshold: number;
+    private _formatters;
+    /**
+     * Create a new execution tracker
+     * @param options Tracker configuration options
+     */
+    constructor(options?: ExecutionTrackerOptions);
+    /**
+     * Start timing a function execution
+     * @param label Function name or label
+     * @param parentExecutionId ID of parent execution if nested
+     * @param options Additional options
+     * @returns Execution ID
+     */
+    startTimer(label: string, parentExecutionId?: string | null, options?: TimerOptions): string;
+    /**
+     * End timing a function execution
+     * @param executionId ID of the execution to end
+     * @param result Result of the function
+     * @param error Error if the function threw
+     * @returns Execution data
+     */
+    endTimer(executionId: string, result?: any, error?: Error | null): ExecutionData | null;
+    /**
+     * Generate a visualization of the execution flow
+     * @param execution The execution to visualize
+     * @param depth Current depth in the tree
+     * @param isLastChild Whether this is the last child
+     * @param ancestors Array tracking if parents were last children
+     * @returns Formatted execution flow chart
+     */
+    private _generateExecutionFlowChart;
+    /**
+     * Create a trackable version of a function
+     * @param fn Function to track
+     * @param options Tracking options
+     * @returns Tracked version of the function
+     */
+    createTrackable<T extends (...args: any[]) => any>(fn: T, options?: Record<string, any>): (...args: Parameters<T>) => ReturnType<T>;
+    /**
+     * Track a module's methods
+     * @param module Module to track
+     * @param options Tracking options
+     * @returns Tracked module
+     */
+    trackModule<T extends Record<string, any>>(module: T, options?: Record<string, any>): T;
+    /**
+     * Track a function execution directly
+     * @param fn Function to track
+     * @param options Tracking options
+     * @returns Function result
+     */
+    track<T>(fn: () => T, options?: Record<string, any>): T;
+    /**
+     * Reset the tracker state
+     */
+    reset(): void;
+}
+/**
+ * Interface for performance monitor options
+ */
+export interface PerformanceMonitorOptions {
+    trackingMode?: string;
+    silent?: boolean;
+    trackMemory?: boolean;
+    enableNestedTracking?: boolean;
+    threshold?: number;
+    sampleRate?: number;
+}
+/**
+ * Main performance monitoring interface
+ */
+export declare class OptimizedPerformanceMonitor {
+    private config;
+    private executionTracker;
+    /**
+     * Create a new performance monitor instance
+     * @param options Configuration options
+     */
+    constructor(options?: PerformanceMonitorOptions);
+    /**
+     * Track a function execution
+     * @param fn The function to track
+     * @param options Tracking options
+     * @returns Result of the tracked function
+     */
+    track<T>(fn: () => T, options?: Record<string, any>): T;
+    /**
+     * Create a trackable version of a function
+     * @param fn The function to track
+     * @param options Tracking options
+     * @returns Tracked version of the function
+     */
+    createTrackable<T extends (...args: any[]) => any>(fn: T, options?: Record<string, any>): (...args: Parameters<T>) => ReturnType<T>;
+    /**
+     * Register a module for tracking
+     * @param module The module or object containing methods to track
+     * @param options Tracking options
+     * @returns Modified module with tracked methods
+     */
+    registerModule<T extends Record<string, any>>(module: T, options?: Record<string, any>): T;
+    /**
+     * Set configuration options
+     * @param config Configuration to update
+     * @returns Current configuration after update
+     */
+    setConfig(config?: Partial<PerformanceMonitorOptions>): Record<string, any>;
+    /**
+     * Enable silent mode (no console output)
+     * @returns This instance for chaining
+     */
+    enableSilentMode(): OptimizedPerformanceMonitor;
+    /**
+     * Disable silent mode (allow console output)
+     * @returns This instance for chaining
+     */
+    disableSilentMode(): OptimizedPerformanceMonitor;
+    /**
+     * Set the tracking mode
+     * @param mode Tracking mode from TrackingMode enum
+     * @returns This instance for chaining
+     */
+    setTrackingMode(mode: string): OptimizedPerformanceMonitor;
+    /**
+     * Enable memory usage tracking
+     * @returns This instance for chaining
+     */
+    enableMemoryTracking(): OptimizedPerformanceMonitor;
+    /**
+     * Disable memory usage tracking
+     * @returns This instance for chaining
+     */
+    disableMemoryTracking(): OptimizedPerformanceMonitor;
+    /**
+     * Set the sampling rate
+     * @param rate Sampling rate between 0.0 and 1.0
+     * @returns This instance for chaining
+     */
+    setSampleRate(rate: number): OptimizedPerformanceMonitor;
+    /**
+     * Reset the tracker state
+     * @returns This instance for chaining
+     */
+    reset(): OptimizedPerformanceMonitor;
+}