forge-sql-orm 2.1.5 → 2.1.7

package/src/utils/forgeDriver.ts

@@ -1,55 +1,234 @@
 import { sql, UpdateQueryResponse } from "@forge/sql";
-import {saveMetaDataInContextContext} from "./metadataContextUtils";
+import { saveMetaDataToContext } from "./metadataContextUtils";
+import { getOperationType } from "./requestTypeContextUtils";
 
+/**
+ * Metadata structure for Forge SQL query results.
+ * Contains execution timing, response size, and field information.
+ */
 export type ForgeSQLMetadata = {
-    dbExecutionTime: number,
-    responseSize: number,
-    fields: {
-        "catalog": string,
-        "name": string,
-        "schema": string,
-        "characterSet": number,
-        "decimals": number,
-        "table": string,
-        "orgTable": string,
-        "orgName": string,
-        "flags": number,
-        "columnType": number,
-        "columnLength": number
-    }[]
+  dbExecutionTime: number;
+  responseSize: number;
+  fields: {
+    catalog: string;
+    name: string;
+    schema: string;
+    characterSet: number;
+    decimals: number;
+    table: string;
+    orgTable: string;
+    orgName: string;
+    flags: number;
+    columnType: number;
+    columnLength: number;
+  }[];
 };
 
+/**
+ * Result structure for Forge SQL queries.
+ * Contains rows data and execution metadata.
+ */
 export interface ForgeSQLResult {
   rows: Record<string, unknown>[] | Record<string, unknown>;
-  metadata: ForgeSQLMetadata
+  metadata: ForgeSQLMetadata;
 }
 
