backtest-kit 1.1.6 → 1.1.7

package/README.md

@@ -1,4 +1,4 @@
-# Backtest Kit
+# 🧿 Backtest Kit
 
 > A production-ready TypeScript framework for backtesting and live trading strategies with crash-safe state persistence, signal validation, and memory-optimized architecture.
 
@@ -22,7 +22,9 @@
 - 🛑 **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** - 45+ unit tests covering validation, PNL, callbacks, reports, and event system
+- 🧪 **Comprehensive Test Coverage** - 50+ unit tests covering validation, PNL, callbacks, reports, and event system
+- 💾 **Zero Data Download** - Unlike Freqtrade, no need to download gigabytes of historical data - plug any data source (CCXT, database, API)
+- 🔒 **Safe Math & Robustness** - All metrics protected against NaN/Infinity with unsafe numeric checks, returns N/A for invalid calculations
 
 ## Installation
 
@@ -106,7 +108,7 @@ addStrategy({
   interval: "5m", // Throttling: signals generated max once per 5 minutes
   getSignal: async (symbol) => {
     // Your signal generation logic
-    // Validation happens automatically (prices, TP/SL logic, timestamps)
+    // Validation happens automatically (prices, TP/SL logic)
     return {
       position: "long",
       note: "BTC breakout",
@@ -114,14 +116,13 @@ addStrategy({
       priceTakeProfit: 51000,  // Must be > priceOpen for long
       priceStopLoss: 49000,     // Must be < priceOpen for long
       minuteEstimatedTime: 60,  // Signal duration in minutes
-      timestamp: Date.now(),
     };
   },
   callbacks: {
-    onOpen: (backtest, symbol, signal) => {
+    onOpen: (symbol, signal, currentPrice, backtest) => {
       console.log(`[${backtest ? "BT" : "LIVE"}] Signal opened:`, signal.id);
     },
-    onClose: (backtest, symbol, priceClose, signal) => {
+    onClose: (symbol, signal, priceClose, backtest) => {
       console.log(`[${backtest ? "BT" : "LIVE"}] Signal closed:`, priceClose);
     },
   },
@@ -348,7 +349,6 @@ All signals are validated automatically before execution:
   priceTakeProfit: 51000,  // ✅ 51000 > 50000
   priceStopLoss: 49000,     // ✅ 49000 < 50000
   minuteEstimatedTime: 60,  // ✅ positive
-  timestamp: Date.now(),    // ✅ positive
 }
 
 // ❌ Invalid long signal - throws error
@@ -465,7 +465,26 @@ const stopBacktest = Backtest.background("BTCUSDT", {
   frameName: "1d-backtest"
 });
 
-// Generate markdown report
+// Get raw statistical data (Controller)
+const stats = await Backtest.getData("my-strategy");
+console.log(stats);
+// Returns:
+// {
+//   signalList: [...],           // All closed signals
+//   totalSignals: 10,
+//   winCount: 7,
+//   lossCount: 3,
+//   winRate: 70.0,               // Percentage (higher is better)
+//   avgPnl: 1.23,                // Average PNL % (higher is better)
+//   totalPnl: 12.30,             // Total PNL % (higher is better)
+//   stdDev: 2.45,                // Standard deviation (lower is better)
+//   sharpeRatio: 0.50,           // Risk-adjusted return (higher is better)
+//   annualizedSharpeRatio: 9.55, // Sharpe × √365 (higher is better)
+//   certaintyRatio: 1.75,        // avgWin / |avgLoss| (higher is better)
+//   expectedYearlyReturns: 156   // Estimated yearly trades (higher is better)
+// }
+
+// Generate markdown report (View)
 const markdown = await Backtest.getReport("my-strategy");
 console.log(markdown);
 
@@ -476,29 +495,75 @@ await Backtest.dump("my-strategy");
 await Backtest.dump("my-strategy", "./custom/path");
 ```
 
-**Report includes:**
-- Total closed signals
+**getData() returns BacktestStatistics:**
+- `signalList` - Array of all closed signals
+- `totalSignals` - Total number of closed signals
+- `winCount` / `lossCount` - Number of winning/losing trades
+- `winRate` - Win percentage (higher is better)
+- `avgPnl` - Average PNL percentage (higher is better)
+- `totalPnl` - Total PNL percentage (higher is better)
+- `stdDev` - Standard deviation / volatility (lower is better)
+- `sharpeRatio` - Risk-adjusted return (higher is better)
+- `annualizedSharpeRatio` - Sharpe Ratio × √365 (higher is better)
+- `certaintyRatio` - avgWin / |avgLoss| (higher is better)
+- `expectedYearlyReturns` - Estimated number of trades per year (higher is better)
+
+**getReport() includes:**
+- All metrics from getData() formatted as markdown
 - All signal details (prices, TP/SL, PNL, duration, close reason)
 - Timestamps for each signal
+- "Higher is better" / "Lower is better" annotations
 
 ### Live Trading Reports
 
 ```typescript
 import { Live } from "backtest-kit";
 
-// Generate live trading report
+// Get raw statistical data (Controller)
+const stats = await Live.getData("my-strategy");
+console.log(stats);
+// Returns:
+// {
+//   eventList: [...],            // All events (idle, opened, active, closed)
+//   totalEvents: 15,
+//   totalClosed: 5,
+//   winCount: 3,
+//   lossCount: 2,
+//   winRate: 60.0,               // Percentage (higher is better)
+//   avgPnl: 1.23,                // Average PNL % (higher is better)
+//   totalPnl: 6.15,              // Total PNL % (higher is better)
+//   stdDev: 1.85,                // Standard deviation (lower is better)
+//   sharpeRatio: 0.66,           // Risk-adjusted return (higher is better)
+//   annualizedSharpeRatio: 12.61,// Sharpe × √365 (higher is better)
+//   certaintyRatio: 2.10,        // avgWin / |avgLoss| (higher is better)
+//   expectedYearlyReturns: 365   // Estimated yearly trades (higher is better)
+// }
+
+// Generate markdown report (View)
 const markdown = await Live.getReport("my-strategy");
 
 // Save to disk (default: ./logs/live/my-strategy.md)
 await Live.dump("my-strategy");
 ```
 
-**Report includes:**
-- Total events (idle, opened, active, closed)
-- Closed signals count
-- Win rate (% wins, wins/losses)
-- Average PNL percentage
+**getData() returns LiveStatistics:**
+- `eventList` - Array of all events (idle, opened, active, closed)
+- `totalEvents` - Total number of events
+- `totalClosed` - Total number of closed signals
+- `winCount` / `lossCount` - Number of winning/losing trades
+- `winRate` - Win percentage (higher is better)
+- `avgPnl` - Average PNL percentage (higher is better)
+- `totalPnl` - Total PNL percentage (higher is better)
+- `stdDev` - Standard deviation / volatility (lower is better)
+- `sharpeRatio` - Risk-adjusted return (higher is better)
+- `annualizedSharpeRatio` - Sharpe Ratio × √365 (higher is better)
+- `certaintyRatio` - avgWin / |avgLoss| (higher is better)
+- `expectedYearlyReturns` - Estimated number of trades per year (higher is better)
+
+**getReport() includes:**
+- All metrics from getData() formatted as markdown
 - Signal-by-signal details with current state
+- "Higher is better" / "Lower is better" annotations
 
 **Report example:**
 ```markdown
@@ -506,8 +571,14 @@ await Live.dump("my-strategy");
 
 Total events: 15
 Closed signals: 5
-Win rate: 60.00% (3W / 2L)
-Average PNL: +1.23%
+Win rate: 60.00% (3W / 2L) (higher is better)
+Average PNL: +1.23% (higher is better)
+Total PNL: +6.15% (higher is better)
+Standard Deviation: 1.85% (lower is better)
+Sharpe Ratio: 0.66 (higher is better)
+Annualized Sharpe Ratio: 12.61 (higher is better)
+Certainty Ratio: 2.10 (higher is better)
+Expected Yearly Returns: 365 trades (higher is better)
 
 | Timestamp | Action | Symbol | Signal ID | Position | ... | PNL (net) | Close Reason |
 |-----------|--------|--------|-----------|----------|-----|-----------|--------------|
@@ -744,7 +815,7 @@ const quantity = await formatQuantity("BTCUSDT", 0.123456789);
 #### Backtest API
 
 ```typescript
-import { Backtest } from "backtest-kit";
+import { Backtest, BacktestStatistics } from "backtest-kit";
 
 // Stream backtest results
 Backtest.run(
@@ -762,7 +833,10 @@ Backtest.background(
   context: { strategyName, exchangeName, frameName }
 ): Promise<() => void> // Returns cancellation function
 
-// Generate markdown report
+// Get raw statistical data (Controller)
+Backtest.getData(strategyName: string): Promise<BacktestStatistics>
+
+// Generate markdown report (View)
 Backtest.getReport(strategyName: string): Promise<string>
 
 // Save report to disk
@@ -772,7 +846,7 @@ Backtest.dump(strategyName: string, path?: string): Promise<void>
 #### Live Trading API
 
 ```typescript
-import { Live } from "backtest-kit";
+import { Live, LiveStatistics } from "backtest-kit";
 
 // Stream live results (infinite)
 Live.run(
@@ -789,7 +863,10 @@ Live.background(
   context: { strategyName, exchangeName }
 ): Promise<() => void> // Returns cancellation function
 
-// Generate markdown report
+// Get raw statistical data (Controller)
+Live.getData(strategyName: string): Promise<LiveStatistics>
+
+// Generate markdown report (View)
 Live.getReport(strategyName: string): Promise<string>
 
 // Save report to disk
@@ -798,18 +875,58 @@ Live.dump(strategyName: string, path?: string): Promise<void>
 
 ## Type Definitions
 
+### Statistics Types
+
+```typescript
+// Backtest statistics (exported from "backtest-kit")
+interface BacktestStatistics {
+  signalList: IStrategyTickResultClosed[];  // All closed signals
+  totalSignals: number;
+  winCount: number;
+  lossCount: number;
+  winRate: number | null;               // Win percentage (higher is better)
+  avgPnl: number | null;                // Average PNL % (higher is better)
+  totalPnl: number | null;              // Total PNL % (higher is better)
+  stdDev: number | null;                // Standard deviation (lower is better)
+  sharpeRatio: number | null;           // Risk-adjusted return (higher is better)
+  annualizedSharpeRatio: number | null; // Sharpe × √365 (higher is better)
+  certaintyRatio: number | null;        // avgWin / |avgLoss| (higher is better)
+  expectedYearlyReturns: number | null; // Estimated yearly trades (higher is better)
+}
+
+// Live statistics (exported from "backtest-kit")
+interface LiveStatistics {
+  eventList: TickEvent[];               // All events (idle, opened, active, closed)
+  totalEvents: number;
+  totalClosed: number;
+  winCount: number;
+  lossCount: number;
+  winRate: number | null;               // Win percentage (higher is better)
+  avgPnl: number | null;                // Average PNL % (higher is better)
+  totalPnl: number | null;              // Total PNL % (higher is better)
+  stdDev: number | null;                // Standard deviation (lower is better)
+  sharpeRatio: number | null;           // Risk-adjusted return (higher is better)
+  annualizedSharpeRatio: number | null; // Sharpe × √365 (higher is better)
+  certaintyRatio: number | null;        // avgWin / |avgLoss| (higher is better)
+  expectedYearlyReturns: number | null; // Estimated yearly trades (higher is better)
+}
+```
+
 ### Signal Data
 
 ```typescript
 interface ISignalRow {
-  id: string;                    // Auto-generated
+  id: string;                     // UUID v4 auto-generated
   position: "long" | "short";
-  note: string;
+  note?: string;
   priceOpen: number;
   priceTakeProfit: number;
   priceStopLoss: number;
   minuteEstimatedTime: number;
-  timestamp: number;
+  exchangeName: string;
+  strategyName: string;
+  timestamp: number;              // Signal creation timestamp
+  symbol: string;                 // Trading pair (e.g., "BTCUSDT")
 }
 ```
 
@@ -817,9 +934,27 @@ interface ISignalRow {
 
 ```typescript
 type IStrategyTickResult =
-  | { action: "idle"; signal: null }
-  | { action: "opened"; signal: ISignalRow }
-  | { action: "active"; signal: ISignalRow; currentPrice: number }
+  | {
+      action: "idle";
+      signal: null;
+      strategyName: string;
+      exchangeName: string;
+      currentPrice: number;
+    }
+  | {
+      action: "opened";
+      signal: ISignalRow;
+      strategyName: string;
+      exchangeName: string;
+      currentPrice: number;
+    }
+  | {
+      action: "active";
+      signal: ISignalRow;
+      currentPrice: number;
+      strategyName: string;
+      exchangeName: string;
+    }
   | {
       action: "closed";
       signal: ISignalRow;
@@ -827,10 +962,12 @@ type IStrategyTickResult =
       closeReason: "take_profit" | "stop_loss" | "time_expired";
       closeTimestamp: number;
       pnl: {
-        priceOpenWithCosts: number;
-        priceCloseWithCosts: number;
         pnlPercentage: number;
+        priceOpen: number;        // Entry price adjusted with slippage and fees
+        priceClose: number;       // Exit price adjusted with slippage and fees
       };
+      strategyName: string;
+      exchangeName: string;
     };
 ```
 

package/build/index.cjs

@@ -1043,8 +1043,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 +1063,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);
         };
     }
     /**
@@ -1206,6 +1205,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,
@@ -3997,8 +3997,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"),
  *   },
  * });
  * ```

package/build/index.mjs

@@ -1041,8 +1041,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;
         };
@@ -1062,7 +1061,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);
         };
     }
     /**
@@ -1204,6 +1203,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     }
     const signalRow = {
         id: 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,
@@ -3995,8 +3995,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"),
  *   },
  * });
  * ```

package/package.json

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

package/types.d.ts

@@ -370,7 +370,7 @@ interface ISignalDto {
     /** Human-readable description of signal reason */
     note?: string;
     /** Entry price for the position */
-    priceOpen: number;
+    priceOpen?: number;
     /** Take profit target price (must be > priceOpen for long, < priceOpen for short) */
     priceTakeProfit: number;
     /** Stop loss exit price (must be < priceOpen for long, > priceOpen for short) */
@@ -385,6 +385,8 @@ interface ISignalDto {
 interface ISignalRow extends ISignalDto {
     /** Unique signal identifier (UUID v4 auto-generated) */
     id: string;
+    /** Entry price for the position */
+    priceOpen: number;
     /** Unique exchange identifier for execution */
     exchangeName: ExchangeName;
     /** Unique strategy identifier for execution */
@@ -597,8 +599,8 @@ type StrategyName = string;
  *     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"),
  *   },
  * });
  * ```
@@ -1593,10 +1595,7 @@ declare const BASE_WAIT_FOR_INIT_SYMBOL: unique symbol;
  * Signal data stored in persistence layer.
  * Contains nullable signal for atomic updates.
  */
-interface ISignalData {
-    /** Current signal state (null when no active signal) */
-    signalRow: ISignalRow | null;
-}
+type SignalData = ISignalRow | null;
 /**
  * Type helper for PersistBase instance.
  */
@@ -1777,7 +1776,7 @@ declare class PersistSignalUtils {
      * PersistSignalAdaper.usePersistSignalAdapter(RedisPersist);
      * ```
      */
-    usePersistSignalAdapter(Ctor: TPersistBaseCtor<StrategyName, ISignalData>): void;
+    usePersistSignalAdapter(Ctor: TPersistBaseCtor<StrategyName, SignalData>): void;
     /**
      * Reads persisted signal data for a strategy and symbol.
      *
@@ -3092,4 +3091,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type BacktestStatistics, type CandleInterval, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type ICandleData, type IExchangeSchema, type IFrameSchema, type IPersistBase, type ISignalData, type ISignalDto, type ISignalRow, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, Live, type LiveStatistics, MethodContextService, PersistBase, PersistSignalAdaper, type ProgressContract, type SignalInterval, type TPersistBase, type TPersistBaseCtor, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listStrategies, listenDone, listenDoneOnce, listenError, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };
+export { Backtest, type BacktestStatistics, type CandleInterval, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type ICandleData, type IExchangeSchema, type IFrameSchema, type IPersistBase, type ISignalDto, type ISignalRow, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, Live, type LiveStatistics, MethodContextService, PersistBase, PersistSignalAdaper, type ProgressContract, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listStrategies, listenDone, listenDoneOnce, listenError, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };