backtest-kit 3.0.17 → 3.1.0

package/build/index.mjs

@@ -1,6 +1,6 @@
 import { createActivator } from 'di-kit';
 import { scoped } from 'di-scoped';
-import { Subject, makeExtendable, singleshot, getErrorMessage, memoize, not, errorData, trycatch, retry, queued, sleep, randomString, str, isObject, ToolRegistry, typo, and, resolveDocuments, timeout, TIMEOUT_SYMBOL as TIMEOUT_SYMBOL$1, compose, singlerun } from 'functools-kit';
+import { Subject, makeExtendable, singleshot, getErrorMessage, memoize, not, errorData, trycatch, retry, queued, sleep, randomString, str, isObject, ToolRegistry, typo, and, Source, resolveDocuments, timeout, TIMEOUT_SYMBOL as TIMEOUT_SYMBOL$1, compose, singlerun } from 'functools-kit';
 import * as fs from 'fs/promises';
 import fs__default, { stat, opendir, readFile } from 'fs/promises';
 import path, { join, dirname } from 'path';
@@ -422,6 +422,13 @@ const GLOBAL_CONFIG = {
      * Default: 50 signals
      */
     CC_MAX_SIGNALS: 50,
+    /**
+     * Enables mutex locking for candle fetching to prevent concurrent fetches of the same candles.
+     * This can help avoid redundant API calls and ensure data consistency when multiple processes/threads attempt to fetch candles simultaneously.
+     *
+     * Default: true (mutex locking enabled for candle fetching)
+     */
+    CC_ENABLE_CANDLE_FETCH_MUTEX: true,
 };
 const DEFAULT_CONFIG = Object.freeze({ ...GLOBAL_CONFIG });
 
@@ -692,10 +699,10 @@ async function writeFileAtomic(file, data, options = {}) {
     }
 }
 
