forge-sql-orm 2.1.15 → 2.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-sql-orm",
-  "version": "2.1.15",
+  "version": "2.1.17",
   "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",
@@ -25,25 +25,25 @@
     "database"
   ],
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
+    "@eslint/js": "^9.39.2",
     "@types/luxon": "^3.7.1",
-    "@types/node": "^24.10.1",
-    "@typescript-eslint/eslint-plugin": "^8.48.0",
-    "@typescript-eslint/parser": "^8.48.0",
-    "@vitest/coverage-v8": "^4.0.14",
-    "@vitest/ui": "^4.0.14",
-    "eslint": "^9.39.1",
+    "@types/node": "^25.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "@vitest/ui": "^4.0.16",
+    "eslint": "^9.39.2",
     "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.2",
+    "knip": "^5.74.0",
     "patch-package": "^8.0.1",
-    "prettier": "^3.7.2",
+    "prettier": "^3.7.4",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3",
     "uuid": "^13.0.0",
-    "vitest": "^4.0.14"
+    "vitest": "^4.0.16"
   },
   "license": "MIT",
   "author": "Vasyl Zakharchenko",
@@ -71,13 +71,14 @@
     "README.md"
   ],
   "peerDependencies": {
-    "@forge/sql": "^3.0.12",
-    "drizzle-orm": "^0.44.7"
+    "@forge/sql": "^3.0.14",
+    "drizzle-orm": "^0.45.1"
   },
   "optionalDependencies": {
     "@forge/kvs": "^1.2.0"
   },
   "dependencies": {
+    "@forge/events": "^2.0.14",
     "luxon": "^3.7.2",
     "node-sql-parser": "^5.3.13"
   },

package/src/async/PrintQueryConsumer.ts

@@ -0,0 +1,114 @@
+import { AsyncEvent } from "@forge/events";
+import {
+  MetadataQueryOptions,
+  printDegradationQueries,
+  Statistic,
+} from "../utils/metadataContextUtils";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
+
+/**
+ * Event payload for async query degradation analysis.
+ * Contains query performance statistics and metadata for analysis.
+ */
+export type AsyncEventPrintQuery = {
+  /** Total database execution time across all queries in milliseconds */
+  totalDbExecutionTime: number;
+  /** Total response size across all queries in bytes */
+  totalResponseSize: number;
+  /** Timestamp when the query execution started */
+  beginTime: Date;
+  /** Query analysis options with all fields set to defaults if not provided */
+  options: Required<MetadataQueryOptions>;
+  /** Array of query statistics including SQL, parameters, and execution metadata */
+  statistics: Statistic[];
+};
+
+/**
+ * Consumer function for processing async query degradation events.
+ *
+ * This function is called by the Forge event system when a query degradation event
+ * is received from the queue. It processes the event and prints query performance
+ * analysis including execution plans for slow queries.
+ *
+ * The function logs a warning message with job ID, total DB time, query count, and
+ * start time to help correlate with the original resolver/service logs.
+ *
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @param event - The async event containing query degradation data
+ * @returns Promise that resolves when query analysis is complete
+ *
+ * @example
+ * ```yaml
+ * # manifest.yml - Configure consumer for async query degradation analysis
+ * modules:
+ *   consumer:
+ *     - key: print-degradation-queries
+ *       queue: degradationQueue
+ *       function: handlerAsyncDegradation
+ *   function:
+ *     - key: handlerAsyncDegradation
+ *       handler: index.handlerAsyncDegradation
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // index.ts - Handler function that processes async events
+ * import { AsyncEvent } from "@forge/events";
+ * import { printDegradationQueriesConsumer } from "forge-sql-orm";
+ * import { FORGE_SQL_ORM } from "./utils/forgeSqlOrmUtils";
+ *
+ * export const handlerAsyncDegradation = (event: AsyncEvent) => {
+ *   return printDegradationQueriesConsumer(FORGE_SQL_ORM, event);
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using async queue in resolver - Enable async processing
+ * resolver.define("fetch", async (req: Request) => {
+ *   return await FORGE_SQL_ORM.executeWithMetadata(
+ *     async () => {
+ *       // ... your queries ...
+ *       return await SQL_QUERY;
+ *     },
+ *     async (totalDbExecutionTime, totalResponseSize, printQueries) => {
+ *       if (totalDbExecutionTime > 800) {
+ *         await printQueries(); // Will queue for async processing
+ *       }
+ *     },
+ *     { asyncQueueName: "degradationQueue" } // Enable async processing
+ *   );
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Log correlation - How to find related logs
+ * //
+ * // 1. In resolver/service log, you'll see:
+ * //    [Performance Analysis] Query degradation event queued for async processing | Job ID: abc-123 | ...
+ * //
+ * // 2. In consumer log (handlerAsyncDegradation), search for the same Job ID:
+ * //    [Performance Analysis] Processing query degradation event | Job ID: abc-123 | ...
+ * //
+ * // 3. To find all related logs, search logs for: "Job ID: abc-123"
+ * //    This will show both the queuing event and the processing event
+ * //
+ * // Example log flow:
+ * // WARN resolver: [Performance Analysis] Query degradation event queued... | Job ID: abc-123
+ * // WARN handlerAsyncDegradation: [Performance Analysis] Processing query degradation event | Job ID: abc-123
+ * // WARN handlerAsyncDegradation: SQL: SELECT ... | Time: 3514 ms
+ * ```
+ */
+export async function printDegradationQueriesConsumer(
+  forgeSQLORM: ForgeSqlOperation,
+  event: AsyncEvent,
+): Promise<void> {
+  const body: AsyncEventPrintQuery = event.body as AsyncEventPrintQuery;
+  body.beginTime = new Date(body.beginTime);
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[Performance Analysis] Processing query degradation event | Job ID: ${event.jobId} | Total DB time: ${body.totalDbExecutionTime}ms | Queries: ${body.statistics.length} | Started: ${body.beginTime.toISOString()}`,
+  );
+  await printDegradationQueries(forgeSQLORM, body);
+}

package/src/core/ForgeSQLQueryBuilder.ts

@@ -6,6 +6,7 @@ import {
   customType,
   MySqlSelectBuilder,
   MySqlTable,
+  MySqlColumn,
 } from "drizzle-orm/mysql-core";
 import {
   MySqlSelectDynamic,
@@ -56,7 +57,6 @@ 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";
 
 /**
@@ -1025,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