// SPDX-FileCopyrightText: 2025-2026 Vasyl Zakharchenko
// SPDX-License-Identifier: MIT

import { ForgeSQLCrudOperations } from "./ForgeSQLCrudOperations";
import {
  VerioningModificationForgeSQL,
  ForgeSqlOperation,
  ForgeSqlOrmOptions,
  SchemaAnalyzeForgeSql,
  SchemaSqlForgeSql,
} from "./ForgeSQLQueryBuilder";
import { ForgeSQLSelectOperations } from "./ForgeSQLSelectOperations";
import {
  drizzle,
  MySqlRemoteDatabase,
  MySqlRemotePreparedQueryHKT,
  MySqlRemoteQueryResultHKT,
} from "drizzle-orm/mysql-proxy";
import { createForgeDriverProxy } from "../utils/forgeDriverProxy";
import type { SelectedFields } from "drizzle-orm/mysql-core/query-builders/select.types";
import { MySqlSelectBuilder } from "drizzle-orm/mysql-core";
import {
  patchDbWithSelectAliased,
  SelectAliasedDistinctType,
  SelectAliasedType,
  NopCache,
} from "../lib";
import { ForgeSQLAnalyseOperation } from "./ForgeSQLAnalyseOperations";
import { MySqlTable } from "drizzle-orm/mysql-core/table";
import {
  MySqlDeleteBase,
  MySqlInsertBuilder,
  MySqlUpdateBuilder,
} from "drizzle-orm/mysql-core/query-builders";
import {
  localCacheApplicationContext,
  getErrorMessage,
  getLastestMetadata,
  metadataQueryContext,
  MetadataQueryOptions,
  normalizeSqlForLoggingRegex,
} from "../utils";
import { SQLWrapper } from "drizzle-orm/sql/sql";
import { WithSubquery } from "drizzle-orm/subquery";
import { operationTypeQueryContext } from "../utils/requestTypeContextUtils";
import type { MySqlQueryResultKind } from "drizzle-orm/mysql-core/session";

/**
 * Implementation of ForgeSQLORM that uses Drizzle ORM for query building.
 * This class provides a bridge between Forge SQL and Drizzle ORM, allowing
 * to use Drizzle's query builder while executing queries through Forge SQL.
 */
class ForgeSQLORMImpl implements ForgeSqlOperation {
  private static instance: ForgeSQLORMImpl | null = null;
  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- MySqlRemoteDatabase's schema generic is a Drizzle internal type; this driver is schema-agnostic at this layer
  private readonly drizzle: MySqlRemoteDatabase<any> & {
    selectAliased: SelectAliasedType;
    selectAliasedDistinct: SelectAliasedDistinctType;
  };
  private readonly crudOperations: VerioningModificationForgeSQL;
  private readonly fetchOperations: SchemaSqlForgeSql;
  private readonly analyzeOperations: SchemaAnalyzeForgeSql;

  /**
   * Private constructor to enforce singleton behavior.
   * @param options - Options for configuring ForgeSQL ORM behavior.
   */
  private constructor(options?: ForgeSqlOrmOptions) {
    try {
      const newOptions: ForgeSqlOrmOptions = options ?? {
        logRawSqlQuery: false,
        logCache: false,
        disableOptimisticLocking: false,
        cacheWrapTable: true,
        cacheTTL: 120,
        cacheImplementation: new NopCache(),
      };

      if (newOptions.logRawSqlQuery) {
        // eslint-disable-next-line no-console
        console.debug("Initializing ForgeSQLORM...");
      }
      // Initialize Drizzle instance with our custom driver
      const proxiedDriver = createForgeDriverProxy(this, newOptions.logRawSqlQuery);
      this.drizzle = patchDbWithSelectAliased(
        drizzle(proxiedDriver, { logger: newOptions.logRawSqlQuery }),
        newOptions,
      );
      this.crudOperations = new ForgeSQLCrudOperations(this, newOptions);
      this.fetchOperations = new ForgeSQLSelectOperations(newOptions);
      this.analyzeOperations = new ForgeSQLAnalyseOperation(this);
    } catch (error) {
      // eslint-disable-next-line no-console
      console.error("ForgeSQLORM initialization failed:", error);
      throw error;
    }
  }

