backtest-kit 1.1.4 → 1.1.5

package/README.md

@@ -21,6 +21,7 @@
 - 📝 **Markdown Reports** - Auto-generated trading reports with statistics (win rate, avg PNL)
 - 🛑 **Graceful Shutdown** - Live.background() waits for open positions to close before stopping
 - 💉 **Strategy Dependency Injection** - addStrategy() enables DI pattern for trading strategies
+- 🔍 **Schema Reflection API** - listExchanges(), listStrategies(), listFrames() for runtime introspection
 - 🧪 **Comprehensive Test Coverage** - 30+ 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:**

package/build/index.cjs

@@ -1129,6 +1129,11 @@ const errorEmitter = new functoolsKit.Subject();
  * Emits when background tasks complete (Live.background, Backtest.background).
  */
 const doneEmitter = new functoolsKit.Subject();
+/**
+ * Progress emitter for backtest execution progress.
+ * Emits progress updates during backtest execution.
+ */
+const progressEmitter = new functoolsKit.Subject();
 
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
@@ -2402,6 +2407,7 @@ class BacktestLogicPrivateService {
         this.strategyGlobalService = inject(TYPES.strategyGlobalService);
         this.exchangeGlobalService = inject(TYPES.exchangeGlobalService);
         this.frameGlobalService = inject(TYPES.frameGlobalService);
+        this.methodContextService = inject(TYPES.methodContextService);
     }
     /**
      * Runs backtest for a symbol, streaming closed signals as async generator.
@@ -2422,9 +2428,21 @@ class BacktestLogicPrivateService {
             symbol,
         });
         const timeframes = await this.frameGlobalService.getTimeframe(symbol);
+        const totalFrames = timeframes.length;
         let i = 0;
         while (i < timeframes.length) {
             const when = timeframes[i];
+            // Emit progress event if context is available
+            {
+                await progressEmitter.next({
+                    exchangeName: this.methodContextService.context.exchangeName,
+                    strategyName: this.methodContextService.context.strategyName,
+                    symbol,
+                    totalFrames,
+                    processedFrames: i,
+                    progress: totalFrames > 0 ? i / totalFrames : 0,
+                });
+            }
             const result = await this.strategyGlobalService.tick(symbol, when, true);
             // Если сигнал открыт, вызываем backtest
             if (result.action === "opened") {
@@ -2461,6 +2479,17 @@ class BacktestLogicPrivateService {
             }
             i++;
         }
+        // Emit final progress event (100%)
+        {
+            await progressEmitter.next({
+                exchangeName: this.methodContextService.context.exchangeName,
+                strategyName: this.methodContextService.context.strategyName,
+                symbol,
+                totalFrames,
+                processedFrames: totalFrames,
+                progress: 1.0,
+            });
+        }
     }
 }
 
@@ -3479,6 +3508,15 @@ class ExchangeValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered exchange schemas
+         * @public
+         * @returns Array of exchange schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("exchangeValidationService list");
+            return Array.from(this._exchangeMap.values());
+        };
     }
 }
 
@@ -3531,6 +3569,15 @@ class StrategyValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered strategy schemas
+         * @public
+         * @returns Array of strategy schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("strategyValidationService list");
+            return Array.from(this._strategyMap.values());
+        };
     }
 }
 
@@ -3583,6 +3630,15 @@ class FrameValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered frame schemas
+         * @public
+         * @returns Array of frame schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("frameValidationService list");
+            return Array.from(this._frameMap.values());
+        };
     }
 }
 
@@ -3828,6 +3884,102 @@ function addFrame(frameSchema) {
     backtest$1.frameSchemaService.register(frameSchema.frameName, frameSchema);
 }
 
+const LIST_EXCHANGES_METHOD_NAME = "list.listExchanges";
+const LIST_STRATEGIES_METHOD_NAME = "list.listStrategies";
+const LIST_FRAMES_METHOD_NAME = "list.listFrames";
+/**
+ * Returns a list of all registered exchange schemas.
+ *
+ * Retrieves all exchanges that have been registered via addExchange().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of exchange schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listExchanges, addExchange } from "backtest-kit";
+ *
+ * addExchange({
+ *   exchangeName: "binance",
+ *   note: "Binance cryptocurrency exchange",
+ *   getCandles: async (symbol, interval, since, limit) => [...],
+ *   formatPrice: async (symbol, price) => price.toFixed(2),
+ *   formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+ * });
+ *
+ * const exchanges = listExchanges();
+ * console.log(exchanges);
+ * // [{ exchangeName: "binance", note: "Binance cryptocurrency exchange", ... }]
+ * ```
+ */
+async function listExchanges() {
+    backtest$1.loggerService.log(LIST_EXCHANGES_METHOD_NAME);
+    return await backtest$1.exchangeValidationService.list();
+}
+/**
+ * Returns a list of all registered strategy schemas.
+ *
+ * Retrieves all strategies that have been registered via addStrategy().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of strategy schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listStrategies, addStrategy } from "backtest-kit";
+ *
+ * addStrategy({
+ *   strategyName: "my-strategy",
+ *   note: "Simple moving average crossover strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => ({
+ *     position: "long",
+ *     priceOpen: 50000,
+ *     priceTakeProfit: 51000,
+ *     priceStopLoss: 49000,
+ *     minuteEstimatedTime: 60,
+ *   }),
+ * });
+ *
+ * const strategies = listStrategies();
+ * console.log(strategies);
+ * // [{ strategyName: "my-strategy", note: "Simple moving average...", ... }]
+ * ```
+ */
+async function listStrategies() {
+    backtest$1.loggerService.log(LIST_STRATEGIES_METHOD_NAME);
+    return await backtest$1.strategyValidationService.list();
+}
+/**
+ * Returns a list of all registered frame schemas.
+ *
+ * Retrieves all frames that have been registered via addFrame().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of frame schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listFrames, addFrame } from "backtest-kit";
+ *
+ * addFrame({
+ *   frameName: "1d-backtest",
+ *   note: "One day backtest period for testing",
+ *   interval: "1m",
+ *   startDate: new Date("2024-01-01T00:00:00Z"),
+ *   endDate: new Date("2024-01-02T00:00:00Z"),
+ * });
+ *
+ * const frames = listFrames();
+ * console.log(frames);
+ * // [{ frameName: "1d-backtest", note: "One day backtest...", ... }]
+ * ```
+ */
+async function listFrames() {
+    backtest$1.loggerService.log(LIST_FRAMES_METHOD_NAME);
+    return await backtest$1.frameValidationService.list();
+}
+
 const LISTEN_SIGNAL_METHOD_NAME = "event.listenSignal";
 const LISTEN_SIGNAL_ONCE_METHOD_NAME = "event.listenSignalOnce";
 const LISTEN_SIGNAL_LIVE_METHOD_NAME = "event.listenSignalLive";
