forge-sql-orm 2.1.23 → 2.1.25

package/src/utils/forgeDriverProxy.ts

@@ -16,6 +16,42 @@ const QUERY_ERROR_CODES = {
  */
 const STATEMENTS_SUMMARY_DELAY_MS = 200;
 
+/**
+ * Checks if error is a timeout or out-of-memory error.
+ */
+function isQueryError(error: any): { isTimeout: boolean; isOutOfMemory: boolean } {
+  const isTimeout = error?.code === QUERY_ERROR_CODES.TIMEOUT;
+  const isOutOfMemory = error?.context?.debug?.errno === QUERY_ERROR_CODES.OUT_OF_MEMORY_ERRNO;
+  return { isTimeout, isOutOfMemory };
+}
+
+/**
+ * Handles timeout or out-of-memory errors by analyzing the query.
+ */
+async function handleQueryError(
+  queryStartTime: number,
+  forgeSqlOperation: ForgeSqlOperation,
+  isTimeout: boolean,
+): Promise<void> {
+  // Wait for CLUSTER_STATEMENTS_SUMMARY to be populated with our failed query data
+  await new Promise((resolve) => setTimeout(resolve, STATEMENTS_SUMMARY_DELAY_MS));
+
+  const queryEndTime = Date.now();
+  const queryDuration = queryEndTime - queryStartTime;
+  const errorType: "OOM" | "TIMEOUT" = isTimeout ? "TIMEOUT" : "OOM";
+
+  if (isTimeout) {
+    // eslint-disable-next-line no-console
+    console.error(` TIMEOUT detected - Query exceeded time limit`);
+  } else {
+    // eslint-disable-next-line no-console
+    console.error(`OUT OF MEMORY detected - Query exceeded memory limit`);
+  }
+
+  // Analyze the failed query using CLUSTER_STATEMENTS_SUMMARY
+  await handleErrorsWithPlan(forgeSqlOperation, queryDuration, errorType);
+}
+
 /**
  * Creates a proxy for the forgeDriver that injects SQL hints and handles query analysis
  * @param forgeSqlOperation - The ForgeSQL operation instance
@@ -51,28 +87,10 @@ export function createForgeDriverProxy(
       // Execute the query with injected hints
       return await forgeDriver(modifiedQuery, params, method);
     } catch (error: any) {
-      // Check if this is a timeout or out-of-memory error that we want to analyze
-      const isTimeoutError = error.code === QUERY_ERROR_CODES.TIMEOUT;
-      const isOutOfMemoryError =
-        error?.context?.debug?.errno === QUERY_ERROR_CODES.OUT_OF_MEMORY_ERRNO;
-
-      if (isTimeoutError || isOutOfMemoryError) {
-        // Wait for CLUSTER_STATEMENTS_SUMMARY to be populated with our failed query data
-        await new Promise((resolve) => setTimeout(resolve, STATEMENTS_SUMMARY_DELAY_MS));
+      const { isTimeout, isOutOfMemory } = isQueryError(error);
 
-        const queryEndTime = Date.now();
-        const queryDuration = queryEndTime - queryStartTime;
-        let errorType: "OOM" | "TIMEOUT" = "TIMEOUT";
-        if (isTimeoutError) {
-          // eslint-disable-next-line no-console
-          console.error(` TIMEOUT detected - Query exceeded time limit`);
-        } else {
-          // eslint-disable-next-line no-console
-          console.error(`OUT OF MEMORY detected - Query exceeded memory limit`);
-          errorType = "OOM";
-        }
-        // Analyze the failed query using CLUSTER_STATEMENTS_SUMMARY
-        await handleErrorsWithPlan(forgeSqlOperation, queryDuration, errorType);
+      if (isTimeout || isOutOfMemory) {
+        await handleQueryError(queryStartTime, forgeSqlOperation, isTimeout);
       }
 
       // Log SQL error details if requested

package/src/utils/sqlHints.ts

@@ -26,38 +26,33 @@ export function injectSqlHints(query: string, hints?: SqlHints): string {
   // Normalize the query for easier matching
   const normalizedQuery = query.trim().toUpperCase();
 
-  // Get the appropriate hints based on query type
+  // Map query types to their hints
+  const queryTypeMap: Record<string, string[] | undefined> = {
+    SELECT: hints.select,
+    INSERT: hints.insert,
+    UPDATE: hints.update,
+    DELETE: hints.delete,
+  };
+
+  // Find matching query type and get hints
   let queryHints: string[] | undefined;
-
-  if (normalizedQuery.startsWith("SELECT")) {
-    queryHints = hints.select;
-  } else if (normalizedQuery.startsWith("INSERT")) {
-    queryHints = hints.insert;
-  } else if (normalizedQuery.startsWith("UPDATE")) {
-    queryHints = hints.update;
-  } else if (normalizedQuery.startsWith("DELETE")) {
-    queryHints = hints.delete;
+  let queryPrefix: string | null = null;
+
+  for (const [type, typeHints] of Object.entries(queryTypeMap)) {
+    if (normalizedQuery.startsWith(type)) {
+      queryPrefix = type;
+      queryHints = typeHints;
+      break;
+    }
   }
 
   // If no hints for this query type, return original query
-  if (!queryHints || queryHints.length === 0) {
+  if (!queryHints || queryHints.length === 0 || !queryPrefix) {
     return query;
   }
 
-  // Join all hints with spaces
+  // Join all hints with spaces and inject into query
   const hintsString = queryHints.join(" ");
-
-  // Inject hints into the query
-  if (normalizedQuery.startsWith("SELECT")) {
-    return `SELECT /*+ ${hintsString} */ ${query.substring(6)}`;
-  } else if (normalizedQuery.startsWith("INSERT")) {
-    return `INSERT /*+ ${hintsString} */ ${query.substring(6)}`;
-  } else if (normalizedQuery.startsWith("UPDATE")) {
-    return `UPDATE /*+ ${hintsString} */ ${query.substring(6)}`;
-  } else if (normalizedQuery.startsWith("DELETE")) {
-    return `DELETE /*+ ${hintsString} */ ${query.substring(6)}`;
-  }
-
-  // If no match found, return original query
-  return query;
+  const prefixLength = queryPrefix.length;
+  return `${queryPrefix} /*+ ${hintsString} */ ${query.substring(prefixLength)}`;
 }

package/src/utils/sqlUtils.ts

@@ -1,3 +1,4 @@
+// qlty-ignore: +qlty:file-complexity
 import {
   and,
   AnyColumn,
@@ -60,40 +61,46 @@ interface ConfigBuilderData {
   [key: string]: any;
 }
 
+/**
+ * Parses a string value using multiple DateTime parsers.
+ */
+function parseStringToDate(value: string, format: string): Date {
+  // 1. Try to parse using the provided format (strict mode)
+  const dt = DateTime.fromFormat(value, format);
+  if (dt.isValid) {
+    return dt.toJSDate();
+  }
+
+  // 2. Try to parse as SQL string
+  const sqlDt = DateTime.fromSQL(value);
+  if (sqlDt.isValid) {
+    return sqlDt.toJSDate();
+  }
+
+  // 3. Try to parse as RFC2822 string
+  const isoDt = DateTime.fromRFC2822(value);
+  if (isoDt.isValid) {
+    return isoDt.toJSDate();
+  }
+
+  // 4. Fallback: use native Date constructor
+  return new Date(value);
+}
+
 /**
  * Parses a date string into a Date object using the specified format
  * @param value - The date string to parse or Date
  * @param format - The format to use for parsing
  * @returns Date object
  */
-
 export const parseDateTime = (value: string | Date, format: string): Date => {
   let result: Date;
   if (value instanceof Date) {
     result = value;
   } else {
-    // 1. Try to parse using the provided format (strict mode)
-    const dt = DateTime.fromFormat(value, format);
-    if (dt.isValid) {
-      result = dt.toJSDate();
-    } else {
-      // 2. Try to parse as SQL string
-      const sqlDt = DateTime.fromSQL(value);
-      if (sqlDt.isValid) {
-        result = sqlDt.toJSDate();
-      } else {
-        // 3. Try to parse as RFC2822 string
-        const isoDt = DateTime.fromRFC2822(value);
-        if (isoDt.isValid) {
-          result = isoDt.toJSDate();
-        } else {
-          // 4. Fallback: use native Date constructor
-          result = new Date(value);
-        }
-      }
-    }
+    result = parseStringToDate(value, format);
   }
-  // 4. Ensure the result is a valid Date object
+  // Ensure the result is a valid Date object
   if (Number.isNaN(result.getTime())) {
     result = new Date(value);
   }
@@ -667,38 +674,61 @@ export function applyFromDriverTransform<T, TSelection>(
   });
 }
 
+/**
+ * Checks if an object is a plain object (not Date, Array, etc.).
+ */
+function isPlainObject(obj: unknown): boolean {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    (!obj.constructor || obj.constructor.name === "Object")
+  );
+}
+
+/**
+ * Processes a single value in the null branches processing.
+ */
+function processValueEntry(
+  key: string,
+  value: unknown,
+  result: Record<string, unknown>,
+  allNull: { value: boolean },
+): void {
+  if (value === null || value === undefined) {
+    result[key] = null;
+    return;
+  }
+
+  if (typeof value === "object" && isPlainObject(value)) {
+    const processed = processNullBranches(value as Record<string, unknown>);
+    result[key] = processed;
+    if (processed !== null) {
+      allNull.value = false;
+    }
+  } else {
+    result[key] = value;
+    allNull.value = false;
+  }
+}
+
 function processNullBranches(obj: Record<string, unknown>): Record<string, unknown> | null {
   if (obj === null || typeof obj !== "object") {
     return obj;
   }
 
   // Skip built-in objects like Date, Array, etc.
-  if (obj.constructor && obj.constructor.name !== "Object") {
+  if (!isPlainObject(obj)) {
     return obj;
   }
 
   const result: Record<string, unknown> = {};
-  let allNull = true;
+  const allNull = { value: true };
 
   for (const [key, value] of Object.entries(obj)) {
-    if (value === null || value === undefined) {
-      result[key] = null;
-      continue;
-    }
-
-    if (typeof value === "object") {
-      const processed = processNullBranches(value as Record<string, unknown>);
-      result[key] = processed;
-      if (processed !== null) {
-        allNull = false;
-      }
-    } else {
-      result[key] = value;
-      allNull = false;
-    }
+    processValueEntry(key, value, result, allNull);
   }
 
-  return allNull ? null : result;
+  return allNull.value ? null : result;
 }
 
 export function formatLimitOffset(limitOrOffset: number): number {
@@ -745,6 +775,37 @@ function buildClusterStatementsSummaryQuery(forgeSQLORM: ForgeSqlOperation, time
     );
 }
 
+/**
+ * Formats and logs query performance result.
+ */
+function formatAndLogQueryResult(result: {
+  digestText: string;
+  avgLatency: number | bigint;
+  avgMem: number | bigint;
+  stmtType: string;
+  execCount: number | bigint;
+  plan: string | null;
+}): void {
+  const avgTimeMs = Number(result.avgLatency) / 1_000_000;
+  const avgMemMB = Number(result.avgMem) / 1_000_000;
+
+  // eslint-disable-next-line no-console
+  console.warn(
+    `SQL: ${result.digestText} | Memory: ${avgMemMB.toFixed(2)} MB | Time: ${avgTimeMs.toFixed(2)} ms | stmtType: ${result.stmtType} | Executions: ${Number(result.execCount)}\n Plan:${result.plan}`,
+  );
+}
+
+/**
+ * Handles errors in query execution plan retrieval.
+ */
+function handleQueryPlanError(error: unknown): void {
+  // eslint-disable-next-line no-console
+  console.debug(
+    `Error occurred while retrieving query execution plan: ${error instanceof Error ? error.message : "Unknown error"}. Try again after some time`,
+    error,
+  );
+}
+
 /**
  * Analyzes and prints query performance data from CLUSTER_STATEMENTS_SUMMARY table.
  *
@@ -785,22 +846,10 @@ export async function printQueriesWithPlan(
     );
 
     for (const result of results) {
-      // Average execution time (convert from nanoseconds to milliseconds)
-      const avgTimeMs = Number(result.avgLatency) / 1_000_000;
-      const avgMemMB = Number(result.avgMem) / 1_000_000;
-
-      // 1. Query info: SQL, memory, time, executions
-      // eslint-disable-next-line no-console
-      console.warn(
-        `SQL: ${result.digestText} | Memory: ${avgMemMB.toFixed(2)} MB | Time: ${avgTimeMs.toFixed(2)} ms | stmtType: ${result.stmtType} | Executions: ${result.execCount}\n Plan:${result.plan}`,
-      );
+      formatAndLogQueryResult(result);
     }
   } catch (error) {
-    // eslint-disable-next-line no-console
-    console.debug(
-      `Error occurred while retrieving query execution plan: ${error instanceof Error ? error.message : "Unknown error"}. Try again after some time`,
-      error,
-    );
+    handleQueryPlanError(error);
   }
 }
 
@@ -823,22 +872,10 @@ export async function handleErrorsWithPlan(
     );
 
     for (const result of results) {
-      // Average execution time (convert from nanoseconds to milliseconds)
-      const avgTimeMs = Number(result.avgLatency) / 1_000_000;
-      const avgMemMB = Number(result.avgMem) / 1_000_000;
-
-      // 1. Query info: SQL, memory, time, executions
-      // eslint-disable-next-line no-console
-      console.warn(
-        `SQL: ${result.digestText} | Memory: ${avgMemMB.toFixed(2)} MB | Time: ${avgTimeMs.toFixed(2)} ms | stmtType: ${result.stmtType} | Executions: ${result.execCount}\n Plan:${result.plan}`,
-      );
+      formatAndLogQueryResult(result);
     }
   } catch (error) {
-    // eslint-disable-next-line no-console
-    console.debug(
-      `Error occurred while retrieving query execution plan: ${error instanceof Error ? error.message : "Unknown error"}. Try again after some time`,
-      error,
-    );
+    handleQueryPlanError(error);
   }
 }
 
@@ -873,6 +910,48 @@ const SESSION_ALIAS_NAME_ORM = "orm";
  *
  * @throws Does not throw - errors are logged to console.debug instead
  */
+/**
+ * Builds slow query query for specified hours.
+ */
+function buildSlowQueryQuery(forgeSQLORM: ForgeSqlOperation, hours: number) {
+  return forgeSQLORM
+    .getDrizzleQueryBuilder()
+    .select({
+      query: withTidbHint(slowQuery.query),
+      queryTime: slowQuery.queryTime,
+      memMax: slowQuery.memMax,
+      plan: slowQuery.plan,
+    })
+    .from(slowQuery)
+    .where(
+      and(
+        isNotNull(slowQuery.digest),
+        ne(slowQuery.sessionAlias, SESSION_ALIAS_NAME_ORM),
+        gte(
+          slowQuery.time,
+          sql`DATE_SUB
+                            (NOW(), INTERVAL
+                            ${hours}
+                            HOUR
+                            )`,
+        ),
+      ),
+    );
+}
+
+/**
+ * Formats slow query result message.
+ */
+function formatSlowQueryMessage(result: {
+  query: string | null;
+  queryTime: number | null;
+  memMax: number | bigint | null;
+  plan: string | null;
+}): string {
+  const memMaxMB = result.memMax ? Number(result.memMax) / 1_000_000 : 0;
+  return `Found SlowQuery SQL: ${result.query} | Memory: ${memMaxMB.toFixed(2)} MB | Time: ${result.queryTime} ms\n Plan:${result.plan}`;
+}
+
 export async function slowQueryPerHours(
   forgeSQLORM: ForgeSqlOperation,
   hours: number,
@@ -880,51 +959,22 @@ export async function slowQueryPerHours(
 ) {
   try {
     const timeoutMs = timeout ?? 1500;
+    const query = buildSlowQueryQuery(forgeSQLORM, hours);
     const results = await withTimeout(
-      forgeSQLORM
-        .getDrizzleQueryBuilder()
-        .select({
-          query: withTidbHint(slowQuery.query),
-          queryTime: slowQuery.queryTime,
-          memMax: slowQuery.memMax,
-          plan: slowQuery.plan,
-        })
-        .from(slowQuery)
-        .where(
-          and(
-            isNotNull(slowQuery.digest),
-            ne(slowQuery.sessionAlias, SESSION_ALIAS_NAME_ORM),
-            gte(
-              slowQuery.time,
-              sql`DATE_SUB
-                            (NOW(), INTERVAL
-                            ${hours}
-                            HOUR
-                            )`,
-            ),
-          ),
-        ),
+      query,
       `Timeout ${timeoutMs}ms in slowQueryPerHours - transient timeouts are usually fine; repeated timeouts mean this diagnostic query is consistently slow and should be investigated`,
       timeoutMs,
     );
     const response: string[] = [];
     for (const result of results) {
-      // Convert memory from bytes to MB and handle null values
-      const memMaxMB = result.memMax ? Number(result.memMax) / 1_000_000 : 0;
-
-      const message = `Found SlowQuery SQL: ${result.query} | Memory: ${memMaxMB.toFixed(2)} MB | Time: ${result.queryTime} ms\n Plan:${result.plan}`;
+      const message = formatSlowQueryMessage(result);
       response.push(message);
-      // 1. Query info: SQL, memory, time, executions
       // eslint-disable-next-line no-console
       console.warn(message);
     }
     return response;
   } catch (error) {
-    // eslint-disable-next-line no-console
-    console.debug(
-      `Error occurred while retrieving query execution plan: ${error instanceof Error ? error.message : "Unknown error"}. Try again after some time`,
-      error,
-    );
+    handleQueryPlanError(error);
     return [
       `Error occurred while retrieving query execution plan: ${error instanceof Error ? error.message : "Unknown 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 {