backtest-kit 3.5.2 → 3.7.0

package/build/index.cjs

@@ -801,6 +801,11 @@ const PERSIST_LOG_UTILS_METHOD_NAME_WRITE_DATA = "PersistLogUtils.writeLogData";
 const PERSIST_LOG_UTILS_METHOD_NAME_USE_JSON = "PersistLogUtils.useJson";
 const PERSIST_LOG_UTILS_METHOD_NAME_USE_DUMMY = "PersistLogUtils.useDummy";
 const PERSIST_LOG_UTILS_METHOD_NAME_USE_PERSIST_LOG_ADAPTER = "PersistLogUtils.usePersistLogAdapter";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_READ_DATA = "PersistMeasureUtils.readMeasureData";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_WRITE_DATA = "PersistMeasureUtils.writeMeasureData";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_USE_JSON = "PersistMeasureUtils.useJson";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_USE_DUMMY = "PersistMeasureUtils.useDummy";
+const PERSIST_MEASURE_UTILS_METHOD_NAME_USE_PERSIST_MEASURE_ADAPTER = "PersistMeasureUtils.usePersistMeasureAdapter";
 const BASE_WAIT_FOR_INIT_FN_METHOD_NAME = "PersistBase.waitForInitFn";
 const BASE_UNLINK_RETRY_COUNT = 5;
 const BASE_UNLINK_RETRY_DELAY = 1000;
