backtest-kit 1.1.3 → 1.1.5

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) */
@@ -536,6 +542,27 @@ interface IStrategy {
      * @returns Promise resolving to closed result (always completes signal)
      */
     backtest: (candles: ICandleData[]) => Promise<IStrategyBacktestResult>;
+    /**
+     * Stops the strategy from generating new signals.
+     *
+     * Sets internal flag to prevent getSignal from being called on subsequent ticks.
+     * Does NOT force-close active pending signals - they continue monitoring until natural closure (TP/SL/time_expired).
+     *
+     * Use case: Graceful shutdown in live trading mode without abandoning open positions.
+     *
+     * @param symbol - Trading pair symbol (e.g., "BTCUSDT")
+     * @returns Promise that resolves immediately when stop flag is set
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown in Live.background() cancellation
+     * const cancel = await Live.background("BTCUSDT", { ... });
+     *
+     * // Later: stop new signals, let existing ones close naturally
+     * await cancel();
+     * ```
+     */
+    stop: (symbol: string) => Promise<void>;
 }
 /**
  * Unique strategy identifier.
@@ -645,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.
  *
@@ -675,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.
  *
@@ -903,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.
@@ -1737,6 +1910,25 @@ declare class StrategyConnectionService implements IStrategy {
      * @returns Promise resolving to backtest result (signal or idle)
      */
     backtest: (candles: ICandleData[]) => Promise<IStrategyBacktestResult>;
+    /**
+     * Stops the specified strategy from generating new signals.
+     *
+     * Delegates to ClientStrategy.stop() which sets internal flag to prevent
+     * getSignal from being called on subsequent ticks.
+     *
+     * @param strategyName - Name of strategy to stop
+     * @returns Promise that resolves when stop flag is set
+     */
+    stop: (strategyName: StrategyName) => Promise<void>;
+    /**
+     * Clears the memoized ClientStrategy instance from cache.
+     *
+     * Forces re-initialization of strategy on next getStrategy call.
+     * Useful for resetting strategy state or releasing resources.
+     *
+     * @param strategyName - Name of strategy to clear from cache
+     */
+    clear: (strategyName: StrategyName) => Promise<void>;
 }
 
 /**
@@ -1912,6 +2104,25 @@ declare class StrategyGlobalService {
      * @returns Closed signal result with PNL
      */
     backtest: (symbol: string, candles: ICandleData[], when: Date, backtest: boolean) => Promise<IStrategyBacktestResult>;
+    /**
+     * Stops the strategy from generating new signals.
+     *
+     * Delegates to StrategyConnectionService.stop() to set internal flag.
+     * Does not require execution context.
+     *
+     * @param strategyName - Name of strategy to stop
+     * @returns Promise that resolves when stop flag is set
+     */
+    stop: (strategyName: StrategyName) => Promise<void>;
+    /**
+     * Clears the memoized ClientStrategy instance from cache.
+     *
+     * Delegates to StrategyConnectionService.clear() to remove strategy from cache.
+     * Forces re-initialization of strategy on next operation.
+     *
+     * @param strategyName - Name of strategy to clear from cache
+     */
+    clear: (strategyName: StrategyName) => Promise<void>;
 }
 
 /**
@@ -2066,7 +2277,7 @@ declare class FrameSchemaService {
      * @param value - Partial schema updates
      * @throws Error if frame name doesn't exist
      */
-    override(key: FrameName, value: Partial<IFrameSchema>): void;
+    override(key: FrameName, value: Partial<IFrameSchema>): IFrameSchema;
     /**
      * Retrieves a frame schema by name.
      *
@@ -2095,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.
      *
@@ -2583,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[]>;
 }
 
 /**
@@ -2614,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[]>;
 }
 
 /**
@@ -2645,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: {
@@ -2677,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 };