  /**
   * Executes a query and provides access to execution metadata with performance monitoring.
   * This method allows you to capture detailed information about query execution
   * including database execution time, response size, and query analysis capabilities.
   *
   * The method aggregates metrics across all database operations within the query function,
   * making it ideal for monitoring resolver performance and detecting performance issues.
   *
   * @template T - The return type of the query
   * @param query - A function that returns a Promise with the query result. Can contain multiple database operations.
   * @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.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 - When `true` (default), printed SQL is passed through {@link ForgeSqlOperation.normalizationSQL}. Set to `false` to log raw SQL if normalization causes issues
   * @returns Promise with the query result
   *
   * @example
   * ```typescript
   * // Basic usage with performance monitoring
   * const result = await forgeSQL.executeWithMetadata(
   *   async () => {
   *     const users = await forgeSQL.selectFrom(usersTable);
   *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
   *     return { users, orders };
   *   },
   *   (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 printQueriesWithPlan(); // Analyze and print query execution plans
   *     } else if (totalDbExecutionTime > threshold) {
   *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
   *     }
   *
   *     console.log(`DB response size: ${totalResponseSize} bytes`);
   *   }
   * );
   * ```
   *
   * @example
   * ```typescript
   * // Resolver with performance monitoring
   * resolver.define("fetch", async (req: Request) => {
   *   try {
   *     return await forgeSQL.executeWithMetadata(
   *       async () => {
   *         // Resolver logic with multiple queries
   *         const users = await forgeSQL.selectFrom(demoUsers);
   *         const orders = await forgeSQL.selectFrom(demoOrders)
   *           .where(eq(demoOrders.userId, demoUsers.id));
   *         return { users, orders };
   *       },
   *       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 printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
   *         } else if (totalDbExecutionTime > threshold) {
   *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
   *         }
   *
   *         console.log(`DB response size: ${totalResponseSize} bytes`);
   *       }
   *     );
   *   } catch (e) {
   *     const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
   *     console.error(error, e);
   *     throw error;
   *   }
   * });
   * ```
   *
   * @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>,
    onMetadata: (
      totalDbExecutionTime: number,
      totalResponseSize: number,
      printQueriesWithPlan: () => Promise<void>,
    ) => Promise<void> | void,
    options?: MetadataQueryOptions,
  ): Promise<T> {
    return metadataQueryContext.run(
      {
        totalDbExecutionTime: 0,
        totalResponseSize: 0,
        beginTime: new Date(),
        forgeSQLORM: this,
        printQueriesWithPlan: async () => {
          return;
        },
        options: options,
        statistics: [],
      },
      async () => {
        const result = await query();
        const metadata = await getLastestMetadata();
        try {
          if (metadata) {
            await onMetadata(
              metadata.totalDbExecutionTime,
              metadata.totalResponseSize,
              metadata.printQueriesWithPlan,
            );
          }
        } catch (e) {
          // eslint-disable-next-line no-console
          console.error(
            "[ForgeSQLORM][executeWithMetadata] Failed to run onMetadata callback",
            {
              errorMessage: getErrorMessage(e),
              errorStack: e instanceof Error ? e.stack : undefined,
              totalDbExecutionTime: metadata?.totalDbExecutionTime,
              totalResponseSize: metadata?.totalResponseSize,
              beginTime: metadata?.beginTime,
            },
            e,
          );
        }
        return result;
      },
    );
  }

  /**
   * Executes operations within a local cache context and returns a value.
   * This provides in-memory caching for select queries within a single request scope.
   *
   * @param cacheContext - Function containing operations that will benefit from local caching
   * @returns Promise that resolves to the return value of the cacheContext function
   */
  async executeWithLocalCacheContextAndReturnValue<T>(cacheContext: () => Promise<T>): Promise<T> {
    return await localCacheApplicationContext.run(
      localCacheApplicationContext.getStore() ?? { cache: {} },
      async () => {
        return await cacheContext();
      },
    );
  }

