backtest-kit 5.0.0 → 5.1.0

package/package.json

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

package/types.d.ts

@@ -2164,8 +2164,8 @@ interface ISignalRow extends ISignalDto {
          * Used to slice _entry to only entries that existed at this partial.
          */
         entryCountAtClose: number;
-        /** Debug only timestamp in milliseconds */
-        debugTimestamp?: number;
+        /** Unix timestamp in milliseconds when this partial close was executed */
+        timestamp: number;
     }>;
     /**
      * Trailing stop-loss price that overrides priceStopLoss when set.
@@ -2188,8 +2188,8 @@ interface ISignalRow extends ISignalDto {
         price: number;
         /** Cost of this entry in USD (e.g. 100 for $100 position) */
         cost: number;
-        /** Debug only timestamp in milliseconds */
-        debugTimestamp?: number;
+        /** Unix timestamp in milliseconds when this entry was executed */
+        timestamp: number;
     }>;
     /**
      * Trailing take-profit price that overrides priceTakeProfit when set.
@@ -2866,9 +2866,29 @@ interface IStrategy {
      * @param symbol - Trading pair symbol
      * @returns Promise resolving to array of entry records or null
      */
-    getPositionEntries: (symbol: string) => Promise<Array<{
+    getPositionEntries: (symbol: string, timestamp: number) => Promise<Array<{
         price: number;
         cost: number;
+        timestamp: number;
+    }> | null>;
+    /**
+     * Returns the history of partial closes for the current pending signal.
+     *
+     * Each record includes the type (profit or loss), percentage closed, price, cost basis at close, and timestamp.
+     * Used for tracking how the position was partially closed over time.
+     *
+     * Returns null if no pending signal exists or no partial closes were executed.
+     *
+     * @param symbol - Trading pair symbol
+     * @returns Promise resolving to array of partial close records or null
+     */
+    getPositionPartials: (symbol: string) => Promise<Array<{
+        type: "profit" | "loss";
+        percent: number;
+        currentPrice: number;
+        costBasisAtClose: number;
+        entryCountAtClose: number;
+        timestamp: number;
     }> | null>;
     /**
      * Fast backtest using historical candles.
@@ -2988,14 +3008,15 @@ interface IStrategy {
      * @param percentToClose - Absolute percentage of position to close (0-100)
      * @param currentPrice - Current market price for partial close
      * @param backtest - Whether running in backtest mode
+     * @param timestamp - Unix timestamp (ms) of the candle that triggered this partial close
      * @returns Promise<boolean> - true if partial close executed, false if skipped
      *
      * @example
      * ```typescript
      * callbacks: {
-     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest) => {
+     *   onPartialProfit: async (symbol, signal, currentPrice, percentTp, backtest, timestamp) => {
      *     if (percentTp >= 50) {
-     *       const success = await strategy.partialProfit(symbol, 25, currentPrice, backtest);
+     *       const success = await strategy.partialProfit(symbol, 25, currentPrice, backtest, timestamp);
      *       if (success) {
      *         console.log('Partial profit executed');
      *       }
@@ -3004,7 +3025,7 @@ interface IStrategy {
      * }
      * ```
      */
-    partialProfit: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    partialProfit: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean, timestamp: number) => Promise<boolean>;
     /**
      * Checks whether `partialProfit` would succeed without executing it.
      *
@@ -3043,14 +3064,15 @@ interface IStrategy {
      * @param percentToClose - Absolute percentage of position to close (0-100)
      * @param currentPrice - Current market price for partial close
      * @param backtest - Whether running in backtest mode
+     * @param timestamp - Unix timestamp (ms) of the candle that triggered this partial close
      * @returns Promise<boolean> - true if partial close executed, false if skipped
      *
      * @example
      * ```typescript
      * callbacks: {
-     *   onPartialLoss: async (symbol, signal, currentPrice, percentSl, backtest) => {
+     *   onPartialLoss: async (symbol, signal, currentPrice, percentSl, backtest, timestamp) => {
      *     if (percentSl >= 80) {
-     *       const success = await strategy.partialLoss(symbol, 50, currentPrice, backtest);
+     *       const success = await strategy.partialLoss(symbol, 50, currentPrice, backtest, timestamp);
      *       if (success) {
      *         console.log('Partial loss executed');
      *       }
@@ -3059,7 +3081,7 @@ interface IStrategy {
      * }
      * ```
      */
