backtest-kit 3.6.0 → 3.7.1

package/README.md

@@ -204,72 +204,181 @@ Customize via `setConfig()`:
 
 Backtest Kit is **not a data-processing library** - it is a **time execution engine**. Think of the engine as an **async stream of time**, where your strategy is evaluated step by step.
 
+### 💰 How PNL Works
+
+These three functions work together to manage a position dynamically. To reduce position linearity, the framework treats every DCA entry as a fixed **$100 unit** regardless of price — this flattens the effective entry curve and makes PNL weighting independent of position size.
+
+**Public API:**
+- **`commitAverageBuy`** — adds a new DCA entry. For LONG, **only accepted when current price is below a new low**. Silently rejected otherwise. This prevents averaging up.
+- **`commitPartialProfit`** — closes X% of the position at a profit. Locks in gains while keeping exposure.
+- **`commitPartialLoss`** — closes X% of the position at a loss. Cuts exposure before the stop-loss is hit.
+
+<details>
+  <summary>
+    The Math
+  </summary>
+
+  **Scenario:** LONG entry @ 1000, 4 DCA attempts (1 rejected), 3 partials, closed at TP.
+  `totalInvested = $400` (4 × $100, rejected attempt not counted).
+
+  **Entries**
+  ```
+    entry#1 @ 1000  → 0.10000 coins
+      commitPartialProfit(30%) @ 1150          ← cnt=1
+    entry#2 @ 950   → 0.10526 coins
+    entry#3 @ 880   → 0.11364 coins
+      commitPartialLoss(20%)   @ 860           ← cnt=3
+    entry#4 @ 920   → 0.10870 coins
+      commitPartialProfit(40%) @ 1050          ← cnt=4
+    entry#5 @ 980   ✗ REJECTED (980 > ep3≈929.90)
+    totalInvested = $400
+  ```
+
+  **Partial#1 — commitPartialProfit @ 1150, 30%, cnt=1**
+  ```
+    effectivePrice = hm(1000) = 1000
+    costBasis = $100
+    partialDollarValue = 30% × 100 = $30  → weight = 30/400 = 0.075
+    pnl = (1150−1000)/1000 × 100 = +15.00%
+    costBasis → $70
+    coins sold: 0.03000 × 1150 = $34.50
+    remaining:  0.07000
+  ```
+
+  **DCA after Partial#1**
+  ```
+    entry#2 @ 950  (950 < ep1=1000 ✓ accepted)
+    entry#3 @ 880  (880 < ep1=1000 ✓ accepted)
+    coins: 0.07000 + 0.10526 + 0.11364 = 0.28890
+  ```
+
+  **Partial#2 — commitPartialLoss @ 860, 20%, cnt=3**
+  ```
+    costBasis = 70 + 100 + 100 = $270
+    ep2 = 270 / 0.28890 ≈ 934.93
+    partialDollarValue = 20% × 270 = $54  → weight = 54/400 = 0.135
+    pnl = (860−934.93)/934.93 × 100 ≈ −8.01%
+    costBasis → $216
+    coins sold: 0.05778 × 860 = $49.69
+    remaining:  0.23112
+  ```
+
+  **DCA after Partial#2**
+  ```
+    entry#4 @ 920  (920 < ep2=934.93 ✓ accepted)
+    coins: 0.23112 + 0.10870 = 0.33982
+  ```
+
+  **Partial#3 — commitPartialProfit @ 1050, 40%, cnt=4**
+  ```
+    costBasis = 216 + 100 = $316
+    ep3 = 316 / 0.33982 ≈ 929.90
+    partialDollarValue = 40% × 316 = $126.4  → weight = 126.4/400 = 0.316
+    pnl = (1050−929.90)/929.90 × 100 ≈ +12.92%
+    costBasis → $189.6
+    coins sold: 0.13593 × 1050 = $142.72
+    remaining:  0.20389
+  ```
+
+  **DCA after Partial#3 — rejected**
+  ```
+    entry#5 @ 980  (980 > ep3≈929.90 ✗ REJECTED)
+  ```
+
+  **Close at TP @ 1200**
+  ```
+    ep_final = ep3 ≈ 929.90  (no new entries)
+    coins: 0.20389
+
+    remainingDollarValue = 400 − 30 − 54 − 126.4 = $189.6
+    weight = 189.6/400 = 0.474
+    pnl = (1200−929.90)/929.90 × 100 ≈ +29.05%
+    coins sold: 0.20389 × 1200 = $244.67
+  ```
+
+  **Result (toProfitLossDto)**
+  ```
+    0.075 × (+15.00) = +1.125
+    0.135 × (−8.01)  = −1.081
+    0.316 × (+12.92) = +4.083
+    0.474 × (+29.05) = +13.770
+    ─────────────────────────────
+                    ≈ +17.90%
+
+    Cross-check (coins):
+    34.50 + 49.69 + 142.72 + 244.67 = $471.58
+    (471.58 − 400) / 400 × 100      = +17.90%  ✓
+  ```
+</details>
+
+**`priceOpen`** is the harmonic mean of all accepted DCA entries. After each partial close (`commitPartialProfit` or `commitPartialLoss`), the remaining cost basis is carried forward into the harmonic mean calculation for subsequent entries — so `priceOpen` shifts after every partial, which in turn changes whether the next `commitAverageBuy` call will be accepted.
+
 ### 🔍 How getCandles Works
 
 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 (openTime)