-export const forgeDriver = async (
-  query: string,
-  params: any[],
-  method: "all" | "execute",
-): Promise<{
-  rows: any[];
+/**
+ * Driver result structure for Drizzle ORM compatibility.
+ */
+export interface ForgeDriverResult {
+  rows: unknown[];
   insertId?: number;
   affectedRows?: number;
-}> => {
-  if (method == "execute") {
-    const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
-    if (params) {
-      sqlStatement.bindParams(...params);
+}
+
+/**
+ * Query execution method types.
+ */
+export type QueryMethod = "all" | "execute";
+
+/**
+ * Type guard to check if an object is an UpdateQueryResponse.
+ *
+ * @param obj - The object to check
+ * @returns True if the object is an UpdateQueryResponse
+ */
+export function isUpdateQueryResponse(obj: unknown): obj is UpdateQueryResponse {
+  return (
+    obj !== null &&
+    typeof obj === "object" &&
+    typeof (obj as any).affectedRows === "number" &&
+    typeof (obj as any).insertId === "number"
+  );
+}
+
+/**
+ * Executes a promise with a timeout.
+ *
+ * @param promise - The promise to execute
+ * @param timeoutMs - Timeout in milliseconds (default: 10000ms)
+ * @returns Promise that resolves with the result or rejects on timeout
+ * @throws {Error} When the operation times out
+ */
+async function withTimeout<T>(promise: Promise<T>, timeoutMs: number = 10000): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(
+        new Error(
+          `Atlassian @forge/sql did not return a response within ${timeoutMs}ms (${timeoutMs / 1000} seconds), so the request is blocked. Possible causes: slow query, network issues, or exceeding Forge SQL limits.`,
+        ),
+      );
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
     }
-    const updateQueryResponseResults = await sqlStatement.execute();
-    let result = updateQueryResponseResults.rows as any;
-    return { ...result, rows: [result] };
-  } else {
-    const sqlStatement = await sql.prepare<unknown>(query);
-    if (params) {
-      await sqlStatement.bindParams(...params);
+  }
+}
+
+function inlineParams(sql: string, params: unknown[]): string {
+  let i = 0;
+  return sql.replace(/\?/g, () => {
+    const val = params[i++];
+    if (val === null) return "NULL";
+    if (typeof val === "number") return val.toString();
+    return `'${String(val).replace(/'/g, "''")}'`;
+  });
+}
+
+/**
+ * Processes DDL query results and saves metadata.
+ *
+ * @param result - The DDL query result
+ * @returns Processed result for Drizzle ORM
+ */
+async function processDDLResult(method: QueryMethod, result: any): Promise<ForgeDriverResult> {
+  if (result.metadata) {
+    await saveMetaDataToContext(result.metadata as ForgeSQLMetadata);
+  }
+
+  if (!result?.rows) {
+    return { rows: [] };
+  }
+
+  if (isUpdateQueryResponse(result.rows)) {
+    const oneRow = result.rows as any;
+    return { ...oneRow, rows: [oneRow] };
+  }
+
+  if (Array.isArray(result.rows)) {
+    if (method === "execute") {
+      return { rows: result.rows };
+    } else {
+      const rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
+      return { rows };
     }
-    const result = (await sqlStatement.execute()) as ForgeSQLResult;
-    await saveMetaDataInContextContext(result.metadata)
-    let rows;
-    rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
-    return { rows: rows };
   }
+
+  return { rows: [] };
+}
+
+/**
+ * Processes execute method results (UPDATE, INSERT, DELETE).
+ *
+ * @param query - The SQL query
+ * @param params - Query parameters
+ * @returns Processed result for Drizzle ORM
+ */
+async function processExecuteMethod(query: string, params: unknown[]): Promise<ForgeDriverResult> {
+  const sqlStatement = sql.prepare<UpdateQueryResponse>(query);
+
+  if (params) {
+    sqlStatement.bindParams(...params);
+  }
+
+  const result = await withTimeout(sqlStatement.execute());
+  await saveMetaDataToContext(result.metadata as ForgeSQLMetadata);
+  if (!result?.rows) {
+    return { rows: [] };
+  }
+
+  if (isUpdateQueryResponse(result.rows)) {
+    const oneRow = result.rows as any;
+    return { ...oneRow, rows: [oneRow] };
+  }
+
+  return { rows: result.rows };
+}
+
+/**
+ * Processes all method results (SELECT queries).
+ *
+ * @param query - The SQL query
+ * @param params - Query parameters
+ * @returns Processed result for Drizzle ORM
+ */
+async function processAllMethod(query: string, params: unknown[]): Promise<ForgeDriverResult> {
+  const sqlStatement = await sql.prepare<unknown>(query);
+
+  if (params) {
+    await sqlStatement.bindParams(...params);
+  }
+
+  const result = (await withTimeout(sqlStatement.execute())) as ForgeSQLResult;
+  await saveMetaDataToContext(result.metadata);
+
+  if (!result?.rows) {
+    return { rows: [] };
+  }
+
+  const rows = (result.rows as any[]).map((r) => Object.values(r as Record<string, unknown>));
+
+  return { rows };
+}
+
+/**
+ * Main Forge SQL driver function for Drizzle ORM integration.
+ * Handles DDL operations, execute operations (UPDATE/INSERT/DELETE), and select operations.
+ *
+ * @param query - The SQL query to execute
+ * @param params - Query parameters
+ * @param method - Execution method ("all" for SELECT, "execute" for UPDATE/INSERT/DELETE)
+ * @returns Promise with query results compatible with Drizzle ORM
+ *
+ * @throws {Error} When DDL operations are called with parameters
+ *
+ * @example
+ * ```typescript
+ * // DDL operation
+ * await forgeDriver("CREATE TABLE users (id INT)", [], "all");
+ *
+ * // SELECT operation
+ * await forgeDriver("SELECT * FROM users WHERE id = ?", [1], "all");
+ *
+ * // UPDATE operation
+ * await forgeDriver("UPDATE users SET name = ? WHERE id = ?", ["John", 1], "execute");
+ * ```
+ */
+export const forgeDriver = async (
+  query: string,
+  params: unknown[],
+  method: QueryMethod,
+): Promise<ForgeDriverResult> => {
+  const operationType = await getOperationType();
+
+  // Handle DDL operations
+  if (operationType === "DDL") {
+    const result = await withTimeout(sql.executeDDL(inlineParams(query, params)));
+    return await processDDLResult(method, result);
+  }
+
+  // Handle execute method (UPDATE, INSERT, DELETE)
+  if (method === "execute") {
+    return await processExecuteMethod(query, params ?? []);
+  }
+
+  // Handle all method (SELECT)
+  return await processAllMethod(query, params ?? []);
 };

package/src/utils/forgeDriverProxy.ts

@@ -19,7 +19,7 @@ export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: bool
     const modifiedQuery = injectSqlHints(query, options);
 
     if (options && logRawSqlQuery && modifiedQuery !== query) {
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.debug("injected Hints: " + modifiedQuery);
     }
     try {
@@ -27,7 +27,7 @@ export function createForgeDriverProxy(options?: SqlHints, logRawSqlQuery?: bool
       return await forgeDriver(modifiedQuery, params, method);
     } catch (error) {
       if (logRawSqlQuery) {
-          // eslint-disable-next-line no-console
+        // eslint-disable-next-line no-console
         console.debug("SQL Error:", JSON.stringify(error));
       }
       throw error;

package/src/utils/metadataContextUtils.ts

@@ -1,24 +1,22 @@
 import { AsyncLocalStorage } from "node:async_hooks";
-import {ForgeSQLMetadata} from "./forgeDriver";
+import { ForgeSQLMetadata } from "./forgeDriver";
 
 export type MetadataQueryContext = {
-    totalDbExecutionTime: number,
-    totalResponseSize: number,
-    lastMetadata?: ForgeSQLMetadata;
-}
+  totalDbExecutionTime: number;
+  totalResponseSize: number;
+  lastMetadata?: ForgeSQLMetadata;
+};
 export const metadataQueryContext = new AsyncLocalStorage<MetadataQueryContext>();
 
-export async function saveMetaDataInContextContext(
-  metadata: ForgeSQLMetadata,
-): Promise<void> {
+export async function saveMetaDataToContext(metadata: ForgeSQLMetadata): Promise<void> {
   const context = metadataQueryContext.getStore();
   if (context && metadata) {
-      context.totalResponseSize += metadata.responseSize
-      context.totalDbExecutionTime += metadata.dbExecutionTime
-      context.lastMetadata = metadata;
+    context.totalResponseSize += metadata.responseSize;
+    context.totalDbExecutionTime += metadata.dbExecutionTime;
+    context.lastMetadata = metadata;
   }
 }
 
-export async function getLastestMetadata():Promise<MetadataQueryContext|undefined> {
-    return metadataQueryContext.getStore();
+export async function getLastestMetadata(): Promise<MetadataQueryContext | undefined> {
+  return metadataQueryContext.getStore();
 }

package/src/utils/requestTypeContextUtils.ts

@@ -0,0 +1,11 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export type OperationType = "DML" | "DDL";
+
+export type OperationTypeQueryContext = {
+  operationType: OperationType;
+};
+export const operationTypeQueryContext = new AsyncLocalStorage<OperationTypeQueryContext>();
+
+export async function getOperationType(): Promise<OperationType> {
+  return operationTypeQueryContext.getStore()?.operationType ?? "DML";
+}

package/src/utils/sqlUtils.ts

@@ -329,7 +329,7 @@ export function generateDropTableStatements(
   const dropStatements: string[] = [];
   const validOptions = options ?? { sequence: true, table: true };
   if (!validOptions.sequence && !validOptions.table) {
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.warn('No drop operations requested: both "table" and "sequence" options are false');
     return [];
   }

package/src/webtriggers/applyMigrationsWebTrigger.ts

@@ -31,15 +31,15 @@ export const applySchemaMigrations = async (
     if (typeof migration !== "function") {
       throw new Error("migration is not a function");
     }
-      // eslint-disable-next-line no-console
-    console.log("Provisioning the database");
+    // eslint-disable-next-line no-console
+    console.debug("Provisioning the database");
     await sql._provision();
-      // eslint-disable-next-line no-console
-    console.info("Running schema migrations");
+    // eslint-disable-next-line no-console
+    console.debug("Running schema migrations");
     const migrations = await migration(migrationRunner);
     const successfulMigrations = await migrations.run();
-      // eslint-disable-next-line no-console
-    console.info("Migrations applied:", successfulMigrations);
+    // eslint-disable-next-line no-console
+    console.debug("Migrations applied:", successfulMigrations);
 
     const migrationList = await migrationRunner.list();
     let migrationHistory = "No migrations found";
@@ -53,8 +53,8 @@ export const applySchemaMigrations = async (
         .map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toUTCString()}`)
         .join("\n");
     }
-      // eslint-disable-next-line no-console
-    console.info("Migrations history:\nid, name, migrated_at\n", migrationHistory);
+    // eslint-disable-next-line no-console
+    console.debug("Migrations history:\nid, name, migrated_at\n", migrationHistory);
 
     return {
       headers: { "Content-Type": ["application/json"] },
@@ -70,7 +70,7 @@ export const applySchemaMigrations = async (
       error?.debug?.context?.message ??
       error.message ??
       "Unknown error occurred";
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.error("Error during migration:", errorMessage);
     return {
       headers: { "Content-Type": ["application/json"] },

package/src/webtriggers/clearCacheSchedulerTrigger.ts

@@ -64,7 +64,7 @@ export const clearCacheSchedulerTrigger = async (options?: ForgeSqlOrmOptions) =
       }),
     };
   } catch (error) {
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.error("Error during cache cleanup: ", JSON.stringify(error));
     return {
       headers: { "Content-Type": ["application/json"] },

package/src/webtriggers/dropMigrationWebTrigger.ts

@@ -34,7 +34,7 @@ export async function dropSchemaMigrations(): Promise<TriggerResponse<string>> {
 
     // Execute each statement
     for (const statement of dropStatements) {
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.debug(`execute DDL: ${statement}`);
       await sql.executeDDL(statement);
     }
@@ -49,7 +49,7 @@ export async function dropSchemaMigrations(): Promise<TriggerResponse<string>> {
       error?.debug?.message ??
       error.message ??
       "Unknown error occurred";
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.error(errorMessage);
     return getHttpResponse<string>(500, errorMessage);
   }

package/src/webtriggers/dropTablesMigrationWebTrigger.ts

@@ -34,7 +34,7 @@ export async function dropTableSchemaMigrations(): Promise<TriggerResponse<strin
 
     // Execute each statement
     for (const statement of dropStatements) {
-        // eslint-disable-next-line no-console
+      // eslint-disable-next-line no-console
       console.debug(`execute DDL: ${statement}`);
       await sql.executeDDL(statement);
     }
@@ -49,7 +49,7 @@ export async function dropTableSchemaMigrations(): Promise<TriggerResponse<strin
       error?.debug?.message ??
       error.message ??
       "Unknown error occurred";
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.error(errorMessage);
     return getHttpResponse<string>(500, errorMessage);
   }

package/src/webtriggers/fetchSchemaWebTrigger.ts

@@ -46,7 +46,7 @@ export async function fetchSchemaWebTrigger(): Promise<TriggerResponse<string>>
       error?.debug?.message ??
       error.message ??
       "Unknown error occurred";
-      // eslint-disable-next-line no-console
+    // eslint-disable-next-line no-console
     console.error(errorMessage);
     return getHttpResponse<string>(500, errorMessage);
   }