rawsql-ts/dist/src/transformers/SqlParamInjector.d.ts

[beta]High-performance SQL parser and AST analyzer written in TypeScript. Provides fast parsing and advanced transformation capabilities.

import { SelectQuery, SimpleSelectQuery } from "../models/SelectQuery";
import { SqlParameterValue } from "../models/ValueComponent";
/**
 * Options for SqlParamInjector
 */
export interface SqlParamInjectorOptions {
    /** Whether to ignore case and underscore differences when matching column names */
    ignoreCaseAndUnderscore?: boolean;
    /** Whether to allow injection when all parameters are undefined (defaults to false for safety) */
    allowAllUndefined?: boolean;
    /** Whether to ignore non-existent columns instead of throwing errors (defaults to false for safety) */
    ignoreNonExistentColumns?: boolean;
}
export type StateParameterValue = SqlParameterValue | SqlParameterValue[] | Condition | OrCondition | AndCondition | ExplicitColumnMapping;
/**
 * SqlParamInjector injects state parameters into a SelectQuery model,
 * creating WHERE conditions and setting parameter values.
 */
export declare class SqlParamInjector {
    private tableColumnResolver?;
    private options;
    constructor(optionsOrResolver?: SqlParamInjectorOptions | ((tableName: string) => string[]), options?: SqlParamInjectorOptions);
    /**
     * Injects parameters as WHERE conditions into the given query model.
     * @param query The SelectQuery to modify
     * @param state A record of parameter names and values
     * @returns The modified SelectQuery
     * @throws Error when all parameters are undefined and allowAllUndefined is not set to true
     */
    inject(query: SimpleSelectQuery | string, state: Record<string, number | string | boolean | Date | null | undefined | Condition>): SelectQuery;
    /**
     * Type guard for OR conditions
     */
    private isOrCondition;
    /**
     * Type guard for AND conditions
     */
    private isAndCondition;
    /**
     * Type guard for explicit column mapping without OR
     */
    private isExplicitColumnMapping;
    /**
     * Type guard for objects that need operator validation
     */
    private isValidatableObject;
    /**
     * Parses a qualified column name (table.column) into its components
     * @param qualifiedName The qualified name (e.g., 'users.name' or 'name')
     * @returns Object with table and column parts, or null if invalid
     */
    private parseQualifiedColumnName;
    /**
     * Checks if a column name is qualified (contains a dot)
     */
    private isQualifiedColumnName;
    /**
     * Sanitizes parameter names by replacing dots with underscores
     * This ensures qualified names like 'users.name' become 'users_name' as parameter names
     */
    private sanitizeParameterName;
    /**
     * Type guard for column mapping presence
     */
    private hasColumnMapping;
    /**
     * Type guard for simple values (non-object conditions)
     */
    private isSimpleValue;
    /**
     * Processes a single state parameter
     */
    private processStateParameter;
    /**
     * Processes unqualified parameters, respecting qualified parameter overrides
     */
    private processUnqualifiedParameter;
    /**
     * Processes regular column conditions (non-logical, non-explicit)
     */
    private processRegularColumnCondition;
    /**
     * Finds target query for logical conditions (AND/OR)
     */
    private findTargetQueryForLogicalCondition;
    /**
     * Collects all available columns from a query including CTE columns
     */
    private getAllAvailableColumns;
    /**
     * Collects column names and references from CTE definitions
     */
    private collectCTEColumns;
    /**
     * Recursively collects columns from any SelectQuery type
     */
    private collectColumnsFromSelectQuery;
    /**
     * Builds a mapping between table aliases and real table names for enhanced qualified name resolution
     */
    private buildTableMapping;
    /**
     * Helper method to process a single SourceExpression for table mapping
     */
    private processSourceForMapping;
}
type BaseCondition = {
    '='?: number | string | boolean | Date;
    min?: number | string | Date;
    max?: number | string | Date;
    like?: string;
    ilike?: string;
    in?: (number | string | Date)[];
    any?: (number | string | Date)[];
    '<'?: number | string | Date;
    '>'?: number | string | Date;
    '!='?: number | string | boolean | Date;
    '<>'?: number | string | boolean | Date;
    '<='?: number | string | Date;
    '>='?: number | string | Date;
};
type SingleCondition = BaseCondition & {
    column?: string;
};
type LogicalCondition = {
    column?: string;
    and?: SingleCondition[];
    or?: SingleCondition[];
};
type Condition = BaseCondition | SingleCondition | LogicalCondition;
type OrCondition = {
    or: SingleCondition[];
};
type AndCondition = {
    and: SingleCondition[];
};
type ExplicitColumnMapping = {
    column: string;
} & BaseCondition;
export {};