@@ -3837,6 +3989,7 @@ const LISTEN_SIGNAL_BACKTEST_ONCE_METHOD_NAME = "event.listenSignalBacktestOnce"
 const LISTEN_ERROR_METHOD_NAME = "event.listenError";
 const LISTEN_DONE_METHOD_NAME = "event.listenDone";
 const LISTEN_DONE_ONCE_METHOD_NAME = "event.listenDoneOnce";
+const LISTEN_PROGRESS_METHOD_NAME = "event.listenProgress";
 /**
  * Subscribes to all signal events with queued async processing.
  *
@@ -4092,6 +4245,40 @@ function listenDoneOnce(filterFn, fn) {
     backtest$1.loggerService.log(LISTEN_DONE_ONCE_METHOD_NAME);
     return doneEmitter.filter(filterFn).once(fn);
 }
+/**
+ * Subscribes to backtest progress events with queued async processing.
+ *
+ * Emits during Backtest.background() execution to track progress.
+ * Events are processed sequentially in order received, even if callback is async.
+ * Uses queued wrapper to prevent concurrent execution of the callback.
+ *
+ * @param fn - Callback function to handle progress events
+ * @returns Unsubscribe function to stop listening to events
+ *
+ * @example
+ * ```typescript
+ * import { listenProgress, Backtest } from "backtest-kit";
+ *
+ * const unsubscribe = 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"
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+function listenProgress(fn) {
+    backtest$1.loggerService.log(LISTEN_PROGRESS_METHOD_NAME);
+    return progressEmitter.subscribe(functoolsKit.queued(async (event) => fn(event)));
+}
 
 const GET_CANDLES_METHOD_NAME = "exchange.getCandles";
 const GET_AVERAGE_PRICE_METHOD_NAME = "exchange.getAveragePrice";
@@ -4556,9 +4743,13 @@ exports.getCandles = getCandles;
 exports.getDate = getDate;
 exports.getMode = getMode;
 exports.lib = backtest;
+exports.listExchanges = listExchanges;
+exports.listFrames = listFrames;
+exports.listStrategies = listStrategies;
 exports.listenDone = listenDone;
 exports.listenDoneOnce = listenDoneOnce;
 exports.listenError = listenError;
+exports.listenProgress = listenProgress;
 exports.listenSignal = listenSignal;
 exports.listenSignalBacktest = listenSignalBacktest;
 exports.listenSignalBacktestOnce = listenSignalBacktestOnce;

package/build/index.mjs

@@ -1127,6 +1127,11 @@ const errorEmitter = new Subject();
  * Emits when background tasks complete (Live.background, Backtest.background).
  */
 const doneEmitter = new Subject();
