@andreasnicolaou/query-builder
Version:
A flexible and type-safe query builder for constructing complex conditional expressions with support for nested groups, various operators, and function calls.
213 lines (211 loc) • 8.31 kB
TypeScript
type WordOperator = 'starts with' | 'ends with' | 'contains' | 'matches' | 'like' | 'ilike';
type SetOperator = 'not in' | 'in';
type LogicalOperator = 'and' | 'or';
type ComparisonOperator = '===' | '!==' | '==' | '=' | '!=' | '>=' | '<=' | '<' | '>';
type RangeOperator = 'between' | 'not between';
type NullOperator = 'is null' | 'is not null' | 'is empty' | 'is not empty';
type ArrayStyle = 'parens' | 'brackets';
type Operators = WordOperator | SetOperator | LogicalOperator | ComparisonOperator | RangeOperator | NullOperator;
type PrimitiveValue = string | number | boolean | FunctionCall | null | object;
type RawValueArray = (PrimitiveValue | FunctionCall)[] | RawValueArray[];
type RawValue = PrimitiveValue | RawValueArray;
interface FunctionCall {
$fn: string;
args?: (PrimitiveValue | RawValueArray)[];
}
type QueryBuilderSerialized = (LogicalOperator | Condition | {
group: QueryBuilderSerialized;
})[];
interface Condition {
field: string;
operator: Operators;
value?: RawValue;
}
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>
*/
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;
/**
* Validates if an operator is compatible with a value type
* @param operator The operator to validate
* @param value The value to validate against
* @returns Validation result with error message if invalid
* @memberof QueryBuilder
*/
static validateOperator(operator: Operators, value?: RawValue): {
valid: boolean;
error?: string;
};
/**
* Adds a BETWEEN condition.
*/
between(field: string, range: [RawValue, RawValue], logicalOperator?: LogicalOperator): this;
/**
* Adds an equals (=) condition.
*/
equals(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a greater than (>) condition.
*/
greaterThan(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a greater than or equal (>=) condition.
*/
greaterThanOrEqual(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* 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;
/**
* Adds an ILIKE (case-insensitive like) condition.
*/
ilike(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds an IN condition.
*/
in(field: string, values: RawValueArray, logicalOperator?: LogicalOperator): this;
/**
* Adds an IS EMPTY condition.
*/
isEmpty(field: string, logicalOperator?: LogicalOperator): this;
/**
* Adds an IS NOT EMPTY condition.
*/
isNotEmpty(field: string, logicalOperator?: LogicalOperator): this;
/**
* Adds an IS NOT NULL condition.
*/
isNotNull(field: string, logicalOperator?: LogicalOperator): this;
/**
* Adds an IS NULL condition.
*/
isNull(field: string, logicalOperator?: LogicalOperator): this;
/**
* Adds a less than (<) condition.
*/
lessThan(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a less than or equal (<=) condition.
*/
lessThanOrEqual(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a LIKE condition.
*/
like(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a loose equals (==) condition.
*/
looseEquals(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a NOT BETWEEN condition.
*/
notBetween(field: string, range: [RawValue, RawValue], logicalOperator?: LogicalOperator): this;
/**
* Adds a not equals (!=) condition.
*/
notEquals(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a NOT IN condition.
*/
notIn(field: string, values: RawValueArray, 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;
/**
* Adds a strict equals (===) condition.
*/
strictEquals(field: string, value: RawValue, logicalOperator?: LogicalOperator): this;
/**
* Adds a strict not equals (!==) condition.
*/
strictNotEquals(field: string, value: RawValue, logicalOperator?: LogicalOperator): 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
*/
/**
* Converts the query builder's conditions to a human-readable string representation.
* @param options Optional formatting options (arrayStyle: 'sql' | 'php')
* @returns A string representation of the query conditions
* @memberof QueryBuilder
*/
toString(options?: {
arrayStyle?: ArrayStyle;
}): 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;
}
export { QueryBuilder };
export type { ArrayStyle, ComparisonOperator, Condition, FunctionCall, LogicalOperator, NullOperator, Operators, PrimitiveValue, QueryBuilderSerialized, RangeOperator, RawValue, RawValueArray, SetOperator, SkipWhenOptions, WordOperator };