backtest-kit 2.2.26 → 2.3.1

package/README.md

@@ -205,14 +205,97 @@ Backtest Kit is **not a data-processing library** - it is a **time execution eng
 
 ### 🔍 How getCandles Works
 
-backtest-kit uses Node.js `AsyncLocalStorage` to automatically provide 
-temporal time context to your strategies. Exclusive (aka `[startTime, endTime)`) candle limit being used
+backtest-kit uses Node.js `AsyncLocalStorage` to automatically provide
+temporal time context to your strategies.
+
+  <details>
+    <summary>
+      The Math
+    </summary>
+      
+    For a candle with:
+    - `timestamp` = candle open time
+    - `stepMs` = interval duration (e.g., 60000ms for "1m")
+    - Candle close time = `timestamp + stepMs`
+
+    The candle is included if: `timestamp + stepMs < upperBoundary`
+
+    - `getCandles(symbol, interval, limit)` - Returns data in range `(when - limit*interval, when)`
+      - Fetches historical candles backwards from execution context time
+      - Only fully closed candles are included (candle must close before `when`)
+      - Lower bound: `candle.timestamp > sinceTimestamp` (exclusive)
+      - Upper bound: `candle.timestamp + stepMs < when` (exclusive)
+      - Example: `getCandles("BTCUSDT", "1m", 100)` returns 100 candles ending before current time
+
+    - `getNextCandles(symbol, interval, limit)` - Returns data in range `(when, when + limit*interval)`
+      - Fetches future candles forwards from execution context time (backtest only)
+      - Only fully closed candles are included
+      - Lower bound: `candle.timestamp > when` (exclusive)
+      - Upper bound: `candle.timestamp + stepMs < endTime` (exclusive)
+      - Throws error in live mode to prevent look-ahead bias
+      - Example: `getNextCandles("BTCUSDT", "1m", 10)` returns next 10 candles after current time
+
+    - `getRawCandles(symbol, interval, limit?, sDate?, eDate?)` - Flexible parameter combinations:
+      - `(limit)` - Returns data in range `(now - limit*interval, now)`
+      - `(limit, sDate)` - Returns data in range `(sDate, sDate + limit*interval)`
+      - `(limit, undefined, eDate)` - Returns data in range `(eDate - limit*interval, eDate)`
+      - `(undefined, sDate, eDate)` - Returns data in range `(sDate, eDate)`, limit calculated from range
+      - `(limit, sDate, eDate)` - Returns data in range `(sDate, eDate)`, limit used only for fetch size
+      - All combinations use: `candle.timestamp > sDate && candle.timestamp + stepMs < eDate`
+      - All combinations respect exclusive boundaries and look-ahead bias protection
+
+    **Persistent Cache:**
+    - Candle cache uses identical boundary semantics: `timestamp > sinceTimestamp && timestamp + stepMs < untilTimestamp`
+    - Cache and runtime filters are synchronized to prevent inconsistencies
+    - Cache returns only candles that match the requested time range exactly
+
+  </details>
+
+#### Boundary Semantics:
+
+All methods use **strict exclusive boundaries** - candles at exact boundary times are excluded. This prevents accidental inclusion of boundary conditions in backtest logic and ensures consistent behavior across cache and runtime.
+
+According to this `timestamp` of a candle in backtest-kit is exactly the `openTime`, not ~~`closeTime`~~
+
+**Key principle:** A candle is included only if it **fully closed** before the upper boundary.
+
+### 🔬 Technical Details: The `+ stepMs` Check
+
+**Why check `candle.timestamp + stepMs < upperBoundary` instead of just `candle.timestamp < upperBoundary`?**
+
+Because a candle's **timestamp is when it opens**, not when it closes:
+
+```typescript
+// 1-minute candle example:
+timestamp = 1000      // Candle opens at 1000ms
+stepMs = 60000        // Duration: 60 seconds
+// Candle closes at: 1000 + 60000 = 61000ms
+
+// Without + stepMs (WRONG):
+candle.timestamp < 61000
+1000 < 61000  // TRUE - includes candle that hasn't finished yet!
+
+// With + stepMs (CORRECT):
+candle.timestamp + stepMs < 61000
+1000 + 60000 < 61000
+61000 < 61000  // FALSE - correctly excludes unclosed candle
+```
+
+**This check is applied consistently across:**
+- ✅ `getCandles()` filtering
+- ✅ `getNextCandles()` filtering
+- ✅ `getRawCandles()` filtering (all parameter combinations)
+- ✅ Cache read operations
+- ✅ Cache write operations
+
+**Result:** Zero chance of including incomplete or "forming" candles in your strategy logic.
 
 ### 💭 What this means:
 - `getCandles()` always returns data UP TO the current backtest timestamp using `async_hooks`
 - Multi-timeframe data is automatically synchronized
-- **Impossible to introduce look-ahead bias**
+- **Impossible to introduce look-ahead bias** - all time boundaries are enforced
 - Same code works in both backtest and live modes
+- Boundary semantics prevent edge cases in signal generation
 
 
 ## 🧠 Two Ways to Run the Engine