forge-sql-orm 2.0.30 → 2.1.0

package/src/utils/cacheContextUtils.ts

@@ -0,0 +1,210 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AnyMySqlSelectQueryBuilder, AnyMySqlTable } from "drizzle-orm/mysql-core";
+import { getTableName } from "drizzle-orm/table";
+import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
+import { MySqlSelectDynamic } from "drizzle-orm/mysql-core/query-builders/select.types";
+import { hashKey } from "./cacheUtils";
+import { Query } from "drizzle-orm/sql/sql";
+
+/**
+ * Interface representing the cache application context.
+ * Stores information about tables that are being processed within a cache context.
+ */
+export interface CacheApplicationContext {
+  /** Set of table names (in lowercase) that are being processed within the cache context */
+  tables: Set<string>;
+}
+
+/**
+ * Interface representing the local cache application context.
+ * Stores cached query results in memory for the duration of a local cache context.
+ *
+ * @interface LocalCacheApplicationContext
+ */
+export interface LocalCacheApplicationContext {
+  /**
+   * Cache object mapping query hash keys to cached results
+   * @property {Record<string, {sql: string, data: unknown[]}>} cache - Map of query keys to cached data
+   */
+  cache: Record<
+    string,
+    {
+      sql: string;
+      data: unknown[];
+    }
+  >;
+}
+
+/**
+ * AsyncLocalStorage instance for managing cache context across async operations.
+ * This allows tracking which tables are being processed within a cache context
+ * without explicitly passing context through function parameters.
+ */
+export const cacheApplicationContext = new AsyncLocalStorage<CacheApplicationContext>();
+
+/**
+ * AsyncLocalStorage instance for managing local cache context across async operations.
+ * This allows storing and retrieving cached query results within a local cache context
+ * without explicitly passing context through function parameters.
+ */
+export const localCacheApplicationContext = new AsyncLocalStorage<LocalCacheApplicationContext>();
+
+/**
+ * Saves a table name to the current cache context if one exists.
+ * This function is used to track which tables are being processed within
+ * a cache context for proper cache invalidation.
+ *
+ * @param table - The Drizzle table schema to track
+ * @returns Promise that resolves when the table is saved to context
+ *
+ * @example
+ * ```typescript
+ * await saveTableIfInsideCacheContext(usersTable);
+ * ```
+ */
+export async function saveTableIfInsideCacheContext<T extends AnyMySqlTable>(
+  table: T,
+): Promise<void> {
+  const context = cacheApplicationContext.getStore();
+  if (context) {
+    const tableName = getTableName(table).toLowerCase();
+    context.tables.add(tableName);
+  }
+}
+
+/**
+ * Saves a query result to the local cache context.
+ * This function stores query results in memory for the duration of the local cache context.
+ *
+ * @param query - The Drizzle query to cache
+ * @param rows - The query result data to cache
+ * @returns Promise that resolves when the data is saved to local cache
+ *
+ * @example
+ * ```typescript
+ * const query = db.select({ id: users.id, name: users.name }).from(users);
+ * const results = await query.execute();
+ * await saveQueryLocalCacheQuery(query, results);
+ * ```
+ */
+export async function saveQueryLocalCacheQuery<
+  T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>,
+>(query: T, rows: unknown[]): Promise<void> {
+  const context = localCacheApplicationContext.getStore();
+  if (context) {
+    if (!context.cache) {
+      context.cache = {};
+    }
+    const sql = query as { toSQL: () => Query };
+    const key = hashKey(sql.toSQL());
+    context.cache[key] = {
+      sql: sql.toSQL().sql.toLowerCase(),
+      data: rows,
+    };
+  }
+}
+
+/**
+ * Retrieves a query result from the local cache context.
+ * This function checks if a query result is already cached in memory.
+ *
+ * @param query - The Drizzle query to check for cached results
+ * @returns Promise that resolves to cached data if found, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const query = db.select({ id: users.id, name: users.name }).from(users);
+ * const cachedResult = await getQueryLocalCacheQuery(query);
+ * if (cachedResult) {
+ *   return cachedResult; // Use cached data
+ * }
+ * // Execute query and cache result
+ * ```
+ */
+export async function getQueryLocalCacheQuery<
+  T extends MySqlSelectDynamic<AnyMySqlSelectQueryBuilder>,
+>(query: T): Promise<unknown[] | undefined> {
+  const context = localCacheApplicationContext.getStore();
+  if (context) {
+    if (!context.cache) {
+      context.cache = {};
+    }
+    const sql = query as { toSQL: () => Query };
+    const key = hashKey(sql.toSQL());
+    if (context.cache[key] && context.cache[key].sql === sql.toSQL().sql.toLowerCase()) {
+      return context.cache[key].data;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Evicts cached queries from the local cache context that involve the specified table.
+ * This function removes cached query results that contain the given table name.
+ *
+ * @param table - The Drizzle table schema to evict cache for
+ * @param options - ForgeSQL ORM options containing cache configuration
+ * @returns Promise that resolves when cache eviction is complete
+ *
+ * @example
+ * ```typescript
+ * // After inserting/updating/deleting from users table
+ * await evictLocalCacheQuery(usersTable, forgeSqlOptions);
+ * // All cached queries involving users table are now removed
+ * ```
+ */
+export async function evictLocalCacheQuery<T extends AnyMySqlTable>(
+  table: T,
+  options: ForgeSqlOrmOptions,
+): Promise<void> {
+  const context = localCacheApplicationContext.getStore();
+  if (context) {
+    if (!context.cache) {
+      context.cache = {};
+    }
+    const tableName = getTableName(table);
+    const searchString = options.cacheWrapTable ? `\`${tableName}\`` : tableName;
+    const keyToEvicts: string[] = [];
+    Object.keys(context.cache).forEach((key) => {
+      if (context.cache[key].sql.includes(searchString)) {
+        keyToEvicts.push(key);
+      }
+    });
+    keyToEvicts.forEach((key) => delete context.cache[key]);
+  }
+}
+
+/**
+ * Checks if the given SQL query contains any tables that are currently being processed
+ * within a cache context. This is used to determine if cache should be bypassed
+ * for queries that affect tables being modified within the context.
+ *
+ * @param sql - The SQL query string to check
+ * @param options - ForgeSQL ORM options containing cache configuration
+ * @returns Promise that resolves to true if the SQL contains tables in cache context
+ *
+ * @example
+ * ```typescript
+ * const shouldBypassCache = await isTableContainsTableInCacheContext(
+ *   "SELECT * FROM users WHERE id = 1",
+ *   forgeSqlOptions
+ * );
+ * ```
+ */
+export async function isTableContainsTableInCacheContext(
+  sql: string,
+  options: ForgeSqlOrmOptions,
+): Promise<boolean> {
+  const context = cacheApplicationContext.getStore();
+  if (!context) {
+    return false;
+  }
+
+  const tables = Array.from(context.tables);
+  const lowerSql = sql.toLowerCase();
+
+  return tables.some((table) => {
+    const tablePattern = options.cacheWrapTable ? `\`${table}\`` : table;
+    return lowerSql.includes(tablePattern);
+  });
+}

package/src/utils/cacheUtils.ts

@@ -0,0 +1,403 @@
+import { DateTime } from "luxon";
+import * as crypto from "crypto";
+import { Query } from "drizzle-orm";
+import { AnyMySqlTable } from "drizzle-orm/mysql-core";
+import { getTableName } from "drizzle-orm/table";
+import { Filter, FilterConditions, kvs, WhereConditions } from "@forge/kvs";
+import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
+import { cacheApplicationContext, isTableContainsTableInCacheContext } from "./cacheContextUtils";
+
+// Constants for better maintainability
+const CACHE_CONSTANTS = {
+  BATCH_SIZE: 25,
+  MAX_RETRY_ATTEMPTS: 3,
+  INITIAL_RETRY_DELAY: 1000,
+  RETRY_DELAY_MULTIPLIER: 2,
+  DEFAULT_ENTITY_QUERY_NAME: "sql",
+  DEFAULT_EXPIRATION_NAME: "expiration",
+  DEFAULT_DATA_NAME: "data",
+  HASH_LENGTH: 32,
+} as const;
+
+// Types for better type safety
+type CacheEntity = {
+  [key: string]: string | number;
+};
+
+/**
+ * Gets the current Unix timestamp in seconds.
+ *
+ * @returns Current timestamp as integer
+ */
+function getCurrentTime(): number {
+  const dt = DateTime.now();
+  return Math.floor(dt.toSeconds());
+}
+
+/**
+ * Calculates a future timestamp by adding seconds to the current time.
+ * Validates that the result is within 32-bit integer range.
+ *
+ * @param secondsToAdd - Number of seconds to add to current time
+ * @returns Future timestamp in seconds
+ * @throws Error if the result is out of 32-bit integer range
+ */
+function nowPlusSeconds(secondsToAdd: number): number {
+  const dt = DateTime.now().plus({ seconds: secondsToAdd });
+  return Math.floor(dt.toSeconds());
+}
+
+/**
+ * Generates a hash key for a query based on its SQL and parameters.
+ *
+ * @param query - The Drizzle query object
+ * @returns 32-character hexadecimal hash
+ */
+export function hashKey(query: Query): string {
+  const h = crypto.createHash("sha256");
+  h.update(query.sql.toLowerCase());
+  h.update(JSON.stringify(query.params));
+  return "CachedQuery_" + h.digest("hex").slice(0, CACHE_CONSTANTS.HASH_LENGTH);
+}
+
+/**
+ * Deletes cache entries in batches to respect Forge limits and timeouts.
+ *
+ * @param results - Array of cache entries to delete
+ * @param cacheEntityName - Name of the cache entity
+ * @returns Promise that resolves when all deletions are complete
+ */
+async function deleteCacheEntriesInBatches(
+  results: Array<{ key: string }>,
+  cacheEntityName: string,
+): Promise<void> {
+  for (let i = 0; i < results.length; i += CACHE_CONSTANTS.BATCH_SIZE) {
+    const batch = results.slice(i, i + CACHE_CONSTANTS.BATCH_SIZE);
+    let transactionBuilder = kvs.transact();
+    batch.forEach((result) => {
+      transactionBuilder = transactionBuilder.delete(result.key, { entityName: cacheEntityName });
+    });
+    await transactionBuilder.execute();
+  }
+}
+
+/**
+ * Clears cache entries for specific tables using cursor-based pagination.
+ *
+ * @param tables - Array of table names to clear cache for
+ * @param cursor - Pagination cursor for large result sets
+ * @param options - ForgeSQL ORM options
+ * @returns Total number of deleted cache entries
+ */
+async function clearCursorCache(
+  tables: string[],
+  cursor: string,
+  options: ForgeSqlOrmOptions,
+): Promise<number> {
+  const cacheEntityName = options.cacheEntityName;
+  if (!cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+
+  const entityQueryName = options.cacheEntityQueryName ?? CACHE_CONSTANTS.DEFAULT_ENTITY_QUERY_NAME;
+  let filters = new Filter<{
+    [entityQueryName]: string;
+  }>();
+
+  for (const table of tables) {
+    const wrapIfNeeded = options.cacheWrapTable ? `\`${table}\`` : table;
+    filters.or(entityQueryName, FilterConditions.contains(wrapIfNeeded?.toLowerCase()));
+  }
+
+  let entityQueryBuilder = kvs
+    .entity<{
+      [entityQueryName]: string;
+    }>(cacheEntityName)
+    .query()
+    .index(entityQueryName)
+    .filters(filters);
+
+  if (cursor) {
+    entityQueryBuilder = entityQueryBuilder.cursor(cursor);
+  }
+
+  const listResult = await entityQueryBuilder.limit(100).getMany();
+
+  if (options.logRawSqlQuery) {
+    console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
+  }
+
+  await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
+
+  if (listResult.nextCursor) {
+    return (
+      listResult.results.length + (await clearCursorCache(tables, listResult.nextCursor, options))
+    );
+  } else {
+    return listResult.results.length;
+  }
+}
+
+/**
+ * Clears expired cache entries using cursor-based pagination.
+ *
+ * @param cursor - Pagination cursor for large result sets
+ * @param options - ForgeSQL ORM options
+ * @returns Total number of deleted expired cache entries
+ */
+async function clearExpirationCursorCache(
+  cursor: string,
+  options: ForgeSqlOrmOptions,
+): Promise<number> {
+  const cacheEntityName = options.cacheEntityName;
+  if (!cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+
+  const entityExpirationName =
+    options.cacheEntityExpirationName ?? CACHE_CONSTANTS.DEFAULT_EXPIRATION_NAME;
+  let entityQueryBuilder = kvs
+    .entity<{
+      [entityExpirationName]: number;
+    }>(cacheEntityName)
+    .query()
+    .index(entityExpirationName)
+    .where(WhereConditions.lessThan(Math.floor(DateTime.now().toSeconds())));
+
+  if (cursor) {
+    entityQueryBuilder = entityQueryBuilder.cursor(cursor);
+  }
+
+  const listResult = await entityQueryBuilder.limit(100).getMany();
+
+  if (options.logRawSqlQuery) {
+    console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
+  }
+
+  await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
+
+  if (listResult.nextCursor) {
+    return (
+      listResult.results.length + (await clearExpirationCursorCache(listResult.nextCursor, options))
+    );
+  } else {
+    return listResult.results.length;
+  }
+}
+
+/**
+ * Executes a function with retry logic and exponential backoff.
+ *
+ * @param operation - Function to execute with retry
+ * @param operationName - Name of the operation for logging
+ * @param options - ForgeSQL ORM options for logging
+ * @returns Promise that resolves to the operation result
+ */
+async function executeWithRetry<T>(operation: () => Promise<T>, operationName: string): Promise<T> {
+  let attempt = 0;
+  let delay = CACHE_CONSTANTS.INITIAL_RETRY_DELAY;
+
+  while (attempt < CACHE_CONSTANTS.MAX_RETRY_ATTEMPTS) {
+    try {
+      return await operation();
+    } catch (err: any) {
+      console.warn(`Error during ${operationName}: ${err.message}, retry ${attempt}`, err);
+      attempt++;
+
+      if (attempt >= CACHE_CONSTANTS.MAX_RETRY_ATTEMPTS) {
+        console.error(`Error during ${operationName}: ${err.message}`, err);
+        throw err;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      delay *= CACHE_CONSTANTS.RETRY_DELAY_MULTIPLIER;
+    }
+  }
+
+  throw new Error(`Maximum retry attempts exceeded for ${operationName}`);
+}
+
+/**
+ * Clears cache for a specific table.
+ * Uses cache context if available, otherwise clears immediately.
+ *
+ * @param schema - The table schema to clear cache for
+ * @param options - ForgeSQL ORM options
+ */
+export async function clearCache<T extends AnyMySqlTable>(
+  schema: T,
+  options: ForgeSqlOrmOptions,
+): Promise<void> {
+  const tableName = getTableName(schema);
+  if (cacheApplicationContext.getStore()) {
+    cacheApplicationContext.getStore()?.tables.add(tableName);
+  } else {
+    await clearTablesCache([tableName], options);
+  }
+}
+
+/**
+ * Clears cache for multiple tables with retry logic and performance logging.
+ *
+ * @param tables - Array of table names to clear cache for
+ * @param options - ForgeSQL ORM options
+ * @returns Promise that resolves when cache clearing is complete
+ */
+export async function clearTablesCache(
+  tables: string[],
+  options: ForgeSqlOrmOptions,
+): Promise<void> {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+
+  const startTime = DateTime.now();
+  let totalRecords = 0;
+
+  try {
+    totalRecords = await executeWithRetry(
+      () => clearCursorCache(tables, "", options),
+      "clearing cache",
+    );
+  } finally {
+    if (options.logRawSqlQuery) {
+      const duration = DateTime.now().toSeconds() - startTime.toSeconds();
+      console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
+    }
+  }
+}
+/**
+ * Clears expired cache entries with retry logic and performance logging.
+ *
+ * @param options - ForgeSQL ORM options
+ * @returns Promise that resolves when expired cache clearing is complete
+ */
+export async function clearExpiredCache(options: ForgeSqlOrmOptions): Promise<void> {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+
+  const startTime = DateTime.now();
+  let totalRecords = 0;
+
+  try {
+    totalRecords = await executeWithRetry(
+      () => clearExpirationCursorCache("", options),
+      "clearing expired cache",
+    );
+  } finally {
+    const duration = DateTime.now().toSeconds() - startTime.toSeconds();
+    console.info(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
+  }
+}
+
+/**
+ * Retrieves data from cache if it exists and is not expired.
+ *
+ * @param query - Query object with toSQL method
+ * @param options - ForgeSQL ORM options
+ * @returns Cached data if found and valid, undefined otherwise
+ */
+export async function getFromCache<T>(
+  query: { toSQL: () => Query },
+  options: ForgeSqlOrmOptions,
+): Promise<T | undefined> {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+
+  const entityQueryName = options.cacheEntityQueryName ?? CACHE_CONSTANTS.DEFAULT_ENTITY_QUERY_NAME;
+  const expirationName =
+    options.cacheEntityExpirationName ?? CACHE_CONSTANTS.DEFAULT_EXPIRATION_NAME;
+  const dataName = options.cacheEntityDataName ?? CACHE_CONSTANTS.DEFAULT_DATA_NAME;
+
+  const sqlQuery = query.toSQL();
+  const key = hashKey(sqlQuery);
+
+  // Skip cache if table is in cache context (will be cleared)
+  if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
+    if (options.logRawSqlQuery) {
+      console.warn(`Context contains value to clear. Skip getting from cache`);
+    }
+    return undefined;
+  }
+
+  try {
+    const cacheResult = await kvs.entity<CacheEntity>(options.cacheEntityName).get(key);
+
+    if (
+      cacheResult &&
+      (cacheResult[expirationName] as number) >= getCurrentTime() &&
+      sqlQuery.sql.toLowerCase() === cacheResult[entityQueryName]
+    ) {
+      if (options.logRawSqlQuery) {
+        console.warn(`Get value from cache, cacheKey: ${key}`);
+      }
+      const results = cacheResult[dataName];
+      return JSON.parse(results as string);
+    }
+  } catch (error: any) {
+    console.error(`Error getting from cache: ${error.message}`, error);
+  }
+
+  return undefined;
+}
+
+/**
+ * Stores query results in cache with specified TTL.
+ *
+ * @param query - Query object with toSQL method
+ * @param options - ForgeSQL ORM options
+ * @param results - Data to cache
+ * @param cacheTtl - Time to live in seconds
+ * @returns Promise that resolves when data is stored in cache
+ */
+export async function setCacheResult(
+  query: { toSQL: () => Query },
+  options: ForgeSqlOrmOptions,
+  results: unknown,
+  cacheTtl: number,
+): Promise<void> {
+  if (!options.cacheEntityName) {
+    throw new Error("cacheEntityName is not configured");
+  }
+
+  try {
+    const entityQueryName =
+      options.cacheEntityQueryName ?? CACHE_CONSTANTS.DEFAULT_ENTITY_QUERY_NAME;
+    const expirationName =
+      options.cacheEntityExpirationName ?? CACHE_CONSTANTS.DEFAULT_EXPIRATION_NAME;
+    const dataName = options.cacheEntityDataName ?? CACHE_CONSTANTS.DEFAULT_DATA_NAME;
+
+    const sqlQuery = query.toSQL();
+
+    // Skip cache if table is in cache context (will be cleared)
+    if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
+      if (options.logRawSqlQuery) {
+        console.warn(`Context contains value to clear. Skip setting from cache`);
+      }
+      return;
+    }
+
+    const key = hashKey(sqlQuery);
+
+    await kvs
+      .transact()
+      .set(
+        key,
+        {
+          [entityQueryName]: sqlQuery.sql.toLowerCase(),
+          [expirationName]: nowPlusSeconds(cacheTtl),
+          [dataName]: JSON.stringify(results),
+        },
+        { entityName: options.cacheEntityName },
+      )
+      .execute();
+
+    if (options.logRawSqlQuery) {
+      console.warn(`Store value to cache, cacheKey: ${key}`);
+    }
+  } catch (error: any) {
+    console.error(`Error setting cache: ${error.message}`, error);
+  }
+}

package/src/utils/sqlUtils.ts

@@ -74,6 +74,22 @@ export const parseDateTime = (value: string | Date, format: string): Date => {
   return result;
 };
 
+/**
+ * Helper function to validate and format Date objects using DateTime
+ * @param value - Date object to validate and format
+ * @param format - DateTime format string
+ * @returns Formatted date string
+ * @throws Error if date is invalid
+ */
+export function formatDateTime(value: Date, format: string): string {
+  const fromJSDate = DateTime.fromJSDate(value);
+  if (fromJSDate.isValid) {
+    return fromJSDate.toFormat(format);
+  } else {
+    throw new Error("Invalid Date");
+  }
+}
+
 /**
  * Gets primary keys from the schema.
  * @template T - The type of the table schema

package/src/webtriggers/clearCacheSchedulerTrigger.ts

@@ -0,0 +1,79 @@
+import { clearExpiredCache } from "../utils/cacheUtils";
+import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
+
+/**
+ * Scheduler trigger for clearing expired cache entries.
+ *
+ * This trigger should be configured as a Forge scheduler to automatically
+ * clean up expired cache entries based on their TTL (Time To Live).
+ *
+ * @param options - Optional ForgeSQL ORM configuration. If not provided,
+ *                  uses default cache settings with cacheEntityName: "cache"
+ * @returns Promise that resolves to HTTP response object
+ *
+ * @example
+ * ```typescript
+ * // In your index.ts
+ * import { clearCacheSchedulerTrigger } from "forge-sql-orm";
+ *
+ * export const clearCache = () => {
+ *   return clearCacheSchedulerTrigger({
+ *     cacheEntityName: "cache",
+ *     logRawSqlQuery: true
+ *   });
+ * };
+ * ```
+ *
+ * @example
+ * ```yaml
+ * # In manifest.yml
+ * scheduledTrigger:
+ *   - key: clear-cache-trigger
+ *     function: clearCache
+ *     interval: fiveMinute
+ *
+ * function:
+ *   - key: clearCache
+ *     handler: index.clearCache
+ * ```
+ */
+export const clearCacheSchedulerTrigger = async (options?: ForgeSqlOrmOptions) => {
+  try {
+    const newOptions: ForgeSqlOrmOptions = options ?? {
+      logRawSqlQuery: false,
+      disableOptimisticLocking: false,
+      cacheTTL: 120,
+      cacheEntityName: "cache",
+      cacheEntityQueryName: "sql",
+      cacheEntityExpirationName: "expiration",
+      cacheEntityDataName: "data",
+    };
+    if (!newOptions.cacheEntityName) {
+      throw new Error("cacheEntityName is not configured");
+    }
+    await clearExpiredCache(newOptions);
+
+    return {
+      headers: { "Content-Type": ["application/json"] },
+      statusCode: 200,
+      statusText: "OK",
+      body: JSON.stringify({
+        success: true,
+        message: "Cache cleanup completed successfully",
+        timestamp: new Date().toISOString(),
+      }),
+    };
+  } catch (error) {
+    console.error("Error during cache cleanup: ", JSON.stringify(error));
+    return {
+      headers: { "Content-Type": ["application/json"] },
+      statusCode: 500,
+      statusText: "Internal Server Error",
+      body: JSON.stringify({
+        success: false,
+        error: error instanceof Error ? error.message : "Unknown error during cache cleanup",
+        timestamp: new Date().toISOString(),
+      }),
+    };
+  }
+};