-var _a$2;
+var _a$3;
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
-const INTERVAL_MINUTES$7 = {
+const INTERVAL_MINUTES$8 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -707,7 +714,7 @@ const INTERVAL_MINUTES$7 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$5 = 60000;
+const MS_PER_MINUTE$6 = 60000;
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_USE_PERSIST_SIGNAL_ADAPTER = "PersistSignalUtils.usePersistSignalAdapter";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_READ_DATA = "PersistSignalUtils.readSignalData";
 const PERSIST_SIGNAL_UTILS_METHOD_NAME_WRITE_DATA = "PersistSignalUtils.writeSignalData";
@@ -810,7 +817,7 @@ class PersistBase {
     constructor(entityName, baseDir = join(process.cwd(), "logs/data")) {
         this.entityName = entityName;
         this.baseDir = baseDir;
-        this[_a$2] = singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
+        this[_a$3] = singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
         bt.loggerService.debug(PERSIST_BASE_METHOD_NAME_CTOR, {
             entityName: this.entityName,
             baseDir,
@@ -913,7 +920,7 @@ class PersistBase {
         }
     }
 }
-_a$2 = BASE_WAIT_FOR_INIT_SYMBOL;
+_a$3 = BASE_WAIT_FOR_INIT_SYMBOL;
 // @ts-ignore
 PersistBase = makeExtendable(PersistBase);
 /**
@@ -1607,7 +1614,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
+            const stepMs = INTERVAL_MINUTES$8[interval] * MS_PER_MINUTE$6;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1663,7 +1670,7 @@ class PersistCandleUtils {
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
             // Calculate step in milliseconds to determine candle close time
-            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
+            const stepMs = INTERVAL_MINUTES$8[interval] * MS_PER_MINUTE$6;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1920,8 +1927,71 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$4 = 60000;
-const INTERVAL_MINUTES$6 = {
+var _a$2, _b$2;
+const BUSY_DELAY = 100;
+const SET_BUSY_SYMBOL = Symbol("setBusy");
+const GET_BUSY_SYMBOL = Symbol("getBusy");
+const ACQUIRE_LOCK_SYMBOL = Symbol("acquireLock");
+const RELEASE_LOCK_SYMBOL = Symbol("releaseLock");
+const ACQUIRE_LOCK_FN = async (self) => {
+    while (self[GET_BUSY_SYMBOL]()) {
+        await sleep(BUSY_DELAY);
+    }
+    self[SET_BUSY_SYMBOL](true);
+};
+class Lock {
+    constructor() {
+        this._isBusy = 0;
+        this[_a$2] = queued(ACQUIRE_LOCK_FN);
+        this[_b$2] = () => this[SET_BUSY_SYMBOL](false);
+        this.acquireLock = async () => {
+            await this[ACQUIRE_LOCK_SYMBOL](this);
+        };
+        this.releaseLock = async () => {
+            await this[RELEASE_LOCK_SYMBOL]();
+        };
+    }
+    [SET_BUSY_SYMBOL](isBusy) {
+        this._isBusy += isBusy ? 1 : -1;
+        if (this._isBusy < 0) {
+            throw new Error("Extra release in finally block");
+        }
+    }
+    [GET_BUSY_SYMBOL]() {
+        return !!this._isBusy;
+    }
+}
+_a$2 = ACQUIRE_LOCK_SYMBOL, _b$2 = RELEASE_LOCK_SYMBOL;
+
+const METHOD_NAME_ACQUIRE_LOCK = "CandleUtils.acquireLock";
+const METHOD_NAME_RELEASE_LOCK = "CandleUtils.releaseLock";
+class CandleUtils {
+    constructor() {
+        this._lock = new Lock();
+        this.acquireLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_ACQUIRE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.acquireLock();
+        };
+        this.releaseLock = async (source) => {
+            bt.loggerService.info(METHOD_NAME_RELEASE_LOCK, {
+                source,
+            });
+            if (!GLOBAL_CONFIG.CC_ENABLE_CANDLE_FETCH_MUTEX) {
+                return;
+            }
+            return await this._lock.releaseLock();
+        };
+    }
+}
+const Candle = new CandleUtils();
+
+const MS_PER_MINUTE$5 = 60000;
+const INTERVAL_MINUTES$7 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -1951,7 +2021,7 @@ const INTERVAL_MINUTES$6 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$2 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$4;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$5;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2096,37 +2166,43 @@ const WRITE_CANDLES_CACHE_FN$1 = trycatch(queued(async (candles, dto, self) => {
  * @returns Promise resolving to array of candle data
  */
 const GET_CANDLES_FN = async (dto, since, self) => {
-    const step = INTERVAL_MINUTES$6[dto.interval];
+    const step = INTERVAL_MINUTES$7[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$4;
-    // Try to read from cache first
-    const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
-    if (cachedCandles !== null) {
-        return cachedCandles;
-    }
-    // Cache miss or error - fetch from API
-    let lastError;
-    for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
-        try {
-            const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit, self.params.execution.context.backtest);
-            VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
-            return result;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$5;
+    await Candle.acquireLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
+    try {
+        // Try to read from cache first
+        const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
+        if (cachedCandles !== null) {
+            return cachedCandles;
         }
-        catch (err) {
-            const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
-            const payload = {
-                error: errorData(err),
-                message: getErrorMessage(err),
-            };
-            self.params.logger.warn(message, payload);
-            console.warn(message, payload);
-            lastError = err;
-            await sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+        // Cache miss or error - fetch from API
+        let lastError;
+        for (let i = 0; i !== GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_COUNT; i++) {
+            try {
+                const result = await self.params.getCandles(dto.symbol, dto.interval, since, dto.limit, self.params.execution.context.backtest);
+                VALIDATE_NO_INCOMPLETE_CANDLES_FN(result);
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN$1(result, dto, self);
+                return result;
+            }
+            catch (err) {
+                const message = `ClientExchange GET_CANDLES_FN: attempt ${i + 1} failed for symbol=${dto.symbol}, interval=${dto.interval}, since=${since.toISOString()}, limit=${dto.limit}}`;
+                const payload = {
+                    error: errorData(err),
+                    message: getErrorMessage(err),
+                };
+                self.params.logger.warn(message, payload);
+                console.warn(message, payload);
+                lastError = err;
+                await sleep(GLOBAL_CONFIG.CC_GET_CANDLES_RETRY_DELAY_MS);
+            }
         }
+        throw lastError;
+    }
+    finally {
+        Candle.releaseLock(`ClientExchange GET_CANDLES_FN symbol=${dto.symbol} interval=${dto.interval} limit=${dto.limit}`);
     }
-    throw lastError;
 };
 /**
  * Wrapper to call onCandleData callback with error handling.
@@ -2206,11 +2282,11 @@ class ClientExchange {
             interval,
             limit,
         });
-        const step = INTERVAL_MINUTES$6[interval];
+        const step = INTERVAL_MINUTES$7[interval];
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$4;
+        const stepMs = step * MS_PER_MINUTE$5;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
@@ -2287,11 +2363,11 @@ class ClientExchange {
         if (!this.params.execution.context.backtest) {
             throw new Error(`ClientExchange getNextCandles: cannot fetch future candles in live mode`);
         }
-        const step = INTERVAL_MINUTES$6[interval];
+        const step = INTERVAL_MINUTES$7[interval];
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$4;
+        const stepMs = step * MS_PER_MINUTE$5;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2455,11 +2531,11 @@ class ClientExchange {
             sDate,
             eDate,
         });
-        const step = INTERVAL_MINUTES$6[interval];
+        const step = INTERVAL_MINUTES$7[interval];
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$4;
+        const stepMs = step * MS_PER_MINUTE$5;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
         let sinceTimestamp;
@@ -2588,7 +2664,7 @@ class ClientExchange {
         const alignedTo = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES);
         const to = new Date(alignedTo);
         const from = new Date(alignedTo -
-            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$4);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$5);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -3053,7 +3129,7 @@ const beginTime = (run) => (...args) => {
     return fn();
 };
 
-const INTERVAL_MINUTES$5 = {
+const INTERVAL_MINUTES$6 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -3566,14 +3642,15 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     }
     const currentTime = self.params.execution.context.when.getTime();
     {
-        const intervalMinutes = INTERVAL_MINUTES$5[self.params.interval];
+        const intervalMinutes = INTERVAL_MINUTES$6[self.params.interval];
         const intervalMs = intervalMinutes * 60 * 1000;
-        // Проверяем что прошел нужный интервал с последнего getSignal
+        const alignedTime = Math.floor(currentTime / intervalMs) * intervalMs;
+        // Проверяем что наступил новый интервал (по aligned timestamp)
         if (self._lastSignalTimestamp !== null &&
-            currentTime - self._lastSignalTimestamp < intervalMs) {
+            alignedTime === self._lastSignalTimestamp) {
             return null;
         }
-        self._lastSignalTimestamp = currentTime;
+        self._lastSignalTimestamp = alignedTime;
     }
     const currentPrice = await self.params.exchange.getAveragePrice(self.params.execution.context.symbol);
     const timeoutMs = GLOBAL_CONFIG.CC_MAX_SIGNAL_GENERATION_SECONDS * 1000;
@@ -8177,7 +8254,7 @@ class StrategyConnectionService {
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$4 = {
+const INTERVAL_MINUTES$5 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -8232,7 +8309,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$4[interval];
+    const intervalMinutes = INTERVAL_MINUTES$5[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -13195,7 +13272,49 @@ class BacktestLogicPrivateService {
     }
 }
 
-const TICK_TTL = 1 * 60 * 1000 + 1;
+const EMITTER_CHECK_INTERVAL = 5000;
+const MS_PER_MINUTE$4 = 60000;
+const INTERVAL_MINUTES$4 = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+};
+const createEmitter = memoize(([interval]) => `${interval}`, (interval) => {
+    const tickSubject = new Subject();
+    const intervalMs = INTERVAL_MINUTES$4[interval] * MS_PER_MINUTE$4;
+    {
+        let lastAligned = Math.floor(Date.now() / intervalMs) * intervalMs;
+        Source.fromInterval(EMITTER_CHECK_INTERVAL)
+            .map(() => Math.floor(Date.now() / intervalMs) * intervalMs)
+            .filter((aligned) => {
+            if (aligned !== lastAligned) {
+                lastAligned = aligned;
+                return true;
+            }
+            return false;
+        })
+            .connect(tickSubject.next);
+    }
+    return tickSubject;
+});
+/**
+ * Waits for the next candle interval to start and returns the timestamp of the new candle.
+ * @param {CandleInterval} interval - The candle interval (e.g., "1m", "1h") to wait for.
+ * @returns {Promise<number>} A promise that resolves with the timestamp (in milliseconds) of the next candle start.
+ */
+const waitForCandle = async (interval) => {
+    const emitter = createEmitter(interval);
+    // Subject is multicast
+    return emitter.toPromise();
+};
+
 /**
  * Private service for live trading orchestration using async generators.
  *
@@ -13265,7 +13384,7 @@ class LiveLogicPrivateService {
                     message: getErrorMessage(error),
                 });
                 await errorEmitter.next(error);
-                await sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             this.loggerService.info("liveLogicPrivateService tick result", {
@@ -13300,19 +13419,19 @@ class LiveLogicPrivateService {
                     });
                     break;
                 }
-                await sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             if (result.action === "active") {
-                await sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             if (result.action === "scheduled") {
-                await sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             if (result.action === "waiting") {
-                await sleep(TICK_TTL);
+                await waitForCandle("1m");
                 continue;
             }
             // Yield opened, closed, cancelled results
@@ -13331,7 +13450,7 @@ class LiveLogicPrivateService {
                     break;
                 }
             }
-            await sleep(TICK_TTL);
+            await waitForCandle("1m");
         }
     }
 }
@@ -26264,55 +26383,61 @@ class ExchangeInstance {
             const sinceTimestamp = alignedWhen - limit * stepMs;
             const since = new Date(sinceTimestamp);
             const untilTimestamp = alignedWhen;
-            // Try to read from cache first
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            let allData = [];
-            // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
-            if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = limit;
-                let currentSince = new Date(since.getTime());
-                const isBacktest = await GET_BACKTEST_FN();
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        // Move currentSince forward by the number of candles fetched
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
+            try {
+                // Try to read from cache first
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                let allData = [];
+                // If limit exceeds CC_MAX_CANDLES_PER_REQUEST, fetch data in chunks
+                if (limit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = limit;
+                    let currentSince = new Date(since.getTime());
+                    const isBacktest = await GET_BACKTEST_FN();
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            // Move currentSince forward by the number of candles fetched
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    const isBacktest = await GET_BACKTEST_FN();
+                    allData = await getCandles(symbol, interval, since, limit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
+                        `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== limit) {
+                    throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
+                        `Expected ${limit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                const isBacktest = await GET_BACKTEST_FN();
-                allData = await getCandles(symbol, interval, since, limit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getCandles: adapter returned empty array. ` +
-                    `Expected ${limit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== limit) {
-                throw new Error(`ExchangeInstance getCandles: candle count mismatch. ` +
-                    `Expected ${limit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getCandles symbol=${symbol} interval=${interval} limit=${limit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit }, this.exchangeName);
-            return uniqueData;
         };
         /**
          * Calculates VWAP (Volume Weighted Average Price) from last N 1m candles.
@@ -26546,56 +26671,62 @@ class ExchangeInstance {
                     `Provide one of: (sDate+eDate+limit), (sDate+eDate), (eDate+limit), (sDate+limit), or (limit only). ` +
                     `Got: sDate=${sDate}, eDate=${eDate}, limit=${limit}`);
             }
-            // Try to read from cache first
-            const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
-            const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
-            if (cachedCandles !== null) {
-                return cachedCandles;
-            }
-            // Fetch candles
-            const since = new Date(sinceTimestamp);
-            let allData = [];
-            const isBacktest = await GET_BACKTEST_FN();
-            const getCandles = this._methods.getCandles;
-            if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
-                let remaining = calculatedLimit;
-                let currentSince = new Date(since.getTime());
-                while (remaining > 0) {
-                    const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
-                    const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
-                    allData.push(...chunkData);
-                    remaining -= chunkLimit;
-                    if (remaining > 0) {
-                        currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+            await Candle.acquireLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
+            try {
+                // Try to read from cache first
+                const untilTimestamp = sinceTimestamp + calculatedLimit * stepMs;
+                const cachedCandles = await READ_CANDLES_CACHE_FN({ symbol, interval, limit: calculatedLimit }, sinceTimestamp, untilTimestamp, this.exchangeName);
+                if (cachedCandles !== null) {
+                    return cachedCandles;
+                }
+                // Fetch candles
+                const since = new Date(sinceTimestamp);
+                let allData = [];
+                const isBacktest = await GET_BACKTEST_FN();
+                const getCandles = this._methods.getCandles;
+                if (calculatedLimit > GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST) {
+                    let remaining = calculatedLimit;
+                    let currentSince = new Date(since.getTime());
+                    while (remaining > 0) {
+                        const chunkLimit = Math.min(remaining, GLOBAL_CONFIG.CC_MAX_CANDLES_PER_REQUEST);
+                        const chunkData = await getCandles(symbol, interval, currentSince, chunkLimit, isBacktest);
+                        allData.push(...chunkData);
+                        remaining -= chunkLimit;
+                        if (remaining > 0) {
+                            currentSince = new Date(currentSince.getTime() + chunkLimit * stepMs);
+                        }
                     }
                 }
+                else {
+                    allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
+                }
+                // Apply distinct by timestamp to remove duplicates
+                const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
+                if (allData.length !== uniqueData.length) {
+                    bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
+                }
+                // Validate adapter returned data
+                if (uniqueData.length === 0) {
+                    throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
+                        `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
+                }
+                if (uniqueData[0].timestamp !== sinceTimestamp) {
+                    throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
+                        `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
+                        `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
+                }
+                if (uniqueData.length !== calculatedLimit) {
+                    throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
+                        `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
+                        `Adapter must return exact number of candles requested.`);
+                }
+                // Write to cache after successful fetch
+                await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
+                return uniqueData;
             }
-            else {
-                allData = await getCandles(symbol, interval, since, calculatedLimit, isBacktest);
-            }
-            // Apply distinct by timestamp to remove duplicates
-            const uniqueData = Array.from(new Map(allData.map((candle) => [candle.timestamp, candle])).values());
-            if (allData.length !== uniqueData.length) {
-                bt.loggerService.warn(`ExchangeInstance getRawCandles: Removed ${allData.length - uniqueData.length} duplicate candles by timestamp`);
-            }
-            // Validate adapter returned data
-            if (uniqueData.length === 0) {
-                throw new Error(`ExchangeInstance getRawCandles: adapter returned empty array. ` +
-                    `Expected ${calculatedLimit} candles starting from openTime=${sinceTimestamp}.`);
-            }
-            if (uniqueData[0].timestamp !== sinceTimestamp) {
-                throw new Error(`ExchangeInstance getRawCandles: first candle timestamp mismatch. ` +
-                    `Expected openTime=${sinceTimestamp}, got=${uniqueData[0].timestamp}. ` +
-                    `Adapter must return candles with timestamp=openTime, starting from aligned since.`);
-            }
-            if (uniqueData.length !== calculatedLimit) {
-                throw new Error(`ExchangeInstance getRawCandles: candle count mismatch. ` +
-                    `Expected ${calculatedLimit} candles, got ${uniqueData.length}. ` +
-                    `Adapter must return exact number of candles requested.`);
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
             }
-            // Write to cache after successful fetch
-            await WRITE_CANDLES_CACHE_FN(uniqueData, { symbol, interval, limit: calculatedLimit }, this.exchangeName);
-            return uniqueData;
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);
@@ -37341,4 +37472,4 @@ const set = (object, path, value) => {
     }
 };
 
-export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, warmCandles };
+export { ActionBase, Backtest, Breakeven, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, Markdown, MarkdownFileBase, MarkdownFolderBase, MethodContextService, Notification, NotificationBacktest, NotificationLive, Partial, Performance, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, Report, ReportBase, Risk, Schedule, Storage, StorageBacktest, StorageLive, Strategy, Walker, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, alignToInterval, checkCandles, commitActivateScheduled, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate, waitForCandle, warmCandles };

package/package.json

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