backtest-kit 8.1.2 → 8.2.0

package/build/index.cjs

@@ -21989,14 +21989,24 @@ let ReportStorage$a = class ReportStorage {
             `**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)`}`,
+            `**Annualized Sharpe Ratio:** ${stats.annualizedSharpeRatio === null ? "N/A" : `${stats.annualizedSharpeRatio.toFixed(3)} (higher is better, theoretical)`}`,
             `**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)`}`,
+            `**Expected Yearly Returns:** ${stats.expectedYearlyReturns === null ? "N/A" : `${stats.expectedYearlyReturns > 0 ? "+" : ""}${stats.expectedYearlyReturns.toFixed(2)}% (higher is better, theoretical)`}`,
             `**Avg Peak PNL:** ${stats.avgPeakPnl === null ? "N/A" : `${stats.avgPeakPnl > 0 ? "+" : ""}${stats.avgPeakPnl.toFixed(2)}% (higher is better)`}`,
             `**Avg Max Drawdown PNL:** ${stats.avgFallPnl === null ? "N/A" : `${stats.avgFallPnl.toFixed(2)}% (closer to 0 is better)`}`,
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
-            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
+            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better, theoretical)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            "",
+            `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
+            `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Annualized Sharpe Ratio: theoretical maximum assuming continuous trading. Real-world value is lower due to idle periods.*`,
+            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
+            `*Expected Yearly Returns: theoretical maximum assuming all capital is deployed continuously with no idle time.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
+            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
+            `*All metrics require 100+ signals to be statistically reliable. Time period matters only for Annualized Sharpe Ratio and Expected Yearly Returns — they assume current market conditions hold year-round, which may not reflect reality.*`,
         ].join("\n");
     }
     /**
@@ -22728,8 +22738,18 @@ let ReportStorage$9 = class ReportStorage {
             `**Avg Peak PNL:** ${stats.avgPeakPnl === null ? "N/A" : `${stats.avgPeakPnl > 0 ? "+" : ""}${stats.avgPeakPnl.toFixed(2)}% (higher is better)`}`,
             `**Avg Max Drawdown PNL:** ${stats.avgFallPnl === null ? "N/A" : `${stats.avgFallPnl.toFixed(2)}% (closer to 0 is better)`}`,
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
-            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
+            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better, theoretical)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            "",
+            `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
+            `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Annualized Sharpe Ratio: theoretical maximum assuming continuous trading. Real-world value is lower due to idle periods.*`,
+            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
+            `*Expected Yearly Returns: theoretical maximum assuming all capital is deployed continuously with no idle time.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
+            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
+            `*All metrics require 100+ signals to be statistically reliable. Time period matters only for Annualized Sharpe Ratio and Expected Yearly Returns — they assume current market conditions hold year-round, which may not reflect reality.*`,
         ].join("\n");
     }
     /**
@@ -24851,7 +24871,16 @@ class HeatmapStorage {
             "",
             `**Total Symbols:** ${data.totalSymbols} | **Portfolio PNL:** ${data.portfolioTotalPnl !== null ? functoolsKit.str(data.portfolioTotalPnl, "%") : "N/A"} | **Portfolio Sharpe:** ${data.portfolioSharpeRatio !== null ? functoolsKit.str(data.portfolioSharpeRatio) : "N/A"} | **Total Trades:** ${data.portfolioTotalTrades} | **Avg Peak PNL:** ${data.portfolioAvgPeakPnl !== null ? functoolsKit.str(data.portfolioAvgPeakPnl, "%") : "N/A"} | **Avg Max Drawdown PNL:** ${data.portfolioAvgFallPnl !== null ? functoolsKit.str(data.portfolioAvgFallPnl, "%") : "N/A"}`,
             "",
-            table
+            table,
+            "",
+            `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
+            `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals per symbol.*`,
+            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
+            `*Profit Factor: below 1.0 means strategy is losing overall. Above 1.5 is considered good.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
+            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
+            `*All metrics require 100+ signals per symbol to be statistically reliable. Time period matters only for Calmar Ratio — it assumes current market conditions hold year-round, which may not reflect reality.*`,
         ].join("\n");
     }
     /**
@@ -35786,6 +35815,7 @@ class BrokerProxy {
      */
     async onSignalOpenCommit(payload) {
         if (this._instance.onSignalOpenCommit) {
+            await this.waitForInit();
             await this._instance.onSignalOpenCommit(payload);
             return;
         }
@@ -35800,6 +35830,7 @@ class BrokerProxy {
      */
     async onSignalCloseCommit(payload) {
         if (this._instance.onSignalCloseCommit) {
+            await this.waitForInit();
             await this._instance.onSignalCloseCommit(payload);
             return;
         }
@@ -35814,6 +35845,7 @@ class BrokerProxy {
      */
     async onPartialProfitCommit(payload) {
         if (this._instance.onPartialProfitCommit) {
+            await this.waitForInit();
             await this._instance.onPartialProfitCommit(payload);
             return;
         }
@@ -35828,6 +35860,7 @@ class BrokerProxy {
      */
     async onPartialLossCommit(payload) {
         if (this._instance.onPartialLossCommit) {
+            await this.waitForInit();
             await this._instance.onPartialLossCommit(payload);
             return;
         }
@@ -35842,6 +35875,7 @@ class BrokerProxy {
      */
     async onTrailingStopCommit(payload) {
         if (this._instance.onTrailingStopCommit) {
+            await this.waitForInit();
             await this._instance.onTrailingStopCommit(payload);
             return;
         }
@@ -35856,6 +35890,7 @@ class BrokerProxy {
      */
     async onTrailingTakeCommit(payload) {
         if (this._instance.onTrailingTakeCommit) {
+            await this.waitForInit();
             await this._instance.onTrailingTakeCommit(payload);
             return;
         }
@@ -35870,6 +35905,7 @@ class BrokerProxy {
      */
     async onBreakevenCommit(payload) {
         if (this._instance.onBreakevenCommit) {
+            await this.waitForInit();
             await this._instance.onBreakevenCommit(payload);
             return;
         }
@@ -35884,6 +35920,7 @@ class BrokerProxy {
      */
     async onAverageBuyCommit(payload) {
         if (this._instance.onAverageBuyCommit) {
+            await this.waitForInit();
             await this._instance.onAverageBuyCommit(payload);
             return;
         }

package/build/index.mjs

@@ -21969,14 +21969,24 @@ let ReportStorage$a = class ReportStorage {
             `**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)`}`,
+            `**Annualized Sharpe Ratio:** ${stats.annualizedSharpeRatio === null ? "N/A" : `${stats.annualizedSharpeRatio.toFixed(3)} (higher is better, theoretical)`}`,
             `**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)`}`,
+            `**Expected Yearly Returns:** ${stats.expectedYearlyReturns === null ? "N/A" : `${stats.expectedYearlyReturns > 0 ? "+" : ""}${stats.expectedYearlyReturns.toFixed(2)}% (higher is better, theoretical)`}`,
             `**Avg Peak PNL:** ${stats.avgPeakPnl === null ? "N/A" : `${stats.avgPeakPnl > 0 ? "+" : ""}${stats.avgPeakPnl.toFixed(2)}% (higher is better)`}`,
             `**Avg Max Drawdown PNL:** ${stats.avgFallPnl === null ? "N/A" : `${stats.avgFallPnl.toFixed(2)}% (closer to 0 is better)`}`,
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
-            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
+            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better, theoretical)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            "",
+            `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
+            `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Annualized Sharpe Ratio: theoretical maximum assuming continuous trading. Real-world value is lower due to idle periods.*`,
+            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
+            `*Expected Yearly Returns: theoretical maximum assuming all capital is deployed continuously with no idle time.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
+            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
+            `*All metrics require 100+ signals to be statistically reliable. Time period matters only for Annualized Sharpe Ratio and Expected Yearly Returns — they assume current market conditions hold year-round, which may not reflect reality.*`,
         ].join("\n");
     }
     /**
@@ -22708,8 +22718,18 @@ let ReportStorage$9 = class ReportStorage {
             `**Avg Peak PNL:** ${stats.avgPeakPnl === null ? "N/A" : `${stats.avgPeakPnl > 0 ? "+" : ""}${stats.avgPeakPnl.toFixed(2)}% (higher is better)`}`,
             `**Avg Max Drawdown PNL:** ${stats.avgFallPnl === null ? "N/A" : `${stats.avgFallPnl.toFixed(2)}% (closer to 0 is better)`}`,
             `**Sortino Ratio:** ${stats.sortinoRatio === null ? "N/A" : `${stats.sortinoRatio.toFixed(3)} (higher is better)`}`,
-            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better)`}`,
+            `**Calmar Ratio:** ${stats.calmarRatio === null ? "N/A" : `${stats.calmarRatio.toFixed(3)} (higher is better, theoretical)`}`,
             `**Recovery Factor:** ${stats.recoveryFactor === null ? "N/A" : `${stats.recoveryFactor.toFixed(3)} (higher is better)`}`,
+            "",
+            `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
+            `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Annualized Sharpe Ratio: theoretical maximum assuming continuous trading. Real-world value is lower due to idle periods.*`,
+            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
+            `*Expected Yearly Returns: theoretical maximum assuming all capital is deployed continuously with no idle time.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
+            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
+            `*All metrics require 100+ signals to be statistically reliable. Time period matters only for Annualized Sharpe Ratio and Expected Yearly Returns — they assume current market conditions hold year-round, which may not reflect reality.*`,
         ].join("\n");
     }
     /**
@@ -24831,7 +24851,16 @@ class HeatmapStorage {
             "",
             `**Total Symbols:** ${data.totalSymbols} | **Portfolio PNL:** ${data.portfolioTotalPnl !== null ? str(data.portfolioTotalPnl, "%") : "N/A"} | **Portfolio Sharpe:** ${data.portfolioSharpeRatio !== null ? str(data.portfolioSharpeRatio) : "N/A"} | **Total Trades:** ${data.portfolioTotalTrades} | **Avg Peak PNL:** ${data.portfolioAvgPeakPnl !== null ? str(data.portfolioAvgPeakPnl, "%") : "N/A"} | **Avg Max Drawdown PNL:** ${data.portfolioAvgFallPnl !== null ? str(data.portfolioAvgFallPnl, "%") : "N/A"}`,
             "",
-            table
+            table,
+            "",
+            `*Win Rate: reliable above 200+ signals; below 30 signals a single streak can shift it by 10-20%.*`,
+            `*Sharpe Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals per symbol.*`,
+            `*Sortino Ratio: below 1.0 is poor, 1.0-2.0 is acceptable, above 2.0 is strong. Requires 30+ signals.*`,
+            `*Certainty Ratio: below 1.0 means average loss exceeds average win. Above 1.5 is considered good.*`,
+            `*Profit Factor: below 1.0 means strategy is losing overall. Above 1.5 is considered good.*`,
+            `*Calmar Ratio: below 0.5 is poor, 0.5-1.0 is acceptable, above 1.0 is strong. Based on theoretical yearly returns.*`,
+            `*Recovery Factor: below 1.0 means total profit does not cover max drawdown. Above 3.0 is considered good.*`,
+            `*All metrics require 100+ signals per symbol to be statistically reliable. Time period matters only for Calmar Ratio — it assumes current market conditions hold year-round, which may not reflect reality.*`,
         ].join("\n");
     }
     /**
@@ -35766,6 +35795,7 @@ class BrokerProxy {
      */
     async onSignalOpenCommit(payload) {
         if (this._instance.onSignalOpenCommit) {
+            await this.waitForInit();
             await this._instance.onSignalOpenCommit(payload);
             return;
         }
@@ -35780,6 +35810,7 @@ class BrokerProxy {
      */
     async onSignalCloseCommit(payload) {
         if (this._instance.onSignalCloseCommit) {
+            await this.waitForInit();
             await this._instance.onSignalCloseCommit(payload);
             return;
         }
@@ -35794,6 +35825,7 @@ class BrokerProxy {
      */
     async onPartialProfitCommit(payload) {
         if (this._instance.onPartialProfitCommit) {
+            await this.waitForInit();
             await this._instance.onPartialProfitCommit(payload);
             return;
         }
@@ -35808,6 +35840,7 @@ class BrokerProxy {
      */
     async onPartialLossCommit(payload) {
         if (this._instance.onPartialLossCommit) {
+            await this.waitForInit();
             await this._instance.onPartialLossCommit(payload);
             return;
         }
@@ -35822,6 +35855,7 @@ class BrokerProxy {
      */
     async onTrailingStopCommit(payload) {
         if (this._instance.onTrailingStopCommit) {
+            await this.waitForInit();
             await this._instance.onTrailingStopCommit(payload);
             return;
         }
@@ -35836,6 +35870,7 @@ class BrokerProxy {
      */
     async onTrailingTakeCommit(payload) {
         if (this._instance.onTrailingTakeCommit) {
+            await this.waitForInit();
             await this._instance.onTrailingTakeCommit(payload);
             return;
         }
@@ -35850,6 +35885,7 @@ class BrokerProxy {
      */
     async onBreakevenCommit(payload) {
         if (this._instance.onBreakevenCommit) {
+            await this.waitForInit();
             await this._instance.onBreakevenCommit(payload);
             return;
         }
@@ -35864,6 +35900,7 @@ class BrokerProxy {
      */
     async onAverageBuyCommit(payload) {
         if (this._instance.onAverageBuyCommit) {
+            await this.waitForInit();
             await this._instance.onAverageBuyCommit(payload);
             return;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "8.1.2",
+  "version": "8.2.0",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",