traceperf 0.2.0 → 1.3.0

package/dist/esm/browser.d.ts

@@ -4,141 +4,58 @@
  * This file provides a browser-compatible version of TracePerf that can be used
  * in React, Next.js, or other frontend applications.
  */
-import { ILoggerConfig, LogMode, ITrackOptions } from './types';
+import type { TracePerfConfig, TrackOptions } from './types/options.js';
+import { OptimizedPerformanceMonitor } from './core/optimized-performance-monitor.js';
+import type { ExecutionRecord } from './core/records.js';
 export declare const TrackingMode: {
-    PERFORMANCE: string;
-    BALANCED: string;
-    DETAILED: string;
-    DEBUG: string;
+    readonly PERFORMANCE: "performance";
+    readonly BALANCED: "balanced";
+    readonly DETAILED: "detailed";
+    readonly DEBUG: "debug";
 };
 /**
- * Browser-compatible performance monitoring
+ * Configuration accepted by the browser createTracePerf()/BrowserLogger
  */
-declare class BrowserPerformanceMonitor {
-    private _timers;
-    private _defaultThreshold;
-    constructor(options?: {
-        defaultThreshold?: number;
-    });
-    startTimer(label: string): string;
-    endTimer(id: string): number;
-    isBottleneck(duration: number, threshold?: number): boolean;
-    /**
-     * Get memory usage from browser performance API
-     * @returns Memory usage object with heap metrics or undefined if not available
-     */
-    getMemoryUsage(): {
-        heapUsed: number;
-        heapTotal: number;
-        external: number;
-        rss: number;
-    } | undefined;
-    /**
-     * Calculate memory difference
-     * @param start - Starting memory usage
-     * @returns Memory difference in bytes
-     */
-    getMemoryDiff(start: {
-        heapUsed: number;
-    }): number;
-    now(): number;
-    generateSuggestion(functionName: string, duration: number, memoryUsage?: number): string;
-}
+/** Log levels for BrowserLogger's console methods */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
 /**
- * Browser-compatible execution tracker for tracking function calls and generating flow charts
+ * BrowserLogger console-method filtering:
+ * - dev: everything
+ * - staging: warn and error
+ * - prod: error only
  */
