backtest-kit 3.5.2 → 3.7.0

package/package.json

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

package/types.d.ts

@@ -2989,10 +2989,12 @@ interface ILogEntry {
     id: string;
     /** Log level */
     type: "log" | "debug" | "info" | "warn";
-    /** Unix timestamp in milliseconds when the entry was created */
-    timestamp: number;
+    /** Current Unix timestamp in milliseconds for storage rotate */
+    priority: number;
     /** Date taken from backtest context to improve user experience */
     createdAt: string;
+    /** Unix timestamp in milliseconds taken from backtest context to improve user experience */
+    timestamp: number;
     /** Optional method context associated with the log entry, providing additional details about the execution environment or state when the log was recorded */
     methodContext: IMethodContext | null;
     /** Optional execution context associated with the log entry, providing additional details about the execution environment or state when the log was recorded */
@@ -4738,7 +4740,6 @@ declare function getDefaultColumns(): Readonly<{
  *     priceTakeProfit: 51000,
  *     priceStopLoss: 49000,
  *     minuteEstimatedTime: 60,
- *     timestamp: Date.now(),
  *   }),
  *   callbacks: {
  *     onOpen: (symbol, signal, currentPrice, backtest) => console.log("Signal opened"),
@@ -6859,6 +6860,20 @@ declare function formatQuantity(symbol: string, quantity: number): Promise<strin
  * ```
  */
 declare function getDate(): Promise<Date>;
+/**
+ * Gets the current timestamp from execution context.
+ *
+ * In backtest mode: returns the current timeframe timestamp being processed
+ * In live mode: returns current real-time timestamp
+ *
+ * @returns Promise resolving to current execution context timestamp in milliseconds
+ * @example
+ * ```typescript
+ * const timestamp = await getTimestamp();
+ * console.log(timestamp); // 1700000000000
+ * ```
+ */
+declare function getTimestamp(): Promise<number>;
 /**
  * Gets the current execution mode.
  *
@@ -8443,6 +8458,10 @@ declare const BASE_WAIT_FOR_INIT_SYMBOL: unique symbol;
  * Contains nullable signal for atomic updates.
  */
 type SignalData = ISignalRow | null;
+/**
+ * Cache.file data type stored in persistence layer.
+ */
+type MeasureData = unknown;
 /**
  * Type helper for PersistBase instance.
  */
@@ -9314,6 +9333,57 @@ declare class PersistLogUtils {
  * Used by LogPersistUtils for log entry persistence.
  */
 declare const PersistLogAdapter: PersistLogUtils;
+/**
+ * Utility class for managing external API response cache persistence.
+ *
+ * Features:
+ * - Memoized storage instances per cache bucket (aligned timestamp + symbol)
+ * - Custom adapter support
+ * - Atomic read/write operations
+ * - Crash-safe cache state management
+ *
+ * Used by Cache.file for persistent caching of external API responses.
+ */
+declare class PersistMeasureUtils {
+    private PersistMeasureFactory;
+    private getMeasureStorage;
+    /**
+     * Registers a custom persistence adapter.
+     *
+     * @param Ctor - Custom PersistBase constructor
+     */
+    usePersistMeasureAdapter(Ctor: TPersistBaseCtor<string, unknown>): void;
+    /**
+     * Reads cached measure data for a given bucket and key.
+     *
+     * @param bucket - Storage bucket (e.g. aligned timestamp + symbol)
+     * @param key - Dynamic cache key within the bucket
+     * @returns Promise resolving to cached value or null if not found
+     */
+    readMeasureData: (bucket: string, key: string) => Promise<MeasureData | null>;
+    /**
+     * Writes measure data to disk with atomic file writes.
+     *
+     * @param data - Data to cache
+     * @param bucket - Storage bucket (e.g. aligned timestamp + symbol)
+     * @param key - Dynamic cache key within the bucket
+     * @returns Promise that resolves when write is complete
+     */
+    writeMeasureData: (data: MeasureData, bucket: string, key: string) => Promise<void>;
+    /**
+     * Switches to the default JSON persist adapter.
+     */
+    useJson(): void;
+    /**
+     * Switches to a dummy persist adapter that discards all writes.
+     */
+    useDummy(): void;
+}
+/**
+ * Global singleton instance of PersistMeasureUtils.
+ * Used by Cache.file for persistent caching of external API responses.
+ */
+declare const PersistMeasureAdapter: PersistMeasureUtils;
 
 declare const WAIT_FOR_INIT_SYMBOL$1: unique symbol;
 declare const WRITE_SAFE_SYMBOL$1: unique symbol;
@@ -14559,6 +14629,30 @@ declare const Exchange: ExchangeUtils;
  * Used as a constraint for cached functions.
  */
 type Function = (...args: any[]) => any;
+/**
+ * Async function type for file-cached functions.
+ * First argument is always `symbol: string`, followed by optional spread args.
+ */
+type CacheFileFunction = (symbol: string, ...args: any[]) => Promise<any>;
+/**
+ * Utility type to drop the first argument from a function type.
+ * For example, for a function type `(symbol: string, arg1: number, arg2: string) => Promise<void>`,
+ * this type will infer the rest of the arguments as `[arg1: number, arg2: string]`.
+ */
+type DropFirst<T extends (...args: any) => any> = T extends (first: any, ...rest: infer R) => any ? R : never;
+/**
+ * Extracts the `key` generator argument tuple from a `CacheFileFunction`.
+ * The first two arguments are always `symbol: string` and `alignMs: number` (aligned timestamp),
+ * followed by the rest of the original function's arguments.
+ *
+ * For example, for a function type `(symbol: string, arg1: number, arg2: string) => Promise<void>`,
+ * this type will produce the tuple `[symbol: string, alignMs: number, arg1: number, arg2: string]`.
+ */
+type CacheFileKeyArgs<T extends CacheFileFunction> = [
+    symbol: string,
+    alignMs: number,
+    ...rest: DropFirst<T>
+];
 /**
  * Utility class for function caching with timeframe-based invalidation.
  *
@@ -14579,7 +14673,12 @@ declare class CacheUtils {
      * Memoized function to get or create CacheInstance for a function.
      * Each function gets its own isolated cache instance.
      */
-    private _getInstance;
+    private _getFnInstance;
+    /**
+     * Memoized function to get or create CacheFileInstance for an async function.
+     * Each function gets its own isolated file-cache instance.
+     */
+    private _getFileInstance;
     /**
      * Wrap a function with caching based on timeframe intervals.
      *
@@ -14617,6 +14716,49 @@ declare class CacheUtils {
         interval: CandleInterval;
         key?: (args: Parameters<T>) => K;
     }) => T;
+    /**
+     * Wrap an async function with persistent file-based caching.
+     *
+     * Returns a wrapped version of the function that reads from disk on cache hit
+     * and writes the result to disk on cache miss. Files are stored under
+     * `./dump/data/measure/{name}_{interval}_{index}/`.
+     *
+     * The `run` function reference is used as the memoization key for the underlying
+     * `CacheFileInstance`, so each unique function reference gets its own isolated instance.
+     * Pass the same function reference each time to reuse the same cache.
+     *
+     * @template T - Async function type to cache
+     * @param run - Async function to wrap with file caching
+     * @param context.interval - Candle interval for cache invalidation
+     * @param context.name - Human-readable bucket name; becomes the directory prefix
+     * @param context.key - Optional entity key generator. Receives `[symbol, alignMs, ...rest]`
+     *                      where `alignMs` is the timestamp aligned to `interval`.
+     *                      Default: `([symbol, alignMs]) => \`${symbol}_${alignMs}\``
+     * @returns Wrapped async function with automatic persistent caching
+     *
+     * @example
+     * ```typescript
+     * const fetchData = async (symbol: string, period: number) => {
+     *   return await externalApi.fetch(symbol, period);
+     * };
+     *
+     * // Default key — one cache file per symbol per aligned candle
+     * const cachedFetch = Cache.file(fetchData, { interval: "1h", name: "fetchData" });
+     *
+     * // Custom key — one cache file per symbol + period combination
+     * const cachedFetch = Cache.file(fetchData, {
+     *   interval: "1h",
+     *   name: "fetchData",
+     *   key: ([symbol, alignMs, period]) => `${symbol}_${alignMs}_${period}`,
+     * });
+     * const result = await cachedFetch("BTCUSDT", 14);
+     * ```
+     */
+    file: <T extends CacheFileFunction>(run: T, context: {
+        interval: CandleInterval;
+        name: string;
+        key?: (args: CacheFileKeyArgs<T>) => string;
+    }) => T;
     /**
      * Flush (remove) cached CacheInstance for a specific function or all functions.
      *
@@ -16582,7 +16724,7 @@ declare class ActionBase implements IPublicAction {
      * @example
      * ```typescript
      * pingScheduled(event: SchedulePingContract) {
-     *   const waitTime = Date.now() - event.data.timestampScheduled;
+     *   const waitTime = getTimestamp() - event.data.timestampScheduled;
      *   const waitMinutes = Math.floor(waitTime / 60000);
      *   console.log(`Scheduled signal waiting ${waitMinutes} minutes`);
      * }
@@ -16606,7 +16748,7 @@ declare class ActionBase implements IPublicAction {
      * @example
      * ```typescript
      * pingActive(event: ActivePingContract) {
-     *   const holdTime = Date.now() - event.data.pendingAt;
+     *   const holdTime = getTimestamp() - event.data.pendingAt;
      *   const holdMinutes = Math.floor(holdTime / 60000);
      *   console.log(`Active signal holding ${holdMinutes} minutes`);
      * }
@@ -21612,4 +21754,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, type AverageBuyCommit, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IAggregatedTradeData, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type ILog, type ILogEntry, type ILogger, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicCandleData, 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 ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Log, type LogData, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistNotificationAdapter, 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, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TLogCtor, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, 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, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, 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, shutdown, stopStrategy, validate, waitForCandle, warmCandles };
+export { ActionBase, type ActivateScheduledCommit, type ActivateScheduledCommitNotification, type ActivePingContract, type AverageBuyCommit, Backtest, type BacktestStatisticsModel, Breakeven, type BreakevenAvailableNotification, type BreakevenCommit, type BreakevenCommitNotification, type BreakevenContract, type BreakevenData, Cache, type CancelScheduledCommit, type CandleData, type CandleInterval, type ClosePendingCommit, type ColumnConfig, type ColumnModel, Constant, type CriticalErrorNotification, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type IActionSchema, type IActivateScheduledCommitRow, type IAggregatedTradeData, type IBidData, type IBreakevenCommitRow, type ICandleData, type ICommitRow, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type ILog, type ILogEntry, type ILogger, type IMarkdownDumpOptions, type INotificationUtils, type IOrderBookData, type IPartialLossCommitRow, type IPartialProfitCommitRow, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IPublicAction, type IPublicCandleData, 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 ISizingParams, type ISizingParamsATR, type ISizingParamsFixedPercentage, type ISizingParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStorageSignalRow, type IStorageUtils, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IStrategyTickResultWaiting, type ITrailingStopCommitRow, type ITrailingTakeCommitRow, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, type InfoErrorNotification, Live, type LiveStatisticsModel, Log, type LogData, Markdown, MarkdownFileBase, MarkdownFolderBase, type MarkdownName, type MeasureData, MethodContextService, type MetricStats, Notification, NotificationBacktest, type NotificationData, NotificationLive, type NotificationModel, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossAvailableNotification, type PartialLossCommit, type PartialLossCommitNotification, type PartialLossContract, type PartialProfitAvailableNotification, type PartialProfitCommit, type PartialProfitCommitNotification, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistBreakevenAdapter, PersistCandleAdapter, PersistLogAdapter, PersistMeasureAdapter, PersistNotificationAdapter, 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, StorageBacktest, type StorageData, StorageLive, Strategy, type StrategyActionType, type StrategyCancelReason, type StrategyCloseReason, type StrategyCommitContract, type StrategyEvent, type StrategyStatisticsModel, type TLogCtor, type TMarkdownBase, type TNotificationUtilsCtor, type TPersistBase, type TPersistBaseCtor, type TReportBase, type TStorageUtilsCtor, type TickEvent, type TrailingStopCommit, type TrailingStopCommitNotification, type TrailingTakeCommit, 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, alignToInterval, checkCandles, commitActivateScheduled, commitAverageBuy, commitBreakeven, commitCancelScheduled, commitClosePending, commitPartialLoss, commitPartialProfit, commitTrailingStop, commitTrailingTake, dumpMessages, emitters, formatPrice, formatQuantity, get, getActionSchema, getAggregatedTrades, getAveragePrice, getBacktestTimeframe, getCandles, getColumns, getConfig, getContext, getDate, getDefaultColumns, getDefaultConfig, getExchangeSchema, getFrameSchema, getMode, getNextCandles, getOrderBook, getRawCandles, getRiskSchema, getSizingSchema, getStrategySchema, getSymbol, getTimestamp, 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, shutdown, stopStrategy, validate, waitForCandle, warmCandles };