backtest-kit 3.0.14 → 3.0.16

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";
@@ -1627,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++) {
@@ -1683,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) {
@@ -1940,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,
@@ -1971,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;
 };
 /**
@@ -2116,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) {
@@ -2226,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);
@@ -2307,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();
@@ -2475,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;
@@ -2608,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);
     }
 }
@@ -3073,7 +3073,7 @@ const beginTime = (run) => (...args) => {
     return fn();
 };
 
-const INTERVAL_MINUTES$4 = {
+const INTERVAL_MINUTES$5 = {
     "1m": 1,
     "3m": 3,
     "5m": 5,
@@ -3586,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 &&
@@ -8197,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,
@@ -8252,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}`);
     }
@@ -26048,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).
@@ -26103,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,
@@ -26133,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;
 };
 /**
@@ -26271,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();
@@ -26454,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);
         };
@@ -26497,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);
@@ -26772,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,
@@ -26786,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;
@@ -26811,11 +26811,11 @@ const PRINT_PROGRESS_FN = (fetched, total, symbol, interval) => {
 async function checkCandles(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);
@@ -26885,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);
@@ -36397,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,
@@ -36431,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;
 };
 /**
@@ -36524,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");
@@ -37190,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.
  *
@@ -37366,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;