backtest-kit 2.2.14 → 2.2.16

package/package.json

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

package/types.d.ts

@@ -1003,6 +1003,86 @@ interface IBreakeven {
     clear(symbol: string, data: IPublicSignalRow, priceClose: number, backtest: boolean): Promise<void>;
 }
 
+/**
+ * Base fields for all signal commit events.
+ */
+interface SignalCommitBase {
+    symbol: string;
+    strategyName: StrategyName;
+    exchangeName: ExchangeName;
+    frameName: FrameName;
+    backtest: boolean;
+    /** Timestamp from execution context (tick's when or backtest candle timestamp) */
+    timestamp: number;
+}
+/**
+ * Cancel scheduled signal event.
+ */
+interface CancelScheduledCommit extends SignalCommitBase {
+    action: "cancel-scheduled";
+    cancelId?: string;
+}
+/**
+ * Close pending signal event.
+ */
+interface ClosePendingCommit extends SignalCommitBase {
+    action: "close-pending";
+    closeId?: string;
+}
+/**
+ * Partial profit event.
+ */
+interface PartialProfitCommit extends SignalCommitBase {
+    action: "partial-profit";
+    percentToClose: number;
+    currentPrice: number;
+}
+/**
+ * Partial loss event.
+ */
+interface PartialLossCommit extends SignalCommitBase {
+    action: "partial-loss";
+    percentToClose: number;
+    currentPrice: number;
+}
+/**
+ * Trailing stop event.
+ */
+interface TrailingStopCommit extends SignalCommitBase {
+    action: "trailing-stop";
+    percentShift: number;
+    currentPrice: number;
+}
+/**
+ * Trailing take event.
+ */
+interface TrailingTakeCommit extends SignalCommitBase {
+    action: "trailing-take";
+    percentShift: number;
+    currentPrice: number;
+}
+/**
+ * Breakeven event.
+ */
+interface BreakevenCommit extends SignalCommitBase {
+    action: "breakeven";
+    currentPrice: number;
+}
+/**
+ * Discriminated union for strategy management signal events.
+ *
+ * Emitted by strategyCommitSubject when strategy management actions are executed.
+ *
+ * Consumers:
+ * - StrategyReportService: Persists events to JSON files
+ * - StrategyMarkdownService: Accumulates events for markdown reports
+ *
+ * Note: Signal data (IPublicSignalRow) is NOT included in this contract.
+ * Consumers must retrieve signal data from StrategyCoreService using
+ * getPendingSignal() or getScheduledSignal() methods.
+ */
+type StrategyCommitContract = CancelScheduledCommit | ClosePendingCommit | PartialProfitCommit | PartialLossCommit | TrailingStopCommit | TrailingTakeCommit | BreakevenCommit;
+
 /**
  * Signal generation interval for throttling.
  * Enforces minimum time between getSignal calls.
@@ -1131,19 +1211,53 @@ interface IPublicSignalRow extends ISignalRow {
     partialExecuted: number;
 }
 /**
- * Storage signal row with creation timestamp taken from IStrategyTickResult.
+ * Base storage signal row fields shared by all status variants.
  * Used for persisting signals with accurate creation time.
  */
