import Field from "./Field.js";
import { Logger } from "../Logger.js";
import PaginationList from "./PaginationList.js";
import CommonSearchCriteria from "./CommonSearchCriteria.js";
type PostConstructionFun = (obj: any) => void;
export { PostConstructionFun };
export interface ExecuteSQLFileOptions {
    stopOnError?: boolean;
    throwOnError?: boolean;
}
export default abstract class DBConnection {
    protected readonly logger: Logger;
    constructor();
    /**
     * Begins a database transaction.
     * @abstract
     */
    abstract beginTransaction(): Promise<void>;
    /**
     * Commits the current database transaction.
     * @abstract
     */
    abstract commit(): Promise<void>;
    /**
     * Rolls back the current database transaction.
     * @abstract
     */
    abstract rollback(): Promise<void>;
    /**
     * Closes the underlying database connection.
     * @abstract
     */
    abstract close(): Promise<void>;
    /**
     * Executes a raw SQL statement.
     * @param sql - SQL query string.
     * @protected
     * @abstract
     * @returns Promise resolving to execution result.
     */
    protected abstract executeSQL(sql: string): Promise<any>;
    /**
     * Executes an UPDATE / DELETE / INSERT query and returns the number of affected rows.
     * @param sql - SQL query string.
     * @param params - Parameter array.
     * @abstract
     * @returns Promise resolving to the number of affected rows.
     */
    abstract executeUpdate(sql: string, params: Array<any>): Promise<number>;
    /**
     * Inserts a single record.
     * @param sql - INSERT SQL query string.
     * @param params - Parameter array.
     * @abstract
     * @returns Promise resolving to insertion result.
     */
    abstract insertRecord(sql: string, params: Array<any>): Promise<any>;
    /**
     * Updates matching records.
     * @param sql - UPDATE SQL query string.
     * @param params - Parameter array.
     * @abstract
     * @returns Promise resolving to update result.
     */
    abstract updateRecord(sql: string, params: Array<any>): Promise<any>;
    /**
     * Deletes matching records.
     * @param sql - DELETE SQL query string.
     * @param params - Parameter array.
     * @abstract
     * @returns Promise resolving to the number of affected rows.
     */
    abstract deleteRecord(sql: string, params: Array<any>): Promise<number>;
    /**
     * Extracts the count value from a query result object (defaults to key 'cc').
     * @param data - Result object containing count information.
     * @param key - Column key for the count (defaults to 'cc').
     * @protected
     * @returns Parsed integer count.
     */
    protected getCount(data: any, key?: string): number;
    /**
     * Evaluates whether a value represents a boolean true.
     * Supports 1/0, '1'/'0', 'T'/'F', 't'/'f', true/false.
     * @param value - Target value.
     * @protected
     * @returns True if value represents boolean truth.
     */
    protected getBoolean(value: any): boolean;
    /**
     * Converts specified fields on an object to boolean values.
     * Supports nested field paths (e.g. 'user.isActive').
     * @param data - Data object.
     * @param fields - Array of field property paths.
     */
    convertBooleanFields(data: any, fields: Array<string>): void;
    /**
     * Executes a count query and returns the count value.
     * @param sql - Count SQL query.
     * @param params - Query parameters.
     * @param key - Column key for count (defaults to 'cc').
     */
    executeCountSQL(sql: string, params: Array<any>, key?: string): Promise<number>;
    /**
     * Executes a quick paginated query.
     * @param sql - SQL query string.
     * @param params - Parameter array.
     * @param pageNo - Page number (defaults to 1).
     * @param rowCount - Number of rows per page (defaults to 25).
     */
    quickSearch(sql: string, params?: Array<any>, pageNo?: number, rowCount?: number): Promise<any>;
    /**
     * Sanitizes parameter array by converting any undefined elements to null.
     * @param params - Parameter array or null/undefined.
     * @public
     * @returns Processed parameter array with undefined elements mapped to null, or null if empty.
     */
    sanitizeParams(params?: Array<any> | null): Array<any> | null;
    /**
     * Executes a SELECT query returning a list of mapped objects.
     * @template T - Result item type.
     * @param sql - SQL query string.
     * @param params - Parameter array.
     * @param postConstruction - Optional post-construction callback per object.
     * @param booleanFields - Field names to coerce to boolean values.
     */
    listQuery<T = any>(sql: string, params?: Array<any> | null, postConstruction?: PostConstructionFun | null, booleanFields?: Array<string>): Promise<Array<T>>;
    /**
     * Queries a single record. Returns the first record if multiple match.
     * @template T - Result record type.
     * @param sql - SQL query string.
     * @param params - Parameter array.
     * @param postConstruction - Optional post-construction callback for the mapped object.
     * @param booleanFields - Field names to coerce to boolean values.
     */
    find<T = any>(sql: string, params?: Array<any> | null, postConstruction?: PostConstructionFun | null, booleanFields?: Array<string>): Promise<T | null>;
    /**
     * Reads a SQL file, strips comments, and splits into individual SQL statements.
     * Note: This is a lightweight script splitter for standard DDL/DML migrations and does not parse
     * complex PL/SQL blocks or escaped semicolons inside string literals.
     * @param file - File path.
     * @private
     */
    private loadAndSplitSQL;
    /**
     * Executes a SQL file containing multiple statements.
     * By default stops and throws an Error on statement failure to protect database integrity.
     * @param file - SQL file path.
     * @param options - Execution control options (stopOnError, throwOnError).
     * @returns Promise resolving to true if any error occurred.
     */
    executeSQLFile(file: string, options?: ExecuteSQLFileOptions): Promise<boolean>;
    /**
     * Executes a paginated search query using the provided criteria.
     * @param criteria - CommonSearchCriteria object.
     * @returns Promise resolving to PaginationList.
     */
    executePaginationSQL(criteria: CommonSearchCriteria): Promise<PaginationList>;
    /**
     * Queries all records matching criteria, ignoring pagination.
     * @param criteria - CommonSearchCriteria object.
     * @returns Promise resolving to array of objects.
     */
    queryByCriteria(criteria: CommonSearchCriteria): Promise<Array<any>>;
    /**
     * Executes a raw query statement to fetch database data.
     * @param sql - SQL query string.
     * @param params - Optional parameter array.
     * @protected
     * @abstract
     * @returns Promise resolving to raw database result.
     */
    protected abstract fetchData(sql: string, params?: Array<any>): Promise<any>;
    /**
     * Retrieves field definitions from a query result.
     * @param result - Raw query result.
     * @abstract
     * @returns Array of Field metadata objects.
     */
    abstract getFields(result: any): Array<Field>;
    /**
     * Retrieves row dataset array from a raw query result.
     * @param result - Raw query result.
     * @protected
     * @abstract
     * @returns Array of row data.
     */
    protected abstract getRowSet(result: any): Array<any>;
    /**
     * Retrieves affected row count from an execution result.
     * @param result - Raw execution result.
     * @protected
     * @abstract
     * @returns Affected row count.
     */
    protected abstract getAffectRows(result: any): number;
    /**
     * Converts underscore_case to camelCase.
     * @param name - Field name to convert.
     * @protected
     * @returns CamelCase string.
     */
    protected toCamel(name: string): string;
    /**
     * Builds field name mapping map.
     * Default implementation maps raw field names to camelCase property names (e.g. user_name -> userName).
     * Subclasses can override for custom mapping.
     * @param fields - Array of field metadata.
     * @protected
     * @returns Field mapping Map.
     */
    protected buildFieldsMap(fields: Array<any>): Map<string, string>;
    /**
     * Sets property value on a nested object path (supports dot-separated fields like 'profile.name').
     * @param obj - Target object.
     * @param field - Field path string.
     * @param value - Value to set.
     * @protected
     */
    protected setNestObj(obj: any, field: string, value: any): void;
    /**
     * Maps raw database rows into mapped JavaScript object array.
     * @param result - Raw query result.
     * @protected
     * @returns Array of mapped objects.
     */
    protected resultToList(result: any): Array<any>;
    /**
     * Returns the LIMIT and OFFSET clause for the active database dialect.
     * @param rowCount - Maximum row count.
     * @param offset - Query offset.
     * @returns LIMIT and OFFSET clause string.
     */
    getRowSetLimitClause(rowCount: number, offset: number): string;
    /**
     * Converts the first row of a result into a mapped object, or null if empty.
     * @param result - Raw query result.
     * @protected
     * @abstract
     * @returns First row object or null.
     */
    protected abstract getFirstRow(result: any): any;
}