/**
 * Elide MySQL Module
 *
 * Provides MySQL database connectivity from JavaScript.
 *
 * @module elide:mysql
 * @example
 * ```javascript
 * import { Database } from "elide:mysql"
 *
 * const db = await Database.connect({
 *   host: "localhost",
 *   port: 3306,
 *   database: "myapp",
 *   user: "root",
 *   password: "secret"
 * })
 *
 * const users = await db.query("SELECT * FROM users").all()
 * await db.close()
 * ```
 */
declare module "elide:mysql" {
  /**
   * MySQL connection configuration.
   */
  export interface MysqlConfig {
    /** Database server hostname (default: "localhost"). */
    host?: string;
    /** Database server port (default: 3306). */
    port?: number;
    /** Database name. */
    database: string;
    /** Username for authentication. */
    user: string;
    /** Password for authentication. */
    password: string;
    /** Connection pool configuration. */
    pool?: PoolConfig;
    /** SSL/TLS configuration. */
    ssl?: SslConfig;
    /** Additional connection properties. */
    properties?: Record<string, string>;
  }

  /**
   * Connection pool configuration.
   */
  export interface PoolConfig {
    /** Minimum number of idle connections (default: 2). */
    minSize?: number;
    /** Maximum number of connections (default: 10). */
    maxSize?: number;
    /** Connection timeout in milliseconds (default: 5000). */
    connectionTimeout?: number;
    /** Idle timeout in milliseconds (default: 30000). */
    idleTimeout?: number;
    /** Maximum connection lifetime in milliseconds (default: 1800000). */
    maxLifetime?: number;
    /** Leak detection threshold in milliseconds (0 = disabled). */
    leakDetectionThreshold?: number;
  }

  /**
   * SSL/TLS configuration.
   */
  export interface SslConfig {
    /** Enable SSL/TLS (default: false). */
    enabled?: boolean;
    /** Reject untrusted certificates (default: true). */
    rejectUnauthorized?: boolean;
    /** Path to CA certificate file. */
    ca?: string;
    /** Path to client certificate file. */
    cert?: string;
    /** Path to client key file. */
    key?: string;
  }

  /**
   * Pool statistics.
   */
  export interface PoolStatistics {
    /** Number of active (in-use) connections. */
    activeConnections: number;
    /** Number of idle connections. */
    idleConnections: number;
    /** Total number of connections. */
    totalConnections: number;
    /** Number of threads waiting for a connection. */
    pendingRequests: number;
    /** Maximum pool size. */
    maxConnections: number;
    /** Minimum pool size. */
    minConnections: number;
  }

  /**
   * Query result row.
   */
  export interface Row {
    /** Get column value by name. */
    [column: string]: any;
  }

  /**
   * Query result.
   */
  export interface QueryResult {
    /** Get all rows as an array. */
    all(): Promise<Row[]>;
    /** Get the first row or null. */
    get(): Promise<Row | null>;
    /** Get all rows as arrays of values. */
    values(): Promise<any[][]>;
  }

  /**
   * Execution result.
   */
  export interface ExecResult {
    /** Number of affected rows. */
    affectedRows: number;
    /** Last inserted ID (for INSERT statements). */
    insertId: number | null;
    /** All inserted IDs (for batch inserts). */
    insertIds: number[];
  }

  /**
   * Prepared statement.
   */
  export interface Statement {
    /** Execute as a query (SELECT). */
    query(...args: any[]): Promise<QueryResult>;
    /** Execute as a statement (INSERT/UPDATE/DELETE). */
    exec(...args: any[]): Promise<ExecResult>;
    /** Execute with multiple argument sets. */
    executeBatch(argsList: any[][]): Promise<ExecResult[]>;
    /** Close the statement. */
    close(): void;
  }

  /**
   * Transaction isolation levels.
   */
  export type IsolationLevel =
    | "READ_UNCOMMITTED"
    | "READ_COMMITTED"
    | "REPEATABLE_READ"
    | "SERIALIZABLE";

  /**
   * Transaction.
   */
  export interface Transaction {
    /** Current isolation level. */
    isolation: IsolationLevel;
    /** Whether the transaction is still active. */
    active: boolean;
    /** Execute a query within the transaction. */
    query(sql: string, ...args: any[]): Promise<QueryResult>;
    /** Execute a statement within the transaction. */
    exec(sql: string, ...args: any[]): Promise<ExecResult>;
    /** Commit the transaction. */
    commit(): Promise<void>;
    /** Rollback the transaction. */
    rollback(): Promise<void>;
    /** Create a savepoint. */
    savepoint(name: string): Promise<void>;
    /** Rollback to a savepoint. */
    rollbackTo(name: string): Promise<void>;
  }

  /**
   * MySQL Database connection.
   */
  export interface MysqlDatabase {
    /** Whether the connection pool is active. */
    connected: boolean;
    /** Connection pool statistics. */
    poolStats: PoolStatistics;
    /** Execute a SELECT query. */
    query(sql: string, ...args: any[]): Promise<QueryResult>;
    /** Execute an INSERT/UPDATE/DELETE statement. */
    exec(sql: string, ...args: any[]): Promise<ExecResult>;
    /** Create a prepared statement. */
    prepare(sql: string): Promise<Statement>;
    /** Execute a transaction. */
    transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
    /** Execute multiple statements in a batch. */
    batch(statements: [string, any[]][]): Promise<ExecResult[]>;
    /** Close the connection pool. */
    close(): Promise<void>;
  }

  /**
   * Database class for creating connections.
   */
  export const Database: {
    /**
     * Connect to a MySQL database.
     * @param config Connection configuration or URL string.
     * @returns Connected database instance.
     */
    connect(config: MysqlConfig | string): Promise<MysqlDatabase>;
  };
}