backtest-kit 3.0.4 → 3.0.6

package/README.md

@@ -1,10 +1,10 @@
-<img src="./assets/triangle.svg" height="105px" align="right">
+<img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/consciousness.svg" height="45px" align="right">
 
 # 🧿 Backtest Kit
 
 > A TypeScript framework for backtesting and live trading strategies on multi-asset, crypto, forex or [DEX (peer-to-peer marketplace)](https://en.wikipedia.org/wiki/Decentralized_finance#Decentralized_exchanges), spot, futures with crash-safe persistence, signal validation, and AI optimization.
 
-![future](./assets/prophet.png)
+![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot8.png)
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
 [![npm](https://img.shields.io/npm/v/backtest-kit.svg?style=flat-square)](https://npmjs.org/package/backtest-kit)
@@ -364,7 +364,7 @@ Unlike cloud-based platforms, backtest-kit runs entirely in your environment. Yo
 - Self-hosted - your code, your data, your infrastructure
 - No platform fees or hidden costs
 - Full control over execution and data sources
-- [GUI](https://backtest-kit.github.io/documents/design_30_markdown-report-system.html#method-signatures) for visualization and monitoring
+- [GUI](https://npmjs.com/package/@backtest-kit/ui) for visualization and monitoring
 
 ## 🌍 Ecosystem
 

package/build/index.cjs

@@ -727,7 +727,7 @@ const INTERVAL_MINUTES$5 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$2 = 60000;
+const MS_PER_MINUTE$3 = 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";
@@ -1625,7 +1625,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1681,7 +1681,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$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1938,7 +1938,7 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$1 = 60000;
+const MS_PER_MINUTE$2 = 60000;
 const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
@@ -1969,7 +1969,7 @@ const INTERVAL_MINUTES$4 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$1 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2116,7 +2116,7 @@ const WRITE_CANDLES_CACHE_FN$1 = functoolsKit.trycatch(functoolsKit.queued(async
 const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$4[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$1;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$2;
     // Try to read from cache first
     const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
     if (cachedCandles !== null) {
@@ -2228,7 +2228,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
@@ -2309,7 +2309,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2477,7 +2477,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
         let sinceTimestamp;
@@ -2604,7 +2604,7 @@ class ClientExchange {
         });
         const to = new Date(this.params.execution.context.when.getTime());
         const from = new Date(to.getTime() -
-            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$2);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -35527,7 +35527,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 = 60000;
+const MS_PER_MINUTE$1 = 60000;
 /**
  * Gets current timestamp from execution context if available.
  * Returns current Date() if no execution context exists (non-trading GUI).
@@ -35612,7 +35612,7 @@ const INTERVAL_MINUTES$1 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -35754,7 +35754,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             // Align when down to interval boundary
             const when = await GET_TIMESTAMP_FN();
             const whenTimestamp = when.getTime();
@@ -35931,7 +35931,7 @@ class ExchangeInstance {
                 depth,
             });
             const to = await GET_TIMESTAMP_FN();
-            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE);
+            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
@@ -35978,7 +35978,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             const when = await GET_TIMESTAMP_FN();
             const nowTimestamp = when.getTime();
             const alignedNow = ALIGN_TO_INTERVAL_FN(nowTimestamp, step);
@@ -36251,6 +36251,7 @@ const CACHE_METHOD_NAME_FLUSH = "CacheUtils.flush";
 const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
     "1m": 1,
     "3m": 3,
@@ -36263,6 +36264,34 @@ const INTERVAL_MINUTES = {
     "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
+ *
+ * @param timestamp - Timestamp in milliseconds
+ * @param interval - Candle interval
+ * @returns Aligned timestamp rounded down to interval boundary
+ * @throws Error if interval is unknown
+ *
+ * @example
+ * ```typescript
+ * // Align to 15-minute boundary
+ * const aligned = align(new Date("2025-10-01T00:35:00Z").getTime(), "15m");
+ * // Returns timestamp for 2025-10-01T00:30:00Z
+ *
+ * // Align to 1-hour boundary
+ * const aligned = align(new Date("2025-10-01T01:47:00Z").getTime(), "1h");
+ * // Returns timestamp for 2025-10-01T01:00:00Z
+ * ```
+ */
+const align = (timestamp, interval) => {
+    const intervalMinutes = INTERVAL_MINUTES[interval];
+    if (!intervalMinutes) {
+        throw new Error(`align: unknown interval=${interval}`);
+    }
+    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    return Math.floor(timestamp / intervalMs) * intervalMs;
+};
 /**
  * Create a cache key string from strategy name, exchange name, and backtest mode.
  *
@@ -36357,9 +36386,9 @@ class CacheInstance {
             const currentWhen = bt.executionContextService.context.when;
             const cached = this._cacheMap.get(key);
             if (cached) {
-                const stepMs = step * 60 * 1000;
-                const elapsed = currentWhen.getTime() - cached.when.getTime();
-                if (elapsed >= 0 && elapsed < stepMs) {
+                const currentAligned = align(currentWhen.getTime(), this.interval);
+                const cachedAligned = align(cached.when.getTime(), this.interval);
+                if (currentAligned === cachedAligned) {
                     return cached;
                 }
             }

package/build/index.mjs

@@ -707,7 +707,7 @@ const INTERVAL_MINUTES$5 = {
     "6h": 360,
     "8h": 480,
 };
-const MS_PER_MINUTE$2 = 60000;
+const MS_PER_MINUTE$3 = 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";
@@ -1605,7 +1605,7 @@ class PersistCandleUtils {
             const isInitial = !this.getCandlesStorage.has(key);
             const stateStorage = this.getCandlesStorage(symbol, interval, exchangeName);
             await stateStorage.waitForInit(isInitial);
-            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             // Calculate expected timestamps and fetch each candle directly
             const cachedCandles = [];
             for (let i = 0; i < limit; i++) {
@@ -1661,7 +1661,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$5[interval] * MS_PER_MINUTE$2;
+            const stepMs = INTERVAL_MINUTES$5[interval] * MS_PER_MINUTE$3;
             const now = Date.now();
             // Write each candle as a separate file, skipping incomplete candles
             for (const candle of candles) {
@@ -1918,7 +1918,7 @@ class PersistNotificationUtils {
  */
 const PersistNotificationAdapter = new PersistNotificationUtils();
 
-const MS_PER_MINUTE$1 = 60000;
+const MS_PER_MINUTE$2 = 60000;
 const INTERVAL_MINUTES$4 = {
     "1m": 1,
     "3m": 3,
@@ -1949,7 +1949,7 @@ const INTERVAL_MINUTES$4 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN$1 = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$2;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -2096,7 +2096,7 @@ const WRITE_CANDLES_CACHE_FN$1 = trycatch(queued(async (candles, dto, self) => {
 const GET_CANDLES_FN = async (dto, since, self) => {
     const step = INTERVAL_MINUTES$4[dto.interval];
     const sinceTimestamp = since.getTime();
-    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$1;
+    const untilTimestamp = sinceTimestamp + dto.limit * step * MS_PER_MINUTE$2;
     // Try to read from cache first
     const cachedCandles = await READ_CANDLES_CACHE_FN$1(dto, sinceTimestamp, untilTimestamp, self);
     if (cachedCandles !== null) {
@@ -2208,7 +2208,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
@@ -2289,7 +2289,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getNextCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const now = Date.now();
         // Align when down to interval boundary
         const whenTimestamp = this.params.execution.context.when.getTime();
@@ -2457,7 +2457,7 @@ class ClientExchange {
         if (!step) {
             throw new Error(`ClientExchange getRawCandles: unknown interval=${interval}`);
         }
-        const stepMs = step * MS_PER_MINUTE$1;
+        const stepMs = step * MS_PER_MINUTE$2;
         const whenTimestamp = this.params.execution.context.when.getTime();
         const alignedWhen = ALIGN_TO_INTERVAL_FN$1(whenTimestamp, step);
         let sinceTimestamp;
@@ -2584,7 +2584,7 @@ class ClientExchange {
         });
         const to = new Date(this.params.execution.context.when.getTime());
         const from = new Date(to.getTime() -
-            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
+            GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$2);
         return await this.params.getOrderBook(symbol, depth, from, to, this.params.execution.context.backtest);
     }
 }
@@ -35507,7 +35507,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 = 60000;
+const MS_PER_MINUTE$1 = 60000;
 /**
  * Gets current timestamp from execution context if available.
  * Returns current Date() if no execution context exists (non-trading GUI).
@@ -35592,7 +35592,7 @@ const INTERVAL_MINUTES$1 = {
  * @returns Aligned timestamp rounded down to interval boundary
  */
 const ALIGN_TO_INTERVAL_FN = (timestamp, intervalMinutes) => {
-    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    const intervalMs = intervalMinutes * MS_PER_MINUTE$1;
     return Math.floor(timestamp / intervalMs) * intervalMs;
 };
 /**
@@ -35734,7 +35734,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             // Align when down to interval boundary
             const when = await GET_TIMESTAMP_FN();
             const whenTimestamp = when.getTime();
@@ -35911,7 +35911,7 @@ class ExchangeInstance {
                 depth,
             });
             const to = await GET_TIMESTAMP_FN();
-            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE);
+            const from = new Date(to.getTime() - GLOBAL_CONFIG.CC_ORDER_BOOK_TIME_OFFSET_MINUTES * MS_PER_MINUTE$1);
             const isBacktest = await GET_BACKTEST_FN();
             return await this._methods.getOrderBook(symbol, depth, from, to, isBacktest);
         };
@@ -35958,7 +35958,7 @@ class ExchangeInstance {
             if (!step) {
                 throw new Error(`ExchangeInstance getRawCandles: unknown interval=${interval}`);
             }
-            const stepMs = step * MS_PER_MINUTE;
+            const stepMs = step * MS_PER_MINUTE$1;
             const when = await GET_TIMESTAMP_FN();
             const nowTimestamp = when.getTime();
             const alignedNow = ALIGN_TO_INTERVAL_FN(nowTimestamp, step);
@@ -36231,6 +36231,7 @@ const CACHE_METHOD_NAME_FLUSH = "CacheUtils.flush";
 const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const MS_PER_MINUTE = 60000;
 const INTERVAL_MINUTES = {
     "1m": 1,
     "3m": 3,
@@ -36243,6 +36244,34 @@ const INTERVAL_MINUTES = {
     "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
+ *
+ * @param timestamp - Timestamp in milliseconds
+ * @param interval - Candle interval
+ * @returns Aligned timestamp rounded down to interval boundary
+ * @throws Error if interval is unknown
+ *
+ * @example
+ * ```typescript
+ * // Align to 15-minute boundary
+ * const aligned = align(new Date("2025-10-01T00:35:00Z").getTime(), "15m");
+ * // Returns timestamp for 2025-10-01T00:30:00Z
+ *
+ * // Align to 1-hour boundary
+ * const aligned = align(new Date("2025-10-01T01:47:00Z").getTime(), "1h");
+ * // Returns timestamp for 2025-10-01T01:00:00Z
+ * ```
+ */
+const align = (timestamp, interval) => {
+    const intervalMinutes = INTERVAL_MINUTES[interval];
+    if (!intervalMinutes) {
+        throw new Error(`align: unknown interval=${interval}`);
+    }
+    const intervalMs = intervalMinutes * MS_PER_MINUTE;
+    return Math.floor(timestamp / intervalMs) * intervalMs;
+};
 /**
  * Create a cache key string from strategy name, exchange name, and backtest mode.
  *
@@ -36337,9 +36366,9 @@ class CacheInstance {
             const currentWhen = bt.executionContextService.context.when;
             const cached = this._cacheMap.get(key);
             if (cached) {
-                const stepMs = step * 60 * 1000;
-                const elapsed = currentWhen.getTime() - cached.when.getTime();
-                if (elapsed >= 0 && elapsed < stepMs) {
+                const currentAligned = align(currentWhen.getTime(), this.interval);
+                const cachedAligned = align(cached.when.getTime(), this.interval);
+                if (currentAligned === cachedAligned) {
                     return cached;
                 }
             }

package/package.json

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