backtest-kit 2.2.10 → 2.2.12

package/types.d.ts

@@ -1130,6 +1130,18 @@ interface IPublicSignalRow extends ISignalRow {
      */
     totalExecuted: number;
 }
+/**
+ * Storage signal row with creation timestamp taken from IStrategyTickResult.
+ * Used for persisting signals with accurate creation time.
+ */
+interface IStorageSignalRow extends IPublicSignalRow {
+    /** Creation timestamp taken from IStrategyTickResult */
+    updatedAt: number;
+    /** Storage adapter rewrite priority. Equal to Date.now for live and backtest both */
+    priority: number;
+    /** Current status of the signal */
+    status: "opened" | "scheduled" | "closed" | "cancelled";
+}
 /**
  * Risk signal row for internal risk management.
  * Extends ISignalDto to include priceOpen, originalPriceStopLoss and originalPriceTakeProfit.
@@ -7517,7 +7529,7 @@ declare class PersistBase<EntityName extends string = string> implements IPersis
  */
 declare class PersistSignalUtils {
     private PersistSignalFactory;
-    private getSignalStorage;
+    private getStorage;
     /**
      * Registers a custom persistence adapter.
      *
@@ -8047,6 +8059,71 @@ declare class PersistCandleUtils {
  * ```
  */
 declare const PersistCandleAdapter: PersistCandleUtils;
+/**
+ * Type for persisted signal storage data.
+ * Each signal is stored as a separate file keyed by its id.
+ */
+type StorageData = IStorageSignalRow[];
+/**
+ * Utility class for managing signal storage persistence.
+ *
+ * Features:
+ * - Memoized storage instances
+ * - Custom adapter support
+ * - Atomic read/write operations for StorageData
+ * - Each signal stored as separate file keyed by id
+ * - Crash-safe signal state management
+ *
+ * Used by SignalLiveUtils for live mode persistence of signals.
+ */
+declare class PersistStorageUtils {
+    private PersistStorageFactory;
+    private getStorageStorage;
+    /**
+     * Registers a custom persistence adapter.
+     *
+     * @param Ctor - Custom PersistBase constructor
+     */
+    usePersistStorageAdapter(Ctor: TPersistBaseCtor<string, IStorageSignalRow>): void;
+    /**
+     * Reads persisted signals data.
+     *
+     * Called by StorageLiveUtils/StorageBacktestUtils.waitForInit() to restore state.
+     * Uses keys() from PersistBase to iterate over all stored signals.
+     * Returns empty array if no signals exist.
+     *
+     * @param backtest - If true, reads from backtest storage; otherwise from live storage
+     * @returns Promise resolving to array of signal entries
+     */
+    readStorageData: (backtest: boolean) => Promise<StorageData>;
+    /**
+     * Writes signal data to disk with atomic file writes.
+     *
+     * Called by StorageLiveUtils/StorageBacktestUtils after signal changes to persist state.
+     * Uses signal.id as the storage key for individual file storage.
+     * Uses atomic writes to prevent corruption on crashes.
+     *
+     * @param signalData - Signal entries to persist
+     * @param backtest - If true, writes to backtest storage; otherwise to live storage
+     * @returns Promise that resolves when write is complete
+     */
+    writeStorageData: (signalData: StorageData, backtest: boolean) => Promise<void>;
+    /**
+     * Switches to the default JSON persist adapter.
+     * All future persistence writes will use JSON storage.
+     */
+    useJson(): void;
+    /**
+     * Switches to a dummy persist adapter that discards all writes.
+     * All future persistence writes will be no-ops.
+     */
+    useDummy(): void;
+}
+/**
+ * Global singleton instance of PersistStorageUtils.
+ * Used by SignalLiveUtils for signal storage persistence.
+ */
+declare const PersistStorageAdapter: PersistStorageUtils;
 
 declare const WAIT_FOR_INIT_SYMBOL$1: unique symbol;
 declare const WRITE_SAFE_SYMBOL$1: unique symbol;
@@ -12367,6 +12444,220 @@ declare class RiskUtils {
  */
 declare const Risk: RiskUtils;
 
+type StorageId = IStorageSignalRow["id"];
+/**
+ * Utility class for managing backtest signal history.
+ *
+ * Stores trading signal history for admin dashboard display during backtesting
+ * with automatic initialization, deduplication, and storage limits.
+ *
+ * @example
+ * ```typescript
+ * import { StorageBacktestUtils } from "./classes/Storage";
+ *
+ * const storage = new StorageBacktestUtils();
+ *
+ * // Handle signal events
+ * await storage.handleOpened(tickResult);
+ * await storage.handleClosed(tickResult);
+ *
+ * // Query signals
+ * const signal = await storage.findById("signal-123");
+ * const allSignals = await storage.list();
+ * ```
+ */
+declare class StorageBacktestUtils {
+    private _signals;
+    /**
+     * Initializes storage by loading existing signal history from persist layer.
+     * Uses singleshot to ensure initialization happens only once.
+     */
+    private waitForInit;
+    /**
+     * Persists current signal history to storage.
+     * Sorts by priority and limits to MAX_SIGNALS entries.
+     *
+     * @throws Error if storage not initialized
+     */
+    private _updateStorage;
+    /**
+     * Handles signal opened event.
+     *
+     * @param tick - Tick result containing opened signal data
+     * @returns Promise resolving when storage is updated
+     */
+    handleOpened: (tick: IStrategyTickResultOpened) => Promise<void>;
+    /**
+     * Handles signal closed event.
+     *
+     * @param tick - Tick result containing closed signal data
+     * @returns Promise resolving when storage is updated
+     */
+    handleClosed: (tick: IStrategyTickResultClosed) => Promise<void>;
+    /**
+     * Handles signal scheduled event.
+     *
+     * @param tick - Tick result containing scheduled signal data
+     * @returns Promise resolving when storage is updated
+     */
+    handleScheduled: (tick: IStrategyTickResultScheduled) => Promise<void>;
+    /**
+     * Handles signal cancelled event.
+     *
+     * @param tick - Tick result containing cancelled signal data
+     * @returns Promise resolving when storage is updated
+     */
+    handleCancelled: (tick: IStrategyTickResultCancelled) => Promise<void>;
+    /**
+     * Finds a signal by its unique identifier.
+     *
+     * @param id - Signal identifier
+     * @returns Promise resolving to signal row or null if not found
+     */
+    findById: (id: StorageId) => Promise<IStorageSignalRow | null>;
+    /**
+     * Lists all stored backtest signals.
+     *
+     * @returns Promise resolving to array of signal rows
+     */
+    list: () => Promise<IStorageSignalRow[]>;
+}
+/**
+ * Utility class for managing live trading signal history.
+ *
+ * Stores trading signal history for admin dashboard display during live trading
+ * with automatic initialization, deduplication, and storage limits.
+ *
+ * @example
+ * ```typescript
+ * import { StorageLiveUtils } from "./classes/Storage";
+ *
+ * const storage = new StorageLiveUtils();
+ *
+ * // Handle signal events
+ * await storage.handleOpened(tickResult);
+ * await storage.handleClosed(tickResult);
+ *
+ * // Query signals
+ * const signal = await storage.findById("signal-123");
+ * const allSignals = await storage.list();
+ * ```
+ */
+declare class StorageLiveUtils {
+    private _signals;
+    /**
+     * Initializes storage by loading existing signal history from persist layer.
+     * Uses singleshot to ensure initialization happens only once.
+     */
+    private waitForInit;
+    /**
+     * Persists current signal history to storage.
+     * Sorts by priority and limits to MAX_SIGNALS entries.
+     *
+     * @throws Error if storage not initialized
+     */
+    private _updateStorage;
+    /**
+     * Handles signal opened event.
+     *
+     * @param tick - Tick result containing opened signal data
+     * @returns Promise resolving when history is updated
+     */
+    handleOpened: (tick: IStrategyTickResultOpened) => Promise<void>;
+    /**
+     * Handles signal closed event.
+     *
+     * @param tick - Tick result containing closed signal data
+     * @returns Promise resolving when history is updated
+     */
+    handleClosed: (tick: IStrategyTickResultClosed) => Promise<void>;
+    /**
+     * Handles signal scheduled event.
+     *
+     * @param tick - Tick result containing scheduled signal data
+     * @returns Promise resolving when history is updated
+     */
+    handleScheduled: (tick: IStrategyTickResultScheduled) => Promise<void>;
+    /**
+     * Handles signal cancelled event.
+     *
+     * @param tick - Tick result containing cancelled signal data
+     * @returns Promise resolving when history is updated
+     */
+    handleCancelled: (tick: IStrategyTickResultCancelled) => Promise<void>;
+    /**
+     * Finds a signal by its unique identifier.
+     *
+     * @param id - Signal identifier
+     * @returns Promise resolving to signal row or null if not found
+     */
+    findById: (id: StorageId) => Promise<IStorageSignalRow | null>;
+    /**
+     * Lists all stored live signals.
+     *
+     * @returns Promise resolving to array of signal rows
+     */
+    list: () => Promise<IStorageSignalRow[]>;
+}
+/**
+ * Main storage adapter for signal history management.
+ *
+ * Provides unified interface for accessing backtest and live signal history
+ * for admin dashboard. Subscribes to signal emitters and automatically
+ * updates history on signal events.
+ *
+ * @example
+ * ```typescript
+ * import { Storage } from "./classes/Storage";
+ *
+ * // Enable signal history tracking
+ * const unsubscribe = Storage.enable();
+ *
+ * // Query signals
+ * const backtestSignals = await Storage.listSignalBacktest();
+ * const liveSignals = await Storage.listSignalLive();
+ * const signal = await Storage.findSignalById("signal-123");
+ *
+ * // Disable tracking
+ * Storage.disable();
+ * ```
+ */
+declare class StorageAdapter {
+    _signalLiveUtils: StorageLiveUtils;
+    _signalBacktestUtils: StorageBacktestUtils;
+    /**
+     * Enables signal history tracking by subscribing to emitters.
+     *
+     * @returns Cleanup function to unsubscribe from all emitters
+     */
+    enable: (() => () => void) & functools_kit.ISingleshotClearable;
+    /**
+     * Disables signal history tracking by unsubscribing from emitters.
+     */
+    disable: () => void;
+    /**
+     * Finds a signal by ID across both backtest and live history.
+     *
+     * @param id - Signal identifier
+     * @returns Promise resolving to signal row
+     * @throws Error if signal not found in either storage
+     */
+    findSignalById: (id: StorageId) => Promise<IStorageSignalRow | null>;
+    /**
+     * Lists all backtest signal history.
+     *
+     * @returns Promise resolving to array of backtest signal rows
+     */
+    listSignalBacktest: () => Promise<IStorageSignalRow[]>;
+    /**
+     * Lists all live signal history.
+     *
+     * @returns Promise resolving to array of live signal rows
+     */
+    listSignalLive: () => Promise<IStorageSignalRow[]>;
+}
+declare const Storage: StorageAdapter;
+
 /**
  * Utility class for exchange operations.
  *
@@ -19327,4 +19618,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { ActionBase, type ActivePingContract, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CandleData, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IBidData, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type IOrderBookData, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MethodContextService, type MetricStats, Notification, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Strategy, type StrategyActionType, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TMarkdownBase, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TickEvent, type TrailingStopCommitNotification, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate };
+export { ActionBase, type ActivePingContract, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CandleData, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IBidData, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IMarkdownDumpOptions, type IOrderBookData, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicSignalRow, type IReportDumpOptions, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskSignalRow, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MethodContextService, type MetricStats, Notification, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PersistStorageAdapter, PositionSize, type ProgressBacktestContract, type ProgressWalkerContract, Report, ReportBase, type ReportName, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskRejectionNotification, type RiskStatisticsModel, Schedule, type ScheduleData, type SchedulePingContract, type ScheduleStatisticsModel, type ScheduledEvent, type SignalCancelledNotification, type SignalClosedNotification, type SignalData, type SignalInterval, type SignalOpenedNotification, type SignalScheduledNotification, Storage, type StorageData, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TMarkdownBase, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TickEvent, type TrailingStopCommitNotification, type TrailingTakeCommitNotification, type ValidationErrorNotification, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addActionSchema, addExchangeSchema, addFrameSchema, addRiskSchema, addSizingSchema, addStrategySchema, addWalkerSchema, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, emitters, formatPrice, formatQuantity, get, getActionSchema, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getWalkerSchema, hasTradeContext, backtest as lib, listExchangeSchema, listFrameSchema, listRiskSchema, listSizingSchema, listStrategySchema, listWalkerSchema, listenActivePing, listenActivePingOnce, listenBacktestProgress, listenBreakevenAvailable, listenBreakevenAvailableOnce, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenPartialLossAvailable, listenPartialLossAvailableOnce, listenPartialProfitAvailable, listenPartialProfitAvailableOnce, listenPerformance, listenRisk, listenRiskOnce, listenSchedulePing, listenSchedulePingOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenStrategyCommit, listenStrategyCommitOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, overrideActionSchema, overrideExchangeSchema, overrideFrameSchema, overrideRiskSchema, overrideSizingSchema, overrideStrategySchema, overrideWalkerSchema, parseArgs, roundTicks, set, setColumns, setConfig, setLogger, stopStrategy, validate };