backtest-kit 1.1.4 → 1.1.6

package/README.md

@@ -14,14 +14,15 @@
 - 🔄 **Async Generators** - Memory-efficient streaming for backtest and live execution
 - 📊 **VWAP Pricing** - Volume-weighted average price from last 5 1m candles
 - 🎯 **Signal Lifecycle** - Type-safe state machine (idle → opened → active → closed)
-- 📉 **Accurate PNL** - Calculation with fees (0.1%) and slippage (0.1%)
+- 📈 **Accurate PNL** - Calculation with fees (0.1%) and slippage (0.1%)
 - 🧠 **Interval Throttling** - Prevents signal spam at strategy level
 - ⚡ **Memory Optimized** - Prototype methods + memoization + streaming
 - 🔌 **Flexible Architecture** - Plug your own exchanges and strategies
-- 📝 **Markdown Reports** - Auto-generated trading reports with statistics (win rate, avg PNL)
+- 📝 **Markdown Reports** - Auto-generated trading reports with statistics (win rate, avg PNL, Sharpe Ratio, Standard Deviation, Certainty Ratio, Expected Yearly Returns, Risk-Adjusted Returns)
 - 🛑 **Graceful Shutdown** - Live.background() waits for open positions to close before stopping
 - 💉 **Strategy Dependency Injection** - addStrategy() enables DI pattern for trading strategies
-- 🧪 **Comprehensive Test Coverage** - 30+ unit tests covering validation, PNL, callbacks, reports, and event system
+- 🔍 **Schema Reflection API** - listExchanges(), listStrategies(), listFrames() for runtime introspection
+- 🧪 **Comprehensive Test Coverage** - 45+ unit tests covering validation, PNL, callbacks, reports, and event system
 
 ## Installation
 
@@ -252,6 +253,75 @@ for await (const result of Live.run("BTCUSDT", {
 }
 ```
 
+### 7. Schema Reflection API (Optional)
+
+Retrieve registered schemas at runtime for debugging, documentation, or building dynamic UIs:
+
+```typescript
+import {
+  addExchange,
+  addStrategy,
+  addFrame,
+  listExchanges,
+  listStrategies,
+  listFrames
+} from "backtest-kit";
+
+// Register schemas with notes
+addExchange({
+  exchangeName: "binance",
+  note: "Binance cryptocurrency exchange with database backend",
+  getCandles: async (symbol, interval, since, limit) => [...],
+  formatPrice: async (symbol, price) => price.toFixed(2),
+  formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+});
+
+addStrategy({
+  strategyName: "sma-crossover",
+  note: "Simple moving average crossover strategy (50/200)",
+  interval: "5m",
+  getSignal: async (symbol) => ({...}),
+});
+
+addFrame({
+  frameName: "january-2024",
+  note: "Full month backtest for January 2024",
+  interval: "1m",
+  startDate: new Date("2024-01-01"),
+  endDate: new Date("2024-02-01"),
+});
+
+// List all registered schemas
+const exchanges = await listExchanges();
+console.log("Available exchanges:", exchanges.map(e => ({
+  name: e.exchangeName,
+  note: e.note
+})));
+// Output: [{ name: "binance", note: "Binance cryptocurrency exchange..." }]
+
+const strategies = await listStrategies();
+console.log("Available strategies:", strategies.map(s => ({
+  name: s.strategyName,
+  note: s.note,
+  interval: s.interval
+})));
+// Output: [{ name: "sma-crossover", note: "Simple moving average...", interval: "5m" }]
+
+const frames = await listFrames();
+console.log("Available frames:", frames.map(f => ({
+  name: f.frameName,
+  note: f.note,
+  period: `${f.startDate.toISOString()} - ${f.endDate.toISOString()}`
+})));
+// Output: [{ name: "january-2024", note: "Full month backtest...", period: "2024-01-01..." }]
+```
+
+**Use cases:**
+- Generate documentation automatically from registered schemas
+- Build admin dashboards showing available strategies and exchanges
+- Create CLI tools with auto-completion based on registered schemas
+- Validate configuration files against registered schemas
+
 ## Architecture Overview
 
 The framework follows **clean architecture** with:
@@ -794,41 +864,6 @@ pnl% = (priceOpenWithCosts - priceCloseWithCosts) / priceOpenWithCosts * 100
 6. **Live Trading Ready** - Full implementation with real-time progression
 7. **Error Recovery** - Stateless process with disk-based state
 
-## File Structure
-
-```
-src/
-├── client/                      # Pure business logic (no DI)
-│   ├── ClientStrategy.ts       # Signal lifecycle + validation + persistence
-│   ├── ClientExchange.ts       # VWAP calculation
-│   └── ClientFrame.ts          # Timeframe generation
-├── classes/
-│   └── Persist.ts              # Atomic file persistence
-├── function/                   # High-level API
-│   ├── add.ts                  # addStrategy, addExchange, addFrame
-│   ├── exchange.ts             # getCandles, getAveragePrice, getDate, getMode
-│   └── run.ts                  # DEPRECATED - use logic services instead
-├── interfaces/                 # TypeScript interfaces
-│   ├── Strategy.interface.ts
-│   ├── Exchange.interface.ts
-│   └── Frame.interface.ts
-├── lib/
-│   ├── core/                   # DI container
-│   ├── services/
-│   │   ├── base/              # LoggerService
-│   │   ├── context/           # ExecutionContext, MethodContext
-│   │   ├── connection/        # Client instance creators
-│   │   ├── global/            # Context wrappers
-│   │   ├── schema/            # Registry services
-│   │   └── logic/
-│   │       └── private/       # Async generator orchestration
-│   │           ├── BacktestLogicPrivateService.ts
-│   │           └── LiveLogicPrivateService.ts
-│   └── index.ts               # Public API
-└── helpers/
-    └── toProfitLossDto.ts     # PNL calculation
-```
-
 ## Advanced Examples
 
 ### Multi-Symbol Live Trading
@@ -856,6 +891,24 @@ await Promise.all(
 );
 ```
 
+### Backtest Progress Listener
+
+```typescript
+import { listenProgress, Backtest } from "backtest-kit";
+
+listenProgress((event) => {
+  console.log(`Progress: ${(event.progress * 100).toFixed(2)}%`);
+  console.log(`${event.processedFrames} / ${event.totalFrames} frames`);
+  console.log(`Strategy: ${event.strategyName}, Symbol: ${event.symbol}`);
+});
+
+Backtest.background("BTCUSDT", {
+  strategyName: "my-strategy",
+  exchangeName: "binance",
+  frameName: "1d-backtest"
+});
+```
+
 ### Early Termination
 
 **Using async generator with break:**