+/**
+ * Progress emitter for backtest execution progress.
+ * Emits progress updates during backtest execution.
+ */
+const progressEmitter = new Subject();
 
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
@@ -2400,6 +2405,7 @@ class BacktestLogicPrivateService {
         this.strategyGlobalService = inject(TYPES.strategyGlobalService);
         this.exchangeGlobalService = inject(TYPES.exchangeGlobalService);
         this.frameGlobalService = inject(TYPES.frameGlobalService);
+        this.methodContextService = inject(TYPES.methodContextService);
     }
     /**
      * Runs backtest for a symbol, streaming closed signals as async generator.
@@ -2420,9 +2426,21 @@ class BacktestLogicPrivateService {
             symbol,
         });
         const timeframes = await this.frameGlobalService.getTimeframe(symbol);
+        const totalFrames = timeframes.length;
         let i = 0;
         while (i < timeframes.length) {
             const when = timeframes[i];
+            // Emit progress event if context is available
+            {
+                await progressEmitter.next({
+                    exchangeName: this.methodContextService.context.exchangeName,
+                    strategyName: this.methodContextService.context.strategyName,
+                    symbol,
+                    totalFrames,
+                    processedFrames: i,
+                    progress: totalFrames > 0 ? i / totalFrames : 0,
+                });
+            }
             const result = await this.strategyGlobalService.tick(symbol, when, true);
             // Если сигнал открыт, вызываем backtest
             if (result.action === "opened") {
@@ -2459,6 +2477,17 @@ class BacktestLogicPrivateService {
             }
             i++;
         }
+        // Emit final progress event (100%)
+        {
+            await progressEmitter.next({
+                exchangeName: this.methodContextService.context.exchangeName,
+                strategyName: this.methodContextService.context.strategyName,
+                symbol,
+                totalFrames,
+                processedFrames: totalFrames,
+                progress: 1.0,
+            });
+        }
     }
 }
 
@@ -3477,6 +3506,15 @@ class ExchangeValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered exchange schemas
+         * @public
+         * @returns Array of exchange schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("exchangeValidationService list");
+            return Array.from(this._exchangeMap.values());
+        };
     }
 }
 
@@ -3529,6 +3567,15 @@ class StrategyValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered strategy schemas
+         * @public
+         * @returns Array of strategy schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("strategyValidationService list");
+            return Array.from(this._strategyMap.values());
+        };
     }
 }
 
@@ -3581,6 +3628,15 @@ class FrameValidationService {
             }
             return true;
         });
+        /**
+         * Returns a list of all registered frame schemas
+         * @public
+         * @returns Array of frame schemas with their configurations
+         */
+        this.list = async () => {
+            this.loggerService.log("frameValidationService list");
+            return Array.from(this._frameMap.values());
+        };
     }
 }
 
@@ -3826,6 +3882,102 @@ function addFrame(frameSchema) {
     backtest$1.frameSchemaService.register(frameSchema.frameName, frameSchema);
 }
 
