traceperf 0.1.5 → 0.2.1

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,348 @@ 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 provides a fully synchronized browser implementation that matches the Node.js API:
 
-// Track function performance
-function expensiveCalculation() {
-  // ...complex logic
-  return result;
-}
+```javascript
+import { createTracePerf, BrowserLogger } from 'traceperf/browser';
+
+// Create a browser-optimized instance
+const browserTracker = createTracePerf({
+  logger: new BrowserLogger({
+    silent: false,
+    trackMemory: true
+  })
+});
 
-const result = tracePerf.track(expensiveCalculation);
+// Track function execution
+browserTracker.track(() => {
+  // Your browser-side code
+}, { label: 'browserOperation' });
+
+// Create trackable functions
+const trackedFn = browserTracker.createTrackable(() => {
+  // Function implementation
+}, { label: 'trackedBrowserFn' });
+
+// Track async operations
+await browserTracker.track(async () => {
+  const response = await fetch('/api/data');
+  return response.json();
+}, { label: 'fetchData' });
 ```
 
-### 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();
-    };
-  }, []);
+You can also use it via script tag:
+
+```html
+<script src="dist/traceperf.browser.js"></script>
+<script>
+  const { createTracePerf, BrowserLogger } = TracePerf;
   
-  // Component rendering...
-}
+  const browserTracker = createTracePerf({
+    logger: new BrowserLogger({
+      silent: false,
+      trackMemory: true
+    })
+  });
+  
+  // Use the same API as in Node.js
+  browserTracker.track(() => {
+    // DOM operations or other browser-side logic
+  }, { label: 'domOperation' });
+</script>
 ```
 
-## Advanced Usage
-
-### Tracking Nested Function Calls
+## Synchronized Features
 
-TracePerf provides two approaches for tracking nested function calls, allowing you to visualize the complete execution flow of your application:
+TracePerf now provides a consistent API across Node.js and browser environments:
 
-1. **Using the `createTrackable` method** (recommended)
-2. **Using nested `track` calls**
+- **Unified Tracking API**: The same tracking methods work identically in both environments
+- **Consistent Configuration**: Logger and tracker options are synchronized
+- **Memory Tracking**: Both environments support memory usage tracking
+- **Performance Optimization**: Browser-specific optimizations while maintaining API compatibility
+- **Execution Flow**: Track complex execution flows consistently across environments
 
-#### Using createTrackable (Recommended)
-
-The `createTrackable` method creates tracked versions of your functions that can be used in place of the original functions:
+Example of cross-environment usage:
 
 ```javascript
-function fetchData() {
-  processData();
-  calculateResults();
-}
-
-function processData() {
-  // Some processing logic
-}
-
-function calculateResults() {
-  // Some calculation logic
+// Node.js
+const { createTracePerf } = require('traceperf');
+const nodeTracker = createTracePerf();
+
+// Browser
+import { createTracePerf } from 'traceperf/browser';
+const browserTracker = createTracePerf();
+
+// Both environments support the same API
+async function trackOperation(tracker) {
+  return await tracker.track(async () => {
+    const result = await someAsyncOperation();
+    return processResult(result);
+  }, { 
+    label: 'mainOperation',
+    trackMemory: true
+  });
 }
-
-// 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;
-
-// Execute the tracked top-level function
-trackedFetchData();
 ```
 
-This will produce a complete execution flow chart showing all nested function calls:
+## Examples
 
-```
-Execution Flow:
-┌──────────────────────────────┐
-│         fetchData          │  ⏱  200ms
-└──────────────────────────────┘
-                │  
-                ▼  
-┌──────────────────────────────┐
-│        processData         │  ⏱  500ms ⚠️ SLOW
-└──────────────────────────────┘
-                │  
-                ▼  
-┌──────────────────────────────┐
-│      calculateResults      │  ⏱  300ms
-└──────────────────────────────┘
-```
+TracePerf includes several example files to help you get started:
 
-#### Using Nested Track Calls
+- **`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
 
-For more complex scenarios, you can use nested `track` calls:
+### Tracking an Async Function
 
 ```javascript
