forge-sql-orm 2.1.24 → 2.1.25

package/README.md

@@ -708,10 +708,12 @@ The diagram below shows how Evict Cache works in Forge-SQL-ORM:
 
 The diagram below shows how Scheduled Expiration Cleanup works:
 
+**Note:** forge-sql-orm uses Forge KVS TTL feature (`{ ttl: { unit: "SECONDS", value: number } }`) to mark entries as expired. However, **actual deletion is asynchronous and may take up to 48 hours**. During this window, read operations may still return expired results. The scheduler trigger proactively cleans up expired entries to prevent cache growth from impacting INSERT/UPDATE performance.
+
 1. A periodic scheduler (Forge trigger) runs cache cleanup independently of data modifications.
 2. forge-sql-orm queries the cache entity by the expiration index to find entries with expiration < now.
 3. Entries are deleted in batches (up to 25 per transaction) until the page is empty; pagination is done with a cursor (e.g., 100 per page).
-4. This keeps the cache footprint small and prevents stale data accumulation.
+4. This keeps the cache footprint small and prevents stale data accumulation, especially important when cache size impacts data modification performance.
 
 ![img.png](img/umlCacheEvictScheduler1.png)
 
@@ -734,6 +736,12 @@ The diagram below shows how Cache Context works:
 **@forge/kvs Limits:**
 Please review the [official @forge/kvs quotas and limits](https://developer.atlassian.com/platform/forge/platform-quotas-and-limits/#kvs-and-custom-entity-store-quotas) before implementing caching.
 
+**TTL Limitations:**
+
+- **Maximum TTL**: The maximum supported TTL is 1 year from the time the expiry is set.
+- **Asynchronous deletion**: Expired data is not removed immediately upon expiry. Deletion may take up to 48 hours. During this window, read operations may still return expired results.
+- **Performance impact**: If cache grows large, expired entries can impact INSERT/UPDATE performance. Use the Clear Cache Scheduler Trigger to proactively clean up expired entries.
+
 **Caching Guidelines:**
 
 - Don't cache everything - be selective about what to cache
@@ -741,6 +749,7 @@ Please review the [official @forge/kvs quotas and limits](https://developer.atla
 - Consider data size and frequency of changes
 - Monitor cache usage to stay within quotas
 - Use appropriate TTL values
+- If cache growth impacts performance, configure the Clear Cache Scheduler Trigger
 
 **⚠️ Important Cache Limitations:**
 
@@ -754,10 +763,11 @@ npm install @forge/kvs -S
 
 ### Step 2: Configure Manifest
 
-Add the storage entity configuration and scheduler trigger to your `manifest.yml`:
+Add the storage entity configuration to your `manifest.yml`. The `scheduledTrigger` is **optional** - only configure it if your cache grows large and impacts INSERT/UPDATE performance:
 
 ```yaml
 modules:
+  # Optional: Only needed if cache growth impacts INSERT/UPDATE performance
   scheduledTrigger:
     - key: clear-cache-trigger
       function: clearCache
@@ -814,7 +824,7 @@ const forgeSQL = new ForgeSQL(options);
 - The `cacheEntityName` must exactly match the `name` in your manifest storage entities
 - The entity attributes (`sql`, `expiration`, `data`) are required for proper cache functionality
 - Indexes on `sql` and `expiration` improve cache lookup performance
-- Cache data is automatically cleaned up based on TTL settings
+- Cache data uses Forge KVS TTL for expiration (deletion is asynchronous, may take up to 48 hours)
 - No additional permissions are required beyond standard Forge app permissions
 
 ### Complete Setup Examples
@@ -862,6 +872,7 @@ npm install forge-sql-orm @forge/sql @forge/kvs drizzle-orm -S
 
 ```yaml
 modules:
+  # Optional: Only needed if cache growth impacts INSERT/UPDATE performance
   scheduledTrigger:
     - key: clear-cache-trigger
       function: clearCache
@@ -1681,7 +1692,7 @@ This multi-level approach provides optimal performance by checking the fastest c
 
 ### Cache Configuration
 
-The caching system uses Atlassian Forge's Custom entity store to persist cache data. Each cache entry is stored as a custom entity with automatic TTL management and efficient key-based retrieval.
+The caching system uses Atlassian Forge's Custom entity store to persist cache data. Each cache entry is stored as a custom entity with TTL management via Forge KVS. Note that expired data deletion is asynchronous and may take up to 48 hours. If cache growth impacts INSERT/UPDATE performance, use the Clear Cache Scheduler Trigger for proactive cleanup.
 
 ```typescript
 const options = {
@@ -1706,7 +1717,7 @@ const forgeSQL = new ForgeSQL(options);
 The caching system leverages Forge's Custom entity store to provide:
 
 - **Persistent Storage**: Cache data survives app restarts and deployments
-- **Automatic TTL**: Built-in expiration handling through Forge's entity lifecycle
+- **TTL Support**: Uses Forge KVS TTL feature for expiration (deletion is asynchronous, may take up to 48 hours)
 - **Efficient Retrieval**: Fast key-based lookups using Forge's optimized storage
 - **Data Serialization**: Automatic handling of complex objects and query results
 - **Batch Operations**: Efficient bulk cache operations for better performance
@@ -1905,18 +1916,18 @@ const userResolver = async (req) => {
 
 #### Local Cache (Level 1) vs Global Cache (Level 2)
 
-| Feature            | Local Cache (Level 1)                 | Global Cache (Level 2)                      |
-| ------------------ | ------------------------------------- | ------------------------------------------- |
-| **Storage**        | In-memory (Node.js process)           | Persistent (KVS Custom Entities)            |
-| **Scope**          | Single forge invocation               | Cross-invocation (between calls)            |
-| **Persistence**    | No (cleared on invocation end)        | Yes (survives app redeploy)                 |
-| **Performance**    | Very fast (memory access)             | Fast (KVS optimized storage)                |
-| **Memory Usage**   | Low (invocation-scoped)               | Higher (persistent storage)                 |
-| **Use Case**       | Invocation optimization               | Cross-invocation data sharing               |
-| **Configuration**  | None required                         | Requires KVS setup                          |
-| **TTL Support**    | No (invocation-scoped)                | Yes (automatic expiration)                  |
-| **Cache Eviction** | Automatic on DML operations           | Manual or scheduled cleanup                 |
-| **Best For**       | Repeated queries in single invocation | Frequently accessed data across invocations |
+| Feature            | Local Cache (Level 1)                 | Global Cache (Level 2)                                              |
+| ------------------ | ------------------------------------- | ------------------------------------------------------------------- |
+| **Storage**        | In-memory (Node.js process)           | Persistent (KVS Custom Entities)                                    |
+| **Scope**          | Single forge invocation               | Cross-invocation (between calls)                                    |
+| **Persistence**    | No (cleared on invocation end)        | Yes (survives app redeploy)                                         |
+| **Performance**    | Very fast (memory access)             | Fast (KVS optimized storage)                                        |
+| **Memory Usage**   | Low (invocation-scoped)               | Higher (persistent storage)                                         |
+| **Use Case**       | Invocation optimization               | Cross-invocation data sharing                                       |
+| **Configuration**  | None required                         | Requires KVS setup                                                  |
+| **TTL Support**    | No (invocation-scoped)                | Yes (TTL via Forge KVS, async deletion up to 48h)                   |
+| **Cache Eviction** | Automatic on DML operations           | Manual or scheduled cleanup (optional if cache impacts performance) |
+| **Best For**       | Repeated queries in single invocation | Frequently accessed data across invocations                         |
 
 #### Integration with Global Cache (Level 2)
 
@@ -2519,12 +2530,22 @@ SET foreign_key_checks = 1;
 
 ### 4. Clear Cache Scheduler Trigger
 
-This trigger automatically cleans up expired cache entries based on their TTL (Time To Live). It's useful for:
+This trigger automatically cleans up expired cache entries based on their TTL (Time To Live).
+
+**⚠️ Important:** While Forge KVS uses TTL to mark entries as expired, **actual deletion is asynchronous and may take up to 48 hours**. During this window, read operations may still return expired results. If your cache grows large and impacts INSERT/UPDATE performance, you should use this scheduler trigger to proactively clean up expired entries.
 
-- Automatic cache maintenance
-- Preventing cache storage from growing indefinitely
-- Ensuring optimal cache performance
-- Reducing storage costs
+**When to use:**
+
+- Your cache grows large over time
+- INSERT/UPDATE operations are slowing down due to cache size
+- You need strict expiry semantics (immediate cleanup)
+- You want to reduce storage costs proactively
+
+**When optional:**
+
+- Small cache footprint
+- No performance impact on data modifications
+- You can tolerate expired entries being returned for up to 48 hours
 
 ```typescript
 // Example usage in your Forge app
@@ -2537,9 +2558,10 @@ export const clearCache = () => {
 };
 ```
 
-Configure in `manifest.yml`:
+Configure in `manifest.yml` (optional - only if cache growth impacts INSERT/UPDATE performance):
 
 ```yaml
+# Optional: Only needed if cache growth impacts INSERT/UPDATE performance
 scheduledTrigger:
   - key: clear-cache-trigger
     function: clearCache

package/dist/utils/cacheUtils.d.ts

@@ -25,6 +25,7 @@ export declare function clearCache<T extends AnyMySqlTable>(schema: T, options:
  */
 export declare function clearTablesCache(tables: string[], options: ForgeSqlOrmOptions): Promise<void>;
 /**
+ * since https://developer.atlassian.com/platform/forge/changelog/#CHANGE-3038
  * Clears expired cache entries with retry logic and performance logging.
  *
  * @param options - ForgeSQL ORM options
@@ -34,6 +35,10 @@ export declare function clearExpiredCache(options: ForgeSqlOrmOptions): Promise<
 /**
  * Retrieves data from cache if it exists and is not expired.
  *
+ * Note: Due to Forge KVS asynchronous deletion (up to 48 hours), expired entries may still
+ * be returned. This function checks the expiration timestamp to filter out expired entries.
+ * If cache growth impacts performance, use the Clear Cache Scheduler Trigger.
+ *
  * @param query - Query object with toSQL method
  * @param options - ForgeSQL ORM options
  * @returns Cached data if found and valid, undefined otherwise
@@ -44,11 +49,18 @@ export declare function getFromCache<T>(query: {
 /**
  * Stores query results in cache with specified TTL.
  *
+ * Uses Forge KVS TTL feature to set expiration. Note that expired data deletion is asynchronous:
+ * expired data is not removed immediately upon expiry. Deletion may take up to 48 hours.
+ * During this window, read operations may still return expired results. If your app requires
+ * strict expiry semantics, consider using the Clear Cache Scheduler Trigger to proactively
+ * clean up expired entries, especially if cache growth impacts INSERT/UPDATE performance.
+ *
  * @param query - Query object with toSQL method
  * @param options - ForgeSQL ORM options
  * @param results - Data to cache
- * @param cacheTtl - Time to live in seconds
+ * @param cacheTtl - Time to live in seconds (maximum TTL is 1 year from write time)
  * @returns Promise that resolves when data is stored in cache
+ * @see https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-basic-api/#ttl
  */
 export declare function setCacheResult(query: {
     toSQL: () => Query;

package/dist/utils/cacheUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cacheUtils.d.ts","sourceRoot":"","sources":["../../src/utils/cacheUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AA4ClE;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAK5C;AAmKD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,aAAa,EACtD,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAoBf;AACD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBlF;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CA2CxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA8Cf"}
+{"version":3,"file":"cacheUtils.d.ts","sourceRoot":"","sources":["../../src/utils/cacheUtils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAoElE;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,CAK5C;AAiKD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,aAAa,EACtD,MAAM,EAAE,CAAC,EACT,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EAAE,EAChB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,IAAI,CAAC,CAiBf;AACD;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBlF;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CA2CxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,KAAK,CAAA;CAAE,EAC7B,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,OAAO,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAyCf"}

package/dist/utils/cacheUtils.js

@@ -77,6 +77,29 @@ function nowPlusSeconds(secondsToAdd) {
     const dt = luxon_1.DateTime.now().plus({ seconds: secondsToAdd });
     return Math.floor(dt.toSeconds());
 }
+/**
+ * Logs a message to console.debug when options.logCache is enabled.
+ *
+ * @param message - Message to log
+ * @param options - ForgeSQL ORM options (optional)
+ */
+function debugLog(message, options) {
+    if (options?.logCache) {
+        // eslint-disable-next-line no-console
+        console.debug(message);
+    }
+} /**
+ * Logs a message to console.debug when options.logCache is enabled.
+ *
+ * @param message - Message to log
+ * @param options - ForgeSQL ORM options (optional)
+ */
+function warnLog(message, options) {
+    if (options?.logCache) {
+        // eslint-disable-next-line no-console
+        console.warn(message);
+    }
+}
 /**
  * Generates a hash key for a query based on its SQL and parameters.
  *
@@ -94,16 +117,14 @@ function hashKey(query) {
  *
  * @param results - Array of cache entries to delete
  * @param cacheEntityName - Name of the cache entity
+ * @param options - Forge SQL ORM properties
  * @returns Promise that resolves when all deletions are complete
  */
-async function deleteCacheEntriesInBatches(results, cacheEntityName) {
+async function deleteCacheEntriesInBatches(results, cacheEntityName, options) {
     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_1.kvs.transact();
-        for (const result of batch) {
-            transactionBuilder = transactionBuilder.delete(result.key, { entityName: cacheEntityName });
-        }
-        await transactionBuilder.execute();
+        const batchResult = await kvs_1.kvs.batchDelete(batch.map((result) => ({ key: result.key, entityName: cacheEntityName })));
+        batchResult.failedKeys.forEach((failedKey) => warnLog(JSON.stringify(failedKey), options));
     }
 }
 /**
@@ -134,11 +155,8 @@ async function clearCursorCache(tables, cursor, options) {
         entityQueryBuilder = entityQueryBuilder.cursor(cursor);
     }
     const listResult = await entityQueryBuilder.limit(100).getMany();
-    if (options.logCache) {
-        // eslint-disable-next-line no-console
-        console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
-    }
-    await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
+    debugLog(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`, options);
+    await deleteCacheEntriesInBatches(listResult.results, cacheEntityName, options);
     if (listResult.nextCursor) {
         return (listResult.results.length + (await clearCursorCache(tables, listResult.nextCursor, options)));
     }
@@ -168,10 +186,7 @@ async function clearExpirationCursorCache(cursor, options) {
         entityQueryBuilder = entityQueryBuilder.cursor(cursor);
     }
     const listResult = await entityQueryBuilder.limit(100).getMany();
-    if (options.logCache) {
-        // eslint-disable-next-line no-console
-        console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
-    }
+    debugLog(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`, options);
     await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
     if (listResult.nextCursor) {
         return (listResult.results.length + (await clearExpirationCursorCache(listResult.nextCursor, options)));
@@ -243,14 +258,12 @@ async function clearTablesCache(tables, options) {
         totalRecords = await executeWithRetry(() => clearCursorCache(tables, "", options), "clearing cache");
     }
     finally {
-        if (options.logCache) {
-            const duration = luxon_1.DateTime.now().toSeconds() - startTime.toSeconds();
-            // eslint-disable-next-line no-console
-            console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
-        }
+        const duration = luxon_1.DateTime.now().toSeconds() - startTime.toSeconds();
+        debugLog(`Cleared ${totalRecords} cache records in ${duration} seconds`, options);
     }
 }
 /**
+ * since https://developer.atlassian.com/platform/forge/changelog/#CHANGE-3038
  * Clears expired cache entries with retry logic and performance logging.
  *
  * @param options - ForgeSQL ORM options
@@ -267,15 +280,16 @@ async function clearExpiredCache(options) {
     }
     finally {
         const duration = luxon_1.DateTime.now().toSeconds() - startTime.toSeconds();
-        if (options?.logCache) {
-            // eslint-disable-next-line no-console
-            console.debug(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
-        }
+        debugLog(`Cleared ${totalRecords} expired cache records in ${duration} seconds`, options);
     }
 }
 /**
  * Retrieves data from cache if it exists and is not expired.
  *
+ * Note: Due to Forge KVS asynchronous deletion (up to 48 hours), expired entries may still
+ * be returned. This function checks the expiration timestamp to filter out expired entries.
+ * If cache growth impacts performance, use the Clear Cache Scheduler Trigger.
+ *
  * @param query - Query object with toSQL method
  * @param options - ForgeSQL ORM options
  * @returns Cached data if found and valid, undefined otherwise
@@ -291,23 +305,21 @@ async function getFromCache(query, options) {
     const key = hashKey(sqlQuery);
     // Skip cache if table is in cache context (will be cleared)
     if (await (0, cacheContextUtils_1.isTableContainsTableInCacheContext)(sqlQuery.sql, options)) {
-        if (options.logCache) {
-            // eslint-disable-next-line no-console
-            console.warn(`Context contains value to clear. Skip getting from cache`);
-        }
+        debugLog("Context contains value to clear. Skip getting from cache", options);
         return undefined;
     }
     try {
         const cacheResult = await kvs_1.kvs.entity(options.cacheEntityName).get(key);
-        if (cacheResult &&
-            cacheResult[expirationName] >= getCurrentTime() &&
-            (0, cacheTableUtils_1.extractBacktickedValues)(sqlQuery.sql, options) === cacheResult[entityQueryName]) {
-            if (options.logCache) {
-                // eslint-disable-next-line no-console
-                console.warn(`Get value from cache, cacheKey: ${key}`);
+        if (cacheResult) {
+            if (cacheResult[expirationName] >= getCurrentTime() &&
+                (0, cacheTableUtils_1.extractBacktickedValues)(sqlQuery.sql, options) === cacheResult[entityQueryName]) {
+                debugLog(`Get value from cache, cacheKey: ${key}`, options);
+                const results = cacheResult[dataName];
+                return JSON.parse(results);
+            }
+            else {
+                debugLog(`Expired cache entry still exists (will be automatically removed within 48 hours per Forge KVS TTL documentation), cacheKey: ${key}`, options);
             }
-            const results = cacheResult[dataName];
-            return JSON.parse(results);
         }
     }
     catch (error) {
@@ -319,11 +331,18 @@ async function getFromCache(query, options) {
 /**
  * Stores query results in cache with specified TTL.
  *
+ * Uses Forge KVS TTL feature to set expiration. Note that expired data deletion is asynchronous:
+ * expired data is not removed immediately upon expiry. Deletion may take up to 48 hours.
+ * During this window, read operations may still return expired results. If your app requires
+ * strict expiry semantics, consider using the Clear Cache Scheduler Trigger to proactively
+ * clean up expired entries, especially if cache growth impacts INSERT/UPDATE performance.
+ *
  * @param query - Query object with toSQL method
  * @param options - ForgeSQL ORM options
  * @param results - Data to cache
- * @param cacheTtl - Time to live in seconds
+ * @param cacheTtl - Time to live in seconds (maximum TTL is 1 year from write time)
  * @returns Promise that resolves when data is stored in cache
+ * @see https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-basic-api/#ttl
  */
 async function setCacheResult(query, options, results, cacheTtl) {
     if (!options.cacheEntityName) {
@@ -336,10 +355,7 @@ async function setCacheResult(query, options, results, cacheTtl) {
         const sqlQuery = query.toSQL();
         // Skip cache if table is in cache context (will be cleared)
         if (await (0, cacheContextUtils_1.isTableContainsTableInCacheContext)(sqlQuery.sql, options)) {
-            if (options.logCache) {
-                // eslint-disable-next-line no-console
-                console.warn(`Context contains value to clear. Skip setting from cache`);
-            }
+            debugLog("Context contains value to clear. Skip setting from cache", options);
             return;
         }
         const key = hashKey(sqlQuery);
@@ -347,14 +363,11 @@ async function setCacheResult(query, options, results, cacheTtl) {
             .transact()
             .set(key, {
             [entityQueryName]: (0, cacheTableUtils_1.extractBacktickedValues)(sqlQuery.sql, options),
-            [expirationName]: nowPlusSeconds(cacheTtl),
+            [expirationName]: nowPlusSeconds(cacheTtl + 2),
             [dataName]: JSON.stringify(results),
-        }, { entityName: options.cacheEntityName })
+        }, { entityName: options.cacheEntityName }, { ttl: { value: cacheTtl, unit: "SECONDS" } })
             .execute();
-        if (options.logCache) {
-            // eslint-disable-next-line no-console
-            console.warn(`Store value to cache, cacheKey: ${key}`);
-        }
+        debugLog(`Store value to cache, cacheKey: ${key}`, options);
     }
     catch (error) {
         // eslint-disable-next-line no-console

package/dist/utils/cacheUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"cacheUtils.js","sourceRoot":"","sources":["../../src/utils/cacheUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cacheUtils.js","sourceRoot":"","sources":["../../src/utils/cacheUtils.ts"],"names":[],"mappings":"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"}

package/dist/webtriggers/clearCacheSchedulerTrigger.d.ts

@@ -1,9 +1,27 @@
 import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
 /**
- * Scheduler trigger for clearing expired cache entries.
+ * Scheduler trigger for proactively 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).
+ * **Why this trigger is needed:**
+ *
+ * While forge-sql-orm uses Forge KVS TTL feature to mark entries as expired, **actual deletion
+ * is asynchronous and may take up to 48 hours**. During this window, expired entries remain in
+ * storage and can impact INSERT/UPDATE performance if the cache grows large.
+ *
+ * This scheduler trigger proactively cleans up expired entries by querying the expiration index
+ * and deleting entries where expiration < now, preventing cache growth from impacting data
+ * modification operations.
+ *
+ * **When to use:**
+ * - Your cache grows large over time
+ * - INSERT/UPDATE operations are slowing down due to cache size
+ * - You need strict expiry semantics (immediate cleanup)
+ * - You want to reduce storage costs proactively
+ *
+ * **When optional:**
+ * - Small cache footprint
+ * - No performance impact on data modifications
+ * - You can tolerate expired entries being returned for up to 48 hours
  *
  * @note This function is automatically disabled in production environments and will return a 500 error if called.
  *
@@ -26,7 +44,7 @@ import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
  *
  * @example
  * ```yaml
- * # In manifest.yml
+ * # In manifest.yml (optional - only if cache growth impacts INSERT/UPDATE performance)
  * scheduledTrigger:
  *   - key: clear-cache-trigger
  *     function: clearCache
@@ -36,6 +54,8 @@ import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
  *   - key: clearCache
  *     handler: index.clearCache
  * ```
+ *
+ * @see https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-basic-api/#ttl
  */
 export declare const clearCacheSchedulerTrigger: (options?: ForgeSqlOrmOptions) => Promise<{
     headers: {

package/dist/webtriggers/clearCacheSchedulerTrigger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clearCacheSchedulerTrigger.d.ts","sourceRoot":"","sources":["../../src/webtriggers/clearCacheSchedulerTrigger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,0BAA0B,GAAU,UAAU,kBAAkB;;;;;;;EAwC5E,CAAC"}
+{"version":3,"file":"clearCacheSchedulerTrigger.d.ts","sourceRoot":"","sources":["../../src/webtriggers/clearCacheSchedulerTrigger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,0BAA0B,GAAU,UAAU,kBAAkB;;;;;;;EAwC5E,CAAC"}

package/dist/webtriggers/clearCacheSchedulerTrigger.js

@@ -3,10 +3,28 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearCacheSchedulerTrigger = void 0;
 const cacheUtils_1 = require("../utils/cacheUtils");
 /**
- * Scheduler trigger for clearing expired cache entries.
+ * Scheduler trigger for proactively 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).
+ * **Why this trigger is needed:**
+ *
+ * While forge-sql-orm uses Forge KVS TTL feature to mark entries as expired, **actual deletion
+ * is asynchronous and may take up to 48 hours**. During this window, expired entries remain in
+ * storage and can impact INSERT/UPDATE performance if the cache grows large.
+ *
+ * This scheduler trigger proactively cleans up expired entries by querying the expiration index
+ * and deleting entries where expiration < now, preventing cache growth from impacting data
+ * modification operations.
+ *
+ * **When to use:**
+ * - Your cache grows large over time
+ * - INSERT/UPDATE operations are slowing down due to cache size
+ * - You need strict expiry semantics (immediate cleanup)
+ * - You want to reduce storage costs proactively
+ *
+ * **When optional:**
+ * - Small cache footprint
+ * - No performance impact on data modifications
+ * - You can tolerate expired entries being returned for up to 48 hours
  *
  * @note This function is automatically disabled in production environments and will return a 500 error if called.
  *
@@ -29,7 +47,7 @@ const cacheUtils_1 = require("../utils/cacheUtils");
  *
  * @example
  * ```yaml
- * # In manifest.yml
+ * # In manifest.yml (optional - only if cache growth impacts INSERT/UPDATE performance)
  * scheduledTrigger:
  *   - key: clear-cache-trigger
  *     function: clearCache
@@ -39,6 +57,8 @@ const cacheUtils_1 = require("../utils/cacheUtils");
  *   - key: clearCache
  *     handler: index.clearCache
  * ```
+ *
+ * @see https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-basic-api/#ttl
  */
 const clearCacheSchedulerTrigger = async (options) => {
     try {

package/dist/webtriggers/clearCacheSchedulerTrigger.js.map

@@ -1 +1 @@
-{"version":3,"file":"clearCacheSchedulerTrigger.js","sourceRoot":"","sources":["../../src/webtriggers/clearCacheSchedulerTrigger.ts"],"names":[],"mappings":";;;AAAA,oDAAwD;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACI,MAAM,0BAA0B,GAAG,KAAK,EAAE,OAA4B,EAAE,EAAE;IAC/E,IAAI,CAAC;QACH,MAAM,UAAU,GAAuB,OAAO,IAAI;YAChD,cAAc,EAAE,KAAK;YACrB,wBAAwB,EAAE,KAAK;YAC/B,QAAQ,EAAE,GAAG;YACb,eAAe,EAAE,OAAO;YACxB,oBAAoB,EAAE,KAAK;YAC3B,yBAAyB,EAAE,YAAY;YACvC,mBAAmB,EAAE,MAAM;SAC5B,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,eAAe,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,IAAA,8BAAiB,EAAC,UAAU,CAAC,CAAC;QAEpC,OAAO;YACL,OAAO,EAAE,EAAE,cAAc,EAAE,CAAC,kBAAkB,CAAC,EAAE;YACjD,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,IAAI;YAChB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,sCAAsC;gBAC/C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC;SACH,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,OAAO;YACL,OAAO,EAAE,EAAE,cAAc,EAAE,CAAC,kBAAkB,CAAC,EAAE;YACjD,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,uBAAuB;YACnC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,oCAAoC;gBACpF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC;SACH,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAxCW,QAAA,0BAA0B,8BAwCrC"}
+{"version":3,"file":"clearCacheSchedulerTrigger.js","sourceRoot":"","sources":["../../src/webtriggers/clearCacheSchedulerTrigger.ts"],"names":[],"mappings":";;;AAAA,oDAAwD;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACI,MAAM,0BAA0B,GAAG,KAAK,EAAE,OAA4B,EAAE,EAAE;IAC/E,IAAI,CAAC;QACH,MAAM,UAAU,GAAuB,OAAO,IAAI;YAChD,cAAc,EAAE,KAAK;YACrB,wBAAwB,EAAE,KAAK;YAC/B,QAAQ,EAAE,GAAG;YACb,eAAe,EAAE,OAAO;YACxB,oBAAoB,EAAE,KAAK;YAC3B,yBAAyB,EAAE,YAAY;YACvC,mBAAmB,EAAE,MAAM;SAC5B,CAAC;QACF,IAAI,CAAC,UAAU,CAAC,eAAe,EAAE,CAAC;YAChC,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,IAAA,8BAAiB,EAAC,UAAU,CAAC,CAAC;QAEpC,OAAO;YACL,OAAO,EAAE,EAAE,cAAc,EAAE,CAAC,kBAAkB,CAAC,EAAE;YACjD,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,IAAI;YAChB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,sCAAsC;gBAC/C,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC;SACH,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,8BAA8B,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACrE,OAAO;YACL,OAAO,EAAE,EAAE,cAAc,EAAE,CAAC,kBAAkB,CAAC,EAAE;YACjD,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,uBAAuB;YACnC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,oCAAoC;gBACpF,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC;SACH,CAAC;IACJ,CAAC;AACH,CAAC,CAAC;AAxCW,QAAA,0BAA0B,8BAwCrC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-sql-orm",
-  "version": "2.1.24",
+  "version": "2.1.25",
   "description": "Drizzle ORM integration for Atlassian @forge/sql. Provides a custom driver, schema migration, two levels of caching (local and global via @forge/kvs), optimistic locking, and query analysis.",
   "main": "dist/index.js",
   "homepage": "https://github.com/forge-sql-orm/forge-sql-orm#readme",
@@ -27,9 +27,9 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/luxon": "^3.7.1",
-    "@types/node": "^25.2.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
+    "@types/node": "^25.4.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
     "@vitest/coverage-v8": "^4.0.18",
     "@vitest/ui": "^4.0.18",
     "eslint": "^9.39.2",
@@ -37,7 +37,7 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-vitest": "^0.5.4",
     "husky": "^9.1.7",
-    "knip": "^5.83.0",
+    "knip": "^5.86.0",
     "patch-package": "^8.0.1",
     "prettier": "^3.8.1",
     "ts-node": "^10.9.2",
@@ -71,15 +71,15 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@forge/sql": "^3.0.17",
+    "@forge/sql": "^3.0.19",
     "drizzle-orm": "^0.45.1"
   },
   "optionalDependencies": {
-    "@forge/kvs": "^1.2.5"
+    "@forge/kvs": "^1.4.0"
   },
   "dependencies": {
-    "@forge/api": "^7.0.1",
-    "@forge/events": "^2.0.17",
+    "@forge/api": "^7.1.0",
+    "@forge/events": "^2.1.0",
     "luxon": "^3.7.2",
     "node-sql-parser": "^5.4.0"
   },

package/src/utils/cacheUtils.ts

@@ -48,6 +48,30 @@ function nowPlusSeconds(secondsToAdd: number): number {
   return Math.floor(dt.toSeconds());
 }
 
+/**
+ * Logs a message to console.debug when options.logCache is enabled.
+ *
+ * @param message - Message to log
+ * @param options - ForgeSQL ORM options (optional)
+ */
+function debugLog(message: string, options?: ForgeSqlOrmOptions): void {
+  if (options?.logCache) {
+    // eslint-disable-next-line no-console
+    console.debug(message);
+  }
+} /**
+ * Logs a message to console.debug when options.logCache is enabled.
+ *
+ * @param message - Message to log
+ * @param options - ForgeSQL ORM options (optional)
+ */
+function warnLog(message: string, options?: ForgeSqlOrmOptions): void {
+  if (options?.logCache) {
+    // eslint-disable-next-line no-console
+    console.warn(message);
+  }
+}
+
 /**
  * Generates a hash key for a query based on its SQL and parameters.
  *
@@ -66,19 +90,20 @@ export function hashKey(query: Query): string {
  *
  * @param results - Array of cache entries to delete
  * @param cacheEntityName - Name of the cache entity
+ * @param options - Forge SQL ORM properties
  * @returns Promise that resolves when all deletions are complete
  */
 async function deleteCacheEntriesInBatches(
   results: Array<{ key: string }>,
   cacheEntityName: string,
+  options?: ForgeSqlOrmOptions,
 ): 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();
-    for (const result of batch) {
-      transactionBuilder = transactionBuilder.delete(result.key, { entityName: cacheEntityName });
-    }
-    await transactionBuilder.execute();
+    const batchResult = await kvs.batchDelete(
+      batch.map((result) => ({ key: result.key, entityName: cacheEntityName })),
+    );
+    batchResult.failedKeys.forEach((failedKey) => warnLog(JSON.stringify(failedKey), options));
   }
 }
 
@@ -124,12 +149,9 @@ async function clearCursorCache(
 
   const listResult = await entityQueryBuilder.limit(100).getMany();
 
-  if (options.logCache) {
-    // eslint-disable-next-line no-console
-    console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
-  }
+  debugLog(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`, options);
 
-  await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
+  await deleteCacheEntriesInBatches(listResult.results, cacheEntityName, options);
 
   if (listResult.nextCursor) {
     return (
@@ -172,10 +194,10 @@ async function clearExpirationCursorCache(
 
   const listResult = await entityQueryBuilder.limit(100).getMany();
 
-  if (options.logCache) {
-    // eslint-disable-next-line no-console
-    console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
-  }
+  debugLog(
+    `clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`,
+    options,
+  );
 
   await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
 
@@ -265,14 +287,12 @@ export async function clearTablesCache(
       "clearing cache",
     );
   } finally {
-    if (options.logCache) {
-      const duration = DateTime.now().toSeconds() - startTime.toSeconds();
-      // eslint-disable-next-line no-console
-      console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
-    }
+    const duration = DateTime.now().toSeconds() - startTime.toSeconds();
+    debugLog(`Cleared ${totalRecords} cache records in ${duration} seconds`, options);
   }
 }
 /**
+ * since https://developer.atlassian.com/platform/forge/changelog/#CHANGE-3038
  * Clears expired cache entries with retry logic and performance logging.
  *
  * @param options - ForgeSQL ORM options
@@ -293,16 +313,17 @@ export async function clearExpiredCache(options: ForgeSqlOrmOptions): Promise<vo
     );
   } finally {
     const duration = DateTime.now().toSeconds() - startTime.toSeconds();
-    if (options?.logCache) {
-      // eslint-disable-next-line no-console
-      console.debug(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
-    }
+    debugLog(`Cleared ${totalRecords} expired cache records in ${duration} seconds`, options);
   }
 }
 
 /**
  * Retrieves data from cache if it exists and is not expired.
  *
+ * Note: Due to Forge KVS asynchronous deletion (up to 48 hours), expired entries may still
+ * be returned. This function checks the expiration timestamp to filter out expired entries.
+ * If cache growth impacts performance, use the Clear Cache Scheduler Trigger.
+ *
  * @param query - Query object with toSQL method
  * @param options - ForgeSQL ORM options
  * @returns Cached data if found and valid, undefined otherwise
@@ -325,27 +346,27 @@ export async function getFromCache<T>(
 
   // Skip cache if table is in cache context (will be cleared)
   if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-    if (options.logCache) {
-      // eslint-disable-next-line no-console
-      console.warn(`Context contains value to clear. Skip getting from cache`);
-    }
+    debugLog("Context contains value to clear. Skip getting from cache", options);
     return undefined;
   }
 
   try {
     const cacheResult = await kvs.entity<CacheEntity>(options.cacheEntityName).get(key);
 
-    if (
-      cacheResult &&
-      (cacheResult[expirationName] as number) >= getCurrentTime() &&
-      extractBacktickedValues(sqlQuery.sql, options) === cacheResult[entityQueryName]
-    ) {
-      if (options.logCache) {
-        // eslint-disable-next-line no-console
-        console.warn(`Get value from cache, cacheKey: ${key}`);
+    if (cacheResult) {
+      if (
+        (cacheResult[expirationName] as number) >= getCurrentTime() &&
+        extractBacktickedValues(sqlQuery.sql, options) === cacheResult[entityQueryName]
+      ) {
+        debugLog(`Get value from cache, cacheKey: ${key}`, options);
+        const results = cacheResult[dataName];
+        return JSON.parse(results as string);
+      } else {
+        debugLog(
+          `Expired cache entry still exists (will be automatically removed within 48 hours per Forge KVS TTL documentation), cacheKey: ${key}`,
+          options,
+        );
       }
-      const results = cacheResult[dataName];
-      return JSON.parse(results as string);
     }
   } catch (error: any) {
     // eslint-disable-next-line no-console
@@ -358,11 +379,18 @@ export async function getFromCache<T>(
 /**
  * Stores query results in cache with specified TTL.
  *
+ * Uses Forge KVS TTL feature to set expiration. Note that expired data deletion is asynchronous:
+ * expired data is not removed immediately upon expiry. Deletion may take up to 48 hours.
+ * During this window, read operations may still return expired results. If your app requires
+ * strict expiry semantics, consider using the Clear Cache Scheduler Trigger to proactively
+ * clean up expired entries, especially if cache growth impacts INSERT/UPDATE performance.
+ *
  * @param query - Query object with toSQL method
  * @param options - ForgeSQL ORM options
  * @param results - Data to cache
- * @param cacheTtl - Time to live in seconds
+ * @param cacheTtl - Time to live in seconds (maximum TTL is 1 year from write time)
  * @returns Promise that resolves when data is stored in cache
+ * @see https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-basic-api/#ttl
  */
 export async function setCacheResult(
   query: { toSQL: () => Query },
@@ -385,10 +413,7 @@ export async function setCacheResult(
 
     // Skip cache if table is in cache context (will be cleared)
     if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-      if (options.logCache) {
-        // eslint-disable-next-line no-console
-        console.warn(`Context contains value to clear. Skip setting from cache`);
-      }
+      debugLog("Context contains value to clear. Skip setting from cache", options);
       return;
     }
 
@@ -400,17 +425,15 @@ export async function setCacheResult(
         key,
         {
           [entityQueryName]: extractBacktickedValues(sqlQuery.sql, options),
-          [expirationName]: nowPlusSeconds(cacheTtl),
+          [expirationName]: nowPlusSeconds(cacheTtl + 2),
           [dataName]: JSON.stringify(results),
         },
         { entityName: options.cacheEntityName },
+        { ttl: { value: cacheTtl, unit: "SECONDS" } },
       )
       .execute();
 
-    if (options.logCache) {
-      // eslint-disable-next-line no-console
-      console.warn(`Store value to cache, cacheKey: ${key}`);
-    }
+    debugLog(`Store value to cache, cacheKey: ${key}`, options);
   } catch (error: any) {
     // eslint-disable-next-line no-console
     console.error(`Error setting cache: ${error.message}`, error);

package/src/webtriggers/clearCacheSchedulerTrigger.ts

@@ -2,10 +2,28 @@ import { clearExpiredCache } from "../utils/cacheUtils";
 import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
 
 /**
- * Scheduler trigger for clearing expired cache entries.
+ * Scheduler trigger for proactively 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).
+ * **Why this trigger is needed:**
+ *
+ * While forge-sql-orm uses Forge KVS TTL feature to mark entries as expired, **actual deletion
+ * is asynchronous and may take up to 48 hours**. During this window, expired entries remain in
+ * storage and can impact INSERT/UPDATE performance if the cache grows large.
+ *
+ * This scheduler trigger proactively cleans up expired entries by querying the expiration index
+ * and deleting entries where expiration < now, preventing cache growth from impacting data
+ * modification operations.
+ *
+ * **When to use:**
+ * - Your cache grows large over time
+ * - INSERT/UPDATE operations are slowing down due to cache size
+ * - You need strict expiry semantics (immediate cleanup)
+ * - You want to reduce storage costs proactively
+ *
+ * **When optional:**
+ * - Small cache footprint
+ * - No performance impact on data modifications
+ * - You can tolerate expired entries being returned for up to 48 hours
  *
  * @note This function is automatically disabled in production environments and will return a 500 error if called.
  *
@@ -28,7 +46,7 @@ import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
  *
  * @example
  * ```yaml
- * # In manifest.yml
+ * # In manifest.yml (optional - only if cache growth impacts INSERT/UPDATE performance)
  * scheduledTrigger:
  *   - key: clear-cache-trigger
  *     function: clearCache
@@ -38,6 +56,8 @@ import { ForgeSqlOrmOptions } from "../core/ForgeSQLQueryBuilder";
  *   - key: clearCache
  *     handler: index.clearCache
  * ```
+ *
+ * @see https://developer.atlassian.com/platform/forge/runtime-reference/storage-api-basic-api/#ttl
  */
 export const clearCacheSchedulerTrigger = async (options?: ForgeSqlOrmOptions) => {
   try {