-    partialLoss: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    partialLoss: (symbol: string, percentToClose: number, currentPrice: number, backtest: boolean, timestamp: number) => Promise<boolean>;
     /**
      * Checks whether `partialLoss` would succeed without executing it.
      *
@@ -3318,9 +3340,11 @@ interface IStrategy {
      * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
      * @param currentPrice - New entry price to add to the averaging history
      * @param backtest - Whether running in backtest mode
+     * @param timestamp - Unix timestamp (ms) of the candle that triggered this DCA entry
+     * @param cost - Optional cost of the new entry (defaults to $100 if not provided)
      * @returns Promise<boolean> - true if entry added, false if rejected by direction check
      */
-    averageBuy: (symbol: string, currentPrice: number, backtest: boolean) => Promise<boolean>;
+    averageBuy: (symbol: string, currentPrice: number, backtest: boolean, timestamp: number, cost?: number) => Promise<boolean>;
     /**
      * Checks whether `averageBuy` would succeed without executing it.
      *
@@ -5010,7 +5034,7 @@ declare function getPositionPartials(symbol: string): Promise<{
     currentPrice: number;
     costBasisAtClose: number;
     entryCountAtClose: number;
-    debugTimestamp?: number;
+    timestamp: number;
 }[]>;
 /**
  * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
@@ -11837,7 +11861,7 @@ declare class BacktestUtils {
         currentPrice: number;
         costBasisAtClose: number;
         entryCountAtClose: number;
-        debugTimestamp?: number;
+        timestamp: number;
     }[]>;
     /**
      * Returns the list of DCA entry prices and costs for the current pending signal.
@@ -11863,6 +11887,7 @@ declare class BacktestUtils {
     }) => Promise<{
         price: number;
         cost: number;
+        timestamp: number;
     }[]>;
     /**
      * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
@@ -12958,7 +12983,7 @@ declare class LiveUtils {
         currentPrice: number;
         costBasisAtClose: number;
         entryCountAtClose: number;
-        debugTimestamp?: number;
+        timestamp: number;
     }[]>;
     /**
      * Returns the list of DCA entry prices and costs for the current pending signal.
@@ -12983,6 +13008,7 @@ declare class LiveUtils {
     }) => Promise<{
         price: number;
         cost: number;
+        timestamp: number;
     }[]>;
     /**
      * Checks whether the current price falls within the tolerance zone of any existing DCA entry level.
@@ -16417,7 +16443,7 @@ declare class NotificationBacktestAdapter implements INotificationUtils {
      * Proxies call to the underlying notification adapter.
      * @param data - The signal sync contract data
      */
-    handleSync: (data: SignalSyncContract) => Promise<void>;
+    handleSync: (data: SignalSyncContract) => any;
     /**
      * Handles risk rejection event.
      * Proxies call to the underlying notification adapter.
@@ -16523,7 +16549,7 @@ declare class NotificationLiveAdapter implements INotificationUtils {
      * Proxies call to the underlying notification adapter.
      * @param data - The signal sync contract data
      */