-tracePerf.track(() => {
-  // Top-level function logic
-  
-  tracePerf.track(() => {
-    // Nested function logic
-    
-    tracePerf.track(() => {
-      // Deeply nested function logic
-    }, { label: 'deeplyNestedFunction' });
-    
-  }, { label: 'nestedFunction' });
-  
-}, { label: 'topLevelFunction' });
+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
+  });
+}
 ```
 
-#### Controlling Nested Tracking
-
-You can control nested tracking with the following option:
+### Tracking Nested Functions
 
 ```javascript
-// Disable nested tracking entirely
-tracePerf.track(fetchData, { enableNestedTracking: false });
-```
+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'
+  });
+}
 
-For more examples, see the `examples/nested-tracking.js` and `examples/auto-tracking-example.js` files in the repository.
+async function fetchData() {
+  return await traceperf.track(async () => {
+    // Implementation
+  }, { label: 'fetchData' });
+}
 
-## API Reference for Nested Tracking
+function transformData(data) {
+  return traceperf.track(() => {
+    // Implementation
+  }, { label: 'transformData' });
+}
+```
 
-### createTrackable
+### Optimizing for Production
 
 ```javascript
-tracePerf.createTrackable(fn, options)
-```
+const { createTracePerf, TrackingMode } = require('traceperf');
+
+// Development environment
+const devTracker = createTracePerf({
+  trackingMode: TrackingMode.DETAILED,
+  silent: false,
+  trackMemory: true,
+  threshold: 0 // track everything
+});
 
-Creates a tracked version of a function that can be used for nested function tracking.
+// 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
+});
 
-- `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)
+// Use based on environment
+const traceperf = process.env.NODE_ENV === 'production' ? prodTracker : devTracker;
+```
+
+## Browser Usage
 
-Returns a new function that, when called, will track the execution of the original function.
+To use TracePerf in the browser:
 
-### Track Options for Nested Tracking
+```html
+<script src="dist/traceperf.browser.js"></script>
+<script>
+  const { createTracePerf, TrackingMode } = TracePerf;
+  
+  const browserTracker = createTracePerf({
+    trackingMode: TrackingMode.BALANCED,
+    trackMemory: true
+  });
+  
+  // Now use it to track your functions
+  browserTracker.track(() => {
+    // DOM operations or other browser-side logic
+  }, { label: 'domOperation' });
+</script>
+```
 
-When using the `track` method, you can control nested tracking with these options:
+Or with ES modules:
 
 ```javascript
-tracePerf.track(fn, {
-  // ... other options
-  enableNestedTracking: true, // Enable/disable nested tracking
-});
-``` 
+import { createTracePerf, TrackingMode } from 'traceperf/browser';
 
-```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,
+const browserTracker = createTracePerf({
+  trackingMode: TrackingMode.BALANCED
 });
 
-// Use the custom logger
-logger.info('Custom logger');
+// Track a DOM operation
+browserTracker.track(() => {
+  document.getElementById('output').textContent = 'Updated';
+}, { label: 'updateDOM' });
 ```
 
-## API Reference
-
-### Logging Methods
+## Advanced Tracking Features
 
-- `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)
+### Tracking with Different Modes
 
-### Grouping
-
-- `group(label)`: Start a new log group with the given label
-- `groupEnd()`: End the current log group
+```javascript
+const { createTracePerf, TrackingMode } = require('traceperf');
 
-### Execution Tracking
+// Performance mode - minimal overhead
+const performanceTracker = createTracePerf({
+  trackingMode: TrackingMode.PERFORMANCE
+});
 
-- `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
+// Balanced mode - moderate detail with reasonable overhead
+const balancedTracker = createTracePerf({
+  trackingMode: TrackingMode.BALANCED
+});
 
-### Configuration
+// Detailed mode - maximum information
+const detailedTracker = createTracePerf({
+  trackingMode: TrackingMode.DETAILED
+});
+```
 
-- `setMode(mode)`: Set the operational mode ('dev', 'staging', 'prod')
-- `getMode()`: Get the current operational mode
+### Using Thresholds to Filter Results
 
-## License
+```javascript
+const { createTracePerf } = require('traceperf');
+const tracker = createTracePerf();
 
-MIT 
+// Only log functions that take more than 50ms
+tracker.track(slowFunction, { threshold: 50 });
 
+// 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
+```