backtest-kit 2.3.2 → 3.0.0

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
@@ -372,6 +391,30 @@ Perfect for traders who already have working TradingView strategies. Instead of
 npm install @backtest-kit/pinets pinets backtest-kit
 ```
 
+
+### @backtest-kit/ui
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/ui)** 📊
+
+The **@backtest-kit/ui** package is a full-stack UI framework for visualizing cryptocurrency trading signals, backtests, and real-time market data. Combines a Node.js backend server with a React dashboard - all in one package.
+
+#### Key Features
+- 📈 **Interactive Charts**: Candlestick visualization with Lightweight Charts (1m, 15m, 1h timeframes)
+- 🎯 **Signal Tracking**: View opened, closed, scheduled, and cancelled signals with full details
+- 📊 **Risk Analysis**: Monitor risk rejections and position management
+- 🔔 **Notifications**: Real-time notification system for all trading events
+- 💹 **Trailing & Breakeven**: Visualize trailing stop/take and breakeven events
+- 🎨 **Material Design**: Beautiful UI with MUI 5 and Mantine components
+
+#### Use Case
+Perfect for monitoring your trading bots in production. Instead of building custom dashboards, `@backtest-kit/ui` provides a complete visualization layer out of the box. Each signal view includes detailed information forms, multi-timeframe candlestick charts, and JSON export for all data.
+
+#### Get Started
+```bash
+npm install @backtest-kit/ui backtest-kit ccxt
+```
+
+
 ### @backtest-kit/ollama
 
 > **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/ollama)** 🤖
@@ -416,6 +459,31 @@ Perfect for injecting comprehensive market context into your LLM-powered strateg
 npm install @backtest-kit/signals backtest-kit
 ```
 
+
+### @backtest-kit/sidekick
+
+> **[Explore on NPM](https://www.npmjs.com/package/@backtest-kit/sidekick)** 🧿
+
+The **@backtest-kit/sidekick** package is the easiest way to create a new Backtest Kit trading bot project. Like create-react-app, but for algorithmic trading.
+
+#### Key Features
+- 🚀 **Zero Config**: Get started with one command - no setup required
+- 📦 **Complete Template**: Includes backtest strategy, risk management, and LLM integration
+- 🤖 **AI-Powered**: Pre-configured with DeepSeek, Claude, and GPT-5 fallback chain
+- 📊 **Technical Analysis**: Built-in 50+ indicators via @backtest-kit/signals
+- 🔑 **Environment Setup**: Auto-generated .env with all API key placeholders
+- 📝 **Best Practices**: Production-ready code structure with examples
+
+#### Use Case
+The fastest way to bootstrap a new trading bot project. Instead of manually setting up dependencies, configurations, and boilerplate code, simply run one command and get a working project with LLM-powered strategy, multi-timeframe technical analysis, and risk management validation.
+
+#### Get Started
+```bash
+npx -y @backtest-kit/sidekick my-trading-bot
+cd my-trading-bot
+npm start
+```
+
 ## 🤖 Are you a robot?
 
 **For language models**: Read extended description in [./LLMs.md](./LLMs.md)