ts-prorm-orm 1.1.0

package/dist/query-builders/where-builder.js

@@ -0,0 +1,1532 @@
+"use strict";
+/**
+ * WHERE clause builder for the ORM
+ * Handles complex WHERE conditions with all supported operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WhereBuilder = void 0;
+exports.createWhereBuilder = createWhereBuilder;
+exports.buildWhereClause = buildWhereClause;
+// Import Op from operators for Symbol comparison
+const operators_1 = require("../operators");
+/**
+ * Check if a value is a column reference ({ $col: 'column' })
+ */
+function isColumnReference(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '$col' in value &&
+        typeof value.$col === 'string');
+}
+/**
+ * Check if a key is Op.not Symbol
+ */
+function isOpNot(key) {
+    return key === operators_1.Op.not;
+}
+/**
+ * Check if a value is a literal SQL ({ $literal: 'SQL' })
+ */
+function isLiteralValue(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '$literal' in value &&
+        typeof value.$literal === 'string');
+}
+/**
+ * Convert a value to SQL string if it's a special type ($col, $literal)
+ * Returns the SQL string representation or null if it's a regular value
+ */
+function valueToSql(value, escapeId) {
+    if (isColumnReference(value)) {
+        return escapeId(value.$col);
+    }
+    if (isLiteralValue(value)) {
+        return value.$literal;
+    }
+    return null;
+}
+/**
+ * WhereBuilder class for building WHERE clauses
+ */
+class WhereBuilder {
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Build a WHERE clause from WhereOptions
+     */
+    build(where) {
+        const values = [];
+        if (!where || Object.keys(where).length === 0) {
+            return { sql: '', values };
+        }
+        const result = this.buildCondition(where, values);
+        return { sql: result, values };
+    }
+    /**
+     * Build a condition (can be nested)
+     */
+    buildCondition(condition, values) {
+        if (!condition) {
+            return '';
+        }
+        // Handle primitive values (direct equality)
+        if (typeof condition !== 'object') {
+            values.push(condition);
+            return '?';
+        }
+        // Handle a bare raw-SQL literal used as a whole condition, e.g. a
+        // standalone full-text-search predicate: `where: literal('MATCH(...) AGAINST(...)')`,
+        // `Op.and: [literal('...'), { ... }]`. Without this, `{ $literal }` falls
+        // through to buildFieldConditions() and is silently misread as a field
+        // named "$literal" needing an operator, dropping the condition entirely.
+        if (isLiteralValue(condition)) {
+            return condition.$literal;
+        }
+        const cond = condition;
+        // Handle [Op.not]: { condition } - top-level negation
+        // Check if any key in the object is the Op.not Symbol
+        if (this.hasOpNotKey(cond)) {
+            return this.buildOpNotCondition(cond, values);
+        }
+        // Handle Symbol-based logical operators (Op.and, Op.or, Op.not)
+        if (this.hasLogicalOperatorSymbols(cond)) {
+            return this.buildLogicalCondition(cond, values);
+        }
+        // Handle string-based logical operators: $and, $or, $not
+        if (this.isLogicalOperator(cond)) {
+            return this.buildLogicalCondition(cond, values);
+        }
+        // Handle $where - explicit where clause with column reference
+        if ('$where' in cond) {
+            return this.buildWhereCondition(cond.$where, values);
+        }
+        // Handle field conditions
+        return this.buildFieldConditions(cond, values);
+    }
+    /**
+     * Check if the object has Op.not as a key (can be string or Symbol)
+     */
+    hasOpNotKey(obj) {
+        // Check string keys (for backward compatibility with 'not' string)
+        if (isOpNot('not')) {
+            if ('not' in obj) {
+                return true;
+            }
+        }
+        // Check Symbol keys (for Op.not Symbol)
+        const symbols = Object.getOwnPropertySymbols(obj);
+        return symbols.some((sym) => sym === operators_1.Op.not);
+    }
+    /**
+     * Build a condition with Op.not - { [Op.not]: { ... } } or { not: { ... } }
+     */
+    buildOpNotCondition(cond, values) {
+        // First check for Symbol key (Op.not)
+        const symbols = Object.getOwnPropertySymbols(cond);
+        for (const sym of symbols) {
+            if (sym === operators_1.Op.not) {
+                const notCondition = cond[sym];
+                const result = this.buildCondition(notCondition, values);
+                if (result) {
+                    return `NOT (${result})`;
+                }
+            }
+        }
+        // Also check for string 'not' key for backward compatibility
+        if ('not' in cond) {
+            const notCondition = cond['not'];
+            const result = this.buildCondition(notCondition, values);
+            if (result) {
+                return `NOT (${result})`;
+            }
+        }
+        return '';
+    }
+    /**
+     * Build a $where condition with column reference
+     * { $col: 'user.id', $eq: 1 } => "user"."id" = ?
+     */
+    buildWhereCondition(whereClause, values) {
+        const col = whereClause.$col;
+        if (!col) {
+            return '';
+        }
+        // Get the operator and value (excluding $col)
+        const operatorEntries = Object.entries(whereClause).filter(([k]) => k !== '$col');
+        if (operatorEntries.length === 0) {
+            // Just column reference, no operator - treat as equality with no value
+            return this.escapeId(col);
+        }
+        // Build the condition for each operator
+        const fieldConditions = [];
+        for (const [opKey, opValue] of operatorEntries) {
+            const result = this.buildSingleWhereOperator(col, opKey, opValue, values);
+            if (result) {
+                fieldConditions.push(result);
+            }
+        }
+        return fieldConditions.join(' AND ');
+    }
+    /**
+     * Build a single where operator condition
+     * Handles special value types like $col (column references) and $literal (raw SQL)
+     */
+    buildSingleWhereOperator(field, operator, value, values) {
+        // Check if value is a special type ($col or $literal)
+        const sqlValue = valueToSql(value, this.escapeId.bind(this));
+        switch (operator) {
+            case '$eq':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} = ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} = ?`;
+            case '$ne':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} != ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} != ?`;
+            case '$gt':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} > ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} > ?`;
+            case '$gte':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} >= ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} >= ?`;
+            case '$lt':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} < ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} < ?`;
+            case '$lte':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} <= ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} <= ?`;
+            case '$like':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} LIKE ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} LIKE ?`;
+            case '$notLike':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} NOT LIKE ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} NOT LIKE ?`;
+            case '$iLike':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} ILIKE ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} ILIKE ?`;
+            case '$notILike':
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} NOT ILIKE ${sqlValue}`;
+                }
+                values.push(value);
+                return `${this.escapeId(field)} NOT ILIKE ?`;
+            case '$in':
+                if (Array.isArray(value)) {
+                    // Handle special values in array
+                    const processedValues = [];
+                    const regularValues = [];
+                    value.forEach((v) => {
+                        const sv = valueToSql(v, this.escapeId.bind(this));
+                        if (sv !== null) {
+                            processedValues.push(sv);
+                        }
+                        else {
+                            regularValues.push(v);
+                        }
+                    });
+                    const placeholders = [...processedValues, ...regularValues.map(() => '?')].join(', ');
+                    values.push(...regularValues);
+                    return `${this.escapeId(field)} IN (${placeholders})`;
+                }
+                return '';
+            case '$notIn':
+                if (Array.isArray(value)) {
+                    // Handle special values in array
+                    const processedValues = [];
+                    const regularValues = [];
+                    value.forEach((v) => {
+                        const sv = valueToSql(v, this.escapeId.bind(this));
+                        if (sv !== null) {
+                            processedValues.push(sv);
+                        }
+                        else {
+                            regularValues.push(v);
+                        }
+                    });
+                    const placeholders = [...processedValues, ...regularValues.map(() => '?')].join(', ');
+                    values.push(...regularValues);
+                    return `${this.escapeId(field)} NOT IN (${placeholders})`;
+                }
+                return '';
+            case '$between':
+                if (Array.isArray(value) && value.length === 2) {
+                    const startSql = valueToSql(value[0], this.escapeId.bind(this));
+                    const endSql = valueToSql(value[1], this.escapeId.bind(this));
+                    if (startSql !== null && endSql !== null) {
+                        return `${this.escapeId(field)} BETWEEN ${startSql} AND ${endSql}`;
+                    }
+                    if (startSql !== null) {
+                        values.push(value[1]);
+                        return `${this.escapeId(field)} BETWEEN ${startSql} AND ?`;
+                    }
+                    if (endSql !== null) {
+                        values.push(value[0]);
+                        return `${this.escapeId(field)} BETWEEN ? AND ${endSql}`;
+                    }
+                    values.push(value[0], value[1]);
+                    return `${this.escapeId(field)} BETWEEN ? AND ?`;
+                }
+                return '';
+            case '$notBetween':
+                if (Array.isArray(value) && value.length === 2) {
+                    const startSql = valueToSql(value[0], this.escapeId.bind(this));
+                    const endSql = valueToSql(value[1], this.escapeId.bind(this));
+                    if (startSql !== null && endSql !== null) {
+                        return `${this.escapeId(field)} NOT BETWEEN ${startSql} AND ${endSql}`;
+                    }
+                    if (startSql !== null) {
+                        values.push(value[1]);
+                        return `${this.escapeId(field)} NOT BETWEEN ${startSql} AND ?`;
+                    }
+                    if (endSql !== null) {
+                        values.push(value[0]);
+                        return `${this.escapeId(field)} NOT BETWEEN ? AND ${endSql}`;
+                    }
+                    values.push(value[0], value[1]);
+                    return `${this.escapeId(field)} NOT BETWEEN ? AND ?`;
+                }
+                return '';
+            case '$isNull':
+                return `${this.escapeId(field)} IS NULL`;
+            case '$isNotNull':
+                return `${this.escapeId(field)} IS NOT NULL`;
+            case '$col':
+                // Column reference: compare to another column
+                return `${this.escapeId(field)} = ${this.escapeId(value)}`;
+            default:
+                // Unknown operator
+                return '';
+        }
+    }
+    /**
+     * Check if the object has Op.and, Op.or, or Op.not as keys (Symbol-based logical operators)
+     */
+    hasLogicalOperatorSymbols(obj) {
+        const symbols = Object.getOwnPropertySymbols(obj);
+        return symbols.some((sym) => sym === operators_1.Op.and || sym === operators_1.Op.or || sym === operators_1.Op.not);
+    }
+    /**
+     * Check if the object is a logical operator container
+     */
+    isLogicalOperator(obj) {
+        // Check for string keys ($and, $or, $not)
+        const hasStringKeys = '$and' in obj || '$or' in obj || '$not' in obj;
+        if (hasStringKeys)
+            return true;
+        // Check for Symbol keys (Op.and, Op.or, Op.not)
+        return this.hasLogicalOperatorSymbols(obj);
+    }
+    /**
+     * Build logical conditions ($and, $or, $not) or Symbol-based (Op.and, Op.or, Op.not)
+     */
+    buildLogicalCondition(cond, values) {
+        const conditions = [];
+        // Handle $and (string key)
+        if (cond.$and) {
+            const andConditions = cond.$and
+                .map((c) => {
+                const result = this.buildCondition(c, values);
+                return result ? `(${result})` : '';
+            })
+                .filter((s) => s);
+            if (andConditions.length > 0) {
+                conditions.push(andConditions.join(' AND '));
+            }
+        }
+        // Handle Op.and (Symbol key)
+        const symbolKeys = Object.getOwnPropertySymbols(cond);
+        for (const sym of symbolKeys) {
+            if (sym === operators_1.Op.and) {
+                const andValue = cond[sym];
+                const andConditions = andValue
+                    .map((c) => {
+                    const result = this.buildCondition(c, values);
+                    return result ? `(${result})` : '';
+                })
+                    .filter((s) => s);
+                if (andConditions.length > 0) {
+                    conditions.push(andConditions.join(' AND '));
+                }
+            }
+        }
+        // Handle $or (string key)
+        if (cond.$or) {
+            const orConditions = cond.$or
+                .map((c) => {
+                const result = this.buildCondition(c, values);
+                return result ? `(${result})` : '';
+            })
+                .filter((s) => s);
+            if (orConditions.length > 0) {
+                conditions.push(orConditions.join(' OR '));
+            }
+        }
+        // Handle Op.or (Symbol key)
+        for (const sym of symbolKeys) {
+            if (sym === operators_1.Op.or) {
+                const orValue = cond[sym];
+                const orConditions = orValue
+                    .map((c) => {
+                    const result = this.buildCondition(c, values);
+                    return result ? `(${result})` : '';
+                })
+                    .filter((s) => s);
+                if (orConditions.length > 0) {
+                    conditions.push(orConditions.join(' OR '));
+                }
+            }
+        }
+        // Handle $not (string key)
+        if (cond.$not) {
+            const result = this.buildCondition(cond.$not, values);
+            if (result) {
+                conditions.push(`NOT (${result})`);
+            }
+        }
+        // Handle Op.not (Symbol key)
+        for (const sym of symbolKeys) {
+            if (sym === operators_1.Op.not) {
+                const notValue = cond[sym];
+                const result = this.buildCondition(notValue, values);
+                if (result) {
+                    conditions.push(`NOT (${result})`);
+                }
+            }
+        }
+        return conditions.join(' AND ');
+    }
+    /**
+     * Check if a key is a JSON path Symbol created by Op.json
+     * JSON path symbols have descriptions like "json:$.path" or "json:path"
+     */
+    isJsonPathSymbol(key) {
+        if (typeof key === 'symbol') {
+            const desc = key.description || '';
+            return desc.startsWith('json:');
+        }
+        return false;
+    }
+    /**
+     * Extract the JSON path from a Symbol created by Op.json
+     * The path is stored in the Symbol's description after "json:"
+     */
+    extractJsonPath(key) {
+        const desc = key.description || '';
+        // Remove the "json:" prefix to get the path
+        let path = desc.substring(5);
+        // Ensure path starts with $.
+        if (!path.startsWith('$.')) {
+            path = `$.${path}`;
+        }
+        return path;
+    }
+    /**
+     * Build field-level conditions
+     */
+    buildFieldConditions(cond, values) {
+        const fieldConditions = [];
+        // First, handle string keys from Object.entries
+        for (const [key, value] of Object.entries(cond)) {
+            // Skip logical operators
+            if (key.startsWith('$')) {
+                continue;
+            }
+            if (value === null) {
+                fieldConditions.push(`${this.escapeId(key)} IS NULL`);
+            }
+            else if (typeof value === 'object') {
+                const result = this.buildOperatorCondition(key, value, values);
+                if (result) {
+                    fieldConditions.push(result);
+                }
+            }
+            else {
+                values.push(value);
+                fieldConditions.push(`${this.escapeId(key)} = ?`);
+            }
+        }
+        // Also handle Symbol keys (e.g., Op.json('path') returns a Symbol used as computed property key)
+        const symbolKeys = Object.getOwnPropertySymbols(cond);
+        for (const sym of symbolKeys) {
+            const value = cond[sym];
+            // Check if it's a JSON path Symbol
+            if (this.isJsonPathSymbol(sym)) {
+                const path = this.extractJsonPath(sym);
+                // Parse the path - format is "field.path" or "$.field.path"
+                // We need to extract the column name and JSON path
+                let field;
+                let jsonPath;
+                if (path.startsWith('$.')) {
+                    // Format: $.field.subfield
+                    const withoutDollar = path.substring(2);
+                    const dotIndex = withoutDollar.indexOf('.');
+                    if (dotIndex === -1) {
+                        field = withoutDollar;
+                        jsonPath = '';
+                    }
+                    else {
+                        field = withoutDollar.substring(0, dotIndex);
+                        jsonPath = withoutDollar.substring(dotIndex + 1);
+                    }
+                }
+                else {
+                    // Format: field.subfield
+                    const dotIndex = path.indexOf('.');
+                    if (dotIndex === -1) {
+                        field = path;
+                        jsonPath = '';
+                    }
+                    else {
+                        field = path.substring(0, dotIndex);
+                        jsonPath = path.substring(dotIndex + 1);
+                    }
+                }
+                // Build the JSON extraction SQL
+                const jsonExtract = jsonPath
+                    ? `json_extract(${this.escapeId(field)}, '$.${jsonPath}')`
+                    : this.escapeId(field);
+                if (value === null) {
+                    fieldConditions.push(`${jsonExtract} IS NULL`);
+                }
+                else if (typeof value === 'object') {
+                    // If value is an object with operators (e.g., { $gt: 5 })
+                    // We need to pass the JSON extraction as the field name
+                    const result = this.buildOperatorCondition(jsonExtract, value, values);
+                    if (result) {
+                        fieldConditions.push(result);
+                    }
+                }
+                else {
+                    // Simple comparison
+                    values.push(value);
+                    fieldConditions.push(`${jsonExtract} = ?`);
+                }
+            }
+        }
+        return fieldConditions.join(' AND ');
+    }
+    /**
+     * Build condition for a specific operator
+     */
+    buildOperatorCondition(field, operator, values) {
+        // Helper to handle special values ($col, $literal)
+        const handleValue = (value) => {
+            return valueToSql(value, this.escapeId.bind(this));
+        };
+        // Handle Op.not Symbol as key: { [Op.not]: 'active' } => field != 'active'
+        const symbolKeys = Object.getOwnPropertySymbols(operator);
+        for (const sym of symbolKeys) {
+            if (sym === operators_1.Op.not) {
+                const notValue = operator[sym];
+                const sqlValue = handleValue(notValue);
+                if (sqlValue !== null) {
+                    return `${this.escapeId(field)} != ${sqlValue}`;
+                }
+                values.push(notValue);
+                return `${this.escapeId(field)} != ?`;
+            }
+        }
+        // Also handle 'not' as string key for backward compatibility
+        if ('not' in operator && !operator.$not) {
+            const notValue = operator.not;
+            const sqlValue = handleValue(notValue);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} != ${sqlValue}`;
+            }
+            values.push(notValue);
+            return `${this.escapeId(field)} != ?`;
+        }
+        // $eq - equality
+        if (operator.$eq !== undefined) {
+            const sqlValue = handleValue(operator.$eq);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} = ${sqlValue}`;
+            }
+            values.push(operator.$eq);
+            return `${this.escapeId(field)} = ?`;
+        }
+        // $ne - not equal
+        if (operator.$ne !== undefined) {
+            const sqlValue = handleValue(operator.$ne);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} != ${sqlValue}`;
+            }
+            values.push(operator.$ne);
+            return `${this.escapeId(field)} != ?`;
+        }
+        // $gt - greater than
+        if (operator.$gt !== undefined) {
+            const sqlValue = handleValue(operator.$gt);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} > ${sqlValue}`;
+            }
+            values.push(operator.$gt);
+            return `${this.escapeId(field)} > ?`;
+        }
+        // $gte - greater than or equal
+        if (operator.$gte !== undefined) {
+            const sqlValue = handleValue(operator.$gte);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} >= ${sqlValue}`;
+            }
+            values.push(operator.$gte);
+            return `${this.escapeId(field)} >= ?`;
+        }
+        // $lt - less than
+        if (operator.$lt !== undefined) {
+            const sqlValue = handleValue(operator.$lt);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} < ${sqlValue}`;
+            }
+            values.push(operator.$lt);
+            return `${this.escapeId(field)} < ?`;
+        }
+        // $lte - less than or equal
+        if (operator.$lte !== undefined) {
+            const sqlValue = handleValue(operator.$lte);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} <= ${sqlValue}`;
+            }
+            values.push(operator.$lte);
+            return `${this.escapeId(field)} <= ?`;
+        }
+        // $like - LIKE operator
+        if (operator.$like !== undefined) {
+            const sqlValue = handleValue(operator.$like);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} LIKE ${sqlValue}`;
+            }
+            values.push(operator.$like);
+            return `${this.escapeId(field)} LIKE ?`;
+        }
+        // $notLike - NOT LIKE operator
+        if (operator.$notLike !== undefined) {
+            const sqlValue = handleValue(operator.$notLike);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} NOT LIKE ${sqlValue}`;
+            }
+            values.push(operator.$notLike);
+            return `${this.escapeId(field)} NOT LIKE ?`;
+        }
+        // $in - IN operator
+        if (operator.$in !== undefined) {
+            const inValues = operator.$in;
+            // Handle subquery (literal SQL string starting with SELECT)
+            if (typeof inValues === 'string' && inValues.toUpperCase().startsWith('SELECT')) {
+                return `${this.escapeId(field)} IN (${inValues})`;
+            }
+            // Handle literal SQL subquery object
+            if (typeof inValues === 'object' && inValues !== null && '$literal' in inValues) {
+                return `${this.escapeId(field)} IN (${inValues.$literal})`;
+            }
+            if (!Array.isArray(inValues) || inValues.length === 0) {
+                return '1=0'; // Always false for empty IN
+            }
+            // Handle array of special values
+            const placeholders = [];
+            for (const item of inValues) {
+                const itemSql = handleValue(item);
+                if (itemSql !== null) {
+                    placeholders.push(itemSql);
+                }
+                else {
+                    placeholders.push('?');
+                    values.push(item);
+                }
+            }
+            return `${this.escapeId(field)} IN (${placeholders.join(', ')})`;
+        }
+        // $notIn - NOT IN operator
+        if (operator.$notIn !== undefined) {
+            const notInValues = operator.$notIn;
+            // Handle subquery (literal SQL string starting with SELECT)
+            if (typeof notInValues === 'string' &&
+                notInValues.toUpperCase().startsWith('SELECT')) {
+                return `${this.escapeId(field)} NOT IN (${notInValues})`;
+            }
+            // Handle literal SQL subquery object
+            if (typeof notInValues === 'object' &&
+                notInValues !== null &&
+                '$literal' in notInValues) {
+                return `${this.escapeId(field)} NOT IN (${notInValues.$literal})`;
+            }
+            if (!Array.isArray(notInValues) || notInValues.length === 0) {
+                return '1=1'; // Always true for empty NOT IN
+            }
+            // Handle array of special values
+            const placeholders = [];
+            for (const item of notInValues) {
+                const itemSql = handleValue(item);
+                if (itemSql !== null) {
+                    placeholders.push(itemSql);
+                }
+                else {
+                    placeholders.push('?');
+                    values.push(item);
+                }
+            }
+            return `${this.escapeId(field)} NOT IN (${placeholders.join(', ')})`;
+        }
+        // $between - BETWEEN operator (inclusive)
+        if (operator.$between !== undefined) {
+            const between = operator.$between;
+            const startSql = handleValue(between[0]);
+            const endSql = handleValue(between[1]);
+            if (startSql !== null && endSql !== null) {
+                return `${this.escapeId(field)} BETWEEN ${startSql} AND ${endSql}`;
+            }
+            if (startSql !== null) {
+                values.push(between[1]);
+                return `${this.escapeId(field)} BETWEEN ${startSql} AND ?`;
+            }
+            if (endSql !== null) {
+                values.push(between[0]);
+                return `${this.escapeId(field)} BETWEEN ? AND ${endSql}`;
+            }
+            values.push(between[0], between[1]);
+            return `${this.escapeId(field)} BETWEEN ? AND ?`;
+        }
+        // $exists - EXISTS subquery operator
+        if (operator.$exists !== undefined) {
+            const subquery = operator.$exists;
+            // Handle string subquery
+            if (typeof subquery === 'string') {
+                return `EXISTS (${subquery})`;
+            }
+            // Handle literal SQL subquery
+            if (typeof subquery === 'object' && subquery !== null && '$literal' in subquery) {
+                return `EXISTS (${subquery.$literal})`;
+            }
+            return '1=0'; // Default false if not a valid subquery
+        }
+        // $notExists - NOT EXISTS subquery operator
+        if (operator.$notExists !== undefined) {
+            const subquery = operator.$notExists;
+            // Handle string subquery
+            if (typeof subquery === 'string') {
+                return `NOT EXISTS (${subquery})`;
+            }
+            // Handle literal SQL subquery
+            if (typeof subquery === 'object' && subquery !== null && '$literal' in subquery) {
+                return `NOT EXISTS (${subquery.$literal})`;
+            }
+            return '1=1'; // Default true if not a valid subquery
+        }
+        // $notBetween - NOT BETWEEN operator
+        if (operator.$notBetween !== undefined) {
+            const notBetween = operator.$notBetween;
+            const startSql = handleValue(notBetween[0]);
+            const endSql = handleValue(notBetween[1]);
+            if (startSql !== null && endSql !== null) {
+                return `${this.escapeId(field)} NOT BETWEEN ${startSql} AND ${endSql}`;
+            }
+            if (startSql !== null) {
+                values.push(notBetween[1]);
+                return `${this.escapeId(field)} NOT BETWEEN ${startSql} AND ?`;
+            }
+            if (endSql !== null) {
+                values.push(notBetween[0]);
+                return `${this.escapeId(field)} NOT BETWEEN ? AND ${endSql}`;
+            }
+            values.push(notBetween[0], notBetween[1]);
+            return `${this.escapeId(field)} NOT BETWEEN ? AND ?`;
+        }
+        // $isNull - IS NULL operator
+        if (operator.$isNull !== undefined) {
+            if (operator.$isNull) {
+                return `${this.escapeId(field)} IS NULL`;
+            }
+            else {
+                return `${this.escapeId(field)} IS NOT NULL`;
+            }
+        }
+        // $isNotNull - IS NOT NULL operator (shorthand)
+        if (operator.$isNotNull !== undefined) {
+            if (operator.$isNotNull) {
+                return `${this.escapeId(field)} IS NOT NULL`;
+            }
+            else {
+                return `${this.escapeId(field)} IS NULL`;
+            }
+        }
+        // $regexp - REGEXP operator
+        if (operator.$regexp !== undefined) {
+            const sqlValue = handleValue(operator.$regexp);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} REGEXP ${sqlValue}`;
+            }
+            values.push(operator.$regexp);
+            return `${this.escapeId(field)} REGEXP ?`;
+        }
+        // $notRegexp - NOT REGEXP operator
+        if (operator.$notRegexp !== undefined) {
+            const sqlValue = handleValue(operator.$notRegexp);
+            if (sqlValue !== null) {
+                return `${this.escapeId(field)} NOT REGEXP ${sqlValue}`;
+            }
+            values.push(operator.$notRegexp);
+            return `${this.escapeId(field)} NOT REGEXP ?`;
+        }
+        // $json - JSON column query operator
+        if (operator.$json !== undefined) {
+            const jsonValue = operator.$json;
+            if (typeof jsonValue === 'object' && jsonValue !== null) {
+                // Handle { path: 'key.subkey', value: 'something' }
+                if ('path' in jsonValue && 'value' in jsonValue) {
+                    const path = jsonValue.path;
+                    const normalizedPath = path.startsWith('$.') ? path : `$.${path}`;
+                    values.push(jsonValue.value);
+                    return `${this.buildJsonExtract(field, normalizedPath)} = ?`;
+                }
+                // Handle nested JSON query { key: value } - converts to JSON containment
+                values.push(JSON.stringify(jsonValue));
+                return `${this.escapeId(field)} = ?`;
+            }
+            // Handle plain value for JSON equality
+            values.push(JSON.stringify(jsonValue));
+            return `${this.escapeId(field)} = ?`;
+        }
+        // $jsonPath - JSON path query operator (Op.jsonPath('field', 'path'))
+        // Expected format: { $jsonPath: { field: 'column', path: 'key.subkey' } }
+        if (operator.$jsonPath !== undefined) {
+            const jsonPathValue = operator.$jsonPath;
+            if (typeof jsonPathValue === 'object' && jsonPathValue !== null && 'path' in jsonPathValue) {
+                const path = jsonPathValue.path;
+                const normalizedPath = path.startsWith('$.') ? path : `$.${path}`;
+                const compareValue = jsonPathValue.value;
+                if (compareValue !== undefined) {
+                    // Value comparison: json_extract(field, '$.path') = ?
+                    values.push(compareValue);
+                    return `${this.buildJsonExtract(field, normalizedPath)} = ?`;
+                }
+                // No value - just check if path exists (IS NOT NULL)
+                return `${this.buildJsonExtract(field, normalizedPath)} IS NOT NULL`;
+            }
+            // Fallback
+            return '';
+        }
+        // Handle Symbol-based JSON operators (Op.json('path') creates Symbol.for('json:path'))
+        // These appear as keys starting with '$json:' in the operator object
+        for (const key of Object.keys(operator)) {
+            if (key.startsWith('$json:')) {
+                const jsonPath = key.substring(6); // Remove '$json:' prefix
+                const normalizedPath = jsonPath.startsWith('$.') ? jsonPath : `$.${jsonPath}`;
+                const compareValue = operator[key];
+                if (compareValue !== undefined) {
+                    values.push(compareValue);
+                    return `${this.buildJsonExtract(field, normalizedPath)} = ?`;
+                }
+                // No value - check if path exists
+                return `${this.buildJsonExtract(field, normalizedPath)} IS NOT NULL`;
+            }
+        }
+        // $contains - JSON contains operator (for objects/arrays)
+        // PostgreSQL: @>, MySQL: JSON_CONTAINS, SQLite: json_each
+        if (operator.$contains !== undefined) {
+            const containsValue = operator.$contains;
+            values.push(JSON.stringify(containsValue));
+            // Use JSON_EXTRACT for cross-database compatibility
+            // For exact match, we compare the full JSON
+            return `${this.escapeId(field)} = ?`;
+        }
+        // $containedBy - JSON contained by operator
+        // PostgreSQL: <@
+        if (operator.$containedBy !== undefined) {
+            const containedValue = operator.$containedBy;
+            values.push(JSON.stringify(containedValue));
+            // Cross-database: check if the column's JSON is contained by the value
+            return `${this.escapeId(field)} @> ?`;
+        }
+        // $overlap - JSON overlap (arrays) - PostgreSQL: &&
+        if (operator.$overlap !== undefined) {
+            const overlapValue = operator.$overlap;
+            values.push(JSON.stringify(overlapValue));
+            // Cross-database: check array overlap
+            return `${this.escapeId(field)} @> ?`;
+        }
+        // $arrayContains - PostgreSQL array contains operator (@>)
+        // Only supported in PostgreSQL
+        if (operator.$arrayContains !== undefined) {
+            const containsValue = operator.$arrayContains;
+            if (this.options.dialectName !== 'postgres' && this.options.dialectName !== 'postgresql') {
+                // Array operators only work in PostgreSQL
+                throw new Error('Array operators are only supported in PostgreSQL');
+            }
+            const arraySql = this.buildArrayLiteral(containsValue);
+            return `${this.escapeId(field)} @> ${arraySql}`;
+        }
+        // $arrayContainedBy - PostgreSQL array contained by operator (<@)
+        // Only supported in PostgreSQL
+        if (operator.$arrayContainedBy !== undefined) {
+            const containedValue = operator.$arrayContainedBy;
+            if (this.options.dialectName !== 'postgres' && this.options.dialectName !== 'postgresql') {
+                throw new Error('Array operators are only supported in PostgreSQL');
+            }
+            const arraySql = this.buildArrayLiteral(containedValue);
+            return `${this.escapeId(field)} <@ ${arraySql}`;
+        }
+        // $arrayOverlaps - PostgreSQL array overlaps operator (&&)
+        // Only supported in PostgreSQL
+        if (operator.$arrayOverlaps !== undefined) {
+            const overlapValue = operator.$arrayOverlaps;
+            if (this.options.dialectName !== 'postgres' && this.options.dialectName !== 'postgresql') {
+                throw new Error('Array operators are only supported in PostgreSQL');
+            }
+            const arraySql = this.buildArrayLiteral(overlapValue);
+            return `${this.escapeId(field)} && ${arraySql}`;
+        }
+        // $arrayAny - PostgreSQL array ANY operator
+        // Only supported in PostgreSQL
+        if (operator.$arrayAny !== undefined) {
+            const anyValue = operator.$arrayAny;
+            if (this.options.dialectName !== 'postgres' && this.options.dialectName !== 'postgresql') {
+                throw new Error('Array operators are only supported in PostgreSQL');
+            }
+            const escapedValue = this.options.dialect?.escape
+                ? this.options.dialect.escape(anyValue)
+                : this.escapeValue(anyValue);
+            return `${escapedValue} = ANY(${this.escapeId(field)})`;
+        }
+        // $arrayAll - PostgreSQL array ALL operator
+        // Only supported in PostgreSQL
+        if (operator.$arrayAll !== undefined) {
+            const allValue = operator.$arrayAll;
+            if (this.options.dialectName !== 'postgres' && this.options.dialectName !== 'postgresql') {
+                throw new Error('Array operators are only supported in PostgreSQL');
+            }
+            // For array ALL, we compare: value > ALL(array_column)
+            // This checks if value is greater than all elements in the array
+            const escapedValue = this.options.dialect?.escape
+                ? this.options.dialect.escape(allValue)
+                : this.escapeValue(allValue);
+            // Use the comparison operator from the inner operator if provided
+            if (typeof allValue === 'object' && allValue !== null && '$gt' in allValue) {
+                const compValue = allValue.$gt;
+                const compEscaped = this.options.dialect?.escape
+                    ? this.options.dialect.escape(compValue)
+                    : this.escapeValue(compValue);
+                return `${compEscaped} > ALL(${this.escapeId(field)})`;
+            }
+            return `${escapedValue} = ALL(${this.escapeId(field)})`;
+        }
+        // $keyExists - Check if key exists in JSON
+        // PostgreSQL: ? (jsonb_exists), MySQL: JSON_CONTAINS_PATH, SQLite: json_each
+        if (operator.$keyExists !== undefined) {
+            const keyPath = operator.$keyExists;
+            // Use json_extract for SQLite/MySQL and ->> for PostgreSQL style comparison
+            // Check if the key path returns non-null
+            return `json_extract(${this.escapeId(field)}, '$.${keyPath}') IS NOT NULL`;
+        }
+        // $jsonContains - JSON contains operator (Op.jsonContains)
+        // PostgreSQL: @>, MySQL: JSON_CONTAINS, SQLite: json_extract
+        if (operator.$jsonContains !== undefined) {
+            const containsValue = operator.$jsonContains;
+            values.push(JSON.stringify(containsValue));
+            // Use dialect-specific JSON contains
+            // For cross-database compatibility, we use the default dialect approach
+            // PostgreSQL: @> operator
+            // MySQL: JSON_CONTAINS
+            // SQLite: json_each
+            if (this.options.dialectName === 'postgres') {
+                return `${this.escapeId(field)} @> ?`;
+            }
+            else if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `JSON_CONTAINS(${this.escapeId(field)}, ?)`;
+            }
+            else {
+                // SQLite and default: use JSON comparison
+                return `${this.escapeId(field)} = ?`;
+            }
+        }
+        // $jsonHasKey - JSON has key operator (Op.jsonHasKey)
+        // PostgreSQL: ? (jsonb_exists), MySQL: JSON_CONTAINS_PATH, SQLite: json_each
+        if (operator.$jsonHasKey !== undefined) {
+            const keyPath = String(operator.$jsonHasKey);
+            // Normalize the key path
+            const normalizedKey = keyPath.startsWith('$.') ? keyPath.substring(2) : keyPath;
+            if (this.options.dialectName === 'postgres') {
+                // PostgreSQL: ? operator for jsonb
+                return `${this.escapeId(field)} ? $1`;
+            }
+            else if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                // MySQL/MariaDB: JSON_CONTAINS_PATH(col, 'one', '$.key')
+                return `JSON_CONTAINS_PATH(${this.escapeId(field)}, 'one', '$.${normalizedKey}')`;
+            }
+            else {
+                // SQLite: json_extract returns non-null if key exists
+                return `json_extract(${this.escapeId(field)}, '$.${normalizedKey}') IS NOT NULL`;
+            }
+        }
+        // $jsonPath - JSON path query operator (Op.jsonPath)
+        // PostgreSQL: ->> and #>>, MySQL: JSON_EXTRACT, SQLite: json_extract
+        if (operator.$jsonPath !== undefined) {
+            const jsonPathValue = operator.$jsonPath;
+            if (typeof jsonPathValue === 'object' && jsonPathValue !== null && 'path' in jsonPathValue) {
+                const path = jsonPathValue.path;
+                const normalizedPath = path.startsWith('$.') ? path : `$.${path}`;
+                const compareValue = jsonPathValue.value;
+                if (compareValue !== undefined) {
+                    // Value comparison: json_extract(field, '$.path') = ?
+                    values.push(compareValue);
+                    return `${this.buildJsonExtract(field, normalizedPath)} = ?`;
+                }
+                // No value - just check if path exists (IS NOT NULL)
+                return `${this.buildJsonExtract(field, normalizedPath)} IS NOT NULL`;
+            }
+            // Fallback
+            return '';
+        }
+        // $jsonbExtract - JSONB extract field (PostgreSQL: ->)
+        // Extracts a JSON object field, returns JSON
+        if (operator.$jsonbExtract !== undefined) {
+            const extractValue = operator.$jsonbExtract;
+            if (typeof extractValue === 'object' && extractValue !== null && 'path' in extractValue) {
+                const path = String(extractValue.path);
+                const compareValue = extractValue.value;
+                // PostgreSQL: field -> 'path'
+                const columnRef = this.escapeId(field);
+                if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                    if (compareValue !== undefined) {
+                        values.push(compareValue);
+                        return `${columnRef} -> '${path}' = ?`;
+                    }
+                    return `${columnRef} -> '${path}' IS NOT NULL`;
+                }
+                // Fallback for other dialects: use json_extract
+                const pathStr = path.startsWith('$.') ? path : `$.${path}`;
+                if (compareValue !== undefined) {
+                    values.push(compareValue);
+                    return `json_extract(${columnRef}, '${pathStr}') = ?`;
+                }
+                return `json_extract(${columnRef}, '${pathStr}') IS NOT NULL`;
+            }
+            return '';
+        }
+        // $jsonbExtractText - JSONB extract field as text (PostgreSQL: ->>)
+        // Extracts a JSON object field as text, returns text
+        if (operator.$jsonbExtractText !== undefined) {
+            const extractValue = operator.$jsonbExtractText;
+            if (typeof extractValue === 'object' && extractValue !== null && 'path' in extractValue) {
+                const path = String(extractValue.path);
+                const compareValue = extractValue.value;
+                // PostgreSQL: field ->> 'path'
+                const columnRef = this.escapeId(field);
+                if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                    if (compareValue !== undefined) {
+                        values.push(compareValue);
+                        return `${columnRef} ->> '${path}' = ?`;
+                    }
+                    return `${columnRef} ->> '${path}' IS NOT NULL`;
+                }
+                // Fallback for other dialects: use json_extract
+                const pathStr = path.startsWith('$.') ? path : `$.${path}`;
+                if (compareValue !== undefined) {
+                    values.push(compareValue);
+                    return `json_extract(${columnRef}, '${pathStr}') = ?`;
+                }
+                return `json_extract(${columnRef}, '${pathStr}') IS NOT NULL`;
+            }
+            return '';
+        }
+        // $jsonbExtractPath - JSONB extract by path (PostgreSQL: #>)
+        // Extracts JSON by path, returns JSON
+        if (operator.$jsonbExtractPath !== undefined) {
+            const extractValue = operator.$jsonbExtractPath;
+            if (typeof extractValue === 'object' && extractValue !== null && 'path' in extractValue) {
+                const pathValue = extractValue.path;
+                const compareValue = extractValue.value;
+                // Convert path to PostgreSQL format: ['a', 'b'] -> '{a, b}'
+                const pgPath = Array.isArray(pathValue) ? `{${pathValue.join(', ')}}` : `{${pathValue}}`;
+                const columnRef = this.escapeId(field);
+                if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                    if (compareValue !== undefined) {
+                        values.push(compareValue);
+                        return `${columnRef} #> '${pgPath}' = ?`;
+                    }
+                    return `${columnRef} #> '${pgPath}' IS NOT NULL`;
+                }
+                // Fallback for other dialects
+                const pathStr = Array.isArray(pathValue) ? pathValue.join('.') : pathValue;
+                const jsonPath = pathStr.startsWith('$.') ? pathStr : `$.${pathStr}`;
+                if (compareValue !== undefined) {
+                    values.push(compareValue);
+                    return `json_extract(${columnRef}, '${jsonPath}') = ?`;
+                }
+                return `json_extract(${columnRef}, '${jsonPath}') IS NOT NULL`;
+            }
+            return '';
+        }
+        // $jsonbExtractPathText - JSONB extract by path as text (PostgreSQL: #>>)
+        // Extracts JSON by path as text, returns text
+        if (operator.$jsonbExtractPathText !== undefined) {
+            const extractValue = operator.$jsonbExtractPathText;
+            if (typeof extractValue === 'object' && extractValue !== null && 'path' in extractValue) {
+                const pathValue = extractValue.path;
+                const compareValue = extractValue.value;
+                // Convert path to PostgreSQL format: ['a', 'b'] -> '{a, b}'
+                const pgPath = Array.isArray(pathValue) ? `{${pathValue.join(', ')}}` : `{${pathValue}}`;
+                const columnRef = this.escapeId(field);
+                if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                    if (compareValue !== undefined) {
+                        values.push(compareValue);
+                        return `${columnRef} #>> '${pgPath}' = ?`;
+                    }
+                    return `${columnRef} #>> '${pgPath}' IS NOT NULL`;
+                }
+                // Fallback for other dialects
+                const pathStr = Array.isArray(pathValue) ? pathValue.join('.') : pathValue;
+                const jsonPath = pathStr.startsWith('$.') ? pathStr : `$.${pathStr}`;
+                if (compareValue !== undefined) {
+                    values.push(compareValue);
+                    return `json_extract(${columnRef}, '${jsonPath}') = ?`;
+                }
+                return `json_extract(${columnRef}, '${jsonPath}') IS NOT NULL`;
+            }
+            return '';
+        }
+        // $key - Get value at key path in JSON
+        // Supports: { $key: 'address.city' } or { $key: { path: 'address.city', value: 'NYC' } }
+        if (operator.$key !== undefined) {
+            const keyValue = operator.$key;
+            if (typeof keyValue === 'string') {
+                // Just a key path, return the JSON extraction
+                return `json_extract(${this.escapeId(field)}, '$.${keyValue}')`;
+            }
+            else if (typeof keyValue === 'object' && keyValue !== null && 'path' in keyValue) {
+                // Key path with value comparison
+                const keyObj = keyValue;
+                const path = keyObj.path;
+                const compareValue = keyObj.value;
+                values.push(compareValue);
+                return `json_extract(${this.escapeId(field)}, '$.${path}') = ?`;
+            }
+            // Fallback
+            values.push(operator.$key);
+            return `${this.escapeId(field)} = ?`;
+        }
+        // $jsonConcat - JSONB concatenation (PostgreSQL: ||)
+        if (operator.$jsonConcat !== undefined) {
+            const concatValue = operator.$jsonConcat;
+            if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                values.push(JSON.stringify(concatValue));
+                return `${this.escapeId(field)} || ?`;
+            }
+            // Fallback for other dialects - use string concatenation
+            values.push(JSON.stringify(concatValue));
+            return `${this.escapeId(field)} = ?`;
+        }
+        // $jsonDelete - JSONB delete key (PostgreSQL: -)
+        if (operator.$jsonDelete !== undefined) {
+            const deleteKey = operator.$jsonDelete;
+            if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                return `${this.escapeId(field)} - '${deleteKey}'`;
+            }
+            // Fallback - not supported
+            throw new Error('JSON key deletion is only supported in PostgreSQL');
+        }
+        // $jsonDeletePath - JSONB delete by path (PostgreSQL: #-)
+        if (operator.$jsonDeletePath !== undefined) {
+            const deletePath = operator.$jsonDeletePath;
+            if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                const pgPath = Array.isArray(deletePath)
+                    ? `{${deletePath.join(', ')}}`
+                    : `{${deletePath}}`;
+                return `${this.escapeId(field)} #- '${pgPath}'`;
+            }
+            // Fallback - not supported
+            throw new Error('JSON path deletion is only supported in PostgreSQL');
+        }
+        // $jsonPathExists - JSON path exists (PostgreSQL: @?)
+        if (operator.$jsonPathExists !== undefined) {
+            const pathValue = operator.$jsonPathExists;
+            if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                return `${this.escapeId(field)} @? '${pathValue}'`;
+            }
+            // Fallback for other dialects - use JSON_EXISTS or similar
+            return `${this.escapeId(field)} @? '${pathValue}'`;
+        }
+        // $jsonPathQuery - JSON path query (PostgreSQL: @@)
+        if (operator.$jsonPathQuery !== undefined) {
+            const pathValue = operator.$jsonPathQuery;
+            if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                return `${this.escapeId(field)} @@ '${pathValue}'`;
+            }
+            // Fallback for other dialects
+            return `${this.escapeId(field)} @@ '${pathValue}'`;
+        }
+        // $jsonTypeOf - JSON type of (PostgreSQL: json_typeof)
+        if (operator.$jsonTypeOf !== undefined) {
+            const typeValue = operator.$jsonTypeOf;
+            if (this.options.dialectName === 'postgres' || this.options.dialectName === 'postgresql') {
+                values.push(typeValue);
+                return `json_typeof(${this.escapeId(field)}) = ?`;
+            }
+            // Fallback - not supported
+            throw new Error('JSON type detection is only supported in PostgreSQL');
+        }
+        // $col - Column reference for comparisons (e.g., WHERE column1 = column2)
+        if (operator.$col !== undefined) {
+            const colName = String(operator.$col);
+            return `${this.escapeId(field)} = ${this.escapeId(colName)}`;
+        }
+        // $match - Full-text search (MySQL MATCH AGAINST)
+        // Format: { field: { $match: { columns: string[], mode: 'natural' | 'boolean', searchTerm: string } } }
+        // or using Op.match(): { [Op.match(['title', 'body'])]: 'search term' }
+        if (operator.$match !== undefined) {
+            const matchValue = operator.$match;
+            const searchTerm = typeof matchValue === 'string' ? matchValue : matchValue.searchTerm || '';
+            const columns = matchValue.columns || [field];
+            const mode = matchValue.mode || 'natural';
+            // Helper to escape values using dialect
+            const escapeValue = (val) => {
+                if (this.options.dialect?.escape) {
+                    return this.options.dialect.escape(val);
+                }
+                if (typeof val === 'string') {
+                    return `'${val.replace(/'/g, "''")}'`;
+                }
+                return String(val);
+            };
+            // For MySQL dialect
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                const columnList = columns.map((c) => this.escapeId(c)).join(', ');
+                const modeStr = mode === 'boolean' ? 'IN BOOLEAN MODE' : 'IN NATURAL LANGUAGE MODE';
+                return `MATCH(${columnList}) AGAINST(${escapeValue(searchTerm)} ${modeStr})`;
+            }
+            // For PostgreSQL, use tsvector/tsquery
+            if (this.options.dialectName === 'postgres') {
+                const columnList = columns.map((c) => this.escapeId(c)).join(" || ' ' || ");
+                values.push(searchTerm);
+                return `to_tsvector('english', ${columnList}) @@ to_tsquery('english', ?)`;
+            }
+            // Default fallback for SQLite (no FTS support)
+            values.push(searchTerm);
+            return `${this.escapeId(field)} LIKE ?`;
+        }
+        // $tsvector - PostgreSQL to_tsvector
+        if (operator.$tsvector !== undefined) {
+            const tsvectorValue = operator.$tsvector;
+            const column = tsvectorValue.column || field;
+            const config = tsvectorValue.config || 'english';
+            // This is typically used with @@ operator in PostgreSQL
+            return `to_tsvector('${config}', ${this.escapeId(column)})`;
+        }
+        // $tsquery - PostgreSQL to_tsquery
+        if (operator.$tsquery !== undefined) {
+            const tsqueryValue = operator.$tsquery;
+            const query = tsqueryValue.query;
+            const config = tsqueryValue.config || 'english';
+            if (query) {
+                values.push(query);
+                return `to_tsquery('${config}', ?)`;
+            }
+            // Handle case where tsquery is used with a value: { field: { $tsquery: 'term' } }
+            return `to_tsquery('${config}', ?)`;
+        }
+        // $plainTsquery - PostgreSQL plainto_tsquery
+        if (operator.$plainTsquery !== undefined) {
+            const plainTsqueryValue = operator.$plainTsquery;
+            const query = plainTsqueryValue.query;
+            const config = plainTsqueryValue.config || 'english';
+            if (query) {
+                values.push(query);
+                return `plainto_tsquery('${config}', ?)`;
+            }
+            return `plainto_tsquery('${config}', ?)`;
+        }
+        // $phraseTsquery - PostgreSQL phraseto_tsquery
+        if (operator.$phraseTsquery !== undefined) {
+            const phraseTsqueryValue = operator.$phraseTsquery;
+            const query = phraseTsqueryValue.query;
+            const config = phraseTsqueryValue.config || 'english';
+            if (query) {
+                values.push(query);
+                return `phraseto_tsquery('${config}', ?)`;
+            }
+            return `phraseto_tsquery('${config}', ?)`;
+        }
+        // ============================================
+        // Spatial/Geometric operators
+        // ============================================
+        // Helper to convert geometry value to SQL
+        const buildGeometrySql = (geom, srid) => {
+            if (typeof geom === 'string') {
+                // WKT string - wrap with ST_GeomFromText
+                const sridStr = srid ? `, ${srid}` : '';
+                if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                    return `ST_GeomFromText('${geom}'${sridStr})`;
+                }
+                return `ST_GeomFromText('${geom}'${sridStr})`;
+            }
+            if (typeof geom === 'object' && geom !== null && 'type' in geom && 'coordinates' in geom) {
+                // GeoJSON object
+                const sridStr = srid ? `, ${srid}` : '';
+                return `ST_GeomFromGeoJSON('${JSON.stringify(geom)}'${sridStr})`;
+            }
+            // Just return as-is (assuming it's already a column reference)
+            return String(geom);
+        };
+        // $stDistance - distance between two geometries
+        if (operator.$stDistance !== undefined) {
+            const distOptions = operator.$stDistance;
+            const from = distOptions.from;
+            const distance = distOptions.distance;
+            const srid = distOptions.srid || 4326;
+            const fromSql = buildGeometrySql(from, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                // MySQL: ST_Distance returns distance in units of the SRID
+                values.push(distance);
+                return `ST_Distance(${fieldGeom}, ST_GeomFromText('${typeof from === 'string' ? from : ''}', ${srid})) < ?`;
+            }
+            // PostgreSQL: ST_Distance for geometry, ST_Distance for geography (in meters)
+            values.push(distance);
+            return `ST_Distance(${fieldGeom}, ${fromSql}) < ?`;
+        }
+        // $stWithin - geometry A is within geometry B
+        if (operator.$stWithin !== undefined) {
+            const withinOptions = operator.$stWithin;
+            const geometry = withinOptions.geometry;
+            const srid = withinOptions.srid || 4326;
+            const geomSql = buildGeometrySql(geometry, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_Within(${fieldGeom}, ${geomSql})`;
+            }
+            // PostgreSQL
+            return `ST_Within(${fieldGeom}, ${geomSql})`;
+        }
+        // $stContains - geometry A contains geometry B
+        if (operator.$stContains !== undefined) {
+            const containsOptions = operator.$stContains;
+            const geometry = containsOptions.geometry;
+            const srid = containsOptions.srid || 4326;
+            const geomSql = buildGeometrySql(geometry, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_Contains(${fieldGeom}, ${geomSql})`;
+            }
+            // PostgreSQL
+            return `ST_Contains(${fieldGeom}, ${geomSql})`;
+        }
+        // $stIntersects - two geometries intersect
+        if (operator.$stIntersects !== undefined) {
+            const intersectsOptions = operator.$stIntersects;
+            const geometry = intersectsOptions.geometry;
+            const srid = intersectsOptions.srid || 4326;
+            const geomSql = buildGeometrySql(geometry, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_Intersects(${fieldGeom}, ${geomSql})`;
+            }
+            // PostgreSQL
+            return `ST_Intersects(${fieldGeom}, ${geomSql})`;
+        }
+        // $stDWithin - geometries are within a given distance
+        if (operator.$stDWithin !== undefined) {
+            const dWithinOptions = operator.$stDWithin;
+            const from = dWithinOptions.from;
+            const distance = dWithinOptions.distance;
+            const srid = dWithinOptions.srid || 4326;
+            const spheroid = dWithinOptions.spheroid !== false;
+            const fromSql = buildGeometrySql(from, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                // MySQL 8.0+ uses ST_DWithin
+                values.push(distance);
+                return `ST_DWithin(${fieldGeom}, ST_GeomFromText('${typeof from === 'string' ? from : ''}', ${srid}), ?)`;
+            }
+            // PostgreSQL: ST_DWithin for geometry, ST_DWithin for geography
+            if (spheroid) {
+                values.push(distance);
+                return `ST_DWithin(${fieldGeom}, ${fromSql}, ?)`;
+            }
+            values.push(distance);
+            return `ST_DWithin(${fieldGeom}, ${fromSql}, ?)`;
+        }
+        // $stCrosses - two geometries cross
+        if (operator.$stCrosses !== undefined) {
+            const crossesOptions = operator.$stCrosses;
+            const geometry = crossesOptions.geometry;
+            const srid = crossesOptions.srid || 4326;
+            const geomSql = buildGeometrySql(geometry, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_Crosses(${fieldGeom}, ${geomSql})`;
+            }
+            return `ST_Crosses(${fieldGeom}, ${geomSql})`;
+        }
+        // $stOverlaps - two geometries overlap
+        if (operator.$stOverlaps !== undefined) {
+            const overlapsOptions = operator.$stOverlaps;
+            const geometry = overlapsOptions.geometry;
+            const srid = overlapsOptions.srid || 4326;
+            const geomSql = buildGeometrySql(geometry, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_Overlaps(${fieldGeom}, ${geomSql})`;
+            }
+            return `ST_Overlaps(${fieldGeom}, ${geomSql})`;
+        }
+        // $stTouches - two geometries touch
+        if (operator.$stTouches !== undefined) {
+            const touchesOptions = operator.$stTouches;
+            const geometry = touchesOptions.geometry;
+            const srid = touchesOptions.srid || 4326;
+            const geomSql = buildGeometrySql(geometry, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_Touches(${fieldGeom}, ${geomSql})`;
+            }
+            return `ST_Touches(${fieldGeom}, ${geomSql})`;
+        }
+        // $stEquals - two geometries are equal
+        if (operator.$stEquals !== undefined) {
+            const equalsOptions = operator.$stEquals;
+            const geometry = equalsOptions.geometry;
+            const srid = equalsOptions.srid || 4326;
+            const geomSql = buildGeometrySql(geometry, srid);
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_Equals(${fieldGeom}, ${geomSql})`;
+            }
+            return `ST_Equals(${fieldGeom}, ${geomSql})`;
+        }
+        // $stIsValid - check if geometry is valid
+        if (operator.$stIsValid !== undefined) {
+            const fieldGeom = this.escapeId(field);
+            if (this.options.dialectName === 'mysql' || this.options.dialectName === 'mariadb') {
+                return `ST_IsValid(${fieldGeom})`;
+            }
+            return `ST_IsValid(${fieldGeom})`;
+        }
+        // Handle nested object as implicit equality
+        values.push(operator);
+        return `${this.escapeId(field)} = ?`;
+    }
+    /**
+     * Escape an identifier (column/table name)
+     */
+    escapeId(identifier) {
+        const id = String(identifier ?? '');
+        if (this.options.dialect?.escapeId) {
+            return this.options.dialect.escapeId(id);
+        }
+        // Default quoting
+        return `"${id.replace(/"/g, '""')}"`;
+    }
+    /**
+     * Escape a value for use in a query
+     */
+    escapeValue(value) {
+        if (value === null) {
+            return 'NULL';
+        }
+        if (typeof value === 'string') {
+            return `'${value.replace(/'/g, "''")}'`;
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+        if (typeof value === 'boolean') {
+            return value ? 'TRUE' : 'FALSE';
+        }
+        if (value instanceof Date) {
+            return `'${value.toISOString()}'`;
+        }
+        // Default: JSON stringify
+        return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+    }
+    /**
+     * Build a PostgreSQL array literal from an array value
+     * e.g., ['a', 'b'] => ARRAY['a', 'b']
+     */
+    buildArrayLiteral(value) {
+        if (!Array.isArray(value)) {
+            // Single value - wrap in array
+            const escaped = this.options.dialect?.escape
+                ? this.options.dialect.escape(value)
+                : this.escapeValue(value);
+            return `ARRAY[${escaped}]`;
+        }
+        if (value.length === 0) {
+            return 'ARRAY[]';
+        }
+        const escapedValues = value.map((v) => {
+            return this.options.dialect?.escape ? this.options.dialect.escape(v) : this.escapeValue(v);
+        });
+        return `ARRAY[${escapedValues.join(', ')}]`;
+    }
+    /**
+     * Build a JSON extraction expression based on the dialect
+     * SQLite/MySQL: json_extract(column, '$.path')
+     * PostgreSQL: column->>'path' or #>>'{path}'
+     *
+     * @param field - The JSON/JSONB column name
+     * @param path - The JSON path to extract (e.g., 'settings.theme' or '$.settings.theme')
+     * @returns SQL fragment for JSON extraction
+     */
+    buildJsonExtract(field, path) {
+        const columnRef = this.escapeId(field);
+        const normalizedPath = path.startsWith('$.') ? path : `$.${path}`;
+        // Get dialect name from options if available
+        const dialectName = this.options?.dialectName;
+        // PostgreSQL uses different syntax
+        if (dialectName === 'postgres' || dialectName === 'postgresql') {
+            // Convert path to PostgreSQL format: $.settings.theme -> 'settings', 'theme'
+            const pathParts = normalizedPath.substring(2).split('.');
+            const pgPath = pathParts.map((p) => `'${p}'`).join(', ');
+            return `${columnRef} #>> '{${pgPath}}'`;
+        }
+        // SQLite and MySQL use JSON_EXTRACT / json_extract
+        return `json_extract(${columnRef}, '${normalizedPath}')`;
+    }
+    /**
+     * Build a JSON path query - alias for buildJsonExtract for compatibility
+     */
+    jsonExtract(field, path) {
+        return this.buildJsonExtract(field, path);
+    }
+}
+exports.WhereBuilder = WhereBuilder;
+/**
+ * Create a WhereBuilder instance with default options
+ */
+function createWhereBuilder(options) {
+    return new WhereBuilder(options);
+}
+/**
+ * Quick helper to build a WHERE clause
+ */
+function buildWhereClause(where, options) {
+    const builder = new WhereBuilder(options);
+    return builder.build(where);
+}
+exports.default = WhereBuilder;