@andreasnicolaou/query-builder/dist/types/index.d.ts

A flexible and type-safe query builder for constructing complex conditional expressions with support for nested groups, various operators, and function calls.

export type WordOperator = 'starts with' | 'ends with' | 'contains' | 'matches';
export type SetOperator = 'not in' | 'in';
export type LogicalOperator = 'and' | 'or';
export type ComparisonOperator = '===' | '!==' | '==' | '=' | '!=' | '>=' | '<=' | '<' | '>';
export type Operators = WordOperator | SetOperator | LogicalOperator | ComparisonOperator;
export type PrimitiveValue = string | number | boolean | FunctionCall | null | object;
export type RawValueArray = (PrimitiveValue | FunctionCall)[] | RawValueArray[];
export type RawValue = PrimitiveValue | RawValueArray;
export interface FunctionCall {
    $fn: string;
    args?: (PrimitiveValue | RawValueArray)[];
}
export type QueryBuilderSerialized = (LogicalOperator | Condition | {
    group: QueryBuilderSerialized;
})[];
export interface Condition {
    field: string;
    operator: Operators;
    value?: RawValue;
    negated?: boolean;
}
export interface SkipWhenOptions {
    null?: boolean;
    undefined?: boolean;
    emptyString?: boolean;
    emptyArray?: boolean;
    nan?: boolean;
    emptyObject?: boolean;
}
/**
 * Query builder for constructing complex conditional expressions.
 * Supports nested groups, various operators, and function calls.
 * @author Andreas Nicolaou <anicolaou66@gmail.com>
 */
export declare class QueryBuilder {
    private readonly conditions;
    private skipOptions;
    /**
     * Creates a function call object that can be used as a value in conditions.
     * @param name The name of the function to call
     * @param args Arguments to pass to the function
     * @returns A FunctionCall object representing the function invocation
     * @memberof QueryBuilder
     */
    static fn(name: string, ...args: (PrimitiveValue | RawValueArray)[]): FunctionCall;
    /**
     * Creates a nested group of conditions.
     * @param callback A function that receives a new QueryBuilder for the nested conditions
     * @param logicalOperator The logical operator to combine with previous conditions (default: 'and')
     * @returns The query builder instance for chaining
     * @memberof QueryBuilder
     */
    group(callback: (qb: QueryBuilder) => void, logicalOperator?: LogicalOperator): this;
    /**
     * Configures which values should be skipped when adding conditions.
     * @param options Configuration for value skipping behavior
     * @returns The query builder instance for chaining
     * @memberof QueryBuilder
     */
    skipWhen(options?: SkipWhenOptions): this;
    /**
     * Serializes the query builder's conditions to a JSON-compatible structure.
     * @returns The serialized conditions array
     * @memberof QueryBuilder
     */
    toJSON(): QueryBuilderSerialized;
    /**
     * Converts the query builder's conditions to a human-readable string representation.
     * @returns A string representation of the query conditions
     * @memberof QueryBuilder
     */
    toString(): string;
    /**
     * Adds a condition to the query builder.
     * @param field The field/column to compare
     * @param operator The comparison operator to use
     * @param value The value to compare against (optional for some operators)
     * @param logicalOperator The logical operator to combine with previous conditions (default: 'and')
     * @returns The query builder instance for chaining
     * @memberof QueryBuilder
     */
    where(field: string, operator: Operators, value?: RawValue, logicalOperator?: LogicalOperator): this;
    /**
     * Formats conditions into a string.
     * @param conditions The conditions array to format
     * @param isSubquery Whether this is formatting a nested subquery
     * @returns Formatted string representation of the conditions
     * @memberof QueryBuilder
     */
    private formatConditions;
    /**
     * Checks if a value is a condition array (QueryBuilderSerialized).
     * @param value The value to check
     * @returns True if the value is a condition array, false otherwise
     * @memberof QueryBuilder
     */
    private isConditionArray;
    /**
     * Checks if a value should be skipped based on current skip options
     * @param value The value to check
     * @returns True if the value should be skipped
     * @memberof QueryBuilder
     */
    private shouldSkipValue;
    /**
     * Converts a value to its string representation for query formatting.
     * @param value The value to convert
     * @returns String representation of the value
     * @memberof QueryBuilder
     */
    private valueToString;
}