  /**
   * Executes operations within a local cache context.
   * This provides in-memory caching for select queries within a single request scope.
   *
   * @param cacheContext - Function containing operations that will benefit from local caching
   * @returns Promise that resolves when all operations are complete
   */
  executeWithLocalContext(cacheContext: () => Promise<void>): Promise<void> {
    return this.executeWithLocalCacheContextAndReturnValue<void>(cacheContext);
  }
  /**
   * Creates an insert query builder.
   *
   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
   * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
   *
   * @param table - The table to insert into
   * @returns Insert query builder (no versioning, no cache management)
   */
  insert<TTable extends MySqlTable>(
    table: TTable,
  ): MySqlInsertBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
    return this.drizzle.insertWithCacheContext(table);
  }

  /**
   * Creates an update query builder.
   *
   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
   * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
   *
   * @param table - The table to update
   * @returns Update query builder (no versioning, no cache management)
   */
  update<TTable extends MySqlTable>(
    table: TTable,
  ): MySqlUpdateBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
    return this.drizzle.updateWithCacheContext(table);
  }

  /**
   * Creates a delete query builder.
   *
   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
   * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
   *
   * @param table - The table to delete from
   * @returns Delete query builder (no versioning, no cache management)
   */
  delete<TTable extends MySqlTable>(
    table: TTable,
  ): MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
    return this.drizzle.deleteWithCacheContext(table);
  }

  /**
   * Create the modify operations instance.
   * @returns modify operations.
   */
  modifyWithVersioning(): VerioningModificationForgeSQL {
    return this.crudOperations;
  }

  /**
   * Returns the singleton instance of ForgeSQLORMImpl.
   * @param options - Options for configuring ForgeSQL ORM behavior.
   * @returns The singleton instance of ForgeSQLORMImpl.
   */
  static getInstance(options?: ForgeSqlOrmOptions): ForgeSqlOperation {
    ForgeSQLORMImpl.instance ??= new ForgeSQLORMImpl(options);
    return ForgeSQLORMImpl.instance;
  }

  /**
   * Retrieves the fetch operations instance.
   * @returns Fetch operations.
   */
  fetch(): SchemaSqlForgeSql {
    return this.fetchOperations;
  }

  /**
   * Provides query analysis capabilities including EXPLAIN ANALYZE and slow query analysis.
   * @returns {SchemaAnalyzeForgeSql} Interface for analyzing query performance
   */
  analyze(): SchemaAnalyzeForgeSql {
    return this.analyzeOperations;
  }

  /**
   * Returns a Drizzle query builder instance.
   *
   * ⚠️ IMPORTANT: This method should be used ONLY for query building purposes.
   * The returned instance should NOT be used for direct database connections or query execution.
   * All database operations should be performed through Forge SQL's executeRawSQL or executeRawUpdateSQL methods.
   *
   * @returns A Drizzle query builder instance for query construction only.
   */
  getDrizzleQueryBuilder(): MySqlRemoteDatabase<Record<string, unknown>> & {
    selectAliased: SelectAliasedType;
    selectAliasedDistinct: SelectAliasedDistinctType;
  } {
    return this.drizzle;
  }

  /**
   * Creates a select query with unique field aliases to prevent field name collisions in joins.
   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
   *
   * @template TSelection - The type of the selected fields
   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
   * @throws {Error} If fields parameter is empty
   * @example
   * ```typescript
   * await forgeSQL
   *   .select({user: users, order: orders})
   *   .from(orders)
   *   .innerJoin(users, eq(orders.userId, users.id));
   * ```
   */
  select<TSelection extends SelectedFields>(
    fields: TSelection,
  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT> {
    if (!fields) {
      throw new Error("fields is empty");
    }
    return this.drizzle.selectAliased(fields);
  }

  /**
   * Creates a distinct select query with unique field aliases to prevent field name collisions in joins.
   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
   *
   * @template TSelection - The type of the selected fields
   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A distinct select query builder with unique field aliases
   * @throws {Error} If fields parameter is empty
   * @example
   * ```typescript
   * await forgeSQL
   *   .selectDistinct({user: users, order: orders})
   *   .from(orders)
   *   .innerJoin(users, eq(orders.userId, users.id));
   * ```
   */
  selectDistinct<TSelection extends SelectedFields>(
    fields: TSelection,
  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT> {
    if (!fields) {
      throw new Error("fields is empty");
    }
    return this.drizzle.selectAliasedDistinct(fields);
  }

  /**
   * Creates a select query builder for all columns from a table with field aliasing support.
   * This is a convenience method that automatically selects all columns from the specified table.
   *
   * @template T - The type of the table
   * @param table - The table to select from
   * @returns Select query builder with all table columns and field aliasing support
   * @example
   * ```typescript
   * const users = await forgeSQL.selectFrom(userTable).where(eq(userTable.id, 1));
   * ```
   */
  selectFrom<T extends MySqlTable>(table: T) {
    return this.drizzle.selectFrom(table);
  }

  /**
   * Creates a select distinct query builder for all columns from a table with field aliasing support.
   * This is a convenience method that automatically selects all distinct columns from the specified table.
   *
   * @template T - The type of the table
   * @param table - The table to select from
   * @returns Select distinct query builder with all table columns and field aliasing support
   * @example
   * ```typescript
   * const uniqueUsers = await forgeSQL.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
   * ```
   */
  selectDistinctFrom<T extends MySqlTable>(table: T) {
    return this.drizzle.selectDistinctFrom(table);
  }

  /**
   * Executes a raw SQL query with local cache support.
   * This method provides local caching for raw SQL queries within the current invocation context.
   * Results are cached locally and will be returned from cache on subsequent identical queries.
   *
   * @param query - The SQL query to execute (SQLWrapper or string)
   * @returns Promise with query results
   * @example
   * ```typescript
   * // Using SQLWrapper
   * const result = await forgeSQL.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
   *
   * // Using string
   * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
   * ```
   */
  execute<T>(query: SQLWrapper | string) {
    return this.drizzle.executeQuery<T>(query);
  }

  /**
   * Executes a Data Definition Language (DDL) SQL query.
   * DDL operations include CREATE, ALTER, DROP, TRUNCATE, and other schema modification statements.
   *
   * This method is specifically designed for DDL operations and provides:
   * - Proper operation type context for DDL queries
   * - No caching (DDL operations should not be cached)
   * - Direct execution without query optimization
   *
   * @template T - The expected return type of the query result
   * @param query - The DDL SQL query to execute (SQLWrapper or string)
   * @returns Promise with query results
   * @throws {Error} If the DDL operation fails
   *
   * @example
   * ```typescript
   * // Create a new table
   * await forgeSQL.executeDDL(`
   *   CREATE TABLE users (
   *     id INT PRIMARY KEY AUTO_INCREMENT,
   *     name VARCHAR(255) NOT NULL,
   *     email VARCHAR(255) UNIQUE
   *   )
   * `);
   *
   * // Alter table structure
   * await forgeSQL.executeDDL(sql`
   *   ALTER TABLE users
   *   ADD COLUMN created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   * `);
   *
   * // Drop a table
   * await forgeSQL.executeDDL("DROP TABLE IF EXISTS old_users");
   * ```
   */
  async executeDDL<T>(query: SQLWrapper | string) {
    return this.executeDDLActions(async () => this.drizzle.executeQuery<T>(query));
  }

  /**
   * Executes a series of actions within a DDL operation context.
   * This method provides a way to execute regular SQL queries that should be treated
   * as DDL operations, ensuring proper operation type context for performance monitoring.
   *
   * This method is useful for:
   * - Executing regular SQL queries in DDL context for monitoring purposes
   * - Wrapping non-DDL operations that should be treated as DDL for analysis
   * - Ensuring proper operation type context for complex workflows
   * - Maintaining DDL operation context across multiple function calls
   *
   * @template T - The return type of the actions function
   * @param actions - Function containing SQL operations to execute in DDL context
   * @returns Promise that resolves to the return value of the actions function
   *
   * @example
   * ```typescript
   * // Execute regular SQL queries in DDL context for monitoring
   * await forgeSQL.executeDDLActions(async () => {
   *   const slowQueries = await forgeSQL.execute(`
   *     SELECT * FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
   *     WHERE AVG_LATENCY > 1000000
   *   `);
   *   return slowQueries;
   * });
   *
   * // Execute complex analysis queries in DDL context
   * const result = await forgeSQL.executeDDLActions(async () => {
   *   const tableInfo = await forgeSQL.execute("SHOW TABLES");
   *   const performanceData = await forgeSQL.execute(`
   *     SELECT * FROM INFORMATION_SCHEMA.CLUSTER_STATEMENTS_SUMMARY_HISTORY
   *     WHERE SUMMARY_END_TIME > DATE_SUB(NOW(), INTERVAL 1 HOUR)
   *   `);
   *   return { tableInfo, performanceData };
   * });
   *
   * // Execute monitoring queries with error handling
   * try {
   *   await forgeSQL.executeDDLActions(async () => {
   *     const metrics = await forgeSQL.execute(`
   *       SELECT COUNT(*) as query_count
   *       FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
   *     `);
   *     console.log(`Total queries: ${metrics[0].query_count}`);
   *   });
   * } catch (error) {
   *   console.error("Monitoring query failed:", error);
   * }
   * ```
   */
  async executeDDLActions<T>(actions: () => Promise<T>): Promise<T> {
    return operationTypeQueryContext.run({ operationType: "DDL" }, async () => actions());
  }

  /**
   * Creates a Common Table Expression (CTE) builder for complex queries.
   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
   *
   * @returns WithBuilder for creating CTEs
   * @example
   * ```typescript
   * const withQuery = forgeSQL.$with('userStats').as(
   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
   *     .from(users)
   *     .groupBy(users.id)
   * );
   * ```
   */
  get $with() {
    return this.drizzle.$with;
  }

  /**
   * Creates a query builder that uses Common Table Expressions (CTEs).
   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
   *
   * @param queries - Array of CTE queries created with $with()
   * @returns Query builder with CTE support
   * @example
   * ```typescript
   * const withQuery = forgeSQL.$with('userStats').as(
   *   forgeSQL.select({ userId: users.id, count: sql<number>`count(*)` })
   *     .from(users)
   *     .groupBy(users.id)
   * );
   *
   * const result = await forgeSQL.with(withQuery)
   *   .select({ userId: withQuery.userId, count: withQuery.count })
   *   .from(withQuery);
   * ```
   */
  with(...queries: WithSubquery[]) {
    return this.drizzle.with(...queries);
  }

  /**
   * Normalizes SQL for logging using regex-based literal replacement.
   *
   * @param sql - Raw SQL query string
   * @returns Normalized SQL with literals replaced by `?`
   * @see normalizeSqlForLoggingRegex
   */
  normalizationSQL(sql: string): string {
    return normalizeSqlForLoggingRegex(sql);
  }
}

/**
 * Public class that acts as a wrapper around the private ForgeSQLORMImpl.
 * Provides a clean interface for working with Forge SQL and Drizzle ORM.
 */
class ForgeSQLORM implements ForgeSqlOperation {
  private readonly ormInstance: ForgeSqlOperation;

  constructor(options?: ForgeSqlOrmOptions) {
    this.ormInstance = ForgeSQLORMImpl.getInstance(options);
  }

  /**
   * Executes a query and provides access to execution metadata with performance monitoring.
   * This method allows you to capture detailed information about query execution
   * including database execution time, response size, and query analysis capabilities.
   *
   * The method aggregates metrics across all database operations within the query function,
   * making it ideal for monitoring resolver performance and detecting performance issues.
   *
   * @template T - The return type of the query
   * @param query - A function that returns a Promise with the query result. Can contain multiple database operations.
   * @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.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 - When `true` (default), printed SQL is passed through {@link ForgeSqlOperation.normalizationSQL}. Set to `false` to log raw SQL if normalization causes issues
   * @returns Promise with the query result
   *
   * @example
   * ```typescript
   * // Basic usage with performance monitoring
   * const result = await forgeSQL.executeWithMetadata(
   *   async () => {
   *     const users = await forgeSQL.selectFrom(usersTable);
   *     const orders = await forgeSQL.selectFrom(ordersTable).where(eq(ordersTable.userId, usersTable.id));
   *     return { users, orders };
   *   },
   *   (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 printQueriesWithPlan(); // Analyze and print query execution plans
   *     } else if (totalDbExecutionTime > threshold) {
   *       console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
   *     }
   *
   *     console.log(`DB response size: ${totalResponseSize} bytes`);
   *   }
   * );
   * ```
   *
   * @example
   * ```typescript
   * // Resolver with performance monitoring
   * resolver.define("fetch", async (req: Request) => {
   *   try {
   *     return await forgeSQL.executeWithMetadata(
   *       async () => {
   *         // Resolver logic with multiple queries
   *         const users = await forgeSQL.selectFrom(demoUsers);
   *         const orders = await forgeSQL.selectFrom(demoOrders)
   *           .where(eq(demoOrders.userId, demoUsers.id));
   *         return { users, orders };
   *       },
   *       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 printQueriesWithPlan(); // Optionally log or capture diagnostics for further analysis
   *         } else if (totalDbExecutionTime > threshold) {
   *           console.debug(`[Performance Debug] High DB time: ${totalDbExecutionTime} ms`);
   *         }
   *
   *         console.log(`DB response size: ${totalResponseSize} bytes`);
   *       }
   *     );
   *   } catch (e) {
   *     const error = e?.cause?.debug?.sqlMessage ?? e?.cause;
   *     console.error(error, e);
   *     throw error;
   *   }
   * });
   * ```
   *
   * @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>,
    onMetadata: (
      totalDbExecutionTime: number,
      totalResponseSize: number,
      printQueriesWithPlan: () => Promise<void>,
    ) => Promise<void> | void,
    options?: MetadataQueryOptions,
  ): Promise<T> {
    return this.ormInstance.executeWithMetadata(query, onMetadata, options);
  }

  /**
   * Creates a select query builder for all columns from a table with field aliasing support.
   * This is a convenience method that automatically selects all columns from the specified table.
   *
   * @template T - The type of the table
   * @param table - The table to select from
   * @returns Select query builder with all table columns and field aliasing support
   * @example
   * ```typescript
   * const users = await forgeSQL.selectFrom(userTable).where(eq(userTable.id, 1));
   * ```
   */
  selectFrom<T extends MySqlTable>(table: T) {
    return this.ormInstance.getDrizzleQueryBuilder().selectFrom(table);
  }

  /**
   * Creates a select distinct query builder for all columns from a table with field aliasing support.
   * This is a convenience method that automatically selects all distinct columns from the specified table.
   *
   * @template T - The type of the table
   * @param table - The table to select from
   * @returns Select distinct query builder with all table columns and field aliasing support
   * @example
   * ```typescript
   * const uniqueUsers = await forgeSQL.selectDistinctFrom(userTable).where(eq(userTable.status, 'active'));
   * ```
   */
  selectDistinctFrom<T extends MySqlTable>(table: T) {
    return this.ormInstance.getDrizzleQueryBuilder().selectDistinctFrom(table);
  }

  /**
   * Creates a cacheable select distinct query builder for all columns from a table with field aliasing and caching support.
   * This is a convenience method that automatically selects all distinct columns from the specified table with caching enabled.
   *
   * @template T - The type of the table
   * @param table - The table to select from
   * @param cacheTTL - Optional cache TTL override (defaults to global cache TTL)
   * @returns Select distinct query builder with all table columns, field aliasing, and caching support
   * @example
   * ```typescript
   * const uniqueUsers = await forgeSQL.selectDistinctCacheableFrom(userTable, 300).where(eq(userTable.status, 'active'));
   * ```
   */
  selectDistinctCacheableFrom<T extends MySqlTable>(table: T, cacheTTL?: number) {
    return this.ormInstance.getDrizzleQueryBuilder().selectDistinctFromCacheable(table, cacheTTL);
  }

  /**
   * Executes operations within a local cache context.
   * This provides in-memory caching for select queries within a single request scope.
   *
   * @param cacheContext - Function containing operations that will benefit from local caching
   * @returns Promise that resolves when all operations are complete
   */
  executeWithLocalContext(cacheContext: () => Promise<void>): Promise<void> {
    return this.ormInstance.executeWithLocalContext(cacheContext);
  }

  /**
   * Executes operations within a local cache context and returns a value.
   * This provides in-memory caching for select queries within a single request scope.
   *
   * @param cacheContext - Function containing operations that will benefit from local caching
   * @returns Promise that resolves to the return value of the cacheContext function
   */
  executeWithLocalCacheContextAndReturnValue<T>(cacheContext: () => Promise<T>): Promise<T> {
    return this.ormInstance.executeWithLocalCacheContextAndReturnValue(cacheContext);
  }

  /**
   * Creates an insert query builder.
   *
   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
   * For versioned inserts, use `modifyWithVersioning().insert()` or `modifyWithVersioningAndEvictCache().insert()` instead.
   *
   * @param table - The table to insert into
   * @returns Insert query builder (no versioning, no cache management)
   */
  insert<TTable extends MySqlTable>(
    table: TTable,
  ): MySqlInsertBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
    return this.ormInstance.insert(table);
  }

  /**
   * Creates an update query builder.
   *
   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
   * For versioned updates, use `modifyWithVersioning().updateById()` or `modifyWithVersioningAndEvictCache().updateById()` instead.
   *
   * @param table - The table to update
   * @returns Update query builder (no versioning, no cache management)
   */
  update<TTable extends MySqlTable>(
    table: TTable,
  ): MySqlUpdateBuilder<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
    return this.ormInstance.update(table);
  }

  /**
   * Creates a delete query builder.
   *
   * ⚠️ **IMPORTANT**: This method does NOT support optimistic locking/versioning.
   * For versioned deletes, use `modifyWithVersioning().deleteById()` or `modifyWithVersioningAndEvictCache().deleteById()` instead.
   *
   * @param table - The table to delete from
   * @returns Delete query builder (no versioning, no cache management)
   */
  delete<TTable extends MySqlTable>(
    table: TTable,
  ): MySqlDeleteBase<TTable, MySqlRemoteQueryResultHKT, MySqlRemotePreparedQueryHKT> {
    return this.ormInstance.delete(table);
  }

  /**
   * Creates a select query with unique field aliases to prevent field name collisions in joins.
   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
   *
   * @template TSelection - The type of the selected fields
   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
   * @returns {MySqlSelectBuilder<TSelection, MySql2PreparedQueryHKT>} A select query builder with unique field aliases
   * @throws {Error} If fields parameter is empty
   * @example
   * ```typescript
   * await forgeSQL
   *   .select({user: users, order: orders})
   *   .from(orders)
   *   .innerJoin(users, eq(orders.userId, users.id));
   * ```
   */
  select<TSelection extends SelectedFields>(
    fields: TSelection,
  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT> {
    return this.ormInstance.select(fields);
  }

  /**
   * Creates a distinct select query with unique field aliases to prevent field name collisions in joins.
   * This is particularly useful when working with Atlassian Forge SQL, which collapses fields with the same name in joined tables.
   *
   * @template TSelection - The type of the selected fields
   * @param {TSelection} fields - Object containing the fields to select, with table schemas as values
   * @returns {MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT>} A distinct select query builder with unique field aliases
   * @throws {Error} If fields parameter is empty
   * @example
   * ```typescript
   * await forgeSQL
   *   .selectDistinct({user: users, order: orders})
   *   .from(orders)
   *   .innerJoin(users, eq(orders.userId, users.id));
   * ```
   */
  selectDistinct<TSelection extends SelectedFields>(
    fields: TSelection,
  ): MySqlSelectBuilder<TSelection, MySqlRemotePreparedQueryHKT> {
    return this.ormInstance.selectDistinct(fields);
  }

  /**
   * Proxies the `modify` method from `ForgeSQLORMImpl`.
   * @returns Modify operations.
   */
  modifyWithVersioning(): VerioningModificationForgeSQL {
    return this.ormInstance.modifyWithVersioning();
  }

  /**
   * Proxies the `fetch` method from `ForgeSQLORMImpl`.
   * @returns Fetch operations.
   */
  fetch(): SchemaSqlForgeSql {
    return this.ormInstance.fetch();
  }

  /**
   * Provides query analysis capabilities including EXPLAIN ANALYZE and slow query analysis.
   * @returns {SchemaAnalyzeForgeSql} Interface for analyzing query performance
   */
  analyze(): SchemaAnalyzeForgeSql {
    return this.ormInstance.analyze();
  }

  /**
   * Returns a Drizzle query builder instance.
   *
   * @returns A Drizzle query builder instance for query construction only.
   */
  getDrizzleQueryBuilder() {
    return this.ormInstance.getDrizzleQueryBuilder();
  }

  /**
   * Executes a raw SQL query with local cache support.
   * This method provides local caching for raw SQL queries within the current invocation context.
   * Results are cached locally and will be returned from cache on subsequent identical queries.
   *
   * @param query - The SQL query to execute (SQLWrapper or string)
   * @returns Promise with query results
   * @example
   * ```typescript
   * // Using SQLWrapper
   * const result = await forgeSQL.execute(sql`SELECT * FROM users WHERE id = ${userId}`);
   *
   * // Using string
   * const result = await forgeSQL.execute("SELECT * FROM users WHERE status = 'active'");
   * ```
   */
  execute<T>(
    query: SQLWrapper | string,
  ): Promise<MySqlQueryResultKind<MySqlRemoteQueryResultHKT, T>> {
    return this.ormInstance.execute(query);
  }

  /**
   * Executes a Data Definition Language (DDL) SQL query.
   * DDL operations include CREATE, ALTER, DROP, TRUNCATE, and other schema modification statements.
   *
   * This method is specifically designed for DDL operations and provides:
   * - Proper operation type context for DDL queries
   * - No caching (DDL operations should not be cached)
   * - Direct execution without query optimization
   *
   * @template T - The expected return type of the query result
   * @param query - The DDL SQL query to execute (SQLWrapper or string)
   * @returns Promise with query results
   * @throws {Error} If the DDL operation fails
   *
   * @example
   * ```typescript
   * // Create a new table
   * await forgeSQL.executeDDL(`
   *   CREATE TABLE users (
   *     id INT PRIMARY KEY AUTO_INCREMENT,
   *     name VARCHAR(255) NOT NULL,
   *     email VARCHAR(255) UNIQUE
   *   )
   * `);
   *
   * // Alter table structure
   * await forgeSQL.executeDDL(sql`
   *   ALTER TABLE users
   *   ADD COLUMN created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   * `);
   *
   * // Drop a table
   * await forgeSQL.executeDDL("DROP TABLE IF EXISTS old_users");
   * ```
   */
  executeDDL(query: SQLWrapper | string) {
    return this.ormInstance.executeDDL(query);
  }

  /**
   * Executes a series of actions within a DDL operation context.
   * This method provides a way to execute regular SQL queries that should be treated
   * as DDL operations, ensuring proper operation type context for performance monitoring.
   *
   * This method is useful for:
   * - Executing regular SQL queries in DDL context for monitoring purposes
   * - Wrapping non-DDL operations that should be treated as DDL for analysis
   * - Ensuring proper operation type context for complex workflows
   * - Maintaining DDL operation context across multiple function calls
   *
   * @template T - The return type of the actions function
   * @param actions - Function containing SQL operations to execute in DDL context
   * @returns Promise that resolves to the return value of the actions function
   *
   * @example
   * ```typescript
   * // Execute regular SQL queries in DDL context for monitoring
   * await forgeSQL.executeDDLActions(async () => {
   *   const slowQueries = await forgeSQL.execute(`
   *     SELECT * FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
   *     WHERE AVG_LATENCY > 1000000
   *   `);
   *   return slowQueries;
   * });
   *
   * // Execute complex analysis queries in DDL context
   * const result = await forgeSQL.executeDDLActions(async () => {
   *   const tableInfo = await forgeSQL.execute("SHOW TABLES");
   *   const performanceData = await forgeSQL.execute(`
   *     SELECT * FROM INFORMATION_SCHEMA.CLUSTER_STATEMENTS_SUMMARY_HISTORY
   *     WHERE SUMMARY_END_TIME > DATE_SUB(NOW(), INTERVAL 1 HOUR)
   *   `);
   *   return { tableInfo, performanceData };
   * });
   *
   * // Execute monitoring queries with error handling
   * try {
   *   await forgeSQL.executeDDLActions(async () => {
   *     const metrics = await forgeSQL.execute(`
   *       SELECT COUNT(*) as query_count
   *       FROM INFORMATION_SCHEMA.STATEMENTS_SUMMARY
   *     `);
   *     console.log(`Total queries: ${metrics[0].query_count}`);
   *   });
   * } catch (error) {
   *   console.error("Monitoring query failed:", error);
   * }
   * ```
   */
  executeDDLActions<T>(actions: () => Promise<T>): Promise<T> {
    return this.ormInstance.executeDDLActions(actions);
  }

  /**
   * Creates a Common Table Expression (CTE) builder for complex queries.
   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
   *
   * @returns WithBuilder for creating CTEs
   * @example
   * ```typescript
   * const withQuery = forgeSQL.$with('userStats').as(
   *   forgeSQL.getDrizzleQueryBuilder().select({ userId: users.id, count: sql<number>`count(*)` })
   *     .from(users)
   *     .groupBy(users.id)
   * );
   * ```
   */
  get $with() {
    return this.ormInstance.getDrizzleQueryBuilder().$with;
  }

  /**
   * Creates a query builder that uses Common Table Expressions (CTEs).
   * CTEs allow you to define temporary named result sets that exist within the scope of a single query.
   *
   * @param queries - Array of CTE queries created with $with()
   * @returns Query builder with CTE support
   * @example
   * ```typescript
   * const withQuery = forgeSQL.$with('userStats').as(
   *   forgeSQL.getDrizzleQueryBuilder().select({ userId: users.id, count: sql<number>`count(*)` })
   *     .from(users)
   *     .groupBy(users.id)
   * );
   *
   * const result = await forgeSQL.with(withQuery)
   *   .select({ userId: withQuery.userId, count: withQuery.count })
   *   .from(withQuery);
   * ```
   */
  with(...queries: WithSubquery[]) {
    return this.ormInstance.getDrizzleQueryBuilder().with(...queries);
  }
  /**
   * @inheritdoc ForgeSqlOperation#normalizationSQL
   */
  normalizationSQL(sql: string): string {
    return this.ormInstance.normalizationSQL(sql);
  }
}

export default ForgeSQLORM;