-declare class BrowserExecutionTracker {
-    private _callStack;
-    private _executions;
-    private _currentExecution;
-    private _defaultThreshold;
-    private _globalScope;
-    private _trackedFunctions;
-    private _performanceMonitor;
-    /**
-     * Create a new BrowserExecutionTracker instance
-     *
-     * @param options - Tracker options
-     */
-    constructor(options?: {
-        defaultThreshold?: number;
-    });
-    /**
-     * Generate a performance optimization suggestion based on execution duration
-     *
-     * @param name - Function name
-     * @param duration - Execution duration in ms
-     * @returns Optimization suggestion
-     */
-    private generateSuggestion;
-    /**
-     * Track the execution of a function
-     *
-     * @param fn - The function to track
-     * @param options - Options for tracking
-     * @returns The return value of the tracked function
-     */
-    track<T>(fn: () => T, options?: any): T;
-    /**
-     * Create a trackable version of a function
-     *
-     * This is a helper method to create a tracked version of a function
-     * that can be used for nested function tracking.
-     *
-     * @param fn - The function to make trackable
-     * @param options - Options for tracking
-     * @returns A tracked version of the function
-     */
-    createTrackable<T extends (...args: any[]) => any>(fn: T, options?: Omit<ITrackOptions, 'label'> & {
-        label?: string;
-    }): (...args: Parameters<T>) => ReturnType<T>;
-    /**
-     * Get the current call stack
-     *
-     * @returns The current call stack
-     */
-    getCallStack(): string[];
-    /**
-     * Generate a visual representation of the execution flow
-     *
-     * @returns ASCII flow chart of the execution
-     */
-    generateFlowChart(): string;
-    /**
-     * Prepare execution data for the flow chart
-     *
-     * @param executions - The execution records to prepare
-     * @returns A list of execution data
-     */
-    private prepareExecutionData;
-    /**
-     * Add children to the result list
-     *
-     * @param children - The children to add
-     * @param result - The result list
-     */
-    private addChildrenToResult;
-    /**
-     * Format memory size for display
-     * @param bytes Memory usage in bytes
-     * @returns Formatted string
-     */
-    private formatMemorySize;
-    /**
-     * Clear all execution records
-     */
-    clear(): void;
+export type LogMode = 'dev' | 'staging' | 'prod';
+/**
+ * Configuration accepted by the browser createTracePerf()/BrowserLogger
+ */
+export interface IBrowserTracePerfConfig extends TracePerfConfig {
+    /** Filtering for info/warn/error/debug (default "dev") */
+    mode?: LogMode;
+    /** Calls slower than this (ms) are marked [SLOW] when no threshold is set (default 100) */
+    performanceThreshold?: number;
+    /** Use an existing logger instead of creating a new one */
+    logger?: BrowserLogger;
 }
 /**
- * Browser-compatible logger
+ * Browser-compatible TracePerf instance.
+ *
+ * Shares the core tracker with the Node.js entry (same nesting, statistics,
+ * hooks, exporters and options) and adds console-style logging methods.
+ * Output uses the browser format:
+ *
+ *   Execution Flow:
+ *   → parent (12.34ms)
+ *     → child (10.01ms)
  */
-declare class BrowserLogger {
+declare class BrowserLogger extends OptimizedPerformanceMonitor {
     private _mode;
     private _indentLevel;
-    private _executionTracker;
-    private _performanceMonitor;
-    private _trackingMode;
-    constructor(config?: Partial<ILoggerConfig>);
+    private _slowThreshold;
+    constructor(config?: IBrowserTracePerfConfig);
+    /**
+     * Render an execution tree in the browser output format
+     */
+    formatFlow(root: ExecutionRecord): string;
     info(message: string | object, ...args: any[]): void;
     warn(message: string | object, ...args: any[]): void;
     error(message: string | object, ...args: any[]): void;
@@ -154,24 +71,10 @@ declare class BrowserLogger {
      */
     setTrackingMode(mode: string): BrowserLogger;
     /**
-     * Get the current tracking mode
-     * @returns Current tracking mode
-     */
-    getTrackingMode(): string;
-    track<T>(fn: () => T, options?: ITrackOptions): T;
-    /**
-     * Create a trackable version of a function
-     *
-     * This is a helper method to create a tracked version of a function
-     * that can be used for nested function tracking.
-     *
-     * @param fn - The function to make trackable
-     * @param options - Options for tracking
-     * @returns A tracked version of the function
+     * Create a trackable version of a function. Calls go through `track()`,
+     * so nested trackables attach to their caller.
      */
-    createTrackable<T extends (...args: any[]) => any>(fn: T, options?: Omit<ITrackOptions, 'label'> & {
-        label?: string;
-    }): (...args: Parameters<T>) => ReturnType<T>;
+    createTrackable<T extends (...args: any[]) => any>(fn: T, options?: TrackOptions): (...args: Parameters<T>) => ReturnType<T>;
     private log;
 }
 /**
@@ -179,14 +82,19 @@ declare class BrowserLogger {
  * @param config Configuration options
  * @returns Browser logger instance
  */
-export declare function createBrowserLogger(config?: Partial<ILoggerConfig>): BrowserLogger;
+export declare function createBrowserLogger(config?: IBrowserTracePerfConfig): BrowserLogger;
 /**
  * Create a browser-compatible TracePerf instance
  * Alias of createBrowserLogger for API consistency with Node.js version
  * @param config Configuration options
  * @returns Browser logger instance
  */
-export declare function createTracePerf(config?: Partial<ILoggerConfig>): BrowserLogger;
+export declare function createTracePerf(config?: IBrowserTracePerfConfig): BrowserLogger;
 declare const browserLogger: BrowserLogger;
 export default browserLogger;
-export { BrowserLogger, BrowserPerformanceMonitor, BrowserExecutionTracker };
+export { BrowserLogger };
+export { performanceTimeline } from './core/timeline.js';
+export { toChromeTrace, jsonLinesExporter, openTelemetryExporter, recordToJSON } from './core/exporters.js';
+export { formatTree } from './core/records.js';
+export { instrumentFetch } from './instrument.js';
+export type { ExecutionRecord, TracePerfPlugin } from './core/records.js';