forge-sql-orm 2.1.14 → 2.1.16

package/src/utils/sqlUtils.ts

@@ -100,37 +100,37 @@ export const parseDateTime = (value: string | Date, format: string): Date => {
 };
 
 /**
- * Helper function to validate and format a date-like value using Luxon DateTime.
- * @param value - Date object, ISO/RFC2822/SQL/HTTP string, or timestamp (number|string).
- * @param format - DateTime format string (Luxon format tokens).
- * @returns Formatted date string.
- * @throws Error if value cannot be parsed as a valid date.
+ * Parses a string value into DateTime using multiple format parsers
  */
-export function formatDateTime(
-  value: Date | string | number,
-  format: string,
-  isTimeStamp: boolean,
-): string {
+function parseStringToDateTime(value: string): DateTime | null {
+  const parsers = [DateTime.fromISO, DateTime.fromRFC2822, DateTime.fromSQL, DateTime.fromHTTP];
+
+  for (const parser of parsers) {
+    const dt = parser(value);
+    if (dt.isValid) {
+      return dt;
+    }
+  }
+
+  // Try parsing as number string
+  const parsed = Number(value);
+  if (!Number.isNaN(parsed)) {
+    return DateTime.fromMillis(parsed);
+  }
+
+  return null;
+}
+
+/**
+ * Converts a value to DateTime
+ */
+function valueToDateTime(value: Date | string | number): DateTime {
   let dt: DateTime | null = null;
 
   if (value instanceof Date) {
     dt = DateTime.fromJSDate(value);
   } else if (typeof value === "string") {
-    for (const parser of [
-      DateTime.fromISO,
-      DateTime.fromRFC2822,
-      DateTime.fromSQL,
-      DateTime.fromHTTP,
-    ]) {
-      dt = parser(value);
-      if (dt.isValid) break;
-    }
-    if (!dt?.isValid) {
-      const parsed = Number(value);
-      if (!Number.isNaN(parsed)) {
-        dt = DateTime.fromMillis(parsed);
-      }
-    }
+    dt = parseStringToDateTime(value);
   } else if (typeof value === "number") {
     dt = DateTime.fromMillis(value);
   } else {
@@ -140,20 +140,47 @@ export function formatDateTime(
   if (!dt?.isValid) {
     throw new Error("Invalid Date");
   }
+
+  return dt;
+}
+
+/**
+ * Validates timestamp range for Atlassian Forge compatibility
+ */
+function validateTimestampRange(dt: DateTime): void {
   const minDate = DateTime.fromSeconds(1);
   const maxDate = DateTime.fromMillis(2147483647 * 1000); // 2038-01-19 03:14:07.999 UTC
 
+  if (dt < minDate) {
+    throw new Error(
+      "Atlassian Forge does not support zero or negative timestamps. Allowed range: from '1970-01-01 00:00:01.000000' to '2038-01-19 03:14:07.999999'.",
+    );
+  }
+
+  if (dt > maxDate) {
+    throw new Error(
+      "Atlassian Forge does not support timestamps beyond 2038-01-19 03:14:07.999999. Please use a smaller date within the supported range.",
+    );
+  }
+}
+
+/**
+ * Helper function to validate and format a date-like value using Luxon DateTime.
+ * @param value - Date object, ISO/RFC2822/SQL/HTTP string, or timestamp (number|string).
+ * @param format - DateTime format string (Luxon format tokens).
+ * @param isTimeStamp - Whether to validate timestamp range
+ * @returns Formatted date string.
+ * @throws Error if value cannot be parsed as a valid date.
+ */
+export function formatDateTime(
+  value: Date | string | number,
+  format: string,
+  isTimeStamp: boolean,
+): string {
+  const dt = valueToDateTime(value);
+
   if (isTimeStamp) {
-    if (dt < minDate) {
-      throw new Error(
-        "Atlassian Forge does not support zero or negative timestamps. Allowed range: from '1970-01-01 00:00:01.000000' to '2038-01-19 03:14:07.999999'.",
-      );
-    }
-    if (dt > maxDate) {
-      throw new Error(
-        "Atlassian Forge does not support timestamps beyond 2038-01-19 03:14:07.999999. Please use a smaller date within the supported range.",
-      );
-    }
+    validateTimestampRange(dt);
   }
 
   return dt.toFormat(format);
@@ -169,10 +196,7 @@ export function getPrimaryKeys<T extends AnyMySqlTable>(table: T): [string, AnyC
   const { columns, primaryKeys } = getTableMetadata(table);
 
   // First try to find primary keys in columns
-  const columnPrimaryKeys = Object.entries(columns).filter(([, column]) => column.primary) as [
-    string,
-    AnyColumn,
-  ][];
+  const columnPrimaryKeys = Object.entries(columns).filter(([, column]) => column.primary);
 
   if (columnPrimaryKeys.length > 0) {
     return columnPrimaryKeys;
@@ -199,6 +223,85 @@ export function getPrimaryKeys<T extends AnyMySqlTable>(table: T): [string, AnyC
   return [];
 }
 
+/**
+ * Processes foreign keys from foreignKeysSymbol
+ */
+function processForeignKeysFromSymbol(
+  table: AnyMySqlTable,
+  foreignKeysSymbol: symbol,
+): ForeignKeyBuilder[] {
+  const foreignKeys: ForeignKeyBuilder[] = [];
+  // @ts-ignore
+  const fkArray: any[] = table[foreignKeysSymbol];
+
+  if (!fkArray) {
+    return foreignKeys;
+  }
+
+  for (const fk of fkArray) {
+    if (fk.reference) {
+      const item = fk.reference(fk);
+      foreignKeys.push(item);
+    }
+  }
+
+  return foreignKeys;
+}
+
+/**
+ * Extracts config builders from config builder data
+ */
+function extractConfigBuilders(configBuilderData: any): any[] {
+  if (Array.isArray(configBuilderData)) {
+    return configBuilderData;
+  }
+
+  return Object.values(configBuilderData).map((item) => (item as ConfigBuilderData).value ?? item);
+}
+
+/**
+ * Checks if a builder is a ForeignKeyBuilder
+ */
+function isForeignKeyBuilder(builder: any): boolean {
+  if (!builder?.constructor) {
+    return false;
+  }
+
+  const builderName = builder.constructor.name.toLowerCase();
+  return builderName.includes("foreignkeybuilder");
+}
+
+/**
+ * Processes foreign keys from extraSymbol
+ */
+function processForeignKeysFromExtra(
+  table: AnyMySqlTable,
+  extraSymbol: symbol,
+): ForeignKeyBuilder[] {
+  const foreignKeys: ForeignKeyBuilder[] = [];
+  // @ts-ignore
+  const extraConfigBuilder = table[extraSymbol];
+
+  if (!extraConfigBuilder || typeof extraConfigBuilder !== "function") {
+    return foreignKeys;
+  }
+
+  const configBuilderData = extraConfigBuilder(table);
+  if (!configBuilderData) {
+    return foreignKeys;
+  }
+
+  const configBuilders = extractConfigBuilders(configBuilderData);
+
+  for (const builder of configBuilders) {
+    if (isForeignKeyBuilder(builder)) {
+      foreignKeys.push(builder);
+    }
+  }
+
+  return foreignKeys;
+}
+
 /**
  * Processes foreign keys from both foreignKeysSymbol and extraSymbol
  * @param table - The table schema
@@ -215,57 +318,117 @@ function processForeignKeys(
 
   // Process foreign keys from foreignKeysSymbol
   if (foreignKeysSymbol) {
-    // @ts-ignore
-    const fkArray: any[] = table[foreignKeysSymbol];
-    if (fkArray) {
-      for (const fk of fkArray) {
-        if (fk.reference) {
-          const item = fk.reference(fk);
-          foreignKeys.push(item);
-        }
-      }
-    }
+    foreignKeys.push(...processForeignKeysFromSymbol(table, foreignKeysSymbol));
   }
 
   // Process foreign keys from extraSymbol
   if (extraSymbol) {
-    // @ts-ignore
-    const extraConfigBuilder = table[extraSymbol];
-    if (extraConfigBuilder && typeof extraConfigBuilder === "function") {
-      const configBuilderData = extraConfigBuilder(table);
-      if (configBuilderData) {
-        const configBuilders = Array.isArray(configBuilderData)
-          ? configBuilderData
-          : Object.values(configBuilderData).map(
-              (item) => (item as ConfigBuilderData).value ?? item,
-            );
-
-        for (const builder of configBuilders) {
-          if (!builder?.constructor) continue;
-
-          const builderName = builder.constructor.name.toLowerCase();
-          if (builderName.includes("foreignkeybuilder")) {
-            foreignKeys.push(builder);
-          }
-        }
-      }
-    }
+    foreignKeys.push(...processForeignKeysFromExtra(table, extraSymbol));
   }
 
   return foreignKeys;
 }
 
+/**
+ * Extracts symbols from table schema.
+ * @param table - The table schema
+ * @returns Object containing relevant symbols
+ */
+function extractTableSymbols(table: AnyMySqlTable) {
+  const symbols = Object.getOwnPropertySymbols(table);
+  return {
+    nameSymbol: symbols.find((s) => s.toString().includes("Name")),
+    columnsSymbol: symbols.find((s) => s.toString().includes("Columns")),
+    foreignKeysSymbol: symbols.find((s) => s.toString().includes("ForeignKeys)")),
+    extraSymbol: symbols.find((s) => s.toString().includes("ExtraConfigBuilder")),
+  };
+}
+
+/**
+ * Maps builder to appropriate array based on its type.
+ * @param builder - The builder object
+ * @param builders - The builders object containing all arrays
+ * @returns True if builder was added to a specific array, false otherwise
+ */
+function addBuilderToTypedArray(
+  builder: any,
+  builders: {
+    indexes: AnyIndexBuilder[];
+    checks: CheckBuilder[];
+    primaryKeys: PrimaryKeyBuilder[];
+    uniqueConstraints: UniqueConstraintBuilder[];
+  },
+): boolean {
+  if (!builder?.constructor) {
+    return false;
+  }
+
+  const builderName = builder.constructor.name.toLowerCase();
+  const builderMap = {
+    indexbuilder: builders.indexes,
+    checkbuilder: builders.checks,
+    primarykeybuilder: builders.primaryKeys,
+    uniqueconstraintbuilder: builders.uniqueConstraints,
+  };
+
+  for (const [type, array] of Object.entries(builderMap)) {
+    if (builderName.includes(type)) {
+      array.push(builder);
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Processes extra configuration builders and adds them to the builders object.
+ * @param table - The table schema
+ * @param extraSymbol - The extra symbol from table
+ * @param builders - The builders object to populate
+ */
+function processExtraConfigBuilders(
+  table: AnyMySqlTable,
+  extraSymbol: symbol | undefined,
+  builders: {
+    indexes: AnyIndexBuilder[];
+    checks: CheckBuilder[];
+    foreignKeys: ForeignKeyBuilder[];
+    primaryKeys: PrimaryKeyBuilder[];
+    uniqueConstraints: UniqueConstraintBuilder[];
+    extras: any[];
+  },
+): void {
+  if (!extraSymbol) {
+    return;
+  }
+
+  // @ts-ignore
+  const extraConfigBuilder = table[extraSymbol];
+  if (!extraConfigBuilder || typeof extraConfigBuilder !== "function") {
+    return;
+  }
+
+  const configBuilderData = extraConfigBuilder(table);
+  if (!configBuilderData) {
+    return;
+  }
+
+  const configBuilders = extractConfigBuilders(configBuilderData);
+
+  for (const builder of configBuilders) {
+    addBuilderToTypedArray(builder, builders);
+    builders.extras.push(builder);
+  }
+}
+
 /**
  * Extracts table metadata from the schema.
  * @param {AnyMySqlTable} table - The table schema
  * @returns {MetadataInfo} Object containing table metadata
  */
 export function getTableMetadata(table: AnyMySqlTable): MetadataInfo {
-  const symbols = Object.getOwnPropertySymbols(table);
-  const nameSymbol = symbols.find((s) => s.toString().includes("Name"));
-  const columnsSymbol = symbols.find((s) => s.toString().includes("Columns"));
-  const foreignKeysSymbol = symbols.find((s) => s.toString().includes("ForeignKeys)"));
-  const extraSymbol = symbols.find((s) => s.toString().includes("ExtraConfigBuilder"));
+  const { nameSymbol, columnsSymbol, foreignKeysSymbol, extraSymbol } = extractTableSymbols(table);
 
   // Initialize builders arrays
   const builders = {
@@ -281,47 +444,7 @@ export function getTableMetadata(table: AnyMySqlTable): MetadataInfo {
   builders.foreignKeys = processForeignKeys(table, foreignKeysSymbol, extraSymbol);
 
   // Process extra configuration if available
-  if (extraSymbol) {
-    // @ts-ignore
-    const extraConfigBuilder = table[extraSymbol];
-    if (extraConfigBuilder && typeof extraConfigBuilder === "function") {
-      const configBuilderData = extraConfigBuilder(table);
-      if (configBuilderData) {
-        // Convert configBuilderData to array if it's an object
-        const configBuilders = Array.isArray(configBuilderData)
-          ? configBuilderData
-          : Object.values(configBuilderData).map(
-              (item) => (item as ConfigBuilderData).value ?? item,
-            );
-
-        // Process each builder
-        for (const builder of configBuilders) {
-          if (!builder?.constructor) continue;
-
-          const builderName = builder.constructor.name.toLowerCase();
-
-          // Map builder types to their corresponding arrays
-          const builderMap = {
-            indexbuilder: builders.indexes,
-            checkbuilder: builders.checks,
-            primarykeybuilder: builders.primaryKeys,
-            uniqueconstraintbuilder: builders.uniqueConstraints,
-          };
-
-          // Add builder to appropriate array if it matches any type
-          for (const [type, array] of Object.entries(builderMap)) {
-            if (builderName.includes(type)) {
-              array.push(builder);
-              break;
-            }
-          }
-
-          // Always add to extras array
-          builders.extras.push(builder);
-        }
-      }
-    }
-  }
+  processExtraConfigBuilders(table, extraSymbol, builders);
 
   return {
     tableName: nameSymbol ? (table as any)[nameSymbol] : "",
@@ -372,7 +495,7 @@ function mapSelectTableToAlias(
   const { columns, tableName } = getTableMetadata(table);
   const selectionsTableFields: Record<string, unknown> = {};
   for (const name of Object.keys(columns)) {
-    const column = columns[name] as AnyColumn;
+    const column = columns[name];
     const uniqName = `a_${uniqPrefix}_${tableName}_${column.name}`.toLowerCase();
     const fieldAlias = sql.raw(uniqName);
     selectionsTableFields[name] = sql`${column} as \`${fieldAlias}\``;
@@ -419,38 +542,71 @@ export function mapSelectFieldsWithAlias<TSelection extends SelectedFields>(
   }
   const aliasMap: AliasColumnMap = {};
   const selections: any = {};
-  for (let i = 0; i < Object.entries(fields).length; i++) {
-    const [name, fields1] = Object.entries(fields)[i];
+  for (const [name, fields1] of Object.entries(fields)) {
     mapSelectAllFieldsToAlias(selections, name, name, fields1, aliasMap);
   }
   return { selections, aliasMap };
 }
 
-function getAliasFromDrizzleAlias(value: unknown): string | undefined {
-  const isSQL =
-    value !== null && typeof value === "object" && isSQLWrapper(value) && "queryChunks" in value;
-  if (isSQL) {
-    const sql = value as SQL;
-    const queryChunks = sql.queryChunks;
-    if (queryChunks.length > 3) {
-      const aliasNameChunk = queryChunks[queryChunks.length - 2];
-      if (isSQLWrapper(aliasNameChunk) && "queryChunks" in aliasNameChunk) {
-        const aliasNameChunkSql = aliasNameChunk as SQL;
-        if (aliasNameChunkSql.queryChunks?.length === 1 && aliasNameChunkSql.queryChunks[0]) {
-          const queryChunksStringChunc = aliasNameChunkSql.queryChunks[0];
-          if ("value" in queryChunksStringChunc) {
-            const values = (queryChunksStringChunc as StringChunk).value;
-            if (values && values.length === 1) {
-              return values[0];
-            }
-          }
-        }
-      }
-    }
+/**
+ * Checks if value is a SQL object with queryChunks
+ */
+function isSQLValue(value: unknown): value is SQL {
+  return (
+    value !== null && typeof value === "object" && isSQLWrapper(value) && "queryChunks" in value
+  );
+}
+
+/**
+ * Extracts the alias name chunk from query chunks if it exists and is a SQL object
+ */
+function getAliasNameChunk(queryChunks: any[]): SQL | undefined {
+  if (queryChunks.length <= 3) {
+    return undefined;
   }
+
+  const aliasNameChunk = queryChunks.at(-2);
+  if (isSQLWrapper(aliasNameChunk) && "queryChunks" in aliasNameChunk) {
+    return aliasNameChunk as SQL;
+  }
+
+  return undefined;
+}
+
+/**
+ * Extracts string value from a SQL chunk if it contains a single string value
+ */
+function extractStringValueFromChunk(chunk: SQL): string | undefined {
+  if (chunk.queryChunks?.length !== 1 || !chunk.queryChunks[0]) {
+    return undefined;
+  }
+
+  const stringChunk = chunk.queryChunks[0];
+  if (!("value" in stringChunk)) {
+    return undefined;
+  }
+
+  const values = (stringChunk as StringChunk).value;
+  if (values?.length === 1) {
+    return values[0];
+  }
+
   return undefined;
 }
 
+function getAliasFromDrizzleAlias(value: unknown): string | undefined {
+  if (!isSQLValue(value)) {
+    return undefined;
+  }
+
+  const aliasNameChunk = getAliasNameChunk(value.queryChunks);
+  if (!aliasNameChunk) {
+    return undefined;
+  }
+
+  return extractStringValueFromChunk(aliasNameChunk);
+}
+
 function transformValue(
   value: unknown,
   alias: string,
@@ -504,7 +660,7 @@ export function applyFromDriverTransform<T, TSelection>(
       row as Record<string, unknown>,
       selections as Record<string, unknown>,
       aliasMap,
-    ) as Record<string, unknown>;
+    );
 
     return processNullBranches(transformed) as unknown as T;
   });
@@ -772,5 +928,5 @@ export function withTidbHint<
 >(column: AnyMySqlColumn<TPartial>): AnyMySqlColumn<TPartial> {
   // We lie a bit to TypeScript here: at runtime this is a new SQL fragment,
   // but returning TExpr keeps the column type info in downstream inference.
-  return sql`/*+ SET_VAR(tidb_session_alias=${sql.raw(`${SESSION_ALIAS_NAME_ORM}`)}) */ ${column}` as unknown as AnyMySqlColumn<TPartial>;
+  return sql`/*+ SET_VAR(tidb_session_alias=${sql.raw(SESSION_ALIAS_NAME_ORM)}) */ ${column}` as unknown as AnyMySqlColumn<TPartial>;
 }

package/src/webtriggers/applyMigrationsWebTrigger.ts

@@ -50,7 +50,7 @@ export const applySchemaMigrations = async (
       );
 
       migrationHistory = sortedMigrations
-        .map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toUTCString()}`)
+        .map((y) => `${y.id}, ${y.name}, ${y.migratedAt.toISOString()}`)
         .join("\n");
     }
     // eslint-disable-next-line no-console

package/src/webtriggers/index.ts

@@ -4,6 +4,7 @@ export * from "./fetchSchemaWebTrigger";
 export * from "./dropTablesMigrationWebTrigger";
 export * from "./clearCacheSchedulerTrigger";
 export * from "./slowQuerySchedulerTrigger";
+export * from "./topSlowestStatementLastHourTrigger";
 
 export interface TriggerResponse<BODY> {
   body?: BODY;

package/src/webtriggers/topSlowestStatementLastHourTrigger.ts

@@ -0,0 +1,69 @@
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
+import { slowQuerySchedulerTrigger, TriggerResponse } from "./";
+import { OperationType } from "../utils/requestTypeContextUtils";
+
+export interface TriggerOptions {
+  warnThresholdMs?: number;
+  memoryThresholdBytes?: number;
+  showPlan?: boolean;
+  operationType?: OperationType;
+  topN?: number;
+  hours?: number;
+  tables?: "SUMMARY_AND_HISTORY" | "CLUSTER_SUMMARY_AND_HISTORY";
+}
+
+/**
+ * @deprecated This function is deprecated and will be removed in a future version.
+ *
+ * This function was previously a complex implementation that directly queried
+ * CLUSTER_STATEMENTS_SUMMARY tables to analyze query performance. However, this approach
+ * had reliability issues with long-running functions where metadata could be evicted
+ * before the function completes.
+ *
+ * The recommended replacement is to use the new observability system with `executeWithMetadata`:
+ * - **TopSlowest mode** (default): Deterministic logging of SQL digests executed in resolvers
+ * - **SummaryTable mode** (optional): Uses CLUSTER_STATEMENTS_SUMMARY with a short memory window
+ * - Automatic fallback mechanisms for long-running functions
+ * - More reliable post-mortem diagnostics for Timeout and OOM errors
+ *
+ * Note: `slowQuerySchedulerTrigger` is a different function that analyzes TiDB's slow query log
+ * and is not a direct replacement for this function.
+ *
+ * For more details on the improvements and migration path, see:
+ * https://community.developer.atlassian.com/t/practical-sql-observability-for-forge-apps-with-forge-sql-orm/123456
+ *
+ * @param orm - ForgeSQL ORM instance
+ * @param options - Configuration options (currently passed to slowQuerySchedulerTrigger as a temporary wrapper)
+ * @returns Promise<TriggerResponse<string>> - HTTP response with query results or error
+ *
+ * @example
+ * ```typescript
+ * // Old usage (deprecated):
+ * await topSlowestStatementLastHourTrigger(forgeSQL, { hours: 1 });
+ *
+ * // New usage (recommended - use executeWithMetadata in your resolvers):
+ * await forgeSQL.executeWithMetadata(
+ *   async () => {
+ *     // your resolver logic
+ *   },
+ *   async (totalDbTime, totalResponseSize, printPlan) => {
+ *     // custom observability logic
+ *     if (totalDbTime > 1000) await printPlan();
+ *   },
+ *   {
+ *     mode: "TopSlowest",
+ *     topQueries: 1,
+ *     showSlowestPlans: true
+ *   }
+ * );
+ * ```
+ */
+export const topSlowestStatementLastHourTrigger = async (
+  orm: ForgeSqlOperation,
+  options?: TriggerOptions,
+): Promise<TriggerResponse<string>> => {
+  return slowQuerySchedulerTrigger(
+    orm,
+    options ? { timeout: 3000, hours: options.hours ?? 1 } : { timeout: 3000, hours: 1 },
+  );
+};