backtest-kit 6.4.0 → 6.5.1

package/build/index.mjs

@@ -2709,6 +2709,12 @@ const METHOD_NAME_RELEASE_LOCK = "CandleUtils.releaseLock";
 class CandleUtils {
     constructor() {
         this._lock = new Lock();
+        /**
+         * Acquires the candle fetch mutex if CC_ENABLE_CANDLE_FETCH_MUTEX is enabled.
+         * Prevents concurrent candle fetches from the same exchange.
+         *
+         * @param source - Caller identifier for logging
+         */
         this.acquireLock = async (source) => {
             bt.loggerService.info(METHOD_NAME_ACQUIRE_LOCK, {
                 source,
@@ -2718,6 +2724,12 @@ class CandleUtils {
             }
             return await this._lock.acquireLock();
         };
+        /**
+         * Releases the candle fetch mutex if CC_ENABLE_CANDLE_FETCH_MUTEX is enabled.
+         * Must be called after acquireLock, typically in a finally block.
+         *
+         * @param source - Caller identifier for logging
+         */
         this.releaseLock = async (source) => {
             bt.loggerService.info(METHOD_NAME_RELEASE_LOCK, {
                 source,
@@ -14296,6 +14308,20 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getTotalCostClosed(backtest, symbol, context);
         };
+        /**
+         * 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
+         */
         this.getPositionEffectivePrice = async (backtest, symbol, context) => {
             this.loggerService.log("strategyCoreService getPositionEffectivePrice", {
                 symbol,
@@ -14304,6 +14330,19 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionEffectivePrice(backtest, symbol, context);
         };
+        /**
+         * 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
+         */
         this.getPositionInvestedCount = async (backtest, symbol, context) => {
             this.loggerService.log("strategyCoreService getPositionInvestedCount", {
                 symbol,
@@ -14312,6 +14351,19 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionInvestedCount(backtest, symbol, context);
         };
+        /**
+         * 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
+         */
         this.getPositionInvestedCost = async (backtest, symbol, context) => {
             this.loggerService.log("strategyCoreService getPositionInvestedCost", {
                 symbol,
@@ -14320,6 +14372,20 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionInvestedCost(backtest, symbol, context);
         };
+        /**
+         * 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
+         */
         this.getPositionPnlPercent = async (backtest, symbol, currentPrice, context) => {
             this.loggerService.log("strategyCoreService getPositionPnlPercent", {
                 symbol,
@@ -14329,6 +14395,20 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionPnlPercent(backtest, symbol, currentPrice, context);
         };
+        /**
+         * 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
+         */
         this.getPositionPnlCost = async (backtest, symbol, currentPrice, context) => {
             this.loggerService.log("strategyCoreService getPositionPnlCost", {
                 symbol,
@@ -14338,6 +14418,27 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionPnlCost(backtest, symbol, currentPrice, context);
         };
+        /**
+         * 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]
+         * ```
+         */
         this.getPositionLevels = async (backtest, symbol, context) => {
             this.loggerService.log("strategyCoreService getPositionLevels", {
                 symbol,
@@ -14346,6 +14447,20 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionLevels(backtest, symbol, context);
         };
+        /**
+         * 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
+         */
         this.getPositionPartials = async (backtest, symbol, context) => {
             this.loggerService.log("strategyCoreService getPositionPartials", {
                 symbol,
@@ -14354,6 +14469,27 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.getPositionPartials(backtest, symbol, context);
         };
+        /**
+         * 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 }]
+         * ```
+         */
         this.getPositionEntries = async (backtest, symbol, context) => {
             this.loggerService.log("strategyCoreService getPositionEntries", {
                 symbol,
@@ -14735,6 +14871,28 @@ class StrategyCoreService {
             await this.validate(context);
             return await this.strategyConnectionService.partialLoss(backtest, symbol, percentToClose, currentPrice, context);
         };
+        /**
+         * Checks whether `trailingStop` would succeed without executing it.
+         * Validates context, then delegates to StrategyConnectionService.validateTrailingStop().
+         *
+         * @param backtest - Whether running in backtest mode
+         * @param symbol - Trading pair symbol
+         * @param percentShift - Percentage shift of ORIGINAL SL distance [-100, 100], excluding 0
+         * @param currentPrice - Current market price to validate against
+         * @param context - Execution context with strategyName, exchangeName, frameName
+         * @returns Promise<boolean> - true if `trailingStop` would execute, false otherwise
+         */
+        this.validateTrailingStop = async (backtest, symbol, percentShift, currentPrice, context) => {
+            this.loggerService.log("strategyCoreService validateTrailingStop", {
+                symbol,
+                percentShift,
+                currentPrice,
+                context,
+                backtest,
+            });
+            await this.validate(context);
+            return await this.strategyConnectionService.validateTrailingStop(backtest, symbol, percentShift, currentPrice, context);
+        };
         /**
          * Adjusts the trailing stop-loss distance for an active pending signal.
          *
@@ -14748,7 +14906,7 @@ class StrategyCoreService {
          * @param percentShift - Percentage adjustment to SL distance (-100 to 100)
          * @param currentPrice - Current market price to check for intrusion
          * @param context - Execution context with strategyName, exchangeName, frameName
-         * @returns Promise that resolves when trailing SL is updated
+         * @returns Promise<boolean> - true if trailing SL was updated, false otherwise
          *
          * @example
          * ```typescript
@@ -14763,8 +14921,8 @@ class StrategyCoreService {
          * );
          * ```
          */
-        this.validateTrailingStop = async (backtest, symbol, percentShift, currentPrice, context) => {
-            this.loggerService.log("strategyCoreService validateTrailingStop", {
+        this.trailingStop = async (backtest, symbol, percentShift, currentPrice, context) => {
+            this.loggerService.log("strategyCoreService trailingStop", {
                 symbol,
                 percentShift,
                 currentPrice,
@@ -14772,21 +14930,21 @@ class StrategyCoreService {
                 backtest,
             });
             await this.validate(context);
-            return await this.strategyConnectionService.validateTrailingStop(backtest, symbol, percentShift, currentPrice, context);
+            return await this.strategyConnectionService.trailingStop(backtest, symbol, percentShift, currentPrice, context);
         };
         /**
-         * Checks whether `trailingStop` would succeed without executing it.
-         * Validates context, then delegates to StrategyConnectionService.validateTrailingStop().
+         * Checks whether `trailingTake` would succeed without executing it.
+         * Validates context, then delegates to StrategyConnectionService.validateTrailingTake().
          *
          * @param backtest - Whether running in backtest mode
          * @param symbol - Trading pair symbol
-         * @param percentShift - Percentage shift of ORIGINAL SL distance [-100, 100], excluding 0
+         * @param percentShift - Percentage adjustment to ORIGINAL TP distance [-100, 100], excluding 0
          * @param currentPrice - Current market price to validate against
          * @param context - Execution context with strategyName, exchangeName, frameName
-         * @returns Promise<boolean> - true if `trailingStop` would execute, false otherwise
+         * @returns Promise<boolean> - true if `trailingTake` would execute, false otherwise
          */
-        this.trailingStop = async (backtest, symbol, percentShift, currentPrice, context) => {
-            this.loggerService.log("strategyCoreService trailingStop", {
+        this.validateTrailingTake = async (backtest, symbol, percentShift, currentPrice, context) => {
+            this.loggerService.log("strategyCoreService validateTrailingTake", {
                 symbol,
                 percentShift,
                 currentPrice,
@@ -14794,7 +14952,7 @@ class StrategyCoreService {
                 backtest,
             });
             await this.validate(context);
-            return await this.strategyConnectionService.trailingStop(backtest, symbol, percentShift, currentPrice, context);
+            return await this.strategyConnectionService.validateTrailingTake(backtest, symbol, percentShift, currentPrice, context);
         };
         /**
          * Adjusts the trailing take-profit distance for an active pending signal.
@@ -14805,7 +14963,7 @@ class StrategyCoreService {
          * @param percentShift - Percentage adjustment to TP distance (-100 to 100)
          * @param currentPrice - Current market price to check for intrusion
          * @param context - Strategy context with strategyName, exchangeName, frameName
-         * @returns Promise that resolves when trailing TP is updated
+         * @returns Promise<boolean> - true if trailing TP was updated, false otherwise
          *
          * @example
          * ```typescript
@@ -14820,8 +14978,8 @@ class StrategyCoreService {
          * );
          * ```
          */
-        this.validateTrailingTake = async (backtest, symbol, percentShift, currentPrice, context) => {
-            this.loggerService.log("strategyCoreService validateTrailingTake", {
+        this.trailingTake = async (backtest, symbol, percentShift, currentPrice, context) => {
+            this.loggerService.log("strategyCoreService trailingTake", {
                 symbol,
                 percentShift,
                 currentPrice,
@@ -14829,29 +14987,27 @@ class StrategyCoreService {
                 backtest,
             });
             await this.validate(context);
-            return await this.strategyConnectionService.validateTrailingTake(backtest, symbol, percentShift, currentPrice, context);
+            return await this.strategyConnectionService.trailingTake(backtest, symbol, percentShift, currentPrice, context);
         };
         /**
-         * Checks whether `trailingTake` would succeed without executing it.
-         * Validates context, then delegates to StrategyConnectionService.validateTrailingTake().
+         * Checks whether `breakeven` would succeed without executing it.
+         * Validates context, then delegates to StrategyConnectionService.validateBreakeven().
          *
          * @param backtest - Whether running in backtest mode
          * @param symbol - Trading pair symbol
-         * @param percentShift - Percentage adjustment to ORIGINAL TP distance [-100, 100], excluding 0
          * @param currentPrice - Current market price to validate against
          * @param context - Execution context with strategyName, exchangeName, frameName
-         * @returns Promise<boolean> - true if `trailingTake` would execute, false otherwise
+         * @returns Promise<boolean> - true if `breakeven` would execute, false otherwise
          */
-        this.trailingTake = async (backtest, symbol, percentShift, currentPrice, context) => {
-            this.loggerService.log("strategyCoreService trailingTake", {
+        this.validateBreakeven = async (backtest, symbol, currentPrice, context) => {
+            this.loggerService.log("strategyCoreService validateBreakeven", {
                 symbol,
-                percentShift,
                 currentPrice,
                 context,
                 backtest,
             });
             await this.validate(context);
-            return await this.strategyConnectionService.trailingTake(backtest, symbol, percentShift, currentPrice, context);
+            return await this.strategyConnectionService.validateBreakeven(backtest, symbol, currentPrice, context);
         };
         /**
          * Moves stop-loss to breakeven when price reaches threshold.
@@ -14873,26 +15029,6 @@ class StrategyCoreService {
          * );
          * ```
          */
-        this.validateBreakeven = async (backtest, symbol, currentPrice, context) => {
-            this.loggerService.log("strategyCoreService validateBreakeven", {
-                symbol,
-                currentPrice,
-                context,
-                backtest,
-            });
-            await this.validate(context);
-            return await this.strategyConnectionService.validateBreakeven(backtest, symbol, currentPrice, context);
-        };
-        /**
-         * Checks whether `breakeven` would succeed without executing it.
-         * Validates context, then delegates to StrategyConnectionService.validateBreakeven().
-         *
-         * @param backtest - Whether running in backtest mode
-         * @param symbol - Trading pair symbol
-         * @param currentPrice - Current market price to validate against
-         * @param context - Execution context with strategyName, exchangeName, frameName
-         * @returns Promise<boolean> - true if `breakeven` would execute, false otherwise
-         */
         this.breakeven = async (backtest, symbol, currentPrice, context) => {
             this.loggerService.log("strategyCoreService breakeven", {
                 symbol,
@@ -14937,16 +15073,14 @@ class StrategyCoreService {
             return await this.strategyConnectionService.activateScheduled(backtest, symbol, context, activateId);
         };
         /**
-         * Adds a new DCA entry to the active pending signal.
-         *
-         * Validates strategy existence and delegates to connection service
-         * to add a new averaging entry to the position.
+         * Checks whether `averageBuy` would succeed without executing it.
+         * Validates context, then delegates to StrategyConnectionService.validateAverageBuy().
          *
          * @param backtest - Whether running in backtest mode
          * @param symbol - Trading pair symbol
-         * @param currentPrice - New entry price to add to the averaging history
+         * @param currentPrice - New entry price to validate
          * @param context - Execution context with strategyName, exchangeName, frameName
-         * @returns Promise<boolean> - true if entry added, false if rejected
+         * @returns Promise<boolean> - true if `averageBuy` would execute, false otherwise
          */
         this.validateAverageBuy = async (backtest, symbol, currentPrice, context) => {
             this.loggerService.log("strategyCoreService validateAverageBuy", {
@@ -14959,14 +15093,17 @@ class StrategyCoreService {
             return await this.strategyConnectionService.validateAverageBuy(backtest, symbol, currentPrice, context);
         };
         /**
-         * Checks whether `averageBuy` would succeed without executing it.
-         * Validates context, then delegates to StrategyConnectionService.validateAverageBuy().
+         * Adds a new DCA entry to the active pending signal.
+         *
+         * Validates strategy existence and delegates to connection service
+         * to add a new averaging entry to the position.
          *
          * @param backtest - Whether running in backtest mode
          * @param symbol - Trading pair symbol
-         * @param currentPrice - New entry price to validate
+         * @param currentPrice - New entry price to add to the averaging history
+         * @param cost - Cost basis for this entry in dollars
          * @param context - Execution context with strategyName, exchangeName, frameName
-         * @returns Promise<boolean> - true if `averageBuy` would execute, false otherwise
+         * @returns Promise<boolean> - true if entry added, false if rejected
          */
         this.averageBuy = async (backtest, symbol, currentPrice, context, cost) => {
             this.loggerService.log("strategyCoreService averageBuy", {
@@ -47921,6 +48058,13 @@ class StoragePersistBacktestUtils {
             await this.waitForInit();
             return Array.from(this._signals.values());
         };
+        /**
+         * Handles active ping event for an opened signal.
+         * Updates the signal's PnL and timestamp if the event is newer than the stored state.
+         * Persists updated state to disk.
+         *
+         * @param event - Active ping contract with signal data and current price
+         */
         this.handleActivePing = async (event) => {
             bt.loggerService.info(STORAGE_BACKTEST_METHOD_NAME_HANDLE_ACTIVE_PING, {
                 signalId: event.data.id,
@@ -47944,6 +48088,13 @@ class StoragePersistBacktestUtils {
             });
             await this._updateStorage();
         };
+        /**
+         * Handles schedule ping event for a scheduled signal.
+         * Updates the signal's data and timestamp if the event is newer than the stored state.
+         * Persists updated state to disk.
+         *
+         * @param event - Schedule ping contract with signal data and current price
+         */
         this.handleSchedulePing = async (event) => {
             bt.loggerService.info(STORAGE_BACKTEST_METHOD_NAME_HANDLE_SCHEDULE_PING, {
                 signalId: event.data.id,
@@ -48115,6 +48266,13 @@ class StorageMemoryBacktestUtils {
             bt.loggerService.info(STORAGE_MEMORY_BACKTEST_METHOD_NAME_LIST);
             return Array.from(this._signals.values());
         };
+        /**
+         * Handles active ping event for an opened signal.
+         * Updates the signal's PnL and timestamp if the event is newer than the stored state.
+         * In-memory only — no disk persistence.
+         *
+         * @param event - Active ping contract with signal data and current price
+         */
         this.handleActivePing = async (event) => {
             bt.loggerService.info(STORAGE_MEMORY_BACKTEST_METHOD_NAME_HANDLE_ACTIVE_PING, {
                 signalId: event.data.id,
@@ -48136,6 +48294,13 @@ class StorageMemoryBacktestUtils {
                 updatedAt: event.timestamp,
             });
         };
+        /**
+         * Handles schedule ping event for a scheduled signal.
+         * Updates the signal's data and timestamp if the event is newer than the stored state.
+         * In-memory only — no disk persistence.
+         *
+         * @param event - Schedule ping contract with signal data and current price
+         */
         this.handleSchedulePing = async (event) => {
             bt.loggerService.info(STORAGE_MEMORY_BACKTEST_METHOD_NAME_HANDLE_SCHEDULE_PING, {
                 signalId: event.data.id,
@@ -48215,8 +48380,14 @@ class StorageDummyBacktestUtils {
         this.list = async () => {
             return [];
         };
+        /**
+         * No-op handler for active ping events (dummy adapter discards all writes).
+         */
         this.handleActivePing = async () => {
         };
+        /**
+         * No-op handler for schedule ping events (dummy adapter discards all writes).
+         */
         this.handleSchedulePing = async () => {
         };
     }
@@ -48363,6 +48534,13 @@ class StoragePersistLiveUtils {
             await this.waitForInit();
             return Array.from(this._signals.values());
         };
+        /**
+         * Handles active ping event for an opened signal.
+         * Updates the signal's PnL and timestamp if the event is newer than the stored state.
+         * Persists updated state to disk.
+         *
+         * @param event - Active ping contract with signal data and current price
+         */
         this.handleActivePing = async (event) => {
             bt.loggerService.info(STORAGE_LIVE_METHOD_NAME_HANDLE_ACTIVE_PING, {
                 signalId: event.data.id,
@@ -48386,6 +48564,13 @@ class StoragePersistLiveUtils {
             });
             await this._updateStorage();
         };
+        /**
+         * Handles schedule ping event for a scheduled signal.
+         * Updates the signal's data and timestamp if the event is newer than the stored state.
+         * Persists updated state to disk.
+         *
+         * @param event - Schedule ping contract with signal data and current price
+         */
         this.handleSchedulePing = async (event) => {
             bt.loggerService.info(STORAGE_LIVE_METHOD_NAME_HANDLE_SCHEDULE_PING, {
                 signalId: event.data.id,
@@ -48557,6 +48742,13 @@ class StorageMemoryLiveUtils {
             bt.loggerService.info(STORAGE_MEMORY_LIVE_METHOD_NAME_LIST);
             return Array.from(this._signals.values());
         };
+        /**
+         * Handles active ping event for an opened signal.
+         * Updates the signal's PnL and timestamp if the event is newer than the stored state.
+         * In-memory only — no disk persistence.
+         *
+         * @param event - Active ping contract with signal data and current price
+         */
         this.handleActivePing = async (event) => {
             bt.loggerService.info(STORAGE_MEMORY_LIVE_METHOD_NAME_HANDLE_ACTIVE_PING, {
                 signalId: event.data.id,
@@ -48578,6 +48770,13 @@ class StorageMemoryLiveUtils {
                 updatedAt: event.timestamp,
             });
         };
+        /**
+         * Handles schedule ping event for a scheduled signal.
+         * Updates the signal's data and timestamp if the event is newer than the stored state.
+         * In-memory only — no disk persistence.
+         *
+         * @param event - Schedule ping contract with signal data and current price
+         */
         this.handleSchedulePing = async (event) => {
             bt.loggerService.info(STORAGE_MEMORY_LIVE_METHOD_NAME_HANDLE_SCHEDULE_PING, {
                 signalId: event.data.id,
@@ -48657,8 +48856,14 @@ class StorageDummyLiveUtils {
         this.list = async () => {
             return [];
         };
+        /**
+         * No-op handler for active ping events (dummy adapter discards all writes).
+         */
         this.handleActivePing = async () => {
         };
+        /**
+         * No-op handler for schedule ping events (dummy adapter discards all writes).
+         */
         this.handleSchedulePing = async () => {
         };
     }

package/package.json

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