-interface IStorageSignalRow extends IPublicSignalRow {
+interface IStorageSignalRowBase extends IPublicSignalRow {
     /** Creation timestamp taken from IStrategyTickResult */
     createdAt: number;
     /** Creation timestamp taken from IStrategyTickResult */
     updatedAt: number;
     /** Storage adapter rewrite priority. Equal to Date.now for live and backtest both */
     priority: number;
+}
+/**
+ * Storage signal row for opened status.
+ */
+interface IStorageSignalRowOpened extends IStorageSignalRowBase {
+    /** Current status of the signal */
+    status: "opened";
+}
+/**
+ * Storage signal row for scheduled status.
+ */
+interface IStorageSignalRowScheduled extends IStorageSignalRowBase {
+    /** Current status of the signal */
+    status: "scheduled";
+}
+/**
+ * Storage signal row for closed status.
+ * Only closed signals have PNL data.
+ */
+interface IStorageSignalRowClosed extends IStorageSignalRowBase {
+    /** Current status of the signal */
+    status: "closed";
+    /** Profit and loss value for the signal when closed */
+    pnl: IStrategyPnL;
+}
+/**
+ * Storage signal row for cancelled status.
+ */
+interface IStorageSignalRowCancelled extends IStorageSignalRowBase {
     /** Current status of the signal */
-    status: "opened" | "scheduled" | "closed" | "cancelled";
+    status: "cancelled";
 }
+/**
+ * Discriminated union of storage signal rows.
+ * Use type guards: `row.status === "closed"` for type-safe access to pnl.
+ */
+type IStorageSignalRow = IStorageSignalRowOpened | IStorageSignalRowScheduled | IStorageSignalRowClosed | IStorageSignalRowCancelled;
 /**
  * Risk signal row for internal risk management.
  * Extends ISignalDto to include priceOpen, originalPriceStopLoss and originalPriceTakeProfit.
@@ -5103,84 +5217,6 @@ interface WalkerContract {
     totalStrategies: number;
 }
 
-/**
- * Base fields for all signal commit events.
- */
-interface SignalCommitBase {
-    symbol: string;
-    strategyName: StrategyName;
-    exchangeName: ExchangeName;
-    frameName: FrameName;
-    backtest: boolean;
-}
-/**
- * Cancel scheduled signal event.
- */
-interface CancelScheduledCommit extends SignalCommitBase {
-    action: "cancel-scheduled";
-    cancelId?: string;
-}
-/**
- * Close pending signal event.
- */
-interface ClosePendingCommit extends SignalCommitBase {
-    action: "close-pending";
-    closeId?: string;
-}
-/**
- * Partial profit event.
- */
-interface PartialProfitCommit extends SignalCommitBase {
-    action: "partial-profit";
-    percentToClose: number;
-    currentPrice: number;
-}
-/**
- * Partial loss event.
- */
-interface PartialLossCommit extends SignalCommitBase {
-    action: "partial-loss";
-    percentToClose: number;
-    currentPrice: number;
-}
-/**
- * Trailing stop event.
- */
-interface TrailingStopCommit extends SignalCommitBase {
-    action: "trailing-stop";
-    percentShift: number;
-    currentPrice: number;
-}
-/**
- * Trailing take event.
- */
-interface TrailingTakeCommit extends SignalCommitBase {
-    action: "trailing-take";
-    percentShift: number;
-    currentPrice: number;
-}
-/**
- * Breakeven event.
- */
-interface BreakevenCommit extends SignalCommitBase {
-    action: "breakeven";
-    currentPrice: number;
-}
-/**
- * Discriminated union for strategy management signal events.
- *
- * Emitted by strategyCommitSubject when strategy management actions are executed.
- *
- * Consumers:
- * - StrategyReportService: Persists events to JSON files
- * - StrategyMarkdownService: Accumulates events for markdown reports
- *
- * Note: Signal data (IPublicSignalRow) is NOT included in this contract.
- * Consumers must retrieve signal data from StrategyCoreService using
- * getPendingSignal() or getScheduledSignal() methods.
- */
-type StrategyCommitContract = CancelScheduledCommit | ClosePendingCommit | PartialProfitCommit | PartialLossCommit | TrailingStopCommit | TrailingTakeCommit | BreakevenCommit;
-
 /**
  * Subscribes to all signal events with queued async processing.
  *
@@ -6560,6 +6596,8 @@ interface PartialProfitAvailableNotification {
     priceOpen: number;
     /** Trade direction: "long" (buy) or "short" (sell) */
     position: "long" | "short";
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Partial loss notification.
@@ -6590,6 +6628,8 @@ interface PartialLossAvailableNotification {
     priceOpen: number;
     /** Trade direction: "long" (buy) or "short" (sell) */
     position: "long" | "short";
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Breakeven available notification.
@@ -6618,6 +6658,8 @@ interface BreakevenAvailableNotification {
     priceOpen: number;
     /** Trade direction: "long" (buy) or "short" (sell) */
     position: "long" | "short";
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Partial profit commit notification.
@@ -6642,6 +6684,8 @@ interface PartialProfitCommitNotification {
     percentToClose: number;
     /** Current market price when partial was executed */
     currentPrice: number;
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Partial loss commit notification.
@@ -6666,6 +6710,8 @@ interface PartialLossCommitNotification {
     percentToClose: number;
     /** Current market price when partial was executed */
     currentPrice: number;
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Breakeven commit notification.
@@ -6688,6 +6734,8 @@ interface BreakevenCommitNotification {
     exchangeName: ExchangeName;
     /** Current market price when breakeven was executed */
     currentPrice: number;
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Trailing stop commit notification.
@@ -6712,6 +6760,8 @@ interface TrailingStopCommitNotification {
     percentShift: number;
     /** Current market price when trailing stop was executed */
     currentPrice: number;
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Trailing take commit notification.
@@ -6736,6 +6786,8 @@ interface TrailingTakeCommitNotification {
     percentShift: number;
     /** Current market price when trailing take was executed */
     currentPrice: number;
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Risk rejection notification.
@@ -6766,6 +6818,8 @@ interface RiskRejectionNotification {
     currentPrice: number;
     /** The signal that was rejected */
     pendingSignal: ISignalDto;
+    /** Unix timestamp in milliseconds when the notification was created */
+    createdAt: number;
 }
 /**
  * Scheduled signal notification.
@@ -6844,8 +6898,6 @@ interface InfoErrorNotification {
     error: object;
     /** Human-readable error message */
     message: string;
-    /** Unix timestamp in milliseconds when error occurred */
-    timestamp: number;
     /** Always false for error notifications (errors are from live context) */
     backtest: boolean;
 }
@@ -6862,8 +6914,6 @@ interface CriticalErrorNotification {
     error: object;
     /** Human-readable error message */
     message: string;
-    /** Unix timestamp in milliseconds when critical error occurred */
-    timestamp: number;
     /** Always false for error notifications (errors are from live context) */
     backtest: boolean;
 }
@@ -6880,8 +6930,6 @@ interface ValidationErrorNotification {
     error: object;
     /** Human-readable validation error message */
     message: string;
-    /** Unix timestamp in milliseconds when validation error occurred */
-    timestamp: number;
     /** Always false for error notifications (errors are from live context) */
     backtest: boolean;
 }
@@ -13899,9 +13947,6 @@ type Columns = ColumnModel<StrategyEvent>;
  */
 declare class StrategyMarkdownService {
     readonly loggerService: LoggerService;
-    readonly executionContextService: {
-        readonly context: IExecutionContext;
-    };
     readonly strategyCoreService: StrategyCoreService;
     /**
      * Memoized factory for ReportStorage instances.
@@ -13915,114 +13960,105 @@ declare class StrategyMarkdownService {
     /**
      * Records a cancel-scheduled event when a scheduled signal is cancelled.
      *
-     * Retrieves the scheduled signal from StrategyCoreService and stores
-     * the cancellation event in the appropriate ReportStorage.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      * @param cancelId - Optional identifier for the cancellation reason
      */
     cancelScheduled: (symbol: string, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, cancelId?: string) => Promise<void>;
+    }, timestamp: number, cancelId?: string) => Promise<void>;
     /**
      * Records a close-pending event when a pending signal is closed.
      *
-     * Retrieves the pending signal from StrategyCoreService and stores
-     * the close event in the appropriate ReportStorage.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      * @param closeId - Optional identifier for the close reason
      */
     closePending: (symbol: string, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, closeId?: string) => Promise<void>;
+    }, timestamp: number, closeId?: string) => Promise<void>;
     /**
      * Records a partial-profit event when a portion of the position is closed at profit.
      *
-     * Stores the percentage closed and current price when partial profit-taking occurs.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentToClose - Percentage of position to close (0-100)
      * @param currentPrice - Current market price at time of partial close
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     partialProfit: (symbol: string, percentToClose: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Records a partial-loss event when a portion of the position is closed at loss.
      *
-     * Stores the percentage closed and current price when partial loss-cutting occurs.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentToClose - Percentage of position to close (0-100)
      * @param currentPrice - Current market price at time of partial close
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     partialLoss: (symbol: string, percentToClose: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Records a trailing-stop event when the stop-loss is adjusted.
      *
-     * Stores the percentage shift and current price when trailing stop moves.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentShift - Percentage the stop-loss was shifted
      * @param currentPrice - Current market price at time of adjustment
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     trailingStop: (symbol: string, percentShift: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Records a trailing-take event when the take-profit is adjusted.
      *
-     * Stores the percentage shift and current price when trailing take-profit moves.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentShift - Percentage the take-profit was shifted
      * @param currentPrice - Current market price at time of adjustment
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     trailingTake: (symbol: string, percentShift: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Records a breakeven event when the stop-loss is moved to entry price.
      *
-     * Stores the current price when breakeven protection is activated.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param currentPrice - Current market price at time of breakeven activation
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     breakeven: (symbol: string, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Retrieves aggregated statistics from accumulated strategy events.
      *
@@ -19397,141 +19433,114 @@ declare class RiskReportService {
  * - Events are written via Report.writeData() with "strategy" category
  * - Call unsubscribe() to disable event logging
  *
- * @example
- * ```typescript
- * // Service is typically used internally by strategy management classes
- * strategyReportService.subscribe();
- *
- * // Events are logged automatically when strategy actions occur
- * await strategyReportService.partialProfit("BTCUSDT", 50, 50100, false, {
- *   strategyName: "my-strategy",
- *   exchangeName: "binance",
- *   frameName: "1h"
- * });
- *
- * strategyReportService.unsubscribe();
- * ```
- *
  * @see StrategyMarkdownService for in-memory event accumulation and markdown report generation
  * @see Report for the underlying persistence mechanism
  */
 declare class StrategyReportService {
     readonly loggerService: LoggerService;
-    readonly executionContextService: {
-        readonly context: IExecutionContext;
-    };
     readonly strategyCoreService: StrategyCoreService;
     /**
      * Logs a cancel-scheduled event when a scheduled signal is cancelled.
      *
-     * Retrieves the scheduled signal from StrategyCoreService and writes
-     * the cancellation event to the report file.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      * @param cancelId - Optional identifier for the cancellation reason
      */
     cancelScheduled: (symbol: string, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, cancelId?: string) => Promise<void>;
+    }, timestamp: number, cancelId?: string) => Promise<void>;
     /**
      * Logs a close-pending event when a pending signal is closed.
      *
-     * Retrieves the pending signal from StrategyCoreService and writes
-     * the close event to the report file.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      * @param closeId - Optional identifier for the close reason
      */
     closePending: (symbol: string, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }, closeId?: string) => Promise<void>;
+    }, timestamp: number, closeId?: string) => Promise<void>;
     /**
      * Logs a partial-profit event when a portion of the position is closed at profit.
      *
-     * Records the percentage closed and current price when partial profit-taking occurs.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentToClose - Percentage of position to close (0-100)
      * @param currentPrice - Current market price at time of partial close
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     partialProfit: (symbol: string, percentToClose: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Logs a partial-loss event when a portion of the position is closed at loss.
      *
-     * Records the percentage closed and current price when partial loss-cutting occurs.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentToClose - Percentage of position to close (0-100)
      * @param currentPrice - Current market price at time of partial close
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     partialLoss: (symbol: string, percentToClose: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Logs a trailing-stop event when the stop-loss is adjusted.
      *
-     * Records the percentage shift and current price when trailing stop moves.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentShift - Percentage the stop-loss was shifted
      * @param currentPrice - Current market price at time of adjustment
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     trailingStop: (symbol: string, percentShift: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Logs a trailing-take event when the take-profit is adjusted.
      *
-     * Records the percentage shift and current price when trailing take-profit moves.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param percentShift - Percentage the take-profit was shifted
      * @param currentPrice - Current market price at time of adjustment
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     trailingTake: (symbol: string, percentShift: number, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Logs a breakeven event when the stop-loss is moved to entry price.
      *
-     * Records the current price when breakeven protection is activated.
-     *
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param currentPrice - Current market price at time of breakeven activation
      * @param isBacktest - Whether this is a backtest or live trading event
      * @param context - Strategy context with strategyName, exchangeName, frameName
+     * @param timestamp - Timestamp from StrategyCommitContract (execution context time)
      */
     breakeven: (symbol: string, currentPrice: number, isBacktest: boolean, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
-    }) => Promise<void>;
+    }, timestamp: number) => Promise<void>;
     /**
      * Initializes the service for event logging.
      *