-    handleSync: (data: SignalSyncContract) => Promise<void>;
+    handleSync: (data: SignalSyncContract) => any;
     /**
      * Handles risk rejection event.
      * Proxies call to the underlying notification adapter.
@@ -20907,6 +20933,184 @@ declare class BreakevenConnectionService implements IBreakeven {
     clear: (symbol: string, data: IPublicSignalRow, priceClose: number, backtest: boolean) => Promise<void>;
 }
 
+/**
+ * Service for tracking the latest candle timestamp per symbol-strategy-exchange-frame combination.
+ *
+ * Maintains a memoized BehaviorSubject per unique key that is updated on every strategy tick
+ * by StrategyConnectionService. Consumers can synchronously read the last known timestamp or
+ * await the first value if none has arrived yet.
+ *
+ * Primary use case: providing the current candle time outside of a tick execution context,
+ * e.g., when a command is triggered between ticks.
+ *
+ * Features:
+ * - One BehaviorSubject per (symbol, strategyName, exchangeName, frameName, backtest) key
+ * - Falls back to ExecutionContextService.context.when when called inside an execution context
+ * - Waits up to LISTEN_TIMEOUT ms for the first timestamp if none is cached yet
+ * - clear() disposes the BehaviorSubject for a single key or all keys
+ *
+ * Architecture:
+ * - Registered as singleton in DI container
+ * - Updated by StrategyConnectionService after each tick
+ * - Cleared by Backtest/Live/Walker at strategy start to prevent stale data
+ *
+ * @example
+ * ```typescript
+ * const ts = await backtest.timeMetaService.getTimestamp("BTCUSDT", context, false);
+ * ```
+ */
+declare class TimeMetaService {
+    private readonly loggerService;
+    private readonly executionContextService;
+    /**
+     * Memoized factory for BehaviorSubject streams keyed by (symbol, strategyName, exchangeName, frameName, backtest).
+     *
+     * Each subject holds the latest createdAt timestamp emitted by the strategy iterator for that key.
+     * Instances are cached until clear() is called.
+     */
+    private getSource;
+    /**
+     * Returns the current candle timestamp (in milliseconds) for the given symbol and context.
+     *
+     * When called inside an execution context (i.e., during a signal handler or action),
+     * reads the timestamp directly from ExecutionContextService.context.when.
+     * Otherwise, reads the last value from the cached BehaviorSubject. If no value has
+     * been emitted yet, waits up to LISTEN_TIMEOUT ms for the first tick before throwing.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param context - Strategy, exchange, and frame identifiers
+     * @param backtest - True if backtest mode, false if live mode
+     * @returns Unix timestamp in milliseconds of the latest processed candle
+     * @throws When no timestamp arrives within LISTEN_TIMEOUT ms
+     */
+    getTimestamp: (symbol: string, context: {
+        strategyName: string;
+        exchangeName: string;
+        frameName: string;
+    }, backtest: boolean) => Promise<number>;
+    /**
+     * Pushes a new timestamp value into the BehaviorSubject for the given key.
+     *
+     * Called by StrategyConnectionService after each strategy tick to keep
+     * the cached timestamp up to date.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param timestamp - The createdAt timestamp from the tick (milliseconds)
+     * @param context - Strategy, exchange, and frame identifiers
+     * @param backtest - True if backtest mode, false if live mode
+     */
+    next: (symbol: string, timestamp: number, context: {
+        strategyName: string;
+        exchangeName: string;
+        frameName: string;
+    }, backtest: boolean) => Promise<void>;
+    /**
+     * Disposes cached BehaviorSubject(s) to free memory and prevent stale data.
+     *
+     * When called without arguments, clears all memoized timestamp streams.
+     * When called with a payload, clears only the stream for the specified key.
+     * Should be called at strategy start (Backtest/Live/Walker) to reset state.
+     *
+     * @param payload - Optional key to clear a single stream; omit to clear all
+     */
+    clear: (payload?: {
+        symbol: string;
+        strategyName: string;
+        exchangeName: string;
+        frameName: string;
+        backtest: boolean;
+    }) => void;
+}
+
+/**
+ * Service for tracking the latest market price per symbol-strategy-exchange-frame combination.
+ *
+ * Maintains a memoized BehaviorSubject per unique key that is updated on every strategy tick
+ * by StrategyConnectionService. Consumers can synchronously read the last known price or
+ * await the first value if none has arrived yet.
+ *
+ * Primary use case: providing the current price outside of a tick execution context,
+ * e.g., when a command is triggered between ticks.
+ *
+ * Features:
+ * - One BehaviorSubject per (symbol, strategyName, exchangeName, frameName, backtest) key
+ * - Falls back to ExchangeConnectionService.getAveragePrice when called inside an execution context
+ * - Waits up to LISTEN_TIMEOUT ms for the first price if none is cached yet
+ * - clear() disposes the BehaviorSubject for a single key or all keys
+ *
+ * Architecture:
+ * - Registered as singleton in DI container
+ * - Updated by StrategyConnectionService after each tick
+ * - Cleared by Backtest/Live/Walker at strategy start to prevent stale data
+ *
+ * @example
+ * ```typescript
+ * const price = await backtest.priceMetaService.getCurrentPrice("BTCUSDT", context, false);
+ * ```
+ */
+declare class PriceMetaService {
+    private readonly loggerService;
+    private readonly exchangeConnectionService;
+    /**
+     * Memoized factory for BehaviorSubject streams keyed by (symbol, strategyName, exchangeName, frameName, backtest).
+     *
+     * Each subject holds the latest currentPrice emitted by the strategy iterator for that key.
+     * Instances are cached until clear() is called.
+     */
+    private getSource;
+    /**
+     * Returns the current market price for the given symbol and context.
+     *
+     * When called inside an execution context (i.e., during a signal handler or action),
+     * delegates to ExchangeConnectionService.getAveragePrice for the live exchange price.
+     * Otherwise, reads the last value from the cached BehaviorSubject. If no value has
+     * been emitted yet, waits up to LISTEN_TIMEOUT ms for the first tick before throwing.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param context - Strategy, exchange, and frame identifiers
+     * @param backtest - True if backtest mode, false if live mode
+     * @returns Current market price in quote currency
+     * @throws When no price arrives within LISTEN_TIMEOUT ms
+     */
+    getCurrentPrice: (symbol: string, context: {
+        strategyName: string;
+        exchangeName: string;
+        frameName: string;
+    }, backtest: boolean) => Promise<number>;
+    /**
+     * Pushes a new price value into the BehaviorSubject for the given key.
+     *
+     * Called by StrategyConnectionService after each strategy tick to keep
+     * the cached price up to date.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @param currentPrice - The latest price from the tick
+     * @param context - Strategy, exchange, and frame identifiers
+     * @param backtest - True if backtest mode, false if live mode
+     */
+    next: (symbol: string, currentPrice: number, context: {
+        strategyName: string;
+        exchangeName: string;
+        frameName: string;
+    }, backtest: boolean) => Promise<void>;
+    /**
+     * Disposes cached BehaviorSubject(s) to free memory and prevent stale data.
+     *
+     * When called without arguments, clears all memoized price streams.
+     * When called with a payload, clears only the stream for the specified key.
+     * Should be called at strategy start (Backtest/Live/Walker) to reset state.
+     *
+     * @param payload - Optional key to clear a single stream; omit to clear all
+     */
+    clear: (payload?: {
+        symbol: string;
+        strategyName: string;
+        exchangeName: string;
+        frameName: string;
+        backtest: boolean;
+    }) => void;
+}
+
 /**
  * Type definition for strategy methods.
  * Maps all keys of IStrategy to any type.
@@ -20949,6 +21153,8 @@ declare class StrategyConnectionService implements TStrategy$1 {
     readonly partialConnectionService: PartialConnectionService;
     readonly breakevenConnectionService: BreakevenConnectionService;
     readonly actionCoreService: ActionCoreService;
+    readonly timeMetaService: TimeMetaService;
+    readonly priceMetaService: PriceMetaService;
     /**
      * Retrieves memoized ClientStrategy instance for given symbol-strategy pair with exchange and frame isolation.
      *
@@ -21008,36 +21214,139 @@ declare class StrategyConnectionService implements TStrategy$1 {
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the effective (DCA-averaged) entry price for the current pending signal.
+     *
+     * This is the harmonic mean of all _entry prices, which is the correct
+     * cost-basis price used in all PNL calculations.
+     * With no DCA entries, equals the original priceOpen.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to effective entry price or null
+     */
     getPositionAveragePrice: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the number of DCA entries made for the current pending signal.