-    - `stepMs` = interval duration (e.g., 60000ms for "1m")
-    - Candle close time = `timestamp + stepMs`
-
-    **Alignment:** All timestamps are aligned down to interval boundary.
-    For example, for 15m interval: 00:17 → 00:15, 00:44 → 00:30
-
-    **Adapter contract:**
-    - First candle.timestamp must equal aligned `since`
-    - 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`
-      - **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)
-      - **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 starting from aligned when
-
-    - `getRawCandles(symbol, interval, limit?, sDate?, eDate?)` - Flexible parameter combinations:
-      - `(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:**
-    - Cache lookup calculates expected timestamps: `since + i * stepMs` for i = 0..limit-1
-    - Returns all candles if found, null if any missing (cache miss)
-    - Cache and runtime use identical timestamp calculation logic
-
-  </details>
+<details>
+  <summary>
+    The Math
+  </summary>
+
+  For a candle with:
+  - `timestamp` = candle open time (openTime)
+  - `stepMs` = interval duration (e.g., 60000ms for "1m")
+  - Candle close time = `timestamp + stepMs`
+
+  **Alignment:** All timestamps are aligned down to interval boundary.
+  For example, for 15m interval: 00:17 → 00:15, 00:44 → 00:30
+
+  **Adapter contract:**
+  - First candle.timestamp must equal aligned `since`
+  - 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`
+    - **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)
+    - **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 starting from aligned when
+
+  - `getRawCandles(symbol, interval, limit?, sDate?, eDate?)` - Flexible parameter combinations:
+    - `(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:**
+  - Cache lookup calculates expected timestamps: `since + i * stepMs` for i = 0..limit-1
+  - Returns all candles if found, null if any missing (cache miss)
+  - Cache and runtime use identical timestamp calculation logic
+
+</details>
 
 #### Candle Timestamp Convention:
 
@@ -328,6 +437,57 @@ Unlike candles, most exchanges (e.g. Binance `GET /api/v3/depth`) only expose th
 - `depth` defaults to `CC_ORDER_BOOK_MAX_DEPTH_LEVELS`
 - Adapter receives `(symbol, depth, from, to, backtest)` — may ignore `from`/`to` in live mode
 
+### 🔍 How getAggregatedTrades Works
+
+Aggregated trades fetching uses the same look-ahead bias protection as candles - `to` is always aligned down to the nearest minute boundary so future trades are never visible to the strategy.
+
+**Key principles:**
+- `to` is always aligned down to the 1-minute boundary — prevents look-ahead bias
+- Without `limit`: returns one full window (`CC_AGGREGATED_TRADES_MAX_MINUTES`)
+- With `limit`: paginates backwards until collected, then slices to most recent `limit`
+- Adapter receives `(symbol, from, to, backtest)` — may ignore `from`/`to` in live mode
+
+<details>
+  <summary>
+    The Math
+  </summary>
+
+  **Time range calculation:**
+  - `when` = current execution context time (from AsyncLocalStorage)
+  - `alignedTo` = `Math.floor(when / 60000) * 60000` (aligned down to 1-minute boundary)
+  - `windowMs` = `CC_AGGREGATED_TRADES_MAX_MINUTES * 60000 − 60000`
+  - `to` = `alignedTo`, `from` = `alignedTo − windowMs`
+
+  **Without `limit`:** fetches a single window and returns it as-is.
+
+  **With `limit`:** paginates backwards in `CC_AGGREGATED_TRADES_MAX_MINUTES` chunks until at least `limit` trades are collected, then slices to the most recent `limit` trades.
+
+  **Example with CC_AGGREGATED_TRADES_MAX_MINUTES = 60, limit = 200:**
+  ```
+  when       = 1704067920000   // 2024-01-01 00:12:00 UTC
+  alignedTo  = 1704067800000   // 2024-01-01 00:12:00 → aligned to 00:12:00
+  windowMs   = 59 * 60000      // 3540000ms = 59 minutes
+
+  Window 1:  from = 00:12:00 − 59m = 23:13:00
+              to   = 00:12:00
+  → got 120 trades — not enough
+
+  Window 2:  from = 23:13:00 − 59m = 22:14:00
+              to   = 23:13:00
+  → got 100 more → total 220 trades
+
+  result = last 200 of 220 (most recent)
+  ```
+
+  **Adapter contract:**
+  - `getAggregatedTrades(symbol, from, to, backtest)` is called on the exchange schema
+  - `from`/`to` are `Date` objects
+  - Schema implementation may use the time range (backtest) or ignore it (live trading)
+
+</details>
+
+**Compatible with:** [garch](https://www.npmjs.com/package/garch) for volatility modelling and [volume-anomaly](https://www.npmjs.com/package/volume-anomaly) for detecting abnormal trade volume — both accept the same `from`/`to` time range format that `getAggregatedTrades` produces.
+
 ### 🔬 Technical Details: Timestamp Alignment
 
 **Why align timestamps to interval boundaries?**