@discomedia/utils 1.0.10 → 1.0.11

package/dist/index.mjs

@@ -9880,6 +9880,128 @@ const makeDeepseekCall = async (content, responseFormat = 'json', options = {})
     }
 };
 
+/**
+ * A class to measure performance of code execution.
+ *
+ * This utility records elapsed time during execution and provides a detailed
+ * breakdown of elapsed time between checkpoints.
+ *
+ * Usage example:
+ *   const timer = new PerformanceTimer();
+ *   timer.checkpoint('Start Processing');
+ *   // ... code for processing
+ *   timer.checkpoint('After Task 1');
+ *   // ... additional processing code
+ *   timer.stop();
+ *   console.log(timer.generateReport());
+ *
+ * Methods:
+ *   - checkpoint(label: string): Record a timestamped checkpoint.
+ *   - stop(): Stop the timer and compute the total elapsed time.
+ *   - generateReport(): Return a performance report with total time and phases.
+ *   - formatPerformanceReport(): Return a formatted string of the performance report.
+ *   - getElapsedSeconds(): Get the current elapsed time in seconds.
+ */
+class PerformanceTimer {
+    startTime;
+    checkpoints;
+    totalTime;
+    constructor() {
+        this.startTime = performance.now();
+        this.checkpoints = new Map();
+        this.totalTime = null;
+    }
+    /**
+     * Gets the current elapsed time in seconds.
+     *
+     * @returns The elapsed time in seconds with 3 decimal places of precision.
+     */
+    getElapsedSeconds() {
+        const elapsedMs = this.totalTime ?? (performance.now() - this.startTime);
+        return Number((elapsedMs / 1000).toFixed(3));
+    }
+    /**
+     * Records a checkpoint with the given label.
+     *
+     * @param label - A descriptive label for the checkpoint.
+     */
+    checkpoint(label) {
+        this.checkpoints.set(label, performance.now());
+    }
+    /**
+     * Stops the timer and sets the total elapsed time.
+     */
+    stop() {
+        this.totalTime = performance.now() - this.startTime;
+    }
+    /**
+     * Generates a performance report containing the total elapsed time and
+     * breakdown of phases between checkpoints.
+     *
+     * @returns A performance report object.
+     * @throws Error if the timer is not stopped before generating the report.
+     */
+    analyseReportData() {
+        if (this.totalTime === null) {
+            throw new Error('Timer must be stopped before generating report');
+        }
+        const report = {
+            totalTime: this.totalTime,
+            phases: []
+        };
+        let lastTime = this.startTime;
+        // Convert checkpoints to a sorted array by time
+        const sortedCheckpoints = Array.from(this.checkpoints.entries())
+            .sort((a, b) => a[1] - b[1]);
+        for (const [label, time] of sortedCheckpoints) {
+            const duration = time - lastTime;
+            if (duration < 0) {
+                throw new Error(`Negative duration detected for checkpoint: ${label}`);
+            }
+            report.phases.push({
+                label,
+                duration
+            });
+            lastTime = time;
+        }
+        // Add final phase from last checkpoint to stop
+        if (sortedCheckpoints.length > 0) {
+            const finalDuration = this.totalTime - lastTime;
+            report.phases.push({
+                label: 'Final Processing',
+                duration: Math.max(finalDuration, 0) // Prevent negative duration
+            });
+        }
+        return report;
+    }
+    /**
+     * Returns a formatted string of the performance report.
+     *
+     * @returns A string detailing the total execution time and phase breakdown.
+     */
+    generateReport() {
+        const report = this.analyseReportData();
+        // Format numbers with thousands separators and 2 decimal places
+        const formatNumber = (num) => num.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+        // Calculate column widths
+        const maxLabelLength = Math.max(...report.phases.map(p => p.label.length), 30);
+        const maxDurationLength = Math.max(...report.phases.map(p => formatNumber(p.duration).length), 10);
+        // Create table header
+        let output = `╔${'═'.repeat(maxLabelLength + 2)}╦${'═'.repeat(maxDurationLength + 2)}╗\n`;
+        output += `║ ${'Phase'.padEnd(maxLabelLength)} ║ ${'Time (ms)'.padEnd(maxDurationLength)} ║\n`;
+        output += `╠${'═'.repeat(maxLabelLength + 2)}╬${'═'.repeat(maxDurationLength + 2)}╣\n`;
+        // Add table rows
+        report.phases.forEach(phase => {
+            output += `║ ${phase.label.padEnd(maxLabelLength)} ║ ${formatNumber(phase.duration).padStart(maxDurationLength)} ║\n`;
+        });
+        // Add table footer with total
+        output += `╠${'═'.repeat(maxLabelLength + 2)}╬${'═'.repeat(maxDurationLength + 2)}╣\n`;
+        output += `║ ${'Total'.padEnd(maxLabelLength)} ║ ${formatNumber(report.totalTime).padStart(maxDurationLength)} ║\n`;
+        output += `╚${'═'.repeat(maxLabelLength + 2)}╩${'═'.repeat(maxDurationLength + 2)}╝\n`;
+        return output;
+    }
+}
+
 /**
  * Calculates Bollinger Bands for a given set of price data.
  * Bollinger Bands consist of a middle band (SMA) and two outer bands
@@ -18079,6 +18201,7 @@ const disco = {
         logIfDebug: logIfDebug,
         fetchWithRetry: fetchWithRetry,
         validatePolygonApiKey: validatePolygonApiKey,
+        Timer: PerformanceTimer,
     },
 };