backtest-kit 1.1.5 → 1.1.6

package/README.md

@@ -14,15 +14,15 @@
 - 🔄 **Async Generators** - Memory-efficient streaming for backtest and live execution
 - 📊 **VWAP Pricing** - Volume-weighted average price from last 5 1m candles
 - 🎯 **Signal Lifecycle** - Type-safe state machine (idle → opened → active → closed)
-- 📉 **Accurate PNL** - Calculation with fees (0.1%) and slippage (0.1%)
+- 📈 **Accurate PNL** - Calculation with fees (0.1%) and slippage (0.1%)
 - 🧠 **Interval Throttling** - Prevents signal spam at strategy level
 - ⚡ **Memory Optimized** - Prototype methods + memoization + streaming
 - 🔌 **Flexible Architecture** - Plug your own exchanges and strategies
-- 📝 **Markdown Reports** - Auto-generated trading reports with statistics (win rate, avg PNL)
+- 📝 **Markdown Reports** - Auto-generated trading reports with statistics (win rate, avg PNL, Sharpe Ratio, Standard Deviation, Certainty Ratio, Expected Yearly Returns, Risk-Adjusted Returns)
 - 🛑 **Graceful Shutdown** - Live.background() waits for open positions to close before stopping
 - 💉 **Strategy Dependency Injection** - addStrategy() enables DI pattern for trading strategies
 - 🔍 **Schema Reflection API** - listExchanges(), listStrategies(), listFrames() for runtime introspection
-- 🧪 **Comprehensive Test Coverage** - 30+ unit tests covering validation, PNL, callbacks, reports, and event system
+- 🧪 **Comprehensive Test Coverage** - 45+ unit tests covering validation, PNL, callbacks, reports, and event system
 
 ## Installation
 

package/build/index.cjs

@@ -2742,6 +2742,24 @@ class BacktestGlobalService {
     }
 }
 
