backtest-kit 2.3.2 → 2.3.3

package/README.md

@@ -9,6 +9,7 @@
 [![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)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
+[![Build](https://github.com/tripolskypetr/backtest-kit/actions/workflows/webpack.yml/badge.svg)](https://github.com/tripolskypetr/backtest-kit/actions/workflows/webpack.yml)
 
 Build reliable trading systems: backtest on historical data, deploy live bots with recovery, and optimize strategies using LLMs like Ollama.
 
@@ -226,25 +227,41 @@ temporal time context to your strategies.
     - Adapter must return exactly `limit` candles
     - Sequential timestamps: `since + i * stepMs` for i = 0..limit-1
 
+    **How `since` is calculated from `when`:**
+    - `when` = current execution context time (from AsyncLocalStorage)
+    - `alignedWhen` = `Math.floor(when / stepMs) * stepMs` (aligned down to interval boundary)
+    - `since` = `alignedWhen - limit * stepMs` (go back `limit` candles from aligned when)
+
+    **Boundary semantics (inclusive/exclusive):**
+    - `since` is always **inclusive** — first candle has `timestamp === since`
+    - Exactly `limit` candles are returned
+    - Last candle has `timestamp === since + (limit - 1) * stepMs` — **inclusive**
+    - For `getCandles`: `alignedWhen` is **exclusive** — candle at that timestamp is NOT included (it's a pending/incomplete candle)
+    - For `getRawCandles`: `eDate` is **exclusive** — candle at that timestamp is NOT included (it's a pending/incomplete candle)
+    - For `getNextCandles`: `alignedWhen` is **inclusive** — first candle starts at `alignedWhen` (it's the current candle for backtest, already closed in historical data)
+
     - `getCandles(symbol, interval, limit)` - Returns exactly `limit` candles
       - Aligns `when` down to interval boundary
       - Calculates `since = alignedWhen - limit * stepMs`
-      - First candle.timestamp === since
-      - Example: `getCandles("BTCUSDT", "1m", 100)` returns 100 candles ending at aligned when
+      - **since — inclusive**, first candle.timestamp === since
+      - **alignedWhen — exclusive**, candle at alignedWhen is NOT returned
+      - Range: `[since, alignedWhen)` — half-open interval
+      - Example: `getCandles("BTCUSDT", "1m", 100)` returns 100 candles ending before aligned when
 
     - `getNextCandles(symbol, interval, limit)` - Returns exactly `limit` candles (backtest only)
       - Aligns `when` down to interval boundary
       - `since = alignedWhen` (starts from aligned when, going forward)
-      - First candle.timestamp === since
+      - **since — inclusive**, first candle.timestamp === since
+      - Range: `[alignedWhen, alignedWhen + limit * stepMs)` — half-open interval
       - Throws error in live mode to prevent look-ahead bias
-      - Example: `getNextCandles("BTCUSDT", "1m", 10)` returns next 10 candles after aligned when
+      - Example: `getNextCandles("BTCUSDT", "1m", 10)` returns next 10 candles starting from aligned when
 
     - `getRawCandles(symbol, interval, limit?, sDate?, eDate?)` - Flexible parameter combinations:
-      - `(limit)` - since = alignedWhen - limit * stepMs
-      - `(limit, sDate)` - since = align(sDate), returns `limit` candles forward
-      - `(limit, undefined, eDate)` - since = align(eDate) - limit * stepMs
-      - `(undefined, sDate, eDate)` - since = align(sDate), limit calculated from range
-      - `(limit, sDate, eDate)` - since = align(sDate), returns `limit` candles
+      - `(limit)` - since = alignedWhen - limit * stepMs, range `[since, alignedWhen)`
+      - `(limit, sDate)` - since = align(sDate), returns `limit` candles forward, range `[since, since + limit * stepMs)`
+      - `(limit, undefined, eDate)` - since = align(eDate) - limit * stepMs, **eDate — exclusive**, range `[since, eDate)`
+      - `(undefined, sDate, eDate)` - since = align(sDate), limit calculated from range, **sDate — inclusive, eDate — exclusive**, range `[sDate, eDate)`
+      - `(limit, sDate, eDate)` - since = align(sDate), returns `limit` candles, **sDate — inclusive**
       - All combinations respect look-ahead bias protection (eDate/endTime <= when)
 
     **Persistent Cache:**
@@ -293,6 +310,8 @@ since = alignedWhen - 4 * stepMs
 // [3] timestamp = 1704066300000 (23:45)
 ```
 
+**Pending candle exclusion:** The candle at `00:00:00` (alignedWhen) is NOT included in the result. At `when=00:12:00`, this candle covers the period `[00:00, 00:15)` and is still open (pending). Pending candles have incomplete OHLCV data that would distort technical indicators. Only fully closed candles are returned.
+
 **Validation is applied consistently across:**
 - ✅ `getCandles()` - validates first timestamp and count
 - ✅ `getNextCandles()` - validates first timestamp and count