traceperf 0.1.5 → 0.2.0

package/README.md

@@ -1,20 +1,20 @@
 # TracePerf
 
-Advanced console logging & performance tracking for Node.js applications.
+Advanced performance tracking and execution monitoring for Node.js applications.
 
 [![npm version](https://img.shields.io/npm/v/traceperf.svg)](https://www.npmjs.com/package/traceperf)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
 ## Features
 
-- **Structured and Visually Appealing Logs**: A better alternative to `console.log()` with colors, icons, and formatting.
-- **Execution Flow Tracing**: Track function calls and visualize the execution flow with ASCII art.
-- **Nested Function Tracking**: Multiple approaches to track nested function calls with detailed visualization.
-- **Performance Bottleneck Detection**: Identify slow functions and get suggestions for optimization.
-- **Conditional Logging Modes**: Different logging levels for development, staging, and production.
-- **Nested Logging**: Group related logs with indentation for better readability.
-- **Auto-Remove Debug Logs**: Automatically filter out debug logs in production.
-- **Universal Module Compatibility**: Works with both CommonJS and ESM environments.
+- **High-Performance Execution Monitoring**: Track function execution time with minimal overhead
+- **Memory Usage Tracking**: Monitor memory consumption of your functions and identify memory leaks
+- **Flexible Tracking Modes**: Choose between performance, balanced, and detailed tracking based on your needs
+- **Execution Flow Visualization**: Visualize execution flows with intelligent formatting
+- **Nested Function Tracking**: Track function calls within other functions to understand complex flows
+- **Customizable Threshold Detection**: Focus on functions that exceed specific execution time thresholds
+- **Sampling Control**: Adjust sampling rates to minimize performance impact in production
+- **Universal Module Compatibility**: Works with both CommonJS and ESM environments
 
 ## Installation
 
@@ -22,296 +22,300 @@ Advanced console logging & performance tracking for Node.js applications.
 npm install traceperf
 ```
 
-## Basic Usage
-
-### CommonJS (Node.js)
+## Quick Start
 
 ```javascript
-const tracePerf = require('traceperf');
-
-// Basic logging
-tracePerf.info('This is an info message');
-tracePerf.warn('This is a warning message');
-tracePerf.error('This is an error message');
-tracePerf.debug('This is a debug message');
-
-// Logging with objects
-tracePerf.info('User data:', { id: 1, name: 'John Doe' });
-
-// Nested logging with groups
-tracePerf.group('User Authentication');
-tracePerf.info('Checking credentials');
-tracePerf.warn('Invalid password attempt');
-tracePerf.groupEnd();
+const traceperf = require('traceperf');
+
+// Track a synchronous function
+const result = traceperf.track(() => {
+  // Your code here
+  return 'result';
+}, { label: 'myFunction' });
+
+// Track an asynchronous function
+async function main() {
+  const result = await traceperf.track(async () => {
+    // Your async code here
+    return 'async result';
+  }, { label: 'asyncFunction' });
+}
 ```
 
-### ESM (ECMAScript Modules)
+## Tracking Modes
+
+TracePerf provides different tracking modes to balance performance with detail:
 
 ```javascript
-import tracePerf from 'traceperf';
+const { TrackingMode, createTracePerf } = require('traceperf');
+
+// Create a custom instance with performance-focused tracking
+const performanceTracker = createTracePerf({
+  trackingMode: TrackingMode.PERFORMANCE,
+  silent: true,
+  threshold: 100, // only track functions that take more than 100ms
+  sampleRate: 0.1 // only track 10% of function calls
+});
 
-// Use the same API as with CommonJS
-tracePerf.info('This is an info message');
+// Create a custom instance with detailed tracking for development
+const devTracker = createTracePerf({
+  trackingMode: TrackingMode.DETAILED,
+  trackMemory: true,
+  enableNestedTracking: true
+});
 ```
 
-
-
-## Conditional Logging Modes
+## Tracking Individual Functions
 
 ```javascript
-// Development mode (default)
-tracePerf.setMode('dev');
-tracePerf.debug('Debug message'); // Shown
-tracePerf.info('Info message');   // Shown
-tracePerf.warn('Warning message'); // Shown
-tracePerf.error('Error message'); // Shown
-
-// Staging mode
-tracePerf.setMode('staging');
-tracePerf.debug('Debug message'); // Not shown
-tracePerf.info('Info message');   // Not shown
-tracePerf.warn('Warning message'); // Shown
-tracePerf.error('Error message'); // Shown
-
-// Production mode
-tracePerf.setMode('prod');
-tracePerf.debug('Debug message'); // Not shown
-tracePerf.info('Info message');   // Not shown
-tracePerf.warn('Warning message'); // Not shown
-tracePerf.error('Error message'); // Shown
-```
+// Track a single function execution
+const result = traceperf.track(() => {
+  // Function body
+  return someValue;
+}, {
+  label: 'functionName',
+  threshold: 50, // ms
+  trackMemory: true
+});
 
-## Browser Usage (React, Next.js, etc.)
+// Create a trackable version of an existing function
+const myFunction = (a, b) => a + b;
+const trackedFunction = traceperf.createTrackable(myFunction, { 
+  label: 'addition' 
+});
 
-TracePerf also provides a browser-compatible version for use in frontend applications:
+// Now use it normally
+const sum = trackedFunction(5, 3); // will be tracked
+```
 
-### ESM (Modern Browsers)
+## Tracking Methods in a Module
 
 ```javascript
-// Import the browser version
-import tracePerf from 'traceperf/browser';
+const userService = {
+  getUser: async (id) => { /* implementation */ },
+  updateUser: async (id, data) => { /* implementation */ },
+  deleteUser: async (id) => { /* implementation */ }
+};
+
+// Register all methods for tracking
+const trackedUserService = traceperf.registerModule(userService);
 
-// Use it just like the Node.js version
-tracePerf.info('This works in the browser!');
+// Now all method calls will be tracked
+const user = await trackedUserService.getUser(123);
 ```
 
-### CommonJS (Bundlers with CommonJS support)
+## Advanced Configuration
 
 ```javascript
-// Import the browser version with require
-const tracePerf = require('traceperf/browser');
+const { createTracePerf, TrackingMode } = require('traceperf');
 
-// Use it just like the Node.js version
-tracePerf.info('This works in the browser with CommonJS bundlers!');
+const customTracker = createTracePerf({
+  // Tracking mode affects detail level and performance impact
+  trackingMode: TrackingMode.BALANCED,
+  
+  // Enable or disable performance statistics in console
+  silent: false,
+  
+  // Track memory usage (slight performance impact)
+  trackMemory: true,
+  
+  // Enable tracking of nested function calls
+  enableNestedTracking: true,
+  
+  // Minimum execution time to track (milliseconds)
+  threshold: 50,
+  
+  // Percentage of function calls to track (0.0 to 1.0)
+  sampleRate: 1.0
+});
 ```
 
-### Browser Example
+## Browser Support
 
-```javascript
-// Import using your preferred method
-import tracePerf from 'traceperf/browser';
+TracePerf includes a browser-compatible version:
 
-// Track function performance
-function expensiveCalculation() {
-  // ...complex logic
-  return result;
-}
-
-const result = tracePerf.track(expensiveCalculation);
-```
+```javascript
+import traceperf from 'traceperf/browser';
 
-### React Component Example
-
-```jsx
-import React, { useEffect } from 'react';
-import tracePerf from 'traceperf/browser';
-
-function DataComponent() {
-  useEffect(() => {
-    tracePerf.group('Component Lifecycle');
-    tracePerf.info('Component mounted');
-    
-    // Fetch data with performance tracking
-    tracePerf.track(async () => {
-      const data = await fetchData();
-      // Process data...
-    }, { label: 'fetchAndProcessData', threshold: 300 });
-    
-    return () => {
-      tracePerf.info('Component unmounting');
-      tracePerf.groupEnd();
-    };
-  }, []);
-  
-  // Component rendering...
-}
+// Use the same API as in Node.js
+traceperf.track(() => {
+  // Your code
+});
 ```
 
-## Advanced Usage
+## Examples
 
-### Tracking Nested Function Calls
+TracePerf includes several example files to help you get started:
 
-TracePerf provides two approaches for tracking nested function calls, allowing you to visualize the complete execution flow of your application:
+- **`examples/optimized-tracking-example.js`**: Demonstrates various ways to use the optimized tracking implementation
+- **`examples/browser-example.js`**: Shows how to use TracePerf in browser environments
 
-1. **Using the `createTrackable` method** (recommended)
-2. **Using nested `track` calls**
+### Tracking an Async Function
 
-#### Using createTrackable (Recommended)
+```javascript
+const { createTracePerf } = require('traceperf');
+const traceperf = createTracePerf();
+
+async function fetchData(url) {
+  return traceperf.track(async () => {
+    const response = await fetch(url);
+    return response.json();
+  }, { 
+    label: 'fetchData',
+    trackMemory: true
+  });
+}
+```
 
-The `createTrackable` method creates tracked versions of your functions that can be used in place of the original functions:
+### Tracking Nested Functions
 
 ```javascript
-function fetchData() {
-  processData();
-  calculateResults();
+const { createTracePerf } = require('traceperf');
+const traceperf = createTracePerf({ enableNestedTracking: true });
+
+async function processData() {
+  return await traceperf.track(async () => {
+    // This function call will be automatically tracked as a child
+    const data = await fetchData();
+    return transformData(data);
+  }, { 
+    label: 'processData'
+  });
 }
 
-function processData() {
-  // Some processing logic
+async function fetchData() {
+  return await traceperf.track(async () => {
+    // Implementation
+  }, { label: 'fetchData' });
 }
 
-function calculateResults() {
-  // Some calculation logic
+function transformData(data) {
+  return traceperf.track(() => {
+    // Implementation
+  }, { label: 'transformData' });
 }
+```
 
-// Create tracked versions of all functions
-const trackedFetchData = tracePerf.createTrackable(fetchData, { label: 'fetchData' });
-const trackedProcessData = tracePerf.createTrackable(processData, { label: 'processData' });
-const trackedCalculateResults = tracePerf.createTrackable(calculateResults, { label: 'calculateResults' });
-
-// Replace the global references to enable tracking
-global.processData = trackedProcessData;
-global.calculateResults = trackedCalculateResults;
+### Optimizing for Production
 
-// Execute the tracked top-level function
-trackedFetchData();
-```
+```javascript
+const { createTracePerf, TrackingMode } = require('traceperf');
+
+// Development environment
+const devTracker = createTracePerf({
+  trackingMode: TrackingMode.DETAILED,
+  silent: false,
+  trackMemory: true,
+  threshold: 0 // track everything
+});
 
-This will produce a complete execution flow chart showing all nested function calls:
+// Production environment
+const prodTracker = createTracePerf({
+  trackingMode: TrackingMode.PERFORMANCE,
+  silent: true, // don't log to console
+  trackMemory: false, // minimize overhead
+  threshold: 100, // only track slow functions
+  sampleRate: 0.01 // track only 1% of function calls
+});
 
-```
-Execution Flow:
-┌──────────────────────────────┐
-│         fetchData          │  ⏱  200ms
-└──────────────────────────────┘
-                │  
-                ▼  
-┌──────────────────────────────┐
-│        processData         │  ⏱  500ms ⚠️ SLOW
-└──────────────────────────────┘
-                │  
-                ▼  
-┌──────────────────────────────┐
-│      calculateResults      │  ⏱  300ms
-└──────────────────────────────┘
+// Use based on environment
+const traceperf = process.env.NODE_ENV === 'production' ? prodTracker : devTracker;
 ```
 
-#### Using Nested Track Calls
+## Browser Usage
 
-For more complex scenarios, you can use nested `track` calls:
+To use TracePerf in the browser:
 
-```javascript
-tracePerf.track(() => {
-  // Top-level function logic
+```html
+<script src="dist/traceperf.browser.js"></script>
+<script>
+  const { createTracePerf, TrackingMode } = TracePerf;
   
-  tracePerf.track(() => {
-    // Nested function logic
-    
-    tracePerf.track(() => {
-      // Deeply nested function logic
-    }, { label: 'deeplyNestedFunction' });
-    
-  }, { label: 'nestedFunction' });
+  const browserTracker = createTracePerf({
+    trackingMode: TrackingMode.BALANCED,
+    trackMemory: true
+  });
   
-}, { label: 'topLevelFunction' });
+  // Now use it to track your functions
+  browserTracker.track(() => {
+    // DOM operations or other browser-side logic
+  }, { label: 'domOperation' });
+</script>
 ```
 
-#### Controlling Nested Tracking
-
-You can control nested tracking with the following option:
+Or with ES modules:
 
 ```javascript
-// Disable nested tracking entirely
-tracePerf.track(fetchData, { enableNestedTracking: false });
-```
-
-For more examples, see the `examples/nested-tracking.js` and `examples/auto-tracking-example.js` files in the repository.
+import { createTracePerf, TrackingMode } from 'traceperf/browser';
 
-## API Reference for Nested Tracking
-
-### createTrackable
+const browserTracker = createTracePerf({
+  trackingMode: TrackingMode.BALANCED
+});
 
-```javascript
-tracePerf.createTrackable(fn, options)
+// Track a DOM operation
+browserTracker.track(() => {
+  document.getElementById('output').textContent = 'Updated';
+}, { label: 'updateDOM' });
 ```
 
-Creates a tracked version of a function that can be used for nested function tracking.
+## Advanced Tracking Features
 
-- `fn`: The function to make trackable
-- `options`: Options for tracking
-  - `label`: Custom label for the function (defaults to function name)
-  - `threshold`: Performance threshold in milliseconds
-  - `includeMemory`: Whether to include memory usage tracking
-  - `enableNestedTracking`: Whether to enable nested tracking (default: true)
-
-Returns a new function that, when called, will track the execution of the original function.
-
-### Track Options for Nested Tracking
-
-When using the `track` method, you can control nested tracking with these options:
+### Tracking with Different Modes
 
 ```javascript
-tracePerf.track(fn, {
-  // ... other options
-  enableNestedTracking: true, // Enable/disable nested tracking
+const { createTracePerf, TrackingMode } = require('traceperf');
+
+// Performance mode - minimal overhead
+const performanceTracker = createTracePerf({
+  trackingMode: TrackingMode.PERFORMANCE
 });
-``` 
 
-```javascript
-const { createLogger } = require('traceperf');
-
-// Create a custom logger instance
-const logger = createLogger({
-  mode: 'dev',
-  level: 'debug',
-  colorize: true,
-  timestamp: true,
-  performanceThreshold: 100, // ms
-  indentSize: 2,
+// Balanced mode - moderate detail with reasonable overhead
+const balancedTracker = createTracePerf({
+  trackingMode: TrackingMode.BALANCED
 });
 
-// Use the custom logger
-logger.info('Custom logger');
+// Detailed mode - maximum information
+const detailedTracker = createTracePerf({
+  trackingMode: TrackingMode.DETAILED
+});
 ```
 
-## API Reference
-
-### Logging Methods
+### Using Thresholds to Filter Results
 
-- `info(message, ...args)`: Log an informational message
-- `warn(message, ...args)`: Log a warning message
-- `error(message, ...args)`: Log an error message
-- `debug(message, ...args)`: Log a debug message (filtered in production)
-
-### Grouping
+```javascript
+const { createTracePerf } = require('traceperf');
+const tracker = createTracePerf();
 
-- `group(label)`: Start a new log group with the given label
-- `groupEnd()`: End the current log group
+// Only log functions that take more than 50ms
+tracker.track(slowFunction, { threshold: 50 });
 
-### Execution Tracking
+// Different thresholds for different functions
+tracker.track(criticalFunction, { threshold: 10 }); // Low threshold for critical paths
+tracker.track(backgroundTask, { threshold: 200 }); // Higher threshold for background tasks
+```
 
-- `track(fn, options)`: Track the execution of a function and log performance metrics
-  - `options.label`: Custom label for the tracked function
-  - `options.threshold`: Performance threshold in milliseconds
-  - `options.includeMemory`: Whether to include memory usage tracking
-  - `options.silent`: Whether to suppress logging for this tracking
+### Memory Tracking
 
-### Configuration
+```javascript
+const { createTracePerf } = require('traceperf');
+const tracker = createTracePerf({ trackMemory: true });
+
+// Track memory usage for memory-intensive operations
+const result = tracker.track(() => {
+  // Memory-intensive operations
+  const largeArray = new Array(1000000).fill(Math.random());
+  return processArray(largeArray);
+}, { label: 'memoryIntensiveOperation' });
+```
 
-- `setMode(mode)`: Set the operational mode ('dev', 'staging', 'prod')
-- `getMode()`: Get the current operational mode
+For more examples, see the example files in the `examples/` directory.
 
 ## License
 
 MIT 
 
+## Website
+
+Visit our website at [traceperf.com](https://traceperf.com) for more information, interactive examples, and detailed documentation. 
+

package/dist/browser.d.ts

@@ -5,6 +5,12 @@
  * in React, Next.js, or other frontend applications.
  */
 import { ILoggerConfig, LogMode, ITrackOptions } from './types';
+export declare const TrackingMode: {
+    PERFORMANCE: string;
+    BALANCED: string;
+    DETAILED: string;
+    DEBUG: string;
+};
 /**
  * Browser-compatible performance monitoring
  */
@@ -17,12 +23,25 @@ declare class BrowserPerformanceMonitor {
     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;
 }
 /**
@@ -34,6 +53,8 @@ declare class BrowserExecutionTracker {
     private _currentExecution;
     private _defaultThreshold;
     private _globalScope;
+    private _trackedFunctions;
+    private _performanceMonitor;
     /**
      * Create a new BrowserExecutionTracker instance
      *
@@ -97,6 +118,12 @@ declare class BrowserExecutionTracker {
      * @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
      */
@@ -110,6 +137,7 @@ declare class BrowserLogger {
     private _indentLevel;
     private _executionTracker;
     private _performanceMonitor;
+    private _trackingMode;
     constructor(config?: Partial<ILoggerConfig>);
     info(message: string | object, ...args: any[]): void;
     warn(message: string | object, ...args: any[]): void;
@@ -119,6 +147,17 @@ declare class BrowserLogger {
     groupEnd(): void;
     setMode(mode: LogMode): void;
     getMode(): LogMode;
+    /**
+     * Set the tracking mode
+     * @param mode Tracking mode from TrackingMode enum
+     * @returns This instance for chaining
+     */
+    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
@@ -136,12 +175,18 @@ declare class BrowserLogger {
     private log;
 }
 /**
- * Create a new browser logger instance
- *
- * @param config - Configuration options
- * @returns A new BrowserLogger instance
+ * Create a browser-compatible logger instance
+ * @param config Configuration options
+ * @returns Browser logger instance
  */
 export declare function createBrowserLogger(config?: Partial<ILoggerConfig>): BrowserLogger;
-declare const defaultBrowserLogger: BrowserLogger;
-export default defaultBrowserLogger;
+/**
+ * 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;
+declare const browserLogger: BrowserLogger;
+export default browserLogger;
 export { BrowserLogger, BrowserPerformanceMonitor, BrowserExecutionTracker };