+     *
+     * 1 = original entry only (no DCA).
+     * Increases by 1 with each successful commitAverageBuy().
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to entry count or null
+     */
     getPositionInvestedCount: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the total invested cost basis in dollars for the current pending signal.
+     *
+     * Equal to entryCount × $100 (COST_BASIS_PER_ENTRY).
+     * 1 entry = $100, 2 entries = $200, etc.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to total invested cost in dollars or null
+     */
     getPositionInvestedCost: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the unrealized PNL percentage for the current pending signal at currentPrice.
+     *
+     * Accounts for partial closes, DCA entries, slippage and fees
+     * (delegates to toProfitLossDto).
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to pnlPercentage or null
+     */
     getPositionPnlPercent: (backtest: boolean, symbol: string, currentPrice: number, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the unrealized PNL in dollars for the current pending signal at currentPrice.
+     *
+     * Calculated as: pnlPercentage / 100 × totalInvestedCost
+     * Accounts for partial closes, DCA entries, slippage and fees.
+     *
+     * Returns null if no pending signal exists.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param currentPrice - Current market price
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to pnl in dollars or null
+     */
     getPositionPnlCost: (backtest: boolean, symbol: string, currentPrice: number, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number | null>;
+    /**
+     * Returns the list of DCA entry prices for the current pending signal.
+     *
+     * The first element is always the original priceOpen (initial entry).
+     * Each subsequent element is a price added by commitAverageBuy().
+     *
+     * Returns null if no pending signal exists.
+     * Returns a single-element array [priceOpen] if no DCA entries were made.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to array of entry prices or null
+     *
+     * @example
+     * ```typescript
+     * // No DCA: [43000]
+     * // One DCA: [43000, 42000]
+     * // Two DCA: [43000, 42000, 41500]
+     * ```
+     */
     getPositionLevels: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
         frameName: FrameName;
     }) => Promise<number[] | null>;
