backtest-kit 3.0.13 → 3.0.15

package/README.md

@@ -281,6 +281,53 @@ According to this `timestamp` of a candle in backtest-kit is exactly the `openTi
 - Adapter must return exactly `limit` candles
 - Sequential timestamps: `since + i * stepMs`
 
+
+### 🔍 How getOrderBook Works
+
+Order book fetching uses the same temporal alignment as candles, but with a configurable time offset window instead of candle intervals.
+
+  <details>
+    <summary>
+      The Math
+    </summary>
+
+    **Time range calculation:**
+    - `when` = current execution context time (from AsyncLocalStorage)
+    - `offsetMinutes` = `CC_ORDER_BOOK_TIME_OFFSET_MINUTES` (configurable)
+    - `alignedTo` = `Math.floor(when / (offsetMinutes * 60000)) * (offsetMinutes * 60000)`
+    - `to` = `alignedTo` (aligned down to offset boundary)
+    - `from` = `alignedTo - offsetMinutes * 60000`
+
+    **Adapter contract:**
+    - `getOrderBook(symbol, depth, from, to, backtest)` is called on the exchange schema
+    - `depth` defaults to `CC_ORDER_BOOK_MAX_DEPTH_LEVELS`
+    - The `from`/`to` range represents a time window of exactly `offsetMinutes` duration
+    - Schema implementation may use the time range (backtest) or ignore it (live trading)
+
+    **Example with CC_ORDER_BOOK_TIME_OFFSET_MINUTES = 10:**
+    ```
+    when = 1704067920000       // 2024-01-01 00:12:00 UTC
+    offsetMinutes = 10
+    offsetMs = 10 * 60000      // 600000ms
+
+    alignedTo = Math.floor(1704067920000 / 600000) * 600000
+              = 1704067800000  // 2024-01-01 00:10:00 UTC
+
+    to   = 1704067800000       // 00:10:00 UTC
+    from = 1704067200000       // 00:00:00 UTC
+    ```
+  </details>
+
+#### Order Book Timestamp Convention:
+
+The `from`/`to` range is a **lookback window**. The adapter selects the closest snapshot to `to` in backtest mode, or returns real-time data in live mode. Unlike candles, most exchanges (e.g. Binance `GET /api/v3/depth`) only expose the **current** order book with no historical query support — for backtest you must provide your own snapshot storage.
+
+**Key principles:**
+- Time range is aligned down to `CC_ORDER_BOOK_TIME_OFFSET_MINUTES` boundary
+- `to` = aligned timestamp, `from` = `to - offsetMinutes * 60000`
+- `depth` defaults to `CC_ORDER_BOOK_MAX_DEPTH_LEVELS`
+- Adapter receives `(symbol, depth, from, to, backtest)` — may ignore `from`/`to` in live mode
+
 ### 🔬 Technical Details: Timestamp Alignment
 
 **Why align timestamps to interval boundaries?**

package/build/index.cjs

@@ -715,7 +715,7 @@ async function writeFileAtomic(file, data, options = {}) {
 var _a$2;
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
-const INTERVAL_MINUTES$6 = {
+const INTERVAL_MINUTES$7 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -727,7 +727,7 @@ const INTERVAL_MINUTES$6 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$4 = 60000;
+const MS_PER_MINUTE$5 = 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";
@@ -914,11 +914,13 @@ class PersistBase {
             entityName: this.entityName,
         });
         try {
-            const files = await fs.readdir(this._directory);
-            const entityIds = files
-                .filter((file) => file.endsWith(".json"))
-                .map((file) => file.slice(0, -5))
-                .sort((a, b) => a.localeCompare(b, undefined, {
+            const entityIds = [];
+            for await (const entry of await fs.opendir(this._directory)) {
+                if (entry.isFile() && entry.name.endsWith(".json")) {
+                    entityIds.push(entry.name.slice(0, -5));
+                }
+            }
+            entityIds.sort((a, b) => a.localeCompare(b, undefined, {
                 numeric: true,
                 sensitivity: "base",
             }));
@@ -1625,7 +1627,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$6[interval] * MS_PER_MINUTE$4;
+            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1681,7 +1683,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$6[interval] * MS_PER_MINUTE$4;
+            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1938,8 +1940,8 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$3 = 60000;
-const INTERVAL_MINUTES$5 = {
+const MS_PER_MINUTE$4 = 60000;
+const INTERVAL_MINUTES$6 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -1969,7 +1971,7 @@ const INTERVAL_MINUTES$5 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$2 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$3;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$4;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2114,9 +2116,9 @@ const WRITE_CANDLES_CACHE_FN$1 = functoolsKit.trycatch(functoolsKit.queued(async
  * @returns Promise resolving to array of candle data
  */
 const GET_CANDLES_FN = async (dto, since, self) => {
-    const step = INTERVAL_MINUTES$5[dto.interval];
+    const step = INTERVAL_MINUTES$6[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$3;
+    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) {
@@ -2224,11 +2226,11 @@ class ClientExchange {
             interval,
             limit,
         });
-        const step = INTERVAL_MINUTES$5[interval];
+        const step = INTERVAL_MINUTES$6[interval];
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$3;
+        const stepMs = step * MS_PER_MINUTE$4;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
@@ -2305,11 +2307,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$5[interval];
+        const step = INTERVAL_MINUTES$6[interval];
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$3;
+        const stepMs = step * MS_PER_MINUTE$4;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2473,11 +2475,11 @@ class ClientExchange {
             sDate,
             eDate,
         });
-        const step = INTERVAL_MINUTES$5[interval];
+        const step = INTERVAL_MINUTES$6[interval];
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$3;
+        const stepMs = step * MS_PER_MINUTE$4;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
         let sinceTimestamp;
@@ -2606,7 +2608,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$3);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$4);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -3071,7 +3073,7 @@ const beginTime = (run) => (...args) => {
     return fn();
 };
 
-const INTERVAL_MINUTES$4 = {
+const INTERVAL_MINUTES$5 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -3584,7 +3586,7 @@ const GET_SIGNAL_FN = functoolsKit.trycatch(async (self) => {
     }
     const currentTime = self.params.execution.context.when.getTime();
     {
-        const intervalMinutes = INTERVAL_MINUTES$4[self.params.interval];
+        const intervalMinutes = INTERVAL_MINUTES$5[self.params.interval];
         const intervalMs = intervalMinutes * 60 * 1000;
         // Проверяем что прошел нужный интервал с последнего getSignal
         if (self._lastSignalTimestamp !== null &&
@@ -8195,7 +8197,7 @@ class StrategyConnectionService {
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$3 = {
+const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -8250,7 +8252,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$3[interval];
+    const intervalMinutes = INTERVAL_MINUTES$4[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -26046,7 +26048,7 @@ const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
 const EXCHANGE_METHOD_NAME_GET_ORDER_BOOK = "ExchangeUtils.getOrderBook";
 const EXCHANGE_METHOD_NAME_GET_RAW_CANDLES = "ExchangeUtils.getRawCandles";
-const MS_PER_MINUTE$2 = 60000;
+const MS_PER_MINUTE$3 = 60000;
 /**
  * Gets current timestamp from execution context if available.
  * Returns current Date() if no execution context exists (non-trading GUI).
@@ -26101,7 +26103,7 @@ const DEFAULT_FORMAT_PRICE_FN = async (_symbol, price, _backtest) => {
 const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _depth, _from, _to, _backtest) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
-const INTERVAL_MINUTES$2 = {
+const INTERVAL_MINUTES$3 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -26131,7 +26133,7 @@ const INTERVAL_MINUTES$2 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$1 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$3;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -26269,11 +26271,11 @@ class ExchangeInstance {
                 limit,
             });
             const getCandles = this._methods.getCandles;
-            const step = INTERVAL_MINUTES$2[interval];
+            const step = INTERVAL_MINUTES$3[interval];
             if (!step) {
                 throw new Error(`ExchangeInstance unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE$2;
