backtest-kit 3.0.18 → 3.1.0

package/README.md

@@ -555,6 +555,28 @@ cd my-trading-bot
 npm start
 ```
 
+
+### @backtest-kit/graph
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/graph)** 🔗
+
+The **@backtest-kit/graph** package lets you compose backtest-kit computations as a typed directed acyclic graph (DAG). Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order with automatic parallelism.
+
+#### Key Features
+- 🔌 **DAG Execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
+- 🔒 **Type-Safe Values**: TypeScript infers the return type of every node through the graph via generics
+- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `sourceNode` + `outputNode` builders for authoring
+- 💾 **DB-Ready Serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
+- 🌐 **Context-Aware Fetch**: `sourceNode` receives `(symbol, when, exchangeName)` from the execution context automatically
+
+#### Use Case
+Perfect for multi-timeframe strategies where multiple Pine Script or indicator computations must be combined. Instead of manually chaining async calls, define each computation as a node and let the graph resolve dependencies in parallel. Adding a new filter or timeframe requires no changes to the existing wiring.
+
+#### Get Started
+```bash
+npm install @backtest-kit/graph backtest-kit
+```
+
 ## 🤖 Are you a robot?
 
 **For language models**: Read extended description in [./LLMs.md](./LLMs.md)

package/build/index.cjs

@@ -442,6 +442,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 });
 
@@ -712,7 +719,7 @@ 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$8 = {
@@ -830,7 +837,7 @@ class PersistBase {
     constructor(entityName, baseDir = path.join(process.cwd(), "logs/data")) {
         this.entityName = entityName;
         this.baseDir = baseDir;
-        this[_a$2] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
+        this[_a$3] = functoolsKit.singleshot(async () => await BASE_WAIT_FOR_INIT_FN(this));
         bt.loggerService.debug(PERSIST_BASE_METHOD_NAME_CTOR, {
             entityName: this.entityName,
             baseDir,
@@ -933,7 +940,7 @@ class PersistBase {
         }
     }
 }
-_a$2 = BASE_WAIT_FOR_INIT_SYMBOL;
+_a$3 = BASE_WAIT_FOR_INIT_SYMBOL;
 // @ts-ignore
 PersistBase = functoolsKit.makeExtendable(PersistBase);
 /**
@@ -1940,6 +1947,69 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
+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 functoolsKit.sleep(BUSY_DELAY);
+    }
+    self[SET_BUSY_SYMBOL](true);
+};
+class Lock {
+    constructor() {
+        this._isBusy = 0;
+        this[_a$2] = functoolsKit.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,
@@ -2119,34 +2189,40 @@ const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$7[dto.interval];
     const sinceTimestamp = since.getTime();
     const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$5;
-    // 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;
+    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: functoolsKit.errorData(err),
-                message: functoolsKit.getErrorMessage(err),
-            };
-            self.params.logger.warn(message, payload);
-            console.warn(message, payload);
-            lastError = err;
-            await functoolsKit.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: functoolsKit.errorData(err),
+                    message: functoolsKit.getErrorMessage(err),
+                };
+                self.params.logger.warn(message, payload);
+                console.warn(message, payload);
+                lastError = err;
+                await functoolsKit.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.
@@ -26327,55 +26403,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.
@@ -26609,56 +26691,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;
+            }
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
             }
-            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;
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);

package/build/index.mjs

@@ -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,7 +699,7 @@ 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$8 = {
@@ -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);
 /**
@@ -1920,6 +1927,69 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
+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,
@@ -2099,34 +2169,40 @@ const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$7[dto.interval];
     const sinceTimestamp = since.getTime();
     const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$5;
-    // 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;
+    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.
@@ -26307,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.
@@ -26589,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;
+            }
+            finally {
+                Candle.releaseLock(`ExchangeInstance.getRawCandles symbol=${symbol} interval=${interval} limit=${calculatedLimit}`);
             }
-            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;
         };
         const schema = bt.exchangeSchemaService.get(this.exchangeName);
         this._methods = CREATE_EXCHANGE_INSTANCE_FN(schema);

package/package.json

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

package/types.d.ts

@@ -4246,6 +4246,13 @@ declare const GLOBAL_CONFIG: {
      * Default: 50 signals
      */
     CC_MAX_SIGNALS: number;
+    /**
+     * 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: boolean;
 };
 /**
  * Type for global configuration object.
@@ -4354,6 +4361,7 @@ declare function getConfig(): {
     CC_ORDER_BOOK_MAX_DEPTH_LEVELS: number;
     CC_MAX_NOTIFICATIONS: number;
     CC_MAX_SIGNALS: number;
+    CC_ENABLE_CANDLE_FETCH_MUTEX: boolean;
 };
 /**
  * Retrieves the default configuration object for the framework.
@@ -4390,6 +4398,7 @@ declare function getDefaultConfig(): Readonly<{
     CC_ORDER_BOOK_MAX_DEPTH_LEVELS: number;
     CC_MAX_NOTIFICATIONS: number;
     CC_MAX_SIGNALS: number;
+    CC_ENABLE_CANDLE_FETCH_MUTEX: boolean;
 }>;
 /**
  * Sets custom column configurations for markdown report generation.