+    /**
+     * Returns the list of partial closes for the current pending signal.
+     *
+     * Each entry records a partial profit or loss close event with its type,
+     * percent closed, price at close, cost basis snapshot, and entry count at close.
+     *
+     * Returns null if no pending signal exists.
+     * Returns an empty array if no partial closes have been executed.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to array of partial close records or null
+     */
     getPositionPartials: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
@@ -21048,8 +21357,29 @@ declare class StrategyConnectionService implements TStrategy$1 {
         currentPrice: number;
         costBasisAtClose: number;
         entryCountAtClose: number;
-        debugTimestamp?: number;
+        timestamp: number;
     }[]>;
+    /**
+     * Returns the list of DCA entry prices and costs for the current pending signal.
+     *
+     * Each entry records the price and cost of a single position entry.
+     * The first element is always the original priceOpen (initial entry).
+     * Each subsequent element is an entry added by averageBuy().
+     *
+     * Returns null if no pending signal exists.
+     * Returns a single-element array [{ price: priceOpen, cost }] if no DCA entries were made.
+     *
+     * @param backtest - Whether running in backtest mode
+     * @param symbol - Trading pair symbol
+     * @param context - Execution context with strategyName, exchangeName, frameName
+     * @returns Promise resolving to array of entry records or null
+     *
+     * @example
+     * ```typescript
+     * // No DCA: [{ price: 43000, cost: 100 }]
+     * // One DCA: [{ price: 43000, cost: 100 }, { price: 42000, cost: 100 }]
+     * ```
+     */
     getPositionEntries: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
         exchangeName: ExchangeName;
@@ -21057,6 +21387,7 @@ declare class StrategyConnectionService implements TStrategy$1 {
     }) => Promise<{
         price: number;
         cost: number;
+        timestamp: number;
     }[]>;
     /**
      * Retrieves the currently active scheduled signal for the strategy.
@@ -22301,7 +22632,7 @@ declare class StrategyCoreService implements TStrategy {
         currentPrice: number;
         costBasisAtClose: number;
         entryCountAtClose: number;
-        debugTimestamp?: number;
+        timestamp: number;
     }[]>;
     getPositionEntries: (backtest: boolean, symbol: string, context: {
         strategyName: StrategyName;
@@ -22310,6 +22641,7 @@ declare class StrategyCoreService implements TStrategy {
     }) => Promise<{
         price: number;
         cost: number;
+        timestamp: number;
     }[]>;
     /**
      * Retrieves the currently active scheduled signal for the symbol.
@@ -25328,6 +25660,8 @@ declare const backtest: {
     riskGlobalService: RiskGlobalService;
     partialGlobalService: PartialGlobalService;
     breakevenGlobalService: BreakevenGlobalService;
+    timeMetaService: TimeMetaService;
+    priceMetaService: PriceMetaService;
     exchangeCoreService: ExchangeCoreService;
     strategyCoreService: StrategyCoreService;
     actionCoreService: ActionCoreService;