+            const stepMs = step * MS_PER_MINUTE$3;
             // Align when down to interval boundary
             const when = await GET_TIMESTAMP_FN();
             const whenTimestamp = when.getTime();
@@ -26452,7 +26454,7 @@ class ExchangeInstance {
             const when = await GET_TIMESTAMP_FN();
             const alignedTo = ALIGN_TO_INTERVAL_FN$1(when.getTime(), 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$2);
+            const from = new Date(alignedTo - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$3);
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
@@ -26495,11 +26497,11 @@ class ExchangeInstance {
                 sDate,
                 eDate,
             });
-            const step = INTERVAL_MINUTES$2[interval];
+            const step = INTERVAL_MINUTES$3[interval];
             if (!step) {
                 throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE$2;
+            const stepMs = step * MS_PER_MINUTE$3;
             const when = await GET_TIMESTAMP_FN();
             const nowTimestamp = when.getTime();
             const alignedNow = ALIGN_TO_INTERVAL_FN$1(nowTimestamp, step);
@@ -26770,8 +26772,8 @@ const Exchange = new ExchangeUtils();
 
 const WARM_CANDLES_METHOD_NAME = "cache.warmCandles";
 const CHECK_CANDLES_METHOD_NAME = "cache.checkCandles";
-const MS_PER_MINUTE$1 = 60000;
-const INTERVAL_MINUTES$1 = {
+const MS_PER_MINUTE$2 = 60000;
+const INTERVAL_MINUTES$2 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -26784,7 +26786,7 @@ const INTERVAL_MINUTES$1 = {
     "8h": 480,
 };
 const ALIGN_TO_INTERVAL_FN = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 const BAR_LENGTH = 30;
@@ -26807,59 +26809,66 @@ const PRINT_PROGRESS_FN = (fetched, total, symbol, interval) => {
  * @param params - Validation parameters
  */
 async function checkCandles(params) {
-    const { symbol, exchangeName, interval, baseDir = "./dump/data/candle" } = params;
+    const { symbol, exchangeName, interval, from, to, baseDir = "./dump/data/candle" } = params;
     bt.loggerService.info(CHECK_CANDLES_METHOD_NAME, params);
-    const step = INTERVAL_MINUTES$1[interval];
+    const step = INTERVAL_MINUTES$2[interval];
     if (!step) {
         throw new Error(`checkCandles: unsupported interval=${interval}`);
     }
-    const stepMs = step * MS_PER_MINUTE$1;
+    const stepMs = step * MS_PER_MINUTE$2;
     const dir = path.join(baseDir, exchangeName, symbol, interval);
+    const fromTs = ALIGN_TO_INTERVAL_FN(from.getTime(), step);
+    const toTs = ALIGN_TO_INTERVAL_FN(to.getTime(), step);
     try {
         await fs.stat(dir);
     }
     catch {
         throw new Error(`checkCandles: cache directory not found: ${dir}`);
     }
-    // First pass: count files via async iterator (no memory allocation for file list)
-    let totalFiles = 0;
+    // Collect only filenames (strings) in range via async iterator — no full readdir in memory
+    const files = [];
     for await (const entry of await fs.opendir(dir)) {
-        if (entry.isFile() && entry.name.endsWith(".json")) {
-            totalFiles++;
+        if (!entry.isFile() || !entry.name.endsWith(".json")) {
+            continue;
+        }
+        const ts = Number(entry.name.replace(".json", ""));
+        if (ts >= fromTs && ts < toTs) {
+            files.push(entry.name);
         }
     }
-    if (totalFiles === 0) {
-        throw new Error(`checkCandles: no cached candles in ${dir}`);
+    if (files.length === 0) {
+        throw new Error(`checkCandles: no cached candles in range [${fromTs}, ${toTs}) in ${dir}`);
     }
-    // Second pass: check each file via async iterator with progress
-    let checkd = 0;
+    files.sort();
     let prevTimestamp = null;
     let prevName = null;
-    PRINT_PROGRESS_FN(checkd, totalFiles, symbol, interval);
-    for await (const entry of await fs.opendir(dir)) {
-        if (!entry.isFile() || !entry.name.endsWith(".json")) {
-            continue;
-        }
-        const filePath = path.join(dir, entry.name);
+    PRINT_PROGRESS_FN(0, files.length, symbol, interval);
+    for (let i = 0; i < files.length; i++) {
+        const filePath = path.join(dir, files[i]);
         const raw = await fs.readFile(filePath, "utf-8");
-        const candle = JSON.parse(raw);
+        let candle;
+        try {
+            candle = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`checkCandles: ${files[i]} contains invalid JSON`);
+        }
         const { timestamp } = candle;
         const aligned = ALIGN_TO_INTERVAL_FN(timestamp, step);
         if (timestamp !== aligned) {
-            throw new Error(`checkCandles: ${entry.name} timestamp not aligned to ${interval} boundary (actual=${timestamp}, expected=${aligned})`);
+            throw new Error(`checkCandles: ${files[i]} timestamp not aligned to ${interval} boundary (actual=${timestamp}, expected=${aligned})`);
         }
         if (prevTimestamp !== null) {
             const gap = timestamp - prevTimestamp;
             if (gap !== stepMs) {
-                throw new Error(`checkCandles: gap between ${prevName} and ${entry.name} (actual=${gap}ms, expected=${stepMs}ms)`);
+                throw new Error(`checkCandles: gap between ${prevName} and ${files[i]} (actual=${gap}ms, expected=${stepMs}ms)`);
             }
         }
         prevTimestamp = timestamp;
-        prevName = entry.name;
-        checkd++;
-        PRINT_PROGRESS_FN(checkd, totalFiles, symbol, interval);
+        prevName = files[i];
+        PRINT_PROGRESS_FN(i + 1, files.length, symbol, interval);
     }
-    console.log(`checkCandles: OK ${totalFiles} candles ${symbol} ${interval}`);
+    console.log(`checkCandles: OK ${files.length} candles ${symbol} ${interval}`);
 }
 /**
  * Pre-caches candles for a date range into persist storage.
@@ -26876,11 +26885,11 @@ async function warmCandles(params) {
         from,
         to,
     });
-    const step = INTERVAL_MINUTES$1[interval];
+    const step = INTERVAL_MINUTES$2[interval];
     if (!step) {
         throw new Error(`warmCandles: unsupported interval=${interval}`);
     }
-    const stepMs = step * MS_PER_MINUTE$1;
+    const stepMs = step * MS_PER_MINUTE$2;
     const instance = new ExchangeInstance(exchangeName);
     const sinceTimestamp = ALIGN_TO_INTERVAL_FN(from.getTime(), step);
     const untilTimestamp = ALIGN_TO_INTERVAL_FN(to.getTime(), step);
@@ -36388,8 +36397,8 @@ const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_GC = "CacheInstance.gc";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
-const MS_PER_MINUTE = 60000;
-const INTERVAL_MINUTES = {
+const MS_PER_MINUTE$1 = 60000;
+const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -36422,11 +36431,11 @@ const INTERVAL_MINUTES = {
  * ```
  */
 const align = (timestamp, interval) => {
-    const intervalMinutes = INTERVAL_MINUTES[interval];
+    const intervalMinutes = INTERVAL_MINUTES$1[interval];
     if (!intervalMinutes) {
         throw new Error(`align: unknown interval=${interval}`);
     }
-    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -36515,7 +36524,7 @@ class CacheInstance {
          */
         this.run = (...args) => {
             bt.loggerService.debug(CACHE_METHOD_NAME_RUN, { args });
-            const step = INTERVAL_MINUTES[this.interval];
+            const step = INTERVAL_MINUTES$1[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
                     throw new Error("CacheInstance run requires method context");
@@ -37181,6 +37190,45 @@ class StrategyUtils {
  */
 const Strategy = new StrategyUtils();
 
+const MS_PER_MINUTE = 60000;
+const INTERVAL_MINUTES = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+};
+/**
+ * Aligns timestamp down to the nearest interval boundary.
+ * For example, for 15m interval: 00:17 -> 00:15, 00:44 -> 00:30
+ *
+ * Candle timestamp convention:
+ * - Candle timestamp = openTime (when candle opens)
+ * - Candle with timestamp 00:00 covers period [00:00, 00:15) for 15m interval
+ *
+ * Adapter contract:
+ * - Adapter must return candles with timestamp = openTime
+ * - First returned candle.timestamp must equal aligned since
+ * - Adapter must return exactly `limit` candles
+ *
+ * @param date - Date to align
+ * @param interval - Candle interval (e.g., "1m", "15m", "1h")
+ * @returns New Date aligned down to interval boundary
+ */
+const alignToInterval = (date, interval) => {
+    const minutes = INTERVAL_MINUTES[interval];
+    if (minutes === undefined) {
+        throw new Error(`alignToInterval: unknown interval=${interval}`);
+    }
+    const intervalMs = minutes * MS_PER_MINUTE;
+    return new Date(Math.floor(date.getTime() / intervalMs) * intervalMs);
+};
+
 /**
  * Rounds a price to the appropriate precision based on the tick size.
  *
@@ -37357,6 +37405,7 @@ exports.addRiskSchema = addRiskSchema;
 exports.addSizingSchema = addSizingSchema;
 exports.addStrategySchema = addStrategySchema;
 exports.addWalkerSchema = addWalkerSchema;
+exports.alignToInterval = alignToInterval;
 exports.checkCandles = checkCandles;
 exports.commitActivateScheduled = commitActivateScheduled;
 exports.commitBreakeven = commitBreakeven;

package/build/index.mjs

@@ -695,7 +695,7 @@ async function writeFileAtomic(file, data, options = {}) {
 var _a$2;
 const BASE_WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 // Calculate step in milliseconds for candle close time validation
-const INTERVAL_MINUTES$6 = {
+const INTERVAL_MINUTES$7 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -707,7 +707,7 @@ const INTERVAL_MINUTES$6 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$4 = 60000;
+const MS_PER_MINUTE$5 = 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";
@@ -894,11 +894,13 @@ class PersistBase {
             entityName: this.entityName,
         });
         try {
-            const files = await fs__default.readdir(this._directory);
-            const entityIds = files
-                .filter((file) => file.endsWith(".json"))
-                .map((file) => file.slice(0, -5))
-                .sort((a, b) => a.localeCompare(b, undefined, {
+            const entityIds = [];
+            for await (const entry of await fs__default.opendir(this._directory)) {
+                if (entry.isFile() && entry.name.endsWith(".json")) {
+                    entityIds.push(entry.name.slice(0, -5));
+                }
+            }
+            entityIds.sort((a, b) => a.localeCompare(b, undefined, {
                 numeric: true,
                 sensitivity: "base",
             }));
@@ -1605,7 +1607,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$6[interval] * MS_PER_MINUTE$4;
+            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1661,7 +1663,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$6[interval] * MS_PER_MINUTE$4;
+            const stepMs = INTERVAL_MINUTES$7[interval] * MS_PER_MINUTE$5;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1918,8 +1920,8 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$3 = 60000;
-const INTERVAL_MINUTES$5 = {
+const MS_PER_MINUTE$4 = 60000;
+const INTERVAL_MINUTES$6 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -1949,7 +1951,7 @@ const INTERVAL_MINUTES$5 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$2 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$3;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$4;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2094,9 +2096,9 @@ 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$5[dto.interval];
+    const step = INTERVAL_MINUTES$6[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$3;
+    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) {
@@ -2204,11 +2206,11 @@ class ClientExchange {
             interval,
             limit,
         });
-        const step = INTERVAL_MINUTES$5[interval];
+        const step = INTERVAL_MINUTES$6[interval];
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$3;
+        const stepMs = step * MS_PER_MINUTE$4;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
@@ -2285,11 +2287,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$5[interval];
+        const step = INTERVAL_MINUTES$6[interval];
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$3;
+        const stepMs = step * MS_PER_MINUTE$4;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2453,11 +2455,11 @@ class ClientExchange {
             sDate,
             eDate,
         });
-        const step = INTERVAL_MINUTES$5[interval];
+        const step = INTERVAL_MINUTES$6[interval];
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$3;
+        const stepMs = step * MS_PER_MINUTE$4;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$2(whenTimestamp, step);
         let sinceTimestamp;
@@ -2586,7 +2588,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$3);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$4);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -3051,7 +3053,7 @@ const beginTime = (run) => (...args) => {
     return fn();
 };
 
-const INTERVAL_MINUTES$4 = {
+const INTERVAL_MINUTES$5 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -3564,7 +3566,7 @@ const GET_SIGNAL_FN = trycatch(async (self) => {
     }
     const currentTime = self.params.execution.context.when.getTime();
     {
-        const intervalMinutes = INTERVAL_MINUTES$4[self.params.interval];
+        const intervalMinutes = INTERVAL_MINUTES$5[self.params.interval];
         const intervalMs = intervalMinutes * 60 * 1000;
         // Проверяем что прошел нужный интервал с последнего getSignal
         if (self._lastSignalTimestamp !== null &&
@@ -8175,7 +8177,7 @@ class StrategyConnectionService {
  * Maps FrameInterval to minutes for timestamp calculation.
  * Used to generate timeframe arrays with proper spacing.
  */
-const INTERVAL_MINUTES$3 = {
+const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -8230,7 +8232,7 @@ const GET_TIMEFRAME_FN = async (symbol, self) => {
         symbol,
     });
     const { interval, startDate, endDate } = self.params;
-    const intervalMinutes = INTERVAL_MINUTES$3[interval];
+    const intervalMinutes = INTERVAL_MINUTES$4[interval];
     if (!intervalMinutes) {
         throw new Error(`ClientFrame unknown interval: ${interval}`);
     }
@@ -26026,7 +26028,7 @@ const EXCHANGE_METHOD_NAME_FORMAT_QUANTITY = "ExchangeUtils.formatQuantity";
 const EXCHANGE_METHOD_NAME_FORMAT_PRICE = "ExchangeUtils.formatPrice";
 const EXCHANGE_METHOD_NAME_GET_ORDER_BOOK = "ExchangeUtils.getOrderBook";
 const EXCHANGE_METHOD_NAME_GET_RAW_CANDLES = "ExchangeUtils.getRawCandles";
-const MS_PER_MINUTE$2 = 60000;
+const MS_PER_MINUTE$3 = 60000;
 /**
  * Gets current timestamp from execution context if available.
  * Returns current Date() if no execution context exists (non-trading GUI).
@@ -26081,7 +26083,7 @@ const DEFAULT_FORMAT_PRICE_FN = async (_symbol, price, _backtest) => {
 const DEFAULT_GET_ORDER_BOOK_FN = async (_symbol, _depth, _from, _to, _backtest) => {
     throw new Error(`getOrderBook is not implemented for this exchange`);
 };
-const INTERVAL_MINUTES$2 = {
+const INTERVAL_MINUTES$3 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -26111,7 +26113,7 @@ const INTERVAL_MINUTES$2 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$1 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$3;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -26249,11 +26251,11 @@ class ExchangeInstance {
                 limit,
             });
             const getCandles = this._methods.getCandles;
-            const step = INTERVAL_MINUTES$2[interval];
+            const step = INTERVAL_MINUTES$3[interval];
             if (!step) {
                 throw new Error(`ExchangeInstance unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE$2;
+            const stepMs = step * MS_PER_MINUTE$3;
             // Align when down to interval boundary
             const when = await GET_TIMESTAMP_FN();
             const whenTimestamp = when.getTime();
@@ -26432,7 +26434,7 @@ class ExchangeInstance {
             const when = await GET_TIMESTAMP_FN();
             const alignedTo = ALIGN_TO_INTERVAL_FN$1(when.getTime(), 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$2);
+            const from = new Date(alignedTo - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$3);
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
@@ -26475,11 +26477,11 @@ class ExchangeInstance {
                 sDate,
                 eDate,
             });
-            const step = INTERVAL_MINUTES$2[interval];
+            const step = INTERVAL_MINUTES$3[interval];
             if (!step) {
                 throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE$2;
+            const stepMs = step * MS_PER_MINUTE$3;
             const when = await GET_TIMESTAMP_FN();
             const nowTimestamp = when.getTime();
             const alignedNow = ALIGN_TO_INTERVAL_FN$1(nowTimestamp, step);
@@ -26750,8 +26752,8 @@ const Exchange = new ExchangeUtils();
 
 const WARM_CANDLES_METHOD_NAME = "cache.warmCandles";
 const CHECK_CANDLES_METHOD_NAME = "cache.checkCandles";
-const MS_PER_MINUTE$1 = 60000;
-const INTERVAL_MINUTES$1 = {
+const MS_PER_MINUTE$2 = 60000;
+const INTERVAL_MINUTES$2 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -26764,7 +26766,7 @@ const INTERVAL_MINUTES$1 = {
     "8h": 480,
 };
 const ALIGN_TO_INTERVAL_FN = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 const BAR_LENGTH = 30;
@@ -26787,59 +26789,66 @@ const PRINT_PROGRESS_FN = (fetched, total, symbol, interval) => {
  * @param params - Validation parameters
  */
 async function checkCandles(params) {
-    const { symbol, exchangeName, interval, baseDir = "./dump/data/candle" } = params;
+    const { symbol, exchangeName, interval, from, to, baseDir = "./dump/data/candle" } = params;
     bt.loggerService.info(CHECK_CANDLES_METHOD_NAME, params);
-    const step = INTERVAL_MINUTES$1[interval];
+    const step = INTERVAL_MINUTES$2[interval];
     if (!step) {
         throw new Error(`checkCandles: unsupported interval=${interval}`);
     }
-    const stepMs = step * MS_PER_MINUTE$1;
+    const stepMs = step * MS_PER_MINUTE$2;
     const dir = join(baseDir, exchangeName, symbol, interval);
+    const fromTs = ALIGN_TO_INTERVAL_FN(from.getTime(), step);
+    const toTs = ALIGN_TO_INTERVAL_FN(to.getTime(), step);
     try {
         await stat(dir);
     }
     catch {
         throw new Error(`checkCandles: cache directory not found: ${dir}`);
     }
-    // First pass: count files via async iterator (no memory allocation for file list)
-    let totalFiles = 0;
+    // Collect only filenames (strings) in range via async iterator — no full readdir in memory
+    const files = [];
     for await (const entry of await opendir(dir)) {
-        if (entry.isFile() && entry.name.endsWith(".json")) {
-            totalFiles++;
+        if (!entry.isFile() || !entry.name.endsWith(".json")) {
+            continue;
+        }
+        const ts = Number(entry.name.replace(".json", ""));
+        if (ts >= fromTs && ts < toTs) {
+            files.push(entry.name);
         }
     }
-    if (totalFiles === 0) {
-        throw new Error(`checkCandles: no cached candles in ${dir}`);
+    if (files.length === 0) {
+        throw new Error(`checkCandles: no cached candles in range [${fromTs}, ${toTs}) in ${dir}`);
     }
-    // Second pass: check each file via async iterator with progress
-    let checkd = 0;
+    files.sort();
     let prevTimestamp = null;
     let prevName = null;
-    PRINT_PROGRESS_FN(checkd, totalFiles, symbol, interval);
-    for await (const entry of await opendir(dir)) {
-        if (!entry.isFile() || !entry.name.endsWith(".json")) {
-            continue;
-        }
-        const filePath = join(dir, entry.name);
+    PRINT_PROGRESS_FN(0, files.length, symbol, interval);
+    for (let i = 0; i < files.length; i++) {
+        const filePath = join(dir, files[i]);
         const raw = await readFile(filePath, "utf-8");
-        const candle = JSON.parse(raw);
+        let candle;
+        try {
+            candle = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`checkCandles: ${files[i]} contains invalid JSON`);
+        }
         const { timestamp } = candle;
         const aligned = ALIGN_TO_INTERVAL_FN(timestamp, step);
         if (timestamp !== aligned) {
-            throw new Error(`checkCandles: ${entry.name} timestamp not aligned to ${interval} boundary (actual=${timestamp}, expected=${aligned})`);
+            throw new Error(`checkCandles: ${files[i]} timestamp not aligned to ${interval} boundary (actual=${timestamp}, expected=${aligned})`);
         }
         if (prevTimestamp !== null) {
             const gap = timestamp - prevTimestamp;
             if (gap !== stepMs) {
-                throw new Error(`checkCandles: gap between ${prevName} and ${entry.name} (actual=${gap}ms, expected=${stepMs}ms)`);
+                throw new Error(`checkCandles: gap between ${prevName} and ${files[i]} (actual=${gap}ms, expected=${stepMs}ms)`);
             }
         }
         prevTimestamp = timestamp;
-        prevName = entry.name;
-        checkd++;
-        PRINT_PROGRESS_FN(checkd, totalFiles, symbol, interval);
+        prevName = files[i];
+        PRINT_PROGRESS_FN(i + 1, files.length, symbol, interval);
     }
-    console.log(`checkCandles: OK ${totalFiles} candles ${symbol} ${interval}`);
+    console.log(`checkCandles: OK ${files.length} candles ${symbol} ${interval}`);
 }
 /**
  * Pre-caches candles for a date range into persist storage.
@@ -26856,11 +26865,11 @@ async function warmCandles(params) {
         from,
         to,
     });
-    const step = INTERVAL_MINUTES$1[interval];
+    const step = INTERVAL_MINUTES$2[interval];
     if (!step) {
         throw new Error(`warmCandles: unsupported interval=${interval}`);
     }
-    const stepMs = step * MS_PER_MINUTE$1;
+    const stepMs = step * MS_PER_MINUTE$2;
     const instance = new ExchangeInstance(exchangeName);
     const sinceTimestamp = ALIGN_TO_INTERVAL_FN(from.getTime(), step);
     const untilTimestamp = ALIGN_TO_INTERVAL_FN(to.getTime(), step);
@@ -36368,8 +36377,8 @@ const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_GC = "CacheInstance.gc";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
-const MS_PER_MINUTE = 60000;
-const INTERVAL_MINUTES = {
+const MS_PER_MINUTE$1 = 60000;
+const INTERVAL_MINUTES$1 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -36402,11 +36411,11 @@ const INTERVAL_MINUTES = {
  * ```
  */
 const align = (timestamp, interval) => {
-    const intervalMinutes = INTERVAL_MINUTES[interval];
+    const intervalMinutes = INTERVAL_MINUTES$1[interval];
     if (!intervalMinutes) {
         throw new Error(`align: unknown interval=${interval}`);
     }
-    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -36495,7 +36504,7 @@ class CacheInstance {
          */
         this.run = (...args) => {
             bt.loggerService.debug(CACHE_METHOD_NAME_RUN, { args });
-            const step = INTERVAL_MINUTES[this.interval];
+            const step = INTERVAL_MINUTES$1[this.interval];
             {
                 if (!MethodContextService.hasContext()) {
                     throw new Error("CacheInstance run requires method context");
@@ -37161,6 +37170,45 @@ class StrategyUtils {
  */
 const Strategy = new StrategyUtils();
 
+const MS_PER_MINUTE = 60000;
+const INTERVAL_MINUTES = {
+    "1m": 1,
+    "3m": 3,
+    "5m": 5,
+    "15m": 15,
+    "30m": 30,
+    "1h": 60,
+    "2h": 120,
+    "4h": 240,
+    "6h": 360,
+    "8h": 480,
+};
+/**
+ * Aligns timestamp down to the nearest interval boundary.
+ * For example, for 15m interval: 00:17 -> 00:15, 00:44 -> 00:30
+ *
+ * Candle timestamp convention:
+ * - Candle timestamp = openTime (when candle opens)
+ * - Candle with timestamp 00:00 covers period [00:00, 00:15) for 15m interval
+ *
+ * Adapter contract:
+ * - Adapter must return candles with timestamp = openTime
+ * - First returned candle.timestamp must equal aligned since
+ * - Adapter must return exactly `limit` candles
+ *
+ * @param date - Date to align
+ * @param interval - Candle interval (e.g., "1m", "15m", "1h")
+ * @returns New Date aligned down to interval boundary
+ */
+const alignToInterval = (date, interval) => {
+    const minutes = INTERVAL_MINUTES[interval];
+    if (minutes === undefined) {
+        throw new Error(`alignToInterval: unknown interval=${interval}`);
+    }
+    const intervalMs = minutes * MS_PER_MINUTE;
+    return new Date(Math.floor(date.getTime() / intervalMs) * intervalMs);
+};
+
 /**
  * Rounds a price to the appropriate precision based on the tick size.
  *
@@ -37293,4 +37341,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, 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, warmCandles };

package/package.json

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

package/types.d.ts

@@ -337,6 +337,10 @@ interface ICheckCandlesParams {
     exchangeName: ExchangeName;
     /** Candle time interval (e.g., "1m", "4h") */
     interval: CandleInterval;
+    /** Start date of the validation range (inclusive) */
+    from: Date;
+    /** End date of the validation range (inclusive) */
+    to: Date;
     /** Base directory of candle persist storage (default: "./dump/data/candle") */
     baseDir?: string;
 }
@@ -16178,6 +16182,25 @@ declare namespace emitters {
   export { emitters_activePingSubject as activePingSubject, emitters_backtestScheduleOpenSubject as backtestScheduleOpenSubject, emitters_breakevenSubject as breakevenSubject, emitters_doneBacktestSubject as doneBacktestSubject, emitters_doneLiveSubject as doneLiveSubject, emitters_doneWalkerSubject as doneWalkerSubject, emitters_errorEmitter as errorEmitter, emitters_exitEmitter as exitEmitter, emitters_partialLossSubject as partialLossSubject, emitters_partialProfitSubject as partialProfitSubject, emitters_performanceEmitter as performanceEmitter, emitters_progressBacktestEmitter as progressBacktestEmitter, emitters_progressWalkerEmitter as progressWalkerEmitter, emitters_riskSubject as riskSubject, emitters_schedulePingSubject as schedulePingSubject, emitters_signalBacktestEmitter as signalBacktestEmitter, emitters_signalEmitter as signalEmitter, emitters_signalLiveEmitter as signalLiveEmitter, emitters_strategyCommitSubject as strategyCommitSubject, emitters_validationSubject as validationSubject, emitters_walkerCompleteSubject as walkerCompleteSubject, emitters_walkerEmitter as walkerEmitter, emitters_walkerStopSubject as walkerStopSubject };
 }
 
+/**
+ * Aligns timestamp down to the nearest interval boundary.
+ * For example, for 15m interval: 00:17 -> 00:15, 00:44 -> 00:30
+ *
+ * Candle timestamp convention:
+ * - Candle timestamp = openTime (when candle opens)
+ * - Candle with timestamp 00:00 covers period [00:00, 00:15) for 15m interval
+ *
+ * Adapter contract:
+ * - Adapter must return candles with timestamp = openTime
+ * - First returned candle.timestamp must equal aligned since
+ * - Adapter must return exactly `limit` candles
+ *
+ * @param date - Date to align
+ * @param interval - Candle interval (e.g., "1m", "15m", "1h")
+ * @returns New Date aligned down to interval boundary
+ */
+declare const alignToInterval: (date: Date, interval: CandleInterval) => Date;
+
 /**
  * Rounds a price to the appropriate precision based on the tick size.
  *
@@ -20819,4 +20842,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActivateScheduledCommitRow, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, 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, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActivateScheduledCommitRow, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistNotificationAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Storage, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, 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 };