@@ -2071,6 +2076,92 @@ class PersistLogUtils {
  * Used by LogPersistUtils for log entry persistence.
  */
 const PersistLogAdapter = new 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.
+ */
+class PersistMeasureUtils {
+    constructor() {
+        this.PersistMeasureFactory = PersistBase;
+        this.getMeasureStorage = functoolsKit.memoize(([bucket]) => bucket, (bucket) => Reflect.construct(this.PersistMeasureFactory, [
+            bucket,
+            `./dump/data/measure/`,
+        ]));
+        /**
+         * 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
+         */
+        this.readMeasureData = async (bucket, key) => {
+            bt.loggerService.info(PERSIST_MEASURE_UTILS_METHOD_NAME_READ_DATA, {
+                bucket,
+                key,
+            });
+            const isInitial = !this.getMeasureStorage.has(bucket);
+            const stateStorage = this.getMeasureStorage(bucket);
+            await stateStorage.waitForInit(isInitial);
+            if (await stateStorage.hasValue(key)) {
+                return await stateStorage.readValue(key);
+            }
+            return 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
+         */
+        this.writeMeasureData = async (data, bucket, key) => {
+            bt.loggerService.info(PERSIST_MEASURE_UTILS_METHOD_NAME_WRITE_DATA, {
+                bucket,
+                key,
+            });
+            const isInitial = !this.getMeasureStorage.has(bucket);
+            const stateStorage = this.getMeasureStorage(bucket);
+            await stateStorage.waitForInit(isInitial);
+            await stateStorage.writeValue(key, data);
+        };
+    }
+    /**
+     * Registers a custom persistence adapter.
+     *
+     * @param Ctor - Custom PersistBase constructor
+     */
+    usePersistMeasureAdapter(Ctor) {
+        bt.loggerService.info(PERSIST_MEASURE_UTILS_METHOD_NAME_USE_PERSIST_MEASURE_ADAPTER);
+        this.PersistMeasureFactory = Ctor;
+    }
+    /**
+     * Switches to the default JSON persist adapter.
+     */
+    useJson() {
+        bt.loggerService.log(PERSIST_MEASURE_UTILS_METHOD_NAME_USE_JSON);
+        this.usePersistMeasureAdapter(PersistBase);
+    }
+    /**
+     * Switches to a dummy persist adapter that discards all writes.
+     */
+    useDummy() {
+        bt.loggerService.log(PERSIST_MEASURE_UTILS_METHOD_NAME_USE_DUMMY);
+        this.usePersistMeasureAdapter(PersistDummy);
+    }
+}
+/**
+ * Global singleton instance of PersistMeasureUtils.
+ * Used by Cache.file for persistent caching of external API responses.
+ */
+const PersistMeasureAdapter = new PersistMeasureUtils();
 
 var _a$3, _b$3;
 const BUSY_DELAY = 100;
@@ -10371,7 +10462,7 @@ class ActionBase {
      * @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`);
      * }
@@ -10400,7 +10491,7 @@ class ActionBase {
      * @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`);
      * }
@@ -16102,6 +16193,20 @@ const COLUMN_CONFIG = {
  */
 const DEFAULT_COLUMNS = Object.freeze({ ...COLUMN_CONFIG });
 
+/**
+ * Retrieves the current timestamp based on the execution context.
+ * If an execution context is active (e.g., during a backtest), it returns the timestamp from the context to ensure consistency with the simulated time.
+ * If no execution context is active (e.g., during live operation), it returns the current real-world timestamp.
+ * This function helps maintain accurate timing for logs, metrics, and other time-sensitive operations across both live and backtest modes.
+ * @return {number} The current timestamp in milliseconds, either from the execution context or the real-world clock.
+ */
+const getContextTimestamp = () => {
+    if (ExecutionContextService.hasContext()) {
+        return bt.executionContextService.context.when.getTime();
+    }
+    return Date.now();
+};
+
 var _a$2, _b$2;
 const MARKDOWN_METHOD_NAME_ENABLE = "MarkdownUtils.enable";
 const MARKDOWN_METHOD_NAME_DISABLE = "MarkdownUtils.disable";
@@ -16235,7 +16340,7 @@ class MarkdownFileBase {
             markdownName: this.markdownName,
             data,
             ...searchFlags,
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
         }) + "\n";
         const status = await this[WRITE_SAFE_SYMBOL$2](line);
         if (status === functoolsKit.TIMEOUT_SYMBOL) {
@@ -16779,7 +16884,7 @@ let ReportStorage$7 = class ReportStorage {
      */
     async dump(strategyName, path = "./dump/backtest", columns = COLUMN_CONFIG.backtest_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$9(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("backtest", markdown, {
             path,
@@ -17114,7 +17219,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     addIdleEvent(currentPrice) {
         const newEvent = {
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
             action: "idle",
             currentPrice,
         };
@@ -17170,7 +17275,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     addActiveEvent(data) {
         const newEvent = {
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
             action: "active",
             symbol: data.signal.symbol,
             signalId: data.signal.id,
@@ -17272,7 +17377,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     addWaitingEvent(data) {
         const newEvent = {
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
             action: "waiting",
             symbol: data.signal.symbol,
             signalId: data.signal.id,
@@ -17466,7 +17571,7 @@ let ReportStorage$6 = class ReportStorage {
      */
     async dump(strategyName, path = "./dump/live", columns = COLUMN_CONFIG.live_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$8(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("live", markdown, {
             path,
@@ -17998,7 +18103,7 @@ let ReportStorage$5 = class ReportStorage {
      */
     async dump(strategyName, path = "./dump/schedule", columns = COLUMN_CONFIG.schedule_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$7(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("schedule", markdown, {
             path,
@@ -18463,7 +18568,7 @@ class PerformanceStorage {
      */
     async dump(strategyName, path = "./dump/performance", columns = COLUMN_CONFIG.performance_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$6(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("performance", markdown, {
             path,
@@ -18914,7 +19019,7 @@ let ReportStorage$4 = class ReportStorage {
      */
     async dump(symbol, metric, context, path = "./dump/walker", strategyColumns = COLUMN_CONFIG.walker_strategy_columns, pnlColumns = COLUMN_CONFIG.walker_pnl_columns) {
         const markdown = await this.getReport(symbol, metric, context, strategyColumns, pnlColumns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$5(this.walkerName, timestamp);
         await Markdown.writeData("walker", markdown, {
             path,
@@ -19468,7 +19573,7 @@ class HeatmapStorage {
      */
     async dump(strategyName, path = "./dump/heatmap", columns = COLUMN_CONFIG.heat_columns) {
         const markdown = await this.getReport(strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$4(strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("heat", markdown, {
             path,
@@ -21148,7 +21253,7 @@ let ReportStorage$3 = class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/partial", columns = COLUMN_CONFIG.partial_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$3(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("partial", markdown, {
             path,
@@ -22241,7 +22346,7 @@ let ReportStorage$2 = class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/breakeven", columns = COLUMN_CONFIG.breakeven_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$2(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("breakeven", markdown, {
             path,
@@ -22909,7 +23014,7 @@ let ReportStorage$1 = class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/risk", columns = COLUMN_CONFIG.risk_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN$1(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("risk", markdown, {
             path,
@@ -23393,7 +23498,7 @@ class ReportBase {
             reportName: this.reportName,
             data,
             ...searchFlags,
-            timestamp: Date.now(),
+            timestamp: getContextTimestamp(),
         }) + "\n";
         const status = await this[WRITE_SAFE_SYMBOL$1](line);
         if (status === functoolsKit.TIMEOUT_SYMBOL) {
@@ -23732,7 +23837,7 @@ class BacktestReportService {
         this.tick = async (data) => {
             this.loggerService.log(BACKTEST_REPORT_METHOD_NAME_TICK, { data });
             const baseEvent = {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 action: data.action,
                 symbol: data.symbol,
                 strategyName: data.strategyName,
@@ -23911,7 +24016,7 @@ class LiveReportService {
         this.tick = async (data) => {
             this.loggerService.log(LIVE_REPORT_METHOD_NAME_TICK, { data });
             const baseEvent = {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 action: data.action,
                 symbol: data.symbol,
                 strategyName: data.strategyName,
@@ -24434,7 +24539,7 @@ class WalkerReportService {
         this.tick = async (data) => {
             this.loggerService.log(WALKER_REPORT_METHOD_NAME_TICK, { data });
             await Report.writeData("walker", {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 walkerName: data.walkerName,
                 symbol: data.symbol,
                 exchangeName: data.exchangeName,
@@ -24561,7 +24666,7 @@ class HeatReportService {
                 return;
             }
             await Report.writeData("heat", {
-                timestamp: Date.now(),
+                timestamp: getContextTimestamp(),
                 action: data.action,
                 symbol: data.symbol,
                 strategyName: data.strategyName,
@@ -25883,7 +25988,7 @@ class ReportStorage {
      */
     async dump(symbol, strategyName, path = "./dump/strategy", columns = COLUMN_CONFIG.strategy_columns) {
         const markdown = await this.getReport(symbol, strategyName, columns);
-        const timestamp = Date.now();
+        const timestamp = getContextTimestamp();
         const filename = CREATE_FILE_NAME_FN(this.symbol, strategyName, this.exchangeName, this.frameName, timestamp);
         await Markdown.writeData("strategy", markdown, {
             path,
@@ -28199,6 +28304,7 @@ const GET_AVERAGE_PRICE_METHOD_NAME = "exchange.getAveragePrice";
 const FORMAT_PRICE_METHOD_NAME = "exchange.formatPrice";
 const FORMAT_QUANTITY_METHOD_NAME = "exchange.formatQuantity";
 const GET_DATE_METHOD_NAME = "exchange.getDate";
+const GET_TIMESTAMP_METHOD_NAME = "exchange.getTimestamp";
 const GET_MODE_METHOD_NAME = "exchange.getMode";
 const GET_SYMBOL_METHOD_NAME = "exchange.getSymbol";
 const GET_CONTEXT_METHOD_NAME = "exchange.getContext";
@@ -28364,6 +28470,26 @@ async function getDate() {
     const { when } = bt.executionContextService.context;
     return new Date(when.getTime());
 }
+/**
+ * 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
+ * ```
+ */
+async function getTimestamp() {
+    bt.loggerService.info(GET_TIMESTAMP_METHOD_NAME);
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("getTimestamp requires an execution context");
+    }
+    return getContextTimestamp();
+}
 /**
  * Gets the current execution mode.
  *
@@ -32561,7 +32687,6 @@ const ADD_ACTION_METHOD_NAME = "add.addActionSchema";
  *     priceTakeProfit: 51000,
  *     priceStopLoss: 49000,
  *     minuteEstimatedTime: 60,
- *     timestamp: Date.now(),
  *   }),
  *   callbacks: {
  *     onOpen: (symbol, signal, currentPrice, backtest) => console.log("Signal opened"),
@@ -33488,8 +33613,8 @@ const WAIT_FOR_INIT_SYMBOL = Symbol("wait-for-init");
 const WRITE_SAFE_SYMBOL = Symbol("write-safe");
 /**
  * Backtest execution time retrieval function.
- * Returns the 'when' timestamp from the execution context if available, otherwise returns the current time.
- * This allows log entries to be timestamped according to the backtest timeline rather than real-world time, improving log relevance and user experience during backtest analysis.
+ * Returns the 'when' priority from the execution context if available, otherwise returns the current time.
+ * This allows log entries to be priorityed according to the backtest timeline rather than real-world time, improving log relevance and user experience during backtest analysis.
  */
 const GET_DATE_FN = () => {
     if (ExecutionContextService.hasContext()) {
@@ -33511,7 +33636,7 @@ const GET_METHOD_CONTEXT_FN = () => {
 /**
  * Execution context retrieval function.
  * Returns the current execution context from ExecutionContextService if available, otherwise returns null.
- * This allows log entries to include contextual information about the symbol, timestamp, and backtest mode associated with the log event, providing additional insights into the execution environment when analyzing logs.
+ * This allows log entries to include contextual information about the symbol, priority, and backtest mode associated with the log event, providing additional insights into the execution environment when analyzing logs.
  */
 const GET_EXECUTION_CONTEXT_FN = () => {
     if (ExecutionContextService.hasContext()) {
@@ -33541,7 +33666,7 @@ class LogPersistUtils {
         this.waitForInit = functoolsKit.singleshot(async () => {
             bt.loggerService.info(LOG_PERSIST_METHOD_NAME_WAIT_FOR_INIT);
             const list = await PersistLogAdapter.readLogData();
-            list.sort((a, b) => a.timestamp - b.timestamp);
+            list.sort((a, b) => a.priority - b.priority);
             this._entries = list.slice(-GLOBAL_CONFIG.CC_MAX_LOG_LINES);
         });
         /**
@@ -33557,7 +33682,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "log",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33580,7 +33706,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "debug",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33603,7 +33730,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "info",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33626,7 +33754,8 @@ class LogPersistUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "warn",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33682,7 +33811,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "log",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33703,7 +33833,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "debug",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33724,7 +33855,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "info",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33745,7 +33877,8 @@ class LogMemoryUtils {
             this._entries.push({
                 id: functoolsKit.randomString(),
                 type: "warn",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33859,7 +33992,8 @@ class LogJsonlUtils {
             await this._append({
                 id: functoolsKit.randomString(),
                 type: "log",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33878,7 +34012,8 @@ class LogJsonlUtils {
             await this._append({
                 id: functoolsKit.randomString(),
                 type: "debug",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33897,7 +34032,8 @@ class LogJsonlUtils {
             await this._append({
                 id: functoolsKit.randomString(),
                 type: "info",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -33916,7 +34052,8 @@ class LogJsonlUtils {
             await this._append({
                 id: functoolsKit.randomString(),
                 type: "warn",
-                timestamp: Date.now(),
+                priority: Date.now(),
+                timestamp: getContextTimestamp(),
                 createdAt: date.toISOString(),
                 methodContext: GET_METHOD_CONTEXT_FN(),
                 executionContext: GET_EXECUTION_CONTEXT_FN(),
@@ -38343,6 +38480,8 @@ const CACHE_METHOD_NAME_CLEAR = "CacheInstance.clear";
 const CACHE_METHOD_NAME_RUN = "CacheInstance.run";
 const CACHE_METHOD_NAME_GC = "CacheInstance.gc";
 const CACHE_METHOD_NAME_FN = "CacheUtils.fn";
+const CACHE_METHOD_NAME_FILE = "CacheUtils.file";
+const CACHE_FILE_INSTANCE_METHOD_NAME_RUN = "CacheFileInstance.run";
 const MS_PER_MINUTE$1 = 60000;
 const INTERVAL_MINUTES$1 = {
     "1m": 1,
@@ -38564,6 +38703,95 @@ class CacheInstance {
         };
     }
 }
+/**
+ * Instance class for caching async function results in persistent file storage.
+ *
+ * Provides automatic cache invalidation based on candle intervals.
+ * Cache key = `${alignedTimestamp}_${symbol}` (bucket) + dynamic key (file within bucket).
+ * On cache hit reads from disk, on miss calls the function and writes the result.
+ *
+ * @template T - Async function type to cache
+ * @template K - Dynamic key type
+ *
+ * @example
+ * ```typescript
+ * const instance = new CacheFileInstance(fetchFromApi, "1h");
+ * const result = await instance.run("BTCUSDT", extraArg);
+ * ```
+ */
+class CacheFileInstance {
+    /**
+     * Allocates a new unique index. Called once in the constructor to give each
+     * CacheFileInstance its own namespace in the persistent key space.
+     */
+    static createIndex() {
+        return CacheFileInstance._indexCounter++;
+    }
+    /**
+     * Creates a new CacheFileInstance.
+     *
+     * @param fn - Async function to cache
+     * @param interval - Candle interval for cache invalidation
+     * @param name - Human-readable bucket name used as the directory key (replaces symbol in bucket path)
+     * @param key - Dynamic key generator; receives all args, must return a string.
+     *              Default: `([symbol, alignMs]) => \`${symbol}_${alignMs}\``
+     */
+    constructor(fn, interval, name, key = ([symbol, alignMs]) => `${symbol}_${alignMs}`) {
+        this.fn = fn;
+        this.interval = interval;
+        this.name = name;
+        this.key = key;
+        /**
+         * Execute async function with persistent file caching.
+         *
+         * Algorithm:
+         * 1. Build bucket = `${name}_${interval}_${index}` — fixed per instance, used as directory name
+         * 2. Align execution context `when` to interval boundary → `alignedTs`
+         * 3. Build entity key from the key generator (receives `[symbol, alignedTs, ...rest]`)
+         * 4. Try to read from PersistMeasureAdapter using (bucket, entityKey)
+         * 5. On hit — return cached value
+         * 6. On miss — call fn, write result to disk, return result
+         *
+         * Cache invalidation happens through the entity key: the default key embeds `alignedTs`,
+         * so each new candle interval produces a new file name while the bucket directory stays the same.
+         *
+         * Requires active execution context (symbol, when) and method context.
+         *
+         * @param args - Arguments forwarded to the wrapped function
+         * @returns Cached or freshly computed result
+         */
+        this.run = async (...args) => {
+            bt.loggerService.debug(CACHE_FILE_INSTANCE_METHOD_NAME_RUN, { args });
+            const step = INTERVAL_MINUTES$1[this.interval];
+            {
+                if (!MethodContextService.hasContext()) {
+                    throw new Error("CacheFileInstance run requires method context");
+                }
+                if (!ExecutionContextService.hasContext()) {
+                    throw new Error("CacheFileInstance run requires execution context");
+                }
+                if (!step) {
+                    throw new Error(`CacheFileInstance unknown cache ttl interval=${this.interval}`);
+                }
+            }
+            const [symbol, ...rest] = args;
+            const { when } = bt.executionContextService.context;
+            const alignedTs = align(when.getTime(), this.interval);
+            const bucket = `${this.name}_${this.interval}_${this.index}`;
+            const entityKey = this.key([symbol, alignedTs, ...rest]);
+            const cached = await PersistMeasureAdapter.readMeasureData(bucket, entityKey);
+            if (cached !== null) {
+                return cached;
+            }
+            const result = await this.fn.call(null, ...args);
+            await PersistMeasureAdapter.writeMeasureData(result, bucket, entityKey);
+            return result;
+        };
+        this.index = CacheFileInstance.createIndex();
+    }
+}
+/** Global counter — incremented once per CacheFileInstance construction */
+CacheFileInstance._indexCounter = 0;
 /**
  * Utility class for function caching with timeframe-based invalidation.
  *
@@ -38585,7 +38813,12 @@ class CacheUtils {
          * Memoized function to get or create CacheInstance for a function.
          * Each function gets its own isolated cache instance.
          */
-        this._getInstance = functoolsKit.memoize(([run]) => run, (run, interval, key) => new CacheInstance(run, interval, key));
+        this._getFnInstance = functoolsKit.memoize(([run]) => run, (run, interval, key) => new CacheInstance(run, interval, key));
+        /**
+         * Memoized function to get or create CacheFileInstance for an async function.
+         * Each function gets its own isolated file-cache instance.
+         */
+        this._getFileInstance = functoolsKit.memoize(([run]) => run, (run, interval, name, key) => new CacheFileInstance(run, interval, name, key));
         /**
          * Wrap a function with caching based on timeframe intervals.
          *
@@ -38624,11 +38857,57 @@ class CacheUtils {
                 context,
             });
             const wrappedFn = (...args) => {
-                const instance = this._getInstance(run, context.interval, context.key);
+                const instance = this._getFnInstance(run, context.interval, context.key);
                 return instance.run(...args).value;
             };
             return wrappedFn;
         };
+        /**
+         * 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);
+         * ```
+         */
+        this.file = (run, context) => {
+            bt.loggerService.info(CACHE_METHOD_NAME_FILE, { context });
+            const wrappedFn = (...args) => {
+                const instance = this._getFileInstance(run, context.interval, context.name, context.key);
+                return instance.run(...args);
+            };
+            return wrappedFn;
+        };
         /**
          * Flush (remove) cached CacheInstance for a specific function or all functions.
          *
@@ -38662,7 +38941,7 @@ class CacheUtils {
             bt.loggerService.info(CACHE_METHOD_NAME_FLUSH, {
                 run,
             });
-            this._getInstance.clear(run);
+            this._getFnInstance.clear(run);
         };
         /**
          * Clear cached value for current execution context of a specific function.
@@ -38705,7 +38984,7 @@ class CacheUtils {
                 console.warn(`${CACHE_METHOD_NAME_CLEAR} called without execution context, skipping clear`);
                 return;
             }
-            this._getInstance.get(run).clear();
+            this._getFnInstance.get(run).clear();
         };
         /**
          * Garbage collect expired cache entries for a specific function.
@@ -38737,7 +39016,7 @@ class CacheUtils {
                 console.warn(`${CACHE_METHOD_NAME_GC} called without execution context, skipping garbage collection`);
                 return;
             }
-            return this._getInstance.get(run).gc();
+            return this._getFnInstance.get(run).gc();
         };
     }
 }
@@ -39330,6 +39609,7 @@ exports.PersistBase = PersistBase;
 exports.PersistBreakevenAdapter = PersistBreakevenAdapter;
 exports.PersistCandleAdapter = PersistCandleAdapter;
 exports.PersistLogAdapter = PersistLogAdapter;
+exports.PersistMeasureAdapter = PersistMeasureAdapter;
 exports.PersistNotificationAdapter = PersistNotificationAdapter;
 exports.PersistPartialAdapter = PersistPartialAdapter;
 exports.PersistRiskAdapter = PersistRiskAdapter;
@@ -39390,6 +39670,7 @@ exports.getRiskSchema = getRiskSchema;
 exports.getSizingSchema = getSizingSchema;
 exports.getStrategySchema = getStrategySchema;
 exports.getSymbol = getSymbol;
+exports.getTimestamp = getTimestamp;
 exports.getWalkerSchema = getWalkerSchema;
 exports.hasTradeContext = hasTradeContext;
 exports.lib = backtest;