backtest-kit 1.1.6 → 1.1.8

package/build/index.cjs

@@ -71,6 +71,7 @@ const logicPublicServices$1 = {
 const markdownServices$1 = {
     backtestMarkdownService: Symbol('backtestMarkdownService'),
     liveMarkdownService: Symbol('liveMarkdownService'),
+    performanceMarkdownService: Symbol('performanceMarkdownService'),
 };
 const validationServices$1 = {
     exchangeValidationService: Symbol('exchangeValidationService'),
@@ -1043,8 +1044,7 @@ class PersistSignalUtils {
             const stateStorage = this.getSignalStorage(strategyName);
             await stateStorage.waitForInit(isInitial);
             if (await stateStorage.hasValue(symbol)) {
-                const { signalRow } = await stateStorage.readValue(symbol);
-                return signalRow;
+                return await stateStorage.readValue(symbol);
             }
             return null;
         };
@@ -1064,7 +1064,7 @@ class PersistSignalUtils {
             const isInitial = !this.getSignalStorage.has(strategyName);
             const stateStorage = this.getSignalStorage(strategyName);
             await stateStorage.waitForInit(isInitial);
-            await stateStorage.writeValue(symbol, { signalRow });
+            await stateStorage.writeValue(symbol, signalRow);
         };
     }
     /**
@@ -1134,6 +1134,11 @@ const doneEmitter = new functoolsKit.Subject();
  * Emits progress updates during backtest execution.
  */
 const progressEmitter = new functoolsKit.Subject();
+/**
+ * Performance emitter for execution metrics.
+ * Emits performance metrics for profiling and bottleneck detection.
+ */
+const performanceEmitter = new functoolsKit.Subject();
 
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
@@ -1206,6 +1211,7 @@ const GET_SIGNAL_FN = functoolsKit.trycatch(async (self) => {
     }
     const signalRow = {
         id: functoolsKit.randomString(),
+        priceOpen: await self.params.exchange.getAveragePrice(self.params.execution.context.symbol),
         ...signal,
         symbol: self.params.execution.context.symbol,
         exchangeName: self.params.method.context.exchangeName,
@@ -2427,10 +2433,12 @@ class BacktestLogicPrivateService {
         this.loggerService.log("backtestLogicPrivateService run", {
             symbol,
         });
+        const backtestStartTime = performance.now();
         const timeframes = await this.frameGlobalService.getTimeframe(symbol);
         const totalFrames = timeframes.length;
         let i = 0;
         while (i < timeframes.length) {
+            const timeframeStartTime = performance.now();
             const when = timeframes[i];
             // Emit progress event if context is available
             {
@@ -2446,6 +2454,7 @@ class BacktestLogicPrivateService {
             const result = await this.strategyGlobalService.tick(symbol, when, true);
             // Если сигнал открыт, вызываем backtest
             if (result.action === "opened") {
+                const signalStartTime = performance.now();
                 const signal = result.signal;
                 this.loggerService.info("backtestLogicPrivateService signal opened", {
                     symbol,
@@ -2470,6 +2479,17 @@ class BacktestLogicPrivateService {
                     closeTimestamp: backtestResult.closeTimestamp,
                     closeReason: backtestResult.closeReason,
                 });
+                // Track signal processing duration
+                const signalEndTime = performance.now();
+                await performanceEmitter.next({
+                    timestamp: Date.now(),
+                    metricType: "backtest_signal",
+                    duration: signalEndTime - signalStartTime,
+                    strategyName: this.methodContextService.context.strategyName,
+                    exchangeName: this.methodContextService.context.exchangeName,
+                    symbol,
+                    backtest: true,
+                });
                 // Пропускаем timeframes до closeTimestamp
                 while (i < timeframes.length &&
                     timeframes[i].getTime() < backtestResult.closeTimestamp) {
@@ -2477,6 +2497,17 @@ class BacktestLogicPrivateService {
                 }
                 yield backtestResult;
             }
+            // Track timeframe processing duration
+            const timeframeEndTime = performance.now();
+            await performanceEmitter.next({
+                timestamp: Date.now(),
+                metricType: "backtest_timeframe",
+                duration: timeframeEndTime - timeframeStartTime,
+                strategyName: this.methodContextService.context.strategyName,
+                exchangeName: this.methodContextService.context.exchangeName,
+                symbol,
+                backtest: true,
+            });
             i++;
         }
         // Emit final progress event (100%)
@@ -2490,6 +2521,17 @@ class BacktestLogicPrivateService {
                 progress: 1.0,
             });
         }
+        // Track total backtest duration
+        const backtestEndTime = performance.now();
+        await performanceEmitter.next({
+            timestamp: Date.now(),
+            metricType: "backtest_total",
+            duration: backtestEndTime - backtestStartTime,
+            strategyName: this.methodContextService.context.strategyName,
+            exchangeName: this.methodContextService.context.exchangeName,
+            symbol,
+            backtest: true,
+        });
     }
 }
 
@@ -2514,6 +2556,7 @@ class LiveLogicPrivateService {
     constructor() {
         this.loggerService = inject(TYPES.loggerService);
         this.strategyGlobalService = inject(TYPES.strategyGlobalService);
+        this.methodContextService = inject(TYPES.methodContextService);
     }
     /**
      * Runs live trading for a symbol, streaming results as async generator.
@@ -2542,12 +2585,24 @@ class LiveLogicPrivateService {
             symbol,
         });
         while (true) {
+            const tickStartTime = performance.now();
             const when = new Date();
             const result = await this.strategyGlobalService.tick(symbol, when, false);
             this.loggerService.info("liveLogicPrivateService tick result", {
                 symbol,
                 action: result.action,
             });
+            // Track tick duration
+            const tickEndTime = performance.now();
+            await performanceEmitter.next({
+                timestamp: Date.now(),
+                metricType: "live_tick",
+                duration: tickEndTime - tickStartTime,
+                strategyName: this.methodContextService.context.strategyName,
+                exchangeName: this.methodContextService.context.exchangeName,
+                symbol,
+                backtest: false,
+            });
             if (result.action === "active") {
                 await functoolsKit.sleep(TICK_TTL);
                 continue;
@@ -3224,7 +3279,7 @@ const columns = [
     },
 ];
 /** Maximum number of events to store in live trading reports */
-const MAX_EVENTS = 250;
+const MAX_EVENTS$1 = 250;
 /**
  * Storage class for accumulating all tick events per strategy.
  * Maintains a chronological list of all events (idle, opened, active, closed).
@@ -3257,7 +3312,7 @@ class ReportStorage {
         }
         {
             this._eventList.push(newEvent);
-            if (this._eventList.length > MAX_EVENTS) {
+            if (this._eventList.length > MAX_EVENTS$1) {
                 this._eventList.shift();
             }
         }
@@ -3281,7 +3336,7 @@ class ReportStorage {
             stopLoss: data.signal.priceStopLoss,
         });
         // Trim queue if exceeded MAX_EVENTS
-        if (this._eventList.length > MAX_EVENTS) {
+        if (this._eventList.length > MAX_EVENTS$1) {
             this._eventList.shift();
         }
     }
@@ -3313,7 +3368,7 @@ class ReportStorage {
         else {
             this._eventList.push(newEvent);
             // Trim queue if exceeded MAX_EVENTS
-            if (this._eventList.length > MAX_EVENTS) {
+            if (this._eventList.length > MAX_EVENTS$1) {
                 this._eventList.shift();
             }
         }
@@ -3351,7 +3406,7 @@ class ReportStorage {
         else {
             this._eventList.push(newEvent);
             // Trim queue if exceeded MAX_EVENTS
-            if (this._eventList.length > MAX_EVENTS) {
+            if (this._eventList.length > MAX_EVENTS$1) {
                 this._eventList.shift();
             }
         }
@@ -3665,6 +3720,297 @@ class LiveMarkdownService {
     }
 }
 
+/**
+ * Calculates percentile value from sorted array.
+ */
+function percentile(sortedArray, p) {
+    if (sortedArray.length === 0)
+        return 0;
+    const index = Math.ceil((sortedArray.length * p) / 100) - 1;
+    return sortedArray[Math.max(0, index)];
+}
+/** Maximum number of performance events to store per strategy */
+const MAX_EVENTS = 10000;
+/**
+ * Storage class for accumulating performance metrics per strategy.
+ * Maintains a list of all performance events and provides aggregated statistics.
+ */
+class PerformanceStorage {
+    constructor() {
+        /** Internal list of all performance events for this strategy */
+        this._events = [];
+    }
+    /**
+     * Adds a performance event to the storage.
+     *
+     * @param event - Performance event with timing data
+     */
+    addEvent(event) {
+        this._events.push(event);
+        // Trim queue if exceeded MAX_EVENTS (keep most recent)
+        if (this._events.length > MAX_EVENTS) {
+            this._events.shift();
+        }
+    }
+    /**
+     * Calculates aggregated statistics from all performance events.
+     *
+     * @returns Performance statistics with metrics grouped by type
+     */
+    async getData(strategyName) {
+        if (this._events.length === 0) {
+            return {
+                strategyName,
+                totalEvents: 0,
+                totalDuration: 0,
+                metricStats: {},
+                events: [],
+            };
+        }
+        // Group events by metric type
+        const eventsByType = new Map();
+        for (const event of this._events) {
+            if (!eventsByType.has(event.metricType)) {
+                eventsByType.set(event.metricType, []);
+            }
+            eventsByType.get(event.metricType).push(event);
+        }
+        // Calculate statistics for each metric type
+        const metricStats = {};
+        for (const [metricType, events] of eventsByType.entries()) {
+            const durations = events.map((e) => e.duration).sort((a, b) => a - b);
+            const totalDuration = durations.reduce((sum, d) => sum + d, 0);
+            const avgDuration = totalDuration / durations.length;
+            // Calculate standard deviation
+            const variance = durations.reduce((sum, d) => sum + Math.pow(d - avgDuration, 2), 0) /
+                durations.length;
+            const stdDev = Math.sqrt(variance);
+            metricStats[metricType] = {
+                metricType,
+                count: events.length,
+                totalDuration,
+                avgDuration,
+                minDuration: durations[0],
+                maxDuration: durations[durations.length - 1],
+                stdDev,
+                median: percentile(durations, 50),
+                p95: percentile(durations, 95),
+                p99: percentile(durations, 99),
+            };
+        }
+        const totalDuration = this._events.reduce((sum, e) => sum + e.duration, 0);
+        return {
+            strategyName,
+            totalEvents: this._events.length,
+            totalDuration,
+            metricStats,
+            events: this._events,
+        };
+    }
+    /**
+     * Generates markdown report with performance statistics.
+     *
+     * @param strategyName - Strategy name
+     * @returns Markdown formatted report
+     */
+    async getReport(strategyName) {
+        const stats = await this.getData(strategyName);
+        if (stats.totalEvents === 0) {
+            return functoolsKit.str.newline(`# Performance Report: ${strategyName}`, "", "No performance metrics recorded yet.");
+        }
+        // Sort metrics by total duration (descending) to show bottlenecks first
+        const sortedMetrics = Object.values(stats.metricStats).sort((a, b) => b.totalDuration - a.totalDuration);
+        // Generate summary table
+        const summaryHeader = [
+            "Metric Type",
+            "Count",
+            "Total (ms)",
+            "Avg (ms)",
+            "Min (ms)",
+            "Max (ms)",
+            "Std Dev (ms)",
+            "Median (ms)",
+            "P95 (ms)",
+            "P99 (ms)",
+        ];
+        const summarySeparator = summaryHeader.map(() => "---");
+        const summaryRows = sortedMetrics.map((metric) => [
+            metric.metricType,
+            metric.count.toString(),
+            metric.totalDuration.toFixed(2),
+            metric.avgDuration.toFixed(2),
+            metric.minDuration.toFixed(2),
+            metric.maxDuration.toFixed(2),
+            metric.stdDev.toFixed(2),
+            metric.median.toFixed(2),
+            metric.p95.toFixed(2),
+            metric.p99.toFixed(2),
+        ]);
+        const summaryTableData = [summaryHeader, summarySeparator, ...summaryRows];
+        const summaryTable = functoolsKit.str.newline(summaryTableData.map((row) => `| ${row.join(" | ")} |`));
+        // Calculate percentage of total time for each metric
+        const percentages = sortedMetrics.map((metric) => {
+            const pct = (metric.totalDuration / stats.totalDuration) * 100;
+            return `- **${metric.metricType}**: ${pct.toFixed(1)}% (${metric.totalDuration.toFixed(2)}ms total)`;
+        });
+        return functoolsKit.str.newline(`# Performance Report: ${strategyName}`, "", `**Total events:** ${stats.totalEvents}`, `**Total execution time:** ${stats.totalDuration.toFixed(2)}ms`, `**Number of metric types:** ${Object.keys(stats.metricStats).length}`, "", "## Time Distribution", "", functoolsKit.str.newline(percentages), "", "## Detailed Metrics", "", summaryTable, "", "**Note:** All durations are in milliseconds. P95/P99 represent 95th and 99th percentile response times.");
+    }
+    /**
+     * Saves performance report to disk.
+     *
+     * @param strategyName - Strategy name
+     * @param path - Directory path to save report
+     */
+    async dump(strategyName, path$1 = "./logs/performance") {
+        const markdown = await this.getReport(strategyName);
+        try {
+            const dir = path.join(process.cwd(), path$1);
+            await fs.mkdir(dir, { recursive: true });
+            const filename = `${strategyName}.md`;
+            const filepath = path.join(dir, filename);
+            await fs.writeFile(filepath, markdown, "utf-8");
+            console.log(`Performance report saved: ${filepath}`);
+        }
+        catch (error) {
+            console.error(`Failed to save performance report:`, error);
+        }
+    }
+}
+/**
+ * Service for collecting and analyzing performance metrics.
+ *
+ * Features:
+ * - Listens to performance events via performanceEmitter
+ * - Accumulates metrics per strategy
+ * - Calculates aggregated statistics (avg, min, max, percentiles)
+ * - Generates markdown reports with bottleneck analysis
+ * - Saves reports to disk in logs/performance/{strategyName}.md
+ *
+ * @example
+ * ```typescript
+ * import { listenPerformance } from "backtest-kit";
+ *
+ * // Subscribe to performance events
+ * listenPerformance((event) => {
+ *   console.log(`${event.metricType}: ${event.duration.toFixed(2)}ms`);
+ * });
+ *
+ * // After execution, generate report
+ * const stats = await Performance.getData("my-strategy");
+ * console.log("Bottlenecks:", stats.metricStats);
+ *
+ * // Save report to disk
+ * await Performance.dump("my-strategy");
+ * ```
+ */
+class PerformanceMarkdownService {
+    constructor() {
+        /** Logger service for debug output */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * Memoized function to get or create PerformanceStorage for a strategy.
+         * Each strategy gets its own isolated storage instance.
+         */
+        this.getStorage = functoolsKit.memoize(([strategyName]) => `${strategyName}`, () => new PerformanceStorage());
+        /**
+         * Processes performance events and accumulates metrics.
+         * Should be called from performance tracking code.
+         *
+         * @param event - Performance event with timing data
+         */
+        this.track = async (event) => {
+            this.loggerService.log("performanceMarkdownService track", {
+                event,
+            });
+            const strategyName = event.strategyName || "global";
+            const storage = this.getStorage(strategyName);
+            storage.addEvent(event);
+        };
+        /**
+         * Gets aggregated performance statistics for a strategy.
+         *
+         * @param strategyName - Strategy name to get data for
+         * @returns Performance statistics with aggregated metrics
+         *
+         * @example
+         * ```typescript
+         * const stats = await performanceService.getData("my-strategy");
+         * console.log("Total time:", stats.totalDuration);
+         * console.log("Slowest operation:", Object.values(stats.metricStats)
+         *   .sort((a, b) => b.avgDuration - a.avgDuration)[0]);
+         * ```
+         */
+        this.getData = async (strategyName) => {
+            this.loggerService.log("performanceMarkdownService getData", {
+                strategyName,
+            });
+            const storage = this.getStorage(strategyName);
+            return storage.getData(strategyName);
+        };
+        /**
+         * Generates markdown report with performance analysis.
+         *
+         * @param strategyName - Strategy name to generate report for
+         * @returns Markdown formatted report string
+         *
+         * @example
+         * ```typescript
+         * const markdown = await performanceService.getReport("my-strategy");
+         * console.log(markdown);
+         * ```
+         */
+        this.getReport = async (strategyName) => {
+            this.loggerService.log("performanceMarkdownService getReport", {
+                strategyName,
+            });
+            const storage = this.getStorage(strategyName);
+            return storage.getReport(strategyName);
+        };
+        /**
+         * Saves performance report to disk.
+         *
+         * @param strategyName - Strategy name to save report for
+         * @param path - Directory path to save report
+         *
+         * @example
+         * ```typescript
+         * // Save to default path: ./logs/performance/my-strategy.md
+         * await performanceService.dump("my-strategy");
+         *
+         * // Save to custom path
+         * await performanceService.dump("my-strategy", "./custom/path");
+         * ```
+         */
+        this.dump = async (strategyName, path = "./logs/performance") => {
+            this.loggerService.log("performanceMarkdownService dump", {
+                strategyName,
+                path,
+            });
+            const storage = this.getStorage(strategyName);
+            await storage.dump(strategyName, path);
+        };
+        /**
+         * Clears accumulated performance data from storage.
+         *
+         * @param strategyName - Optional strategy name to clear specific strategy data
+         */
+        this.clear = async (strategyName) => {
+            this.loggerService.log("performanceMarkdownService clear", {
+                strategyName,
+            });
+            this.getStorage.clear(strategyName);
+        };
+        /**
+         * Initializes the service by subscribing to performance events.
+         * Uses singleshot to ensure initialization happens only once.
+         */
+        this.init = functoolsKit.singleshot(async () => {
+            this.loggerService.log("performanceMarkdownService init");
+            performanceEmitter.subscribe(this.track);
+        });
+    }
+}
+
 /**
  * @class ExchangeValidationService
  * Service for managing and validating exchange configurations
@@ -3883,6 +4229,7 @@ class FrameValidationService {
 {
     provide(TYPES.backtestMarkdownService, () => new BacktestMarkdownService());
     provide(TYPES.liveMarkdownService, () => new LiveMarkdownService());
+    provide(TYPES.performanceMarkdownService, () => new PerformanceMarkdownService());
 }
 {
     provide(TYPES.exchangeValidationService, () => new ExchangeValidationService());
@@ -3925,6 +4272,7 @@ const logicPublicServices = {
 const markdownServices = {
     backtestMarkdownService: inject(TYPES.backtestMarkdownService),
     liveMarkdownService: inject(TYPES.liveMarkdownService),
+    performanceMarkdownService: inject(TYPES.performanceMarkdownService),
 };
 const validationServices = {
     exchangeValidationService: inject(TYPES.exchangeValidationService),
@@ -3997,8 +4345,8 @@ const ADD_FRAME_METHOD_NAME = "add.addFrame";
  *     timestamp: Date.now(),
  *   }),
  *   callbacks: {
- *     onOpen: (backtest, symbol, signal) => console.log("Signal opened"),
- *     onClose: (backtest, symbol, priceClose, signal) => console.log("Signal closed"),
+ *     onOpen: (symbol, signal, currentPrice, backtest) => console.log("Signal opened"),
+ *     onClose: (symbol, signal, priceClose, backtest) => console.log("Signal closed"),
  *   },
  * });
  * ```
@@ -4196,6 +4544,7 @@ const LISTEN_ERROR_METHOD_NAME = "event.listenError";
 const LISTEN_DONE_METHOD_NAME = "event.listenDone";
 const LISTEN_DONE_ONCE_METHOD_NAME = "event.listenDoneOnce";
 const LISTEN_PROGRESS_METHOD_NAME = "event.listenProgress";
+const LISTEN_PERFORMANCE_METHOD_NAME = "event.listenPerformance";
 /**
  * Subscribes to all signal events with queued async processing.
  *
@@ -4485,6 +4834,42 @@ function listenProgress(fn) {
     backtest$1.loggerService.log(LISTEN_PROGRESS_METHOD_NAME);
     return progressEmitter.subscribe(functoolsKit.queued(async (event) => fn(event)));
 }
+/**
+ * Subscribes to performance metric events with queued async processing.
+ *
+ * Emits during strategy execution to track timing metrics for operations.
+ * Useful for profiling and identifying performance bottlenecks.
+ * Events are processed sequentially in order received, even if callback is async.
+ * Uses queued wrapper to prevent concurrent execution of the callback.
+ *
+ * @param fn - Callback function to handle performance events
+ * @returns Unsubscribe function to stop listening to events
+ *
+ * @example
+ * ```typescript
+ * import { listenPerformance, Backtest } from "backtest-kit";
+ *
+ * const unsubscribe = listenPerformance((event) => {
+ *   console.log(`${event.metricType}: ${event.duration.toFixed(2)}ms`);
+ *   if (event.duration > 100) {
+ *     console.warn("Slow operation detected:", event.metricType);
+ *   }
+ * });
+ *
+ * Backtest.background("BTCUSDT", {
+ *   strategyName: "my-strategy",
+ *   exchangeName: "binance",
+ *   frameName: "1d-backtest"
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+function listenPerformance(fn) {
+    backtest$1.loggerService.log(LISTEN_PERFORMANCE_METHOD_NAME);
+    return performanceEmitter.subscribe(functoolsKit.queued(async (event) => fn(event)));
+}
 
 const GET_CANDLES_METHOD_NAME = "exchange.getCandles";
 const GET_AVERAGE_PRICE_METHOD_NAME = "exchange.getAveragePrice";
@@ -4969,10 +5354,138 @@ class LiveUtils {
  */
 const Live = new LiveUtils();
 
+/**
+ * Performance class provides static methods for performance metrics analysis.
+ *
+ * Features:
+ * - Get aggregated performance statistics by strategy
+ * - Generate markdown reports with bottleneck analysis
+ * - Save reports to disk
+ * - Clear accumulated metrics
+ *
+ * @example
+ * ```typescript
+ * import { Performance, listenPerformance } from "backtest-kit";
+ *
+ * // Subscribe to performance events
+ * listenPerformance((event) => {
+ *   console.log(`${event.metricType}: ${event.duration.toFixed(2)}ms`);
+ * });
+ *
+ * // Run backtest...
+ *
+ * // Get aggregated statistics
+ * const stats = await Performance.getData("my-strategy");
+ * console.log("Total time:", stats.totalDuration);
+ * console.log("Slowest operations:", Object.values(stats.metricStats)
+ *   .sort((a, b) => b.avgDuration - a.avgDuration)
+ *   .slice(0, 5));
+ *
+ * // Generate and save report
+ * await Performance.dump("my-strategy");
+ * ```
+ */
+class Performance {
+    /**
+     * Gets aggregated performance statistics for a strategy.
+     *
+     * Returns detailed metrics grouped by operation type:
+     * - Count, total duration, average, min, max
+     * - Standard deviation for volatility
+     * - Percentiles (median, P95, P99) for outlier detection
+     *
+     * @param strategyName - Strategy name to analyze
+     * @returns Performance statistics with aggregated metrics
+     *
+     * @example
+     * ```typescript
+     * const stats = await Performance.getData("my-strategy");
+     *
+     * // Find slowest operation type
+     * const slowest = Object.values(stats.metricStats)
+     *   .sort((a, b) => b.avgDuration - a.avgDuration)[0];
+     * console.log(`Slowest: ${slowest.metricType} (${slowest.avgDuration.toFixed(2)}ms avg)`);
+     *
+     * // Check for outliers
+     * for (const metric of Object.values(stats.metricStats)) {
+     *   if (metric.p99 > metric.avgDuration * 5) {
+     *     console.warn(`High variance in ${metric.metricType}: P99=${metric.p99}ms, Avg=${metric.avgDuration}ms`);
+     *   }
+     * }
+     * ```
+     */
+    static async getData(strategyName) {
+        return backtest$1.performanceMarkdownService.getData(strategyName);
+    }
+    /**
+     * Generates markdown report with performance analysis.
+     *
+     * Report includes:
+     * - Time distribution across operation types
+     * - Detailed metrics table with statistics
+     * - Percentile analysis for bottleneck detection
+     *
+     * @param strategyName - Strategy name to generate report for
+     * @returns Markdown formatted report string
+     *
+     * @example
+     * ```typescript
+     * const markdown = await Performance.getReport("my-strategy");
+     * console.log(markdown);
+     *
+     * // Or save to file
+     * import fs from "fs/promises";
+     * await fs.writeFile("performance-report.md", markdown);
+     * ```
+     */
+    static async getReport(strategyName) {
+        return backtest$1.performanceMarkdownService.getReport(strategyName);
+    }
+    /**
+     * Saves performance report to disk.
+     *
+     * Creates directory if it doesn't exist.
+     * Default path: ./logs/performance/{strategyName}.md
+     *
+     * @param strategyName - Strategy name to save report for
+     * @param path - Optional custom directory path
+     *
+     * @example
+     * ```typescript
+     * // Save to default path: ./logs/performance/my-strategy.md
+     * await Performance.dump("my-strategy");
+     *
+     * // Save to custom path: ./reports/perf/my-strategy.md
+     * await Performance.dump("my-strategy", "./reports/perf");
+     * ```
+     */
+    static async dump(strategyName, path = "./logs/performance") {
+        return backtest$1.performanceMarkdownService.dump(strategyName, path);
+    }
+    /**
+     * Clears accumulated performance metrics from memory.
+     *
+     * @param strategyName - Optional strategy name to clear specific strategy's metrics
+     *
+     * @example
+     * ```typescript
+     * // Clear specific strategy metrics
+     * await Performance.clear("my-strategy");
+     *
+     * // Clear all metrics for all strategies
+     * await Performance.clear();
+     * ```
+     */
+    static async clear(strategyName) {
+        return backtest$1.performanceMarkdownService.clear(strategyName);
+    }
+}
+
 exports.Backtest = Backtest;
 exports.ExecutionContextService = ExecutionContextService;
 exports.Live = Live;
 exports.MethodContextService = MethodContextService;
+exports.Performance = Performance;
 exports.PersistBase = PersistBase;
 exports.PersistSignalAdaper = PersistSignalAdaper;
 exports.addExchange = addExchange;
@@ -4991,6 +5504,7 @@ exports.listStrategies = listStrategies;
 exports.listenDone = listenDone;
 exports.listenDoneOnce = listenDoneOnce;
 exports.listenError = listenError;
+exports.listenPerformance = listenPerformance;
 exports.listenProgress = listenProgress;
 exports.listenSignal = listenSignal;
 exports.listenSignalBacktest = listenSignalBacktest;