+/**
+ * Checks if a value is unsafe for display (not a number, NaN, or Infinity).
+ *
+ * @param value - Value to check
+ * @returns true if value is unsafe, false otherwise
+ */
+function isUnsafe$1(value) {
+    if (typeof value !== "number") {
+        return true;
+    }
+    if (isNaN(value)) {
+        return true;
+    }
+    if (!isFinite(value)) {
+        return true;
+    }
+    return false;
+}
 const columns$1 = [
     {
         key: "signalId",
@@ -2834,13 +2852,80 @@ let ReportStorage$1 = class ReportStorage {
         this._signalList.push(data);
     }
     /**
-     * Generates markdown report with all closed signals for a strategy.
+     * Calculates statistical data from closed signals (Controller).
+     * Returns null for any unsafe numeric values (NaN, Infinity, etc).
+     *
+     * @returns Statistical data (empty object if no signals)
+     */
+    async getData() {
+        if (this._signalList.length === 0) {
+            return {
+                signalList: [],
+                totalSignals: 0,
+                winCount: 0,
+                lossCount: 0,
+                winRate: null,
+                avgPnl: null,
+                totalPnl: null,
+                stdDev: null,
+                sharpeRatio: null,
+                annualizedSharpeRatio: null,
+                certaintyRatio: null,
+                expectedYearlyReturns: null,
+            };
+        }
+        const totalSignals = this._signalList.length;
+        const winCount = this._signalList.filter((s) => s.pnl.pnlPercentage > 0).length;
+        const lossCount = this._signalList.filter((s) => s.pnl.pnlPercentage < 0).length;
+        // Calculate basic statistics
+        const avgPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / totalSignals;
+        const totalPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0);
+        const winRate = (winCount / totalSignals) * 100;
+        // Calculate Sharpe Ratio (risk-free rate = 0)
+        const returns = this._signalList.map((s) => s.pnl.pnlPercentage);
+        const variance = returns.reduce((sum, r) => sum + Math.pow(r - avgPnl, 2), 0) / totalSignals;
+        const stdDev = Math.sqrt(variance);
+        const sharpeRatio = stdDev > 0 ? avgPnl / stdDev : 0;
+        const annualizedSharpeRatio = sharpeRatio * Math.sqrt(365);
+        // Calculate Certainty Ratio
+        const wins = this._signalList.filter((s) => s.pnl.pnlPercentage > 0);
+        const losses = this._signalList.filter((s) => s.pnl.pnlPercentage < 0);
+        const avgWin = wins.length > 0
+            ? wins.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / wins.length
+            : 0;
+        const avgLoss = losses.length > 0
+            ? losses.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / losses.length
+            : 0;
+        const certaintyRatio = avgLoss < 0 ? avgWin / Math.abs(avgLoss) : 0;
+        // Calculate Expected Yearly Returns
+        const avgDurationMs = this._signalList.reduce((sum, s) => sum + (s.closeTimestamp - s.signal.timestamp), 0) / totalSignals;
+        const avgDurationDays = avgDurationMs / (1000 * 60 * 60 * 24);
+        const tradesPerYear = avgDurationDays > 0 ? 365 / avgDurationDays : 0;
+        const expectedYearlyReturns = avgPnl * tradesPerYear;
+        return {
+            signalList: this._signalList,
+            totalSignals,
+            winCount,
+            lossCount,
+            winRate: isUnsafe$1(winRate) ? null : winRate,
+            avgPnl: isUnsafe$1(avgPnl) ? null : avgPnl,
+            totalPnl: isUnsafe$1(totalPnl) ? null : totalPnl,
+            stdDev: isUnsafe$1(stdDev) ? null : stdDev,
+            sharpeRatio: isUnsafe$1(sharpeRatio) ? null : sharpeRatio,
+            annualizedSharpeRatio: isUnsafe$1(annualizedSharpeRatio) ? null : annualizedSharpeRatio,
+            certaintyRatio: isUnsafe$1(certaintyRatio) ? null : certaintyRatio,
+            expectedYearlyReturns: isUnsafe$1(expectedYearlyReturns) ? null : expectedYearlyReturns,
+        };
+    }
+    /**
+     * Generates markdown report with all closed signals for a strategy (View).
      *
      * @param strategyName - Strategy name
      * @returns Markdown formatted report with all signals
      */
-    getReport(strategyName) {
-        if (this._signalList.length === 0) {
+    async getReport(strategyName) {
+        const stats = await this.getData();
+        if (stats.totalSignals === 0) {
             return functoolsKit.str.newline(`# Backtest Report: ${strategyName}`, "", "No signals closed yet.");
         }
         const header = columns$1.map((col) => col.label);
@@ -2848,13 +2933,7 @@ let ReportStorage$1 = class ReportStorage {
         const rows = this._signalList.map((closedSignal) => columns$1.map((col) => col.format(closedSignal)));
         const tableData = [header, separator, ...rows];
         const table = functoolsKit.str.newline(tableData.map(row => `| ${row.join(" | ")} |`));
-        // Calculate statistics
-        const totalSignals = this._signalList.length;
-        const winCount = this._signalList.filter((s) => s.pnl.pnlPercentage > 0).length;
-        const lossCount = this._signalList.filter((s) => s.pnl.pnlPercentage < 0).length;
-        const avgPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0) / totalSignals;
-        const totalPnl = this._signalList.reduce((sum, s) => sum + s.pnl.pnlPercentage, 0);
-        return functoolsKit.str.newline(`# Backtest Report: ${strategyName}`, "", table, "", `**Total signals:** ${totalSignals}`, `**Closed signals:** ${totalSignals}`, `**Win rate:** ${((winCount / totalSignals) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`, `**Average PNL:** ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`, `**Total PNL:** ${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`);
+        return functoolsKit.str.newline(`# Backtest Report: ${strategyName}`, "", table, "", `**Total signals:** ${stats.totalSignals}`, `**Closed signals:** ${stats.totalSignals}`, `**Win rate:** ${stats.winRate === null ? "N/A" : `${stats.winRate.toFixed(2)}% (${stats.winCount}W / ${stats.lossCount}L) (higher is better)`}`, `**Average PNL:** ${stats.avgPnl === null ? "N/A" : `${stats.avgPnl > 0 ? "+" : ""}${stats.avgPnl.toFixed(2)}% (higher is better)`}`, `**Total PNL:** ${stats.totalPnl === null ? "N/A" : `${stats.totalPnl > 0 ? "+" : ""}${stats.totalPnl.toFixed(2)}% (higher is better)`}`, `**Standard Deviation:** ${stats.stdDev === null ? "N/A" : `${stats.stdDev.toFixed(3)}% (lower is better)`}`, `**Sharpe Ratio:** ${stats.sharpeRatio === null ? "N/A" : `${stats.sharpeRatio.toFixed(3)} (higher is better)`}`, `**Annualized Sharpe Ratio:** ${stats.annualizedSharpeRatio === null ? "N/A" : `${stats.annualizedSharpeRatio.toFixed(3)} (higher is better)`}`, `**Certainty Ratio:** ${stats.certaintyRatio === null ? "N/A" : `${stats.certaintyRatio.toFixed(3)} (higher is better)`}`, `**Expected Yearly Returns:** ${stats.expectedYearlyReturns === null ? "N/A" : `${stats.expectedYearlyReturns > 0 ? "+" : ""}${stats.expectedYearlyReturns.toFixed(2)}% (higher is better)`}`);
     }
     /**
      * Saves strategy report to disk.
@@ -2863,7 +2942,7 @@ let ReportStorage$1 = class ReportStorage {
      * @param path - Directory path to save report (default: "./logs/backtest")
      */
     async dump(strategyName, path$1 = "./logs/backtest") {
-        const markdown = this.getReport(strategyName);
+        const markdown = await this.getReport(strategyName);
         try {
             const dir = path.join(process.cwd(), path$1);
             await fs.mkdir(dir, { recursive: true });
@@ -2942,6 +3021,27 @@ class BacktestMarkdownService {
             const storage = this.getStorage(data.strategyName);
             storage.addSignal(data);
         };
+        /**
+         * Gets statistical data from all closed signals for a strategy.
+         * Delegates to ReportStorage.getData().
+         *
+         * @param strategyName - Strategy name to get data for
+         * @returns Statistical data object with all metrics
+         *
+         * @example
+         * ```typescript
+         * const service = new BacktestMarkdownService();
+         * const stats = await service.getData("my-strategy");
+         * console.log(stats.sharpeRatio, stats.winRate);
+         * ```
+         */
+        this.getData = async (strategyName) => {
+            this.loggerService.log("backtestMarkdownService getData", {
+                strategyName,
+            });
+            const storage = this.getStorage(strategyName);
+            return storage.getData();
+        };
         /**
          * Generates markdown report with all closed signals for a strategy.
          * Delegates to ReportStorage.generateReport().
@@ -2952,7 +3052,7 @@ class BacktestMarkdownService {
          * @example
          * ```typescript
          * const service = new BacktestMarkdownService();
-         * const markdown = service.generateReport("my-strategy");
+         * const markdown = await service.getReport("my-strategy");
          * console.log(markdown);
          * ```
          */
@@ -3032,6 +3132,24 @@ class BacktestMarkdownService {
     }
 }
 
+/**
+ * Checks if a value is unsafe for display (not a number, NaN, or Infinity).
+ *
+ * @param value - Value to check
+ * @returns true if value is unsafe, false otherwise
+ */
+function isUnsafe(value) {
+    if (typeof value !== "number") {
+        return true;
+    }
+    if (isNaN(value)) {
+        return true;
+    }
+    if (!isFinite(value)) {
+        return true;
+    }
+    return false;
+}
 const columns = [
     {
         key: "timestamp",
@@ -3239,36 +3357,103 @@ class ReportStorage {
         }
     }
     /**
-     * Generates markdown report with all tick events for a strategy.
+     * Calculates statistical data from live trading events (Controller).
+     * Returns null for any unsafe numeric values (NaN, Infinity, etc).
      *
-     * @param strategyName - Strategy name
-     * @returns Markdown formatted report with all events
+     * @returns Statistical data (empty object if no events)
      */
-    getReport(strategyName) {
+    async getData() {
         if (this._eventList.length === 0) {
-            return functoolsKit.str.newline(`# Live Trading Report: ${strategyName}`, "", "No events recorded yet.");
+            return {
+                eventList: [],
+                totalEvents: 0,
+                totalClosed: 0,
+                winCount: 0,
+                lossCount: 0,
+                winRate: null,
+                avgPnl: null,
+                totalPnl: null,
+                stdDev: null,
+                sharpeRatio: null,
+                annualizedSharpeRatio: null,
+                certaintyRatio: null,
+                expectedYearlyReturns: null,
+            };
         }
-        const header = columns.map((col) => col.label);
-        const separator = columns.map(() => "---");
-        const rows = this._eventList.map((event) => columns.map((col) => col.format(event)));
-        const tableData = [header, separator, ...rows];
-        const table = functoolsKit.str.newline(tableData.map(row => `| ${row.join(" | ")} |`));
-        // Calculate statistics
         const closedEvents = this._eventList.filter((e) => e.action === "closed");
         const totalClosed = closedEvents.length;
         const winCount = closedEvents.filter((e) => e.pnl && e.pnl > 0).length;
         const lossCount = closedEvents.filter((e) => e.pnl && e.pnl < 0).length;
+        // Calculate basic statistics
         const avgPnl = totalClosed > 0
             ? closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0) / totalClosed
             : 0;
         const totalPnl = closedEvents.reduce((sum, e) => sum + (e.pnl || 0), 0);
-        return functoolsKit.str.newline(`# Live Trading Report: ${strategyName}`, "", table, "", `**Total events:** ${this._eventList.length}`, `**Closed signals:** ${totalClosed}`, totalClosed > 0
-            ? `**Win rate:** ${((winCount / totalClosed) * 100).toFixed(2)}% (${winCount}W / ${lossCount}L)`
-            : "", totalClosed > 0
-            ? `**Average PNL:** ${avgPnl > 0 ? "+" : ""}${avgPnl.toFixed(2)}%`
-            : "", totalClosed > 0
-            ? `**Total PNL:** ${totalPnl > 0 ? "+" : ""}${totalPnl.toFixed(2)}%`
-            : "");
+        const winRate = (winCount / totalClosed) * 100;
+        // Calculate Sharpe Ratio (risk-free rate = 0)
+        let sharpeRatio = 0;
+        let stdDev = 0;
+        if (totalClosed > 0) {
+            const returns = closedEvents.map((e) => e.pnl || 0);
+            const variance = returns.reduce((sum, r) => sum + Math.pow(r - avgPnl, 2), 0) / totalClosed;
+            stdDev = Math.sqrt(variance);
+            sharpeRatio = stdDev > 0 ? avgPnl / stdDev : 0;
+        }
+        const annualizedSharpeRatio = sharpeRatio * Math.sqrt(365);
+        // Calculate Certainty Ratio
+        let certaintyRatio = 0;
+        if (totalClosed > 0) {
+            const wins = closedEvents.filter((e) => e.pnl && e.pnl > 0);
+            const losses = closedEvents.filter((e) => e.pnl && e.pnl < 0);
+            const avgWin = wins.length > 0
+                ? wins.reduce((sum, e) => sum + (e.pnl || 0), 0) / wins.length
+                : 0;
+            const avgLoss = losses.length > 0
+                ? losses.reduce((sum, e) => sum + (e.pnl || 0), 0) / losses.length
+                : 0;
+            certaintyRatio = avgLoss < 0 ? avgWin / Math.abs(avgLoss) : 0;
+        }
+        // Calculate Expected Yearly Returns
+        let expectedYearlyReturns = 0;
+        if (totalClosed > 0) {
+            const avgDurationMin = closedEvents.reduce((sum, e) => sum + (e.duration || 0), 0) / totalClosed;
+            const avgDurationDays = avgDurationMin / (60 * 24);
+            const tradesPerYear = avgDurationDays > 0 ? 365 / avgDurationDays : 0;
+            expectedYearlyReturns = avgPnl * tradesPerYear;
+        }
+        return {
+            eventList: this._eventList,
+            totalEvents: this._eventList.length,
+            totalClosed,
+            winCount,
+            lossCount,
+            winRate: isUnsafe(winRate) ? null : winRate,
+            avgPnl: isUnsafe(avgPnl) ? null : avgPnl,
+            totalPnl: isUnsafe(totalPnl) ? null : totalPnl,
+            stdDev: isUnsafe(stdDev) ? null : stdDev,
+            sharpeRatio: isUnsafe(sharpeRatio) ? null : sharpeRatio,
+            annualizedSharpeRatio: isUnsafe(annualizedSharpeRatio) ? null : annualizedSharpeRatio,
+            certaintyRatio: isUnsafe(certaintyRatio) ? null : certaintyRatio,
+            expectedYearlyReturns: isUnsafe(expectedYearlyReturns) ? null : expectedYearlyReturns,
+        };
+    }
+    /**
+     * Generates markdown report with all tick events for a strategy (View).
+     *
+     * @param strategyName - Strategy name
+     * @returns Markdown formatted report with all events
+     */
+    async getReport(strategyName) {
+        const stats = await this.getData();
+        if (stats.totalEvents === 0) {
+            return functoolsKit.str.newline(`# Live Trading Report: ${strategyName}`, "", "No events recorded yet.");
+        }
+        const header = columns.map((col) => col.label);
+        const separator = columns.map(() => "---");
+        const rows = this._eventList.map((event) => columns.map((col) => col.format(event)));
+        const tableData = [header, separator, ...rows];
+        const table = functoolsKit.str.newline(tableData.map(row => `| ${row.join(" | ")} |`));
+        return functoolsKit.str.newline(`# Live Trading Report: ${strategyName}`, "", table, "", `**Total events:** ${stats.totalEvents}`, `**Closed signals:** ${stats.totalClosed}`, `**Win rate:** ${stats.winRate === null ? "N/A" : `${stats.winRate.toFixed(2)}% (${stats.winCount}W / ${stats.lossCount}L) (higher is better)`}`, `**Average PNL:** ${stats.avgPnl === null ? "N/A" : `${stats.avgPnl > 0 ? "+" : ""}${stats.avgPnl.toFixed(2)}% (higher is better)`}`, `**Total PNL:** ${stats.totalPnl === null ? "N/A" : `${stats.totalPnl > 0 ? "+" : ""}${stats.totalPnl.toFixed(2)}% (higher is better)`}`, `**Standard Deviation:** ${stats.stdDev === null ? "N/A" : `${stats.stdDev.toFixed(3)}% (lower is better)`}`, `**Sharpe Ratio:** ${stats.sharpeRatio === null ? "N/A" : `${stats.sharpeRatio.toFixed(3)} (higher is better)`}`, `**Annualized Sharpe Ratio:** ${stats.annualizedSharpeRatio === null ? "N/A" : `${stats.annualizedSharpeRatio.toFixed(3)} (higher is better)`}`, `**Certainty Ratio:** ${stats.certaintyRatio === null ? "N/A" : `${stats.certaintyRatio.toFixed(3)} (higher is better)`}`, `**Expected Yearly Returns:** ${stats.expectedYearlyReturns === null ? "N/A" : `${stats.expectedYearlyReturns > 0 ? "+" : ""}${stats.expectedYearlyReturns.toFixed(2)}% (higher is better)`}`);
     }
     /**
      * Saves strategy report to disk.
@@ -3277,7 +3462,7 @@ class ReportStorage {
      * @param path - Directory path to save report (default: "./logs/live")
      */
     async dump(strategyName, path$1 = "./logs/live") {
-        const markdown = this.getReport(strategyName);
+        const markdown = await this.getReport(strategyName);
         try {
             const dir = path.join(process.cwd(), path$1);
             await fs.mkdir(dir, { recursive: true });
@@ -3369,6 +3554,27 @@ class LiveMarkdownService {
                 storage.addClosedEvent(data);
             }
         };
+        /**
+         * Gets statistical data from all live trading events for a strategy.
+         * Delegates to ReportStorage.getData().
+         *
+         * @param strategyName - Strategy name to get data for
+         * @returns Statistical data object with all metrics
+         *
+         * @example
+         * ```typescript
+         * const service = new LiveMarkdownService();
+         * const stats = await service.getData("my-strategy");
+         * console.log(stats.sharpeRatio, stats.winRate);
+         * ```
+         */
+        this.getData = async (strategyName) => {
+            this.loggerService.log("liveMarkdownService getData", {
+                strategyName,
+            });
+            const storage = this.getStorage(strategyName);
+            return storage.getData();
+        };
         /**
          * Generates markdown report with all events for a strategy.
          * Delegates to ReportStorage.getReport().
@@ -4506,6 +4712,24 @@ class BacktestUtils {
                 isStopped = true;
             };
         };
+        /**
+         * Gets statistical data from all closed signals for a strategy.
+         *
+         * @param strategyName - Strategy name to get data for
+         * @returns Promise resolving to statistical data object
+         *
+         * @example
+         * ```typescript
+         * const stats = await Backtest.getData("my-strategy");
+         * console.log(stats.sharpeRatio, stats.winRate);
+         * ```
+         */
+        this.getData = async (strategyName) => {
+            backtest$1.loggerService.info("BacktestUtils.getData", {
+                strategyName,
+            });
+            return await backtest$1.backtestMarkdownService.getData(strategyName);
+        };
         /**
          * Generates markdown report with all closed signals for a strategy.
          *
@@ -4668,6 +4892,24 @@ class LiveUtils {
                 isStopped = true;
             };
         };
+        /**
+         * Gets statistical data from all live trading events for a strategy.
+         *
+         * @param strategyName - Strategy name to get data for
+         * @returns Promise resolving to statistical data object
+         *
+         * @example
+         * ```typescript
+         * const stats = await Live.getData("my-strategy");
+         * console.log(stats.sharpeRatio, stats.winRate);
+         * ```
+         */
+        this.getData = async (strategyName) => {
+            backtest$1.loggerService.info("LiveUtils.getData", {
+                strategyName,
+            });
+            return await backtest$1.liveMarkdownService.getData(strategyName);
+        };
         /**
          * Generates markdown report with all events for a strategy.
          *