+const LIST_EXCHANGES_METHOD_NAME = "list.listExchanges";
+const LIST_STRATEGIES_METHOD_NAME = "list.listStrategies";
+const LIST_FRAMES_METHOD_NAME = "list.listFrames";
+/**
+ * Returns a list of all registered exchange schemas.
+ *
+ * Retrieves all exchanges that have been registered via addExchange().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of exchange schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listExchanges, addExchange } from "backtest-kit";
+ *
+ * addExchange({
+ *   exchangeName: "binance",
+ *   note: "Binance cryptocurrency exchange",
+ *   getCandles: async (symbol, interval, since, limit) => [...],
+ *   formatPrice: async (symbol, price) => price.toFixed(2),
+ *   formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+ * });
+ *
+ * const exchanges = listExchanges();
+ * console.log(exchanges);
+ * // [{ exchangeName: "binance", note: "Binance cryptocurrency exchange", ... }]
+ * ```
+ */
+async function listExchanges() {
+    backtest$1.loggerService.log(LIST_EXCHANGES_METHOD_NAME);
+    return await backtest$1.exchangeValidationService.list();
+}
+/**
+ * Returns a list of all registered strategy schemas.
+ *
+ * Retrieves all strategies that have been registered via addStrategy().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of strategy schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listStrategies, addStrategy } from "backtest-kit";
+ *
+ * addStrategy({
+ *   strategyName: "my-strategy",
+ *   note: "Simple moving average crossover strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => ({
+ *     position: "long",
+ *     priceOpen: 50000,
+ *     priceTakeProfit: 51000,
+ *     priceStopLoss: 49000,
+ *     minuteEstimatedTime: 60,
+ *   }),
+ * });
+ *
+ * const strategies = listStrategies();
+ * console.log(strategies);
+ * // [{ strategyName: "my-strategy", note: "Simple moving average...", ... }]
+ * ```
+ */
+async function listStrategies() {
+    backtest$1.loggerService.log(LIST_STRATEGIES_METHOD_NAME);
+    return await backtest$1.strategyValidationService.list();
+}
+/**
+ * Returns a list of all registered frame schemas.
+ *
+ * Retrieves all frames that have been registered via addFrame().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of frame schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listFrames, addFrame } from "backtest-kit";
+ *
+ * addFrame({
+ *   frameName: "1d-backtest",
+ *   note: "One day backtest period for testing",
+ *   interval: "1m",
+ *   startDate: new Date("2024-01-01T00:00:00Z"),
+ *   endDate: new Date("2024-01-02T00:00:00Z"),
+ * });
+ *
+ * const frames = listFrames();
+ * console.log(frames);
+ * // [{ frameName: "1d-backtest", note: "One day backtest...", ... }]
+ * ```
+ */
+async function listFrames() {
+    backtest$1.loggerService.log(LIST_FRAMES_METHOD_NAME);
+    return await backtest$1.frameValidationService.list();
+}
+
 const LISTEN_SIGNAL_METHOD_NAME = "event.listenSignal";
 const LISTEN_SIGNAL_ONCE_METHOD_NAME = "event.listenSignalOnce";
 const LISTEN_SIGNAL_LIVE_METHOD_NAME = "event.listenSignalLive";
@@ -3835,6 +3987,7 @@ const LISTEN_SIGNAL_BACKTEST_ONCE_METHOD_NAME = "event.listenSignalBacktestOnce"
 const LISTEN_ERROR_METHOD_NAME = "event.listenError";
 const LISTEN_DONE_METHOD_NAME = "event.listenDone";
 const LISTEN_DONE_ONCE_METHOD_NAME = "event.listenDoneOnce";
+const LISTEN_PROGRESS_METHOD_NAME = "event.listenProgress";
 /**
  * Subscribes to all signal events with queued async processing.
  *
@@ -4090,6 +4243,40 @@ function listenDoneOnce(filterFn, fn) {
     backtest$1.loggerService.log(LISTEN_DONE_ONCE_METHOD_NAME);
     return doneEmitter.filter(filterFn).once(fn);
 }
+/**
+ * Subscribes to backtest progress events with queued async processing.
+ *
+ * Emits during Backtest.background() execution to track progress.
+ * Events are processed sequentially in order received, even if callback is async.
+ * Uses queued wrapper to prevent concurrent execution of the callback.
+ *
+ * @param fn - Callback function to handle progress events
+ * @returns Unsubscribe function to stop listening to events
+ *
+ * @example
+ * ```typescript
+ * import { listenProgress, Backtest } from "backtest-kit";
+ *
+ * const unsubscribe = 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"
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+function listenProgress(fn) {
+    backtest$1.loggerService.log(LISTEN_PROGRESS_METHOD_NAME);
+    return progressEmitter.subscribe(queued(async (event) => fn(event)));
+}
 
 const GET_CANDLES_METHOD_NAME = "exchange.getCandles";
 const GET_AVERAGE_PRICE_METHOD_NAME = "exchange.getAveragePrice";
@@ -4538,4 +4725,4 @@ class LiveUtils {
  */
 const Live = new LiveUtils();
 
