forge-sql-orm 2.1.4 → 2.1.5

package/dist/ForgeSQLORM.mjs

@@ -391,7 +391,7 @@ async function clearCursorCache(tables, cursor, options) {
     entityQueryBuilder = entityQueryBuilder.cursor(cursor);
   }
   const listResult = await entityQueryBuilder.limit(100).getMany();
-  if (options.logRawSqlQuery) {
+  if (options.logCache) {
     console.warn(`clear cache Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
   await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
@@ -412,7 +412,7 @@ async function clearExpirationCursorCache(cursor, options) {
     entityQueryBuilder = entityQueryBuilder.cursor(cursor);
   }
   const listResult = await entityQueryBuilder.limit(100).getMany();
-  if (options.logRawSqlQuery) {
+  if (options.logCache) {
     console.warn(`clear expired Records: ${JSON.stringify(listResult.results.map((r) => r.key))}`);
   }
   await deleteCacheEntriesInBatches(listResult.results, cacheEntityName);
@@ -461,7 +461,7 @@ async function clearTablesCache(tables, options) {
       "clearing cache"
     );
   } finally {
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       const duration = DateTime.now().toSeconds() - startTime.toSeconds();
       console.info(`Cleared ${totalRecords} cache records in ${duration} seconds`);
     }
@@ -480,7 +480,7 @@ async function clearExpiredCache(options) {
     );
   } finally {
     const duration = DateTime.now().toSeconds() - startTime.toSeconds();
-    if (options?.logRawSqlQuery) {
+    if (options?.logCache) {
       console.debug(`Cleared ${totalRecords} expired cache records in ${duration} seconds`);
     }
   }
@@ -495,7 +495,7 @@ async function getFromCache(query, options) {
   const sqlQuery = query.toSQL();
   const key = hashKey(sqlQuery);
   if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       console.warn(`Context contains value to clear. Skip getting from cache`);
     }
     return void 0;
@@ -503,7 +503,7 @@ async function getFromCache(query, options) {
   try {
     const cacheResult = await kvs.entity(options.cacheEntityName).get(key);
     if (cacheResult && cacheResult[expirationName] >= getCurrentTime() && sqlQuery.sql.toLowerCase() === cacheResult[entityQueryName]) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
         console.warn(`Get value from cache, cacheKey: ${key}`);
       }
       const results = cacheResult[dataName];
@@ -524,7 +524,7 @@ async function setCacheResult(query, options, results, cacheTtl) {
     const dataName = options.cacheEntityDataName ?? CACHE_CONSTANTS.DEFAULT_DATA_NAME;
     const sqlQuery = query.toSQL();
     if (await isTableContainsTableInCacheContext(sqlQuery.sql, options)) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
         console.warn(`Context contains value to clear. Skip setting from cache`);
       }
       return;
@@ -539,7 +539,7 @@ async function setCacheResult(query, options, results, cacheTtl) {
       },
       { entityName: options.cacheEntityName }
     ).execute();
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       console.warn(`Store value to cache, cacheKey: ${key}`);
     }
   } catch (error) {
@@ -567,7 +567,7 @@ async function saveQueryLocalCacheQuery(query, rows, options) {
       sql: sql2.toSQL().sql.toLowerCase(),
       data: rows
     };
-    if (options.logRawSqlQuery) {
+    if (options.logCache) {
       const q = sql2.toSQL();
       console.debug(
         `[forge-sql-orm][local-cache][SAVE] Stored result in cache. sql="${q.sql}", params=${JSON.stringify(q.params)}`
@@ -584,7 +584,7 @@ async function getQueryLocalCacheQuery(query, options) {
     const sql2 = query;
     const key = hashKey(sql2.toSQL());
     if (context.cache[key] && context.cache[key].sql === sql2.toSQL().sql.toLowerCase()) {
-      if (options.logRawSqlQuery) {
+      if (options.logCache) {
         const q = sql2.toSQL();
         console.debug(
           `[forge-sql-orm][local-cache][HIT] Returned cached result. sql="${q.sql}", params=${JSON.stringify(q.params)}`
@@ -1015,6 +1015,18 @@ class ForgeSQLSelectOperations {
     return updateQueryResponseResults.rows;
   }
 }
+const metadataQueryContext = new AsyncLocalStorage();
+async function saveMetaDataInContextContext(metadata) {
+  const context = metadataQueryContext.getStore();
+  if (context && metadata) {
+    context.totalResponseSize += metadata.responseSize;
+    context.totalDbExecutionTime += metadata.dbExecutionTime;
+    context.lastMetadata = metadata;
+  }
+}
+async function getLastestMetadata() {
+  return metadataQueryContext.getStore();
+}
 const forgeDriver = async (query, params, method) => {
   if (method == "execute") {
     const sqlStatement = sql$1.prepare(query);
@@ -1030,6 +1042,7 @@ const forgeDriver = async (query, params, method) => {
       await sqlStatement.bindParams(...params);
     }
     const result = await sqlStatement.execute();
+    await saveMetaDataInContextContext(result.metadata);
     let rows;
     rows = result.rows.map((r) => Object.values(r));
     return { rows };
@@ -1779,6 +1792,7 @@ class ForgeSQLORMImpl {
     try {
       const newOptions = options ?? {
         logRawSqlQuery: false,
+        logCache: false,
         disableOptimisticLocking: false,
         cacheWrapTable: true,
         cacheTTL: 120,
@@ -1804,6 +1818,42 @@ class ForgeSQLORMImpl {
       throw error;
     }
   }
+  /**
+   * Executes a query and provides access to execution metadata.
+   * This method allows you to capture detailed information about query execution
+   * including database execution time, response size, and Forge SQL metadata.
+   *
+   * @template T - The return type of the query
+   * @param query - A function that returns a Promise with the query result
+   * @param onMetadata - Callback function that receives execution metadata
+   * @returns Promise with the query result
+   * @example
+   * ```typescript
+   * const result = await forgeSQL.executeWithMetadata(
+   *   async () => await forgeSQL.select().from(users).where(eq(users.id, 1)),
+   *   (dbTime, responseSize, metadata) => {
+   *     console.log(`DB execution time: ${dbTime}ms`);
+   *     console.log(`Response size: ${responseSize} bytes`);
+   *     console.log('Forge metadata:', metadata);
+   *   }
+   * );
+   * ```
+   */
+  async executeWithMetadata(query, onMetadata) {
+    return metadataQueryContext.run({
+      totalDbExecutionTime: 0,
+      totalResponseSize: 0
+    }, async () => {
+      try {
+        return await query();
+      } finally {
+        const metadata = await getLastestMetadata();
+        if (metadata && metadata.lastMetadata) {
+          await onMetadata(metadata.totalDbExecutionTime, metadata.totalResponseSize, metadata.lastMetadata);
+        }
+      }
+    });
+  }
   /**
    * Executes operations within a cache context that collects cache eviction events.
    * All clearCache calls within the context are collected and executed in batch at the end.
@@ -2251,6 +2301,30 @@ class ForgeSQLORM {
   constructor(options) {
     this.ormInstance = ForgeSQLORMImpl.getInstance(options);
   }
+  /**
+   * Executes a query and provides access to execution metadata.
+   * This method allows you to capture detailed information about query execution
+   * including database execution time, response size, and Forge SQL metadata.
+   *
+   * @template T - The return type of the query
+   * @param query - A function that returns a Promise with the query result
+   * @param onMetadata - Callback function that receives execution metadata
+   * @returns Promise with the query result
+   * @example
+   * ```typescript
+   * const result = await forgeSQL.executeWithMetadata(
+   *   async () => await forgeSQL.select().from(users).where(eq(users.id, 1)),
+   *   (dbTime, responseSize, metadata) => {
+   *     console.log(`DB execution time: ${dbTime}ms`);
+   *     console.log(`Response size: ${responseSize} bytes`);
+   *     console.log('Forge metadata:', metadata);
+   *   }
+   * );
+   * ```
+   */
+  async executeWithMetadata(query, onMetadata) {
+    return this.ormInstance.executeWithMetadata(query, onMetadata);
+  }
   selectCacheable(fields, cacheTTL) {
     return this.ormInstance.selectCacheable(fields, cacheTTL);
   }
@@ -3199,7 +3273,25 @@ const clearCacheSchedulerTrigger = async (options) => {
     };
   }
 };
-const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, memoryThresholdBytes = 8 * 1024 * 1024) => {
+const DEFAULT_MEMORY_THRESHOLD = 8 * 1024 * 1024;
+const DEFAULT_TIMEOUT = 300;
+const topSlowestStatementLastHourTrigger = async (orm, options) => {
+  if (!orm) {
+    return {
+      statusCode: 500,
+      headers: { "Content-Type": ["application/json"] },
+      body: JSON.stringify({
+        success: false,
+        message: "ORM instance is required",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      })
+    };
+  }
+  let newOptions = options ?? {
+    warnThresholdMs: DEFAULT_TIMEOUT,
+    memoryThresholdBytes: DEFAULT_MEMORY_THRESHOLD,
+    showPlan: false
+  };
   const nsToMs = (v) => {
     const n = Number(v);
     return Number.isFinite(n) ? n / 1e6 : NaN;
@@ -3209,6 +3301,17 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
     return Number.isFinite(n) ? n / (1024 * 1024) : NaN;
   };
   const jsonSafeStringify = (value) => JSON.stringify(value, (_k, v) => typeof v === "bigint" ? v.toString() : v);
+  function sanitizeSQL(sql2, maxLen = 1e3) {
+    let s = sql2;
+    s = s.replace(/--[^\n\r]*/g, "").replace(/\/\*[\s\S]*?\*\//g, "");
+    s = s.replace(/'(?:\\'|[^'])*'/g, "?");
+    s = s.replace(/\b-?\d+(?:\.\d+)?\b/g, "?");
+    s = s.replace(/\s+/g, " ").trim();
+    if (s.length > maxLen) {
+      s = s.slice(0, maxLen) + " …[truncated]";
+    }
+    return s;
+  }
   const TOP_N = 1;
   try {
     const summaryHistory = clusterStatementsSummaryHistory;
@@ -3245,7 +3348,8 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
     const qHistory = orm.getDrizzleQueryBuilder().select(selectShape(summaryHistory)).from(summaryHistory).where(lastHourFilterHistory);
     const qSummary = orm.getDrizzleQueryBuilder().select(selectShape(summary)).from(summary).where(lastHourFilterSummary);
     const combined = unionAll(qHistory, qSummary).as("combined");
-    const thresholdNs = Math.floor(warnThresholdMs * 1e6);
+    const thresholdNs = Math.floor((newOptions.warnThresholdMs ?? DEFAULT_TIMEOUT) * 1e6);
+    const memoryThresholdBytes = newOptions.memoryThresholdBytes ?? DEFAULT_MEMORY_THRESHOLD;
     const grouped = orm.getDrizzleQueryBuilder().select({
       digest: combined.digest,
       stmtType: combined.stmtType,
@@ -3316,8 +3420,8 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
       lastSeen: r.lastSeen,
       planInCache: r.planInCache,
       planCacheHits: r.planCacheHits,
-      digestText: r.digestText,
-      plan: r.plan
+      digestText: sanitizeSQL(r.digestText),
+      plan: newOptions.showPlan ? r.plan : void 0
     }));
     for (const f of formatted) {
       console.warn(
@@ -3325,7 +3429,7 @@ const topSlowestStatementLastHourTrigger = async (orm, warnThresholdMs = 300, me
    digest=${f.digest}
    sql=${(f.digestText || "").slice(0, 300)}${f.digestText && f.digestText.length > 300 ? "…" : ""}`
       );
-      if (f.plan) {
+      if (newOptions.showPlan && f.plan) {
         console.warn(`   full plan:
 ${f.plan}`);
       }
@@ -3338,8 +3442,9 @@ ${f.plan}`);
         success: true,
         window: "last_1h",
         top: TOP_N,
-        warnThresholdMs,
-        memoryThresholdBytes,
+        warnThresholdMs: newOptions.warnThresholdMs,
+        memoryThresholdBytes: newOptions.memoryThresholdBytes,
+        showPlan: newOptions.showPlan,
         rows: formatted,
         generatedAt: (/* @__PURE__ */ new Date()).toISOString()
       })