forge-sql-orm 2.1.14 → 2.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-sql-orm",
-  "version": "2.1.14",
+  "version": "2.1.16",
   "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/vzakharchenko/forge-sql-orm#readme",
@@ -21,28 +21,29 @@
     "drizzle-driver",
     "drizzle-custom-driver",
     "orm",
+    "rovo",
     "database"
   ],
   "devDependencies": {
     "@eslint/js": "^9.39.1",
     "@types/luxon": "^3.7.1",
     "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.47.0",
-    "@typescript-eslint/parser": "^8.47.0",
-    "@vitest/coverage-v8": "^4.0.13",
-    "@vitest/ui": "^4.0.13",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/ui": "^4.0.15",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-vitest": "^0.5.4",
     "husky": "^9.1.7",
-    "knip": "^5.70.1",
+    "knip": "^5.71.0",
     "patch-package": "^8.0.1",
-    "prettier": "^3.6.2",
+    "prettier": "^3.7.4",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
-    "vitest": "^4.0.13"
+    "vitest": "^4.0.15"
   },
   "license": "MIT",
   "author": "Vasyl Zakharchenko",
@@ -70,8 +71,8 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@forge/sql": "^3.0.10",
-    "drizzle-orm": "^0.44.7"
+    "@forge/sql": "^3.0.12",
+    "drizzle-orm": "^0.45.0"
   },
   "optionalDependencies": {
     "@forge/kvs": "^1.2.0"

package/src/core/ForgeSQLORM.ts

@@ -39,7 +39,11 @@ import { cacheApplicationContext, localCacheApplicationContext } from "../utils/
 import { clearTablesCache } from "../utils/cacheUtils";
 import { SQLWrapper } from "drizzle-orm/sql/sql";
 import { WithSubquery } from "drizzle-orm/subquery";
-import { getLastestMetadata, metadataQueryContext } from "../utils/metadataContextUtils";
+import {
+  getLastestMetadata,
+  metadataQueryContext,
+  MetadataQueryOptions,
+} from "../utils/metadataContextUtils";
 import { operationTypeQueryContext } from "../utils/requestTypeContextUtils";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
 import { Rovo } from "./Rovo";
@@ -124,7 +128,15 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    * @param onMetadata - Callback function that receives aggregated execution metadata
    * @param onMetadata.totalDbExecutionTime - Total database execution time across all operations in the query function (in milliseconds)
    * @param onMetadata.totalResponseSize - Total response size across all operations (in bytes)
-   * @param onMetadata.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
+   * @param onMetadata.printQueriesWithPlan - Function to analyze and print query execution plans. Supports two modes:
+   *   - TopSlowest: Prints execution plans for the slowest queries from the current resolver (default)
+   *   - SummaryTable: Uses CLUSTER_STATEMENTS_SUMMARY if within time window
+   * @param options - Optional configuration for query plan printing behavior
+   * @param options.mode - Query plan printing mode: 'TopSlowest' (default) or 'SummaryTable'
+   * @param options.summaryTableWindowTime - Time window in milliseconds for summary table queries (default: 15000ms). Only used when mode is 'SummaryTable'
+   * @param options.topQueries - Number of top slowest queries to analyze when mode is 'TopSlowest' (default: 1)
+   * @param options.showSlowestPlans - Whether to show execution plans for slowest queries in TopSlowest mode (default: true)
+   * @param options.normalizeQuery - Whether to normalize SQL queries by replacing parameter values with '?' placeholders (default: true). Set to false to disable normalization if it causes issues
    * @returns Promise with the query result
    *
    * @example
@@ -136,12 +148,12 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
    *     return { users, orders };
    *   },
-   *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *   (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
    *     const threshold = 500; // ms baseline for this resolver
    *
    *     if (totalDbExecutionTime > threshold * 1.5) {
    *       console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
-   *       await printQueries(); // Analyze and print query execution plans
+   *       await printQueriesWithPlan(); // Analyze and print query execution plans
    *     } else if (totalDbExecutionTime > threshold) {
    *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *     }
@@ -164,12 +176,12 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    *           .where(eq(demoOrders.userId, demoUsers.id));
    *         return { users, orders };
    *       },
-   *       async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *       async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
    *         const threshold = 500; // ms baseline for this resolver
    *
    *         if (totalDbExecutionTime > threshold * 1.5) {
    *           console.warn(`[Performance Warning fetch] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
-   *           await printQueries(); // Optionally log or capture diagnostics for further analysis
+   *           await printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
    *         } else if (totalDbExecutionTime > threshold) {
    *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *         }
@@ -185,7 +197,47 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
    * });
    * ```
    *
-   * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueries()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
+   * @example
+   * ```typescript
+   * // Using TopSlowest mode with custom topQueries
+   * const result = await forgeSQL.executeWithMetadata(
+   *   async () => {
+   *     const users = await forgeSQL.selectFrom(usersTable);
+   *     return users;
+   *   },
+   *   async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+   *     if (totalDbExecutionTime > 1000) {
+   *       await printQueriesWithPlan(); // Will print top 3 slowest queries
+   *     }
+   *   },
+   *   {
+   *     mode: 'TopSlowest', // Print top slowest queries (default)
+   *     topQueries: 3, // Print top 3 slowest queries
+   *   }
+   * );
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Using SummaryTable mode for query analysis
+   * const result = await forgeSQL.executeWithMetadata(
+   *   async () => {
+   *     const users = await forgeSQL.selectFrom(usersTable);
+   *     return users;
+   *   },
+   *   async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
+   *     if (totalDbExecutionTime > 1000) {
+   *       await printQueriesWithPlan(); // Will use CLUSTER_STATEMENTS_SUMMARY if within time window
+   *     }
+   *   },
+   *   {
+   *     mode: 'SummaryTable', // Use summary tables mode
+   *     summaryTableWindowTime: 10000, // 10 second window
+   *   }
+   * );
+   * ```
+   *
+   * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueriesWithPlan()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
    */
   async executeWithMetadata<T>(
     query: () => Promise<T>,
@@ -194,6 +246,7 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
       totalResponseSize: number,
       printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
+    options?: MetadataQueryOptions,
   ): Promise<T> {
     return metadataQueryContext.run(
       {
@@ -204,6 +257,8 @@ class ForgeSQLORMImpl implements ForgeSqlOperation {
         printQueriesWithPlan: async () => {
           return;
         },
+        options: options,
+        statistics: [],
       },
       async () => {
         const result = await query();
@@ -886,7 +941,15 @@ class ForgeSQLORM implements ForgeSqlOperation {
    * @param onMetadata - Callback function that receives aggregated execution metadata
    * @param onMetadata.totalDbExecutionTime - Total database execution time across all operations in the query function (in milliseconds)
    * @param onMetadata.totalResponseSize - Total response size across all operations (in bytes)
-   * @param onMetadata.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
+   * @param onMetadata.printQueriesWithPlan - Function to analyze and print query execution plans. Supports two modes:
+   *   - TopSlowest: Prints execution plans for the slowest queries from the current resolver (default)
+   *   - SummaryTable: Uses CLUSTER_STATEMENTS_SUMMARY if within time window
+   * @param options - Optional configuration for query plan printing behavior
+   * @param options.mode - Query plan printing mode: 'TopSlowest' (default) or 'SummaryTable'
+   * @param options.summaryTableWindowTime - Time window in milliseconds for summary table queries (default: 15000ms). Only used when mode is 'SummaryTable'
+   * @param options.topQueries - Number of top slowest queries to analyze when mode is 'TopSlowest' (default: 1)
+   * @param options.showSlowestPlans - Whether to show execution plans for slowest queries in TopSlowest mode (default: true)
+   * @param options.normalizeQuery - Whether to normalize SQL queries by replacing parameter values with '?' placeholders (default: true). Set to false to disable normalization if it causes issues
    * @returns Promise with the query result
    *
    * @example
@@ -898,12 +961,12 @@ class ForgeSQLORM implements ForgeSqlOperation {
    *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
    *     return { users, orders };
    *   },
-   *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *   (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
    *     const threshold = 500; // ms baseline for this resolver
    *
    *     if (totalDbExecutionTime > threshold * 1.5) {
    *       console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
-   *       await printQueries(); // Analyze and print query execution plans
+   *       await printQueriesWithPlan(); // Analyze and print query execution plans
    *     } else if (totalDbExecutionTime > threshold) {
    *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *     }
@@ -926,12 +989,12 @@ class ForgeSQLORM implements ForgeSqlOperation {
    *           .where(eq(demoOrders.userId, demoUsers.id));
    *         return { users, orders };
    *       },
-   *       async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *       async (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
    *         const threshold = 500; // ms baseline for this resolver
    *
    *         if (totalDbExecutionTime > threshold * 1.5) {
    *           console.warn(`[Performance Warning fetch] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
-   *           await printQueries(); // Optionally log or capture diagnostics for further analysis
+   *           await printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
    *         } else if (totalDbExecutionTime > threshold) {
    *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *         }
@@ -947,7 +1010,7 @@ class ForgeSQLORM implements ForgeSqlOperation {
    * });
    * ```
    *
-   * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueries()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
+   * @note **Important**: When multiple resolvers are running concurrently, their query data may also appear in `printQueriesWithPlan()` analysis, as it queries the global `CLUSTER_STATEMENTS_SUMMARY` table.
    */
   async executeWithMetadata<T>(
     query: () => Promise<T>,
@@ -956,8 +1019,9 @@ class ForgeSQLORM implements ForgeSqlOperation {
       totalResponseSize: number,
       printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
+    options?: MetadataQueryOptions,
   ): Promise<T> {
-    return this.ormInstance.executeWithMetadata(query, onMetadata);
+    return this.ormInstance.executeWithMetadata(query, onMetadata, options);
   }
 
   selectCacheable<TSelection extends SelectedFields>(

package/src/core/ForgeSQLQueryBuilder.ts

@@ -6,6 +6,7 @@ import {
   customType,
   MySqlSelectBuilder,
   MySqlTable,
+  MySqlColumn,
 } from "drizzle-orm/mysql-core";
 import {
   MySqlSelectDynamic,
@@ -56,7 +57,7 @@ import { SQLWrapper } from "drizzle-orm/sql/sql";
 import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";
 import type { WithBuilder } from "drizzle-orm/mysql-core/subquery";
 import { WithSubquery } from "drizzle-orm/subquery";
-import { MySqlColumn } from "drizzle-orm/mysql-core";
+import { MetadataQueryOptions } from "../utils/metadataContextUtils";
 
 /**
  * Core interface for ForgeSQL operations.
@@ -585,7 +586,15 @@ export interface QueryBuilderForgeSql {
    * @param onMetadata - Callback function that receives aggregated execution metadata
    * @param onMetadata.totalDbExecutionTime - Total database execution time across all operations in the query function (in milliseconds)
    * @param onMetadata.totalResponseSize - Total response size across all operations (in bytes)
-   * @param onMetadata.printQueries - Function to analyze and print query execution plans from CLUSTER_STATEMENTS_SUMMARY
+   * @param onMetadata.printQueriesWithPlan - Function to analyze and print query execution plans. Supports two modes:
+   *   - TopSlowest: Prints execution plans for the slowest queries from the current resolver (default)
+   *   - SummaryTable: Uses CLUSTER_STATEMENTS_SUMMARY if within time window
+   * @param options - Optional configuration for query plan printing behavior
+   * @param options.mode - Query plan printing mode: 'TopSlowest' (default) or 'SummaryTable'
+   * @param options.summaryTableWindowTime - Time window in milliseconds for summary table queries (default: 15000ms). Only used when mode is 'SummaryTable'
+   * @param options.topQueries - Number of top slowest queries to analyze when mode is 'TopSlowest' (default: 1)
+   * @param options.showSlowestPlans - Whether to show execution plans for slowest queries in TopSlowest mode (default: true)
+   * @param options.normalizeQuery - Whether to normalize SQL queries by replacing parameter values with '?' placeholders (default: true). Set to false to disable normalization if it causes issues
    * @returns Promise with the query result
    *
    * @example
@@ -597,12 +606,12 @@ export interface QueryBuilderForgeSql {
    *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
    *     return { users, orders };
    *   },
-   *   (totalDbExecutionTime, totalResponseSize, printQueries) => {
+   *   (totalDbExecutionTime, totalResponseSize, printQueriesWithPlan) => {
    *     const threshold = 500; // ms baseline for this resolver
    *
    *     if (totalDbExecutionTime > threshold * 1.5) {
    *       console.warn(`[Performance Warning] Resolver exceeded DB time: ${totalDbExecutionTime} ms`);
-   *       await printQueries(); // Analyze and print query execution plans
+   *       await printQueriesWithPlan(); // Analyze and print query execution plans
    *     } else if (totalDbExecutionTime > threshold) {
    *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
    *     }
@@ -655,6 +664,7 @@ export interface QueryBuilderForgeSql {
       totalResponseSize: number,
       printQueriesWithPlan: () => Promise<void>,
     ) => Promise<void> | void,
+    options?: MetadataQueryOptions,
   ): Promise<T>;
   /**
    * Executes a raw SQL query with local cache support.
@@ -1015,7 +1025,7 @@ export interface SchemaSqlForgeSql {
    * @returns {Promise<T[]>} A list of results as objects
    * @throws {Error} If the query execution fails
    */
-  executeRawSQL<T extends object | unknown>(query: string, params?: SqlParameters[]): Promise<T[]>;
+  executeRawSQL<T>(query: string, params?: SqlParameters[]): Promise<T[]>;
 
   /**
    * Executes a raw SQL update query.

package/src/core/ForgeSQLSelectOperations.ts

@@ -4,6 +4,7 @@ import {
   AnyMySqlSelectQueryBuilder,
   MySqlSelectDynamic,
 } from "drizzle-orm/mysql-core/query-builders/select.types";
+import { SqlParameters } from "@forge/sql/out/sql-statement";
 
 /**
  * Class implementing SQL select operations for ForgeSQL ORM.
@@ -55,7 +56,7 @@ export class ForgeSQLSelectOperations implements SchemaSqlForgeSql {
    * @param {SqlParameters[]} [params] - Optional SQL parameters
    * @returns {Promise<T[]>} A list of results as objects
    */
-  async executeRawSQL<T extends object | unknown>(query: string, params?: unknown[]): Promise<T[]> {
+  async executeRawSQL<T>(query: string, params?: SqlParameters[]): Promise<T[]> {
     if (this.options.logRawSqlQuery) {
       const paramsStr = params ? `, with params: ${JSON.stringify(params)}` : "";
       // eslint-disable-next-line no-console