-export { Backtest, ExecutionContextService, Live, MethodContextService, PersistBase, PersistSignalAdaper, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listenDone, listenDoneOnce, listenError, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };
+export { Backtest, ExecutionContextService, Live, MethodContextService, PersistBase, PersistSignalAdaper, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listStrategies, listenDone, listenDoneOnce, listenError, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -140,6 +140,8 @@ interface IExchangeCallbacks {
 interface IExchangeSchema {
     /** Unique exchange identifier for registration */
     exchangeName: ExchangeName;
+    /** Optional developer note for documentation */
+    note?: string;
     /**
      * Fetch candles from data source (API or database).
      *
@@ -278,6 +280,8 @@ interface IFrameCallbacks {
 interface IFrameSchema {
     /** Unique identifier for this frame */
     frameName: FrameName;
+    /** Optional developer note for documentation */
+    note?: string;
     /** Interval for timestamp generation */
     interval: FrameInterval;
     /** Start of backtest period (inclusive) */
@@ -413,6 +417,8 @@ interface IStrategyCallbacks {
 interface IStrategySchema {
     /** Unique strategy identifier for registration */
     strategyName: StrategyName;
+    /** Optional developer note for documentation */
+    note?: string;
     /** Minimum interval between getSignal calls (throttling) */
     interval: SignalInterval;
     /** Signal generation function (returns null if no signal, validated DTO if signal) */
@@ -666,6 +672,90 @@ declare function addExchange(exchangeSchema: IExchangeSchema): void;
  */
 declare function addFrame(frameSchema: IFrameSchema): void;
 
+/**
+ * Returns a list of all registered exchange schemas.
+ *
+ * Retrieves all exchanges that have been registered via addExchange().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of exchange schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listExchanges, addExchange } from "backtest-kit";
+ *
+ * addExchange({
+ *   exchangeName: "binance",
+ *   note: "Binance cryptocurrency exchange",
+ *   getCandles: async (symbol, interval, since, limit) => [...],
+ *   formatPrice: async (symbol, price) => price.toFixed(2),
+ *   formatQuantity: async (symbol, quantity) => quantity.toFixed(8),
+ * });
+ *
+ * const exchanges = listExchanges();
+ * console.log(exchanges);
+ * // [{ exchangeName: "binance", note: "Binance cryptocurrency exchange", ... }]
+ * ```
+ */
+declare function listExchanges(): Promise<IExchangeSchema[]>;
+/**
+ * Returns a list of all registered strategy schemas.
+ *
+ * Retrieves all strategies that have been registered via addStrategy().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of strategy schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listStrategies, addStrategy } from "backtest-kit";
+ *
+ * addStrategy({
+ *   strategyName: "my-strategy",
+ *   note: "Simple moving average crossover strategy",
+ *   interval: "5m",
+ *   getSignal: async (symbol) => ({
+ *     position: "long",
+ *     priceOpen: 50000,
+ *     priceTakeProfit: 51000,
+ *     priceStopLoss: 49000,
+ *     minuteEstimatedTime: 60,
+ *   }),
+ * });
+ *
+ * const strategies = listStrategies();
+ * console.log(strategies);
+ * // [{ strategyName: "my-strategy", note: "Simple moving average...", ... }]
+ * ```
+ */
+declare function listStrategies(): Promise<IStrategySchema[]>;
+/**
+ * Returns a list of all registered frame schemas.
+ *
+ * Retrieves all frames that have been registered via addFrame().
+ * Useful for debugging, documentation, or building dynamic UIs.
+ *
+ * @returns Array of frame schemas with their configurations
+ *
+ * @example
+ * ```typescript
+ * import { listFrames, addFrame } from "backtest-kit";
+ *
+ * addFrame({
+ *   frameName: "1d-backtest",
+ *   note: "One day backtest period for testing",
+ *   interval: "1m",
+ *   startDate: new Date("2024-01-01T00:00:00Z"),
+ *   endDate: new Date("2024-01-02T00:00:00Z"),
+ * });
+ *
+ * const frames = listFrames();
+ * console.log(frames);
+ * // [{ frameName: "1d-backtest", note: "One day backtest...", ... }]
+ * ```
+ */
+declare function listFrames(): Promise<IFrameSchema[]>;
+
 /**
  * Contract for background execution completion events.
  *
@@ -696,6 +786,37 @@ interface DoneContract {
     symbol: string;
 }
 
+/**
+ * Contract for backtest progress events.
+ *
+ * Emitted during Backtest.background() execution to track progress.
+ * Contains information about total frames, processed frames, and completion percentage.
+ *
+ * @example
+ * ```typescript
+ * import { listenProgress } from "backtest-kit";
+ *
+ * listenProgress((event) => {
+ *   console.log(`Progress: ${(event.progress * 100).toFixed(2)}%`);
+ *   console.log(`Processed: ${event.processedFrames} / ${event.totalFrames}`);
+ * });
+ * ```
+ */
+interface ProgressContract {
+    /** exchangeName - Name of the exchange used in execution */
+    exchangeName: string;
+    /** strategyName - Name of the strategy being executed */
+    strategyName: string;
+    /** symbol - Trading symbol (e.g., "BTCUSDT") */
+    symbol: string;
+    /** totalFrames - Total number of frames to process */
+    totalFrames: number;
+    /** processedFrames - Number of frames processed so far */
+    processedFrames: number;
+    /** progress - Completion percentage from 0.0 to 1.0 */
+    progress: number;
+}
+
 /**
  * Subscribes to all signal events with queued async processing.
  *
@@ -924,6 +1045,37 @@ declare function listenDone(fn: (event: DoneContract) => void): () => void;
  * ```
  */
 declare function listenDoneOnce(filterFn: (event: DoneContract) => boolean, fn: (event: DoneContract) => void): () => void;
+/**
+ * Subscribes to backtest progress events with queued async processing.
+ *
+ * Emits during Backtest.background() execution to track progress.
+ * Events are processed sequentially in order received, even if callback is async.
+ * Uses queued wrapper to prevent concurrent execution of the callback.
+ *
+ * @param fn - Callback function to handle progress events
+ * @returns Unsubscribe function to stop listening to events
+ *
+ * @example
+ * ```typescript
+ * import { listenProgress, Backtest } from "backtest-kit";
+ *
+ * const unsubscribe = 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"
+ * });
+ *
+ * // Later: stop listening
+ * unsubscribe();
+ * ```
+ */
+declare function listenProgress(fn: (event: ProgressContract) => void): () => void;
 
 /**
  * Fetches historical candle data from the registered exchange.
@@ -2154,6 +2306,7 @@ declare class BacktestLogicPrivateService {
     private readonly strategyGlobalService;
     private readonly exchangeGlobalService;
     private readonly frameGlobalService;
+    private readonly methodContextService;
     /**
      * Runs backtest for a symbol, streaming closed signals as async generator.
      *
@@ -2642,6 +2795,12 @@ declare class ExchangeValidationService {
      * Memoized function to cache validation results
      */
     validate: (exchangeName: ExchangeName, source: string) => void;
+    /**
+     * Returns a list of all registered exchange schemas
+     * @public
+     * @returns Array of exchange schemas with their configurations
+     */
+    list: () => Promise<IExchangeSchema[]>;
 }
 
 /**
@@ -2673,6 +2832,12 @@ declare class StrategyValidationService {
      * Memoized function to cache validation results
      */
     validate: (strategyName: StrategyName, source: string) => void;
+    /**
+     * Returns a list of all registered strategy schemas
+     * @public
+     * @returns Array of strategy schemas with their configurations
+     */
+    list: () => Promise<IStrategySchema[]>;
 }
 
 /**
@@ -2704,6 +2869,12 @@ declare class FrameValidationService {
      * Memoized function to cache validation results
      */
     validate: (frameName: FrameName, source: string) => void;
+    /**
+     * Returns a list of all registered frame schemas
+     * @public
+     * @returns Array of frame schemas with their configurations
+     */
+    list: () => Promise<IFrameSchema[]>;
 }
 
 declare const backtest: {
@@ -2736,4 +2907,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type CandleInterval, type EntityId, ExecutionContextService, type FrameInterval, type ICandleData, type IExchangeSchema, type IFrameSchema, type IPersistBase, type ISignalData, type ISignalDto, type ISignalRow, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, Live, MethodContextService, PersistBase, PersistSignalAdaper, type SignalInterval, type TPersistBase, type TPersistBaseCtor, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listenDone, listenDoneOnce, listenError, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };
+export { Backtest, type CandleInterval, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type ICandleData, type IExchangeSchema, type IFrameSchema, type IPersistBase, type ISignalData, type ISignalDto, type ISignalRow, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, Live, MethodContextService, PersistBase, PersistSignalAdaper, type ProgressContract, type SignalInterval, type TPersistBase, type TPersistBaseCtor, addExchange, addFrame, addStrategy, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, backtest as lib, listExchanges, listFrames, listStrategies, listenDone, listenDoneOnce, listenError, listenProgress, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, setLogger };