@carbonorm/carbonnode 3.9.4 → 3.9.6

package/dist/index.cjs.js

@@ -14,6 +14,7 @@ var C6Constants = {
     ADDTIME: 'ADDTIME',
     AS: 'AS',
     ASC: 'ASC',
+    AND: 'AND',
     BETWEEN: 'BETWEEN',
     CONCAT: 'CONCAT',
     CONVERT_TZ: 'CONVERT_TZ',
@@ -87,6 +88,7 @@ var C6Constants = {
     NOW: 'NOW',
     NULL: 'NULL',
     ORDER: 'ORDER',
+    OR: 'OR',
     PAGE: 'PAGE',
     PAGINATION: 'PAGINATION',
     RIGHT_OUTER: 'RIGHT_OUTER',
@@ -1292,6 +1294,10 @@ var AggregateBuilder = /** @class */ (function (_super) {
             args.pop();
         }
         var F = String(fn).toUpperCase();
+        var isGeomFromText = F === C6C.ST_GEOMFROMTEXT.toUpperCase();
+        if (args.length === 1 && Array.isArray(args[0])) {
+            args = args[0];
+        }
         // Parameter placeholder helper: [C6C.PARAM, value]
         if (F === C6C.PARAM) {
             if (!params) {
@@ -1321,7 +1327,7 @@ var AggregateBuilder = /** @class */ (function (_super) {
         }
         var identifierPathRegex = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
         var argList = args
-            .map(function (arg) {
+            .map(function (arg, index) {
             if (Array.isArray(arg))
                 return _this.buildAggregateField(arg, params);
             if (typeof arg === 'string') {
@@ -1332,6 +1338,15 @@ var AggregateBuilder = /** @class */ (function (_super) {
                 // Treat numeric-looking strings as literals, not identifier paths
                 if (isNumericString(arg))
                     return arg;
+                if (isGeomFromText && index === 0) {
+                    var trimmed = arg.trim();
+                    var alreadyQuoted = trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2;
+                    if (alreadyQuoted) {
+                        return trimmed;
+                    }
+                    var escaped = arg.replace(/'/g, "''");
+                    return "'".concat(escaped, "'");
+                }
                 return arg;
             }
             return String(arg);
@@ -1439,24 +1454,43 @@ var ConditionBuilder = /** @class */ (function (_super) {
         var _this = _super !== null && _super.apply(this, arguments) || this;
         _this.aliasMap = {};
         _this.derivedAliases = new Set();
-        _this.OPERATORS = new Set([
-            C6C.EQUAL, C6C.NOT_EQUAL, C6C.LESS_THAN, C6C.LESS_THAN_OR_EQUAL_TO,
-            C6C.GREATER_THAN, C6C.GREATER_THAN_OR_EQUAL_TO,
-            C6C.LIKE, C6C.NOT_LIKE,
-            C6C.IN, C6C.NOT_IN, 'NOT IN',
-            C6C.IS, C6C.IS_NOT,
-            C6C.BETWEEN, 'NOT BETWEEN',
-            C6C.MATCH_AGAINST,
-            C6C.ST_DISTANCE_SPHERE,
-            // spatial predicates
-            C6C.ST_CONTAINS,
-            C6C.ST_INTERSECTS,
-            C6C.ST_WITHIN,
-            C6C.ST_CROSSES,
-            C6C.ST_DISJOINT,
-            C6C.ST_EQUALS,
-            C6C.ST_OVERLAPS,
-            C6C.ST_TOUCHES
+        _this.BOOLEAN_OPERATORS = new Map([
+            [C6C.AND, 'AND'],
+            ['AND', 'AND'],
+            [C6C.OR, 'OR'],
+            ['OR', 'OR'],
+        ]);
+        _this.OPERATOR_ALIASES = new Map([
+            [C6C.EQUAL, C6C.EQUAL],
+            ['=', C6C.EQUAL],
+            [C6C.EQUAL_NULL_SAFE, C6C.EQUAL_NULL_SAFE],
+            ['<=>', C6C.EQUAL_NULL_SAFE],
+            [C6C.NOT_EQUAL, C6C.NOT_EQUAL],
+            ['<>', C6C.NOT_EQUAL],
+            [C6C.LESS_THAN, C6C.LESS_THAN],
+            ['<', C6C.LESS_THAN],
+            [C6C.LESS_THAN_OR_EQUAL_TO, C6C.LESS_THAN_OR_EQUAL_TO],
+            ['<=', C6C.LESS_THAN_OR_EQUAL_TO],
+            [C6C.GREATER_THAN, C6C.GREATER_THAN],
+            ['>', C6C.GREATER_THAN],
+            [C6C.GREATER_THAN_OR_EQUAL_TO, C6C.GREATER_THAN_OR_EQUAL_TO],
+            ['>=', C6C.GREATER_THAN_OR_EQUAL_TO],
+            [C6C.LIKE, C6C.LIKE],
+            ['LIKE', C6C.LIKE],
+            [C6C.NOT_LIKE, 'NOT LIKE'],
+            ['NOT LIKE', 'NOT LIKE'],
+            [C6C.IN, C6C.IN],
+            ['IN', C6C.IN],
+            [C6C.NOT_IN, 'NOT IN'],
+            ['NOT IN', 'NOT IN'],
+            [C6C.IS, C6C.IS],
+            ['IS', C6C.IS],
+            [C6C.IS_NOT, 'IS NOT'],
+            ['IS NOT', 'IS NOT'],
+            [C6C.BETWEEN, C6C.BETWEEN],
+            ['BETWEEN', C6C.BETWEEN],
+            ['NOT BETWEEN', 'NOT BETWEEN'],
+            [C6C.MATCH_AGAINST, C6C.MATCH_AGAINST],
         ]);
         return _this;
     }
@@ -1538,11 +1572,6 @@ var ConditionBuilder = /** @class */ (function (_super) {
         return (fullKey in table.COLUMNS ||
             Object.values(table.COLUMNS).includes(column));
     };
-    ConditionBuilder.prototype.validateOperator = function (op) {
-        if (!this.OPERATORS.has(op)) {
-            throw new Error("Invalid or unsupported SQL operator detected: '".concat(op, "'"));
-        }
-    };
     ConditionBuilder.prototype.addParam = function (params, column, value) {
         var _a, _b, _c, _d, _e;
         // Determine column definition from C6.TABLES to support type-aware conversions (e.g., BINARY hex -> Buffer)
@@ -1564,250 +1593,444 @@ var ConditionBuilder = /** @class */ (function (_super) {
             return '?';
         }
     };
-    ConditionBuilder.prototype.buildBooleanJoinedConditions = function (set, andMode, params) {
-        var _this = this;
-        if (andMode === void 0) { andMode = true; }
-        if (params === void 0) { params = []; }
-        var booleanOperator = andMode ? 'AND' : 'OR';
-        var addCondition = function (column, op, value) {
-            // Normalize common variants
-            var valueNorm = (value === C6C.NULL) ? null : value;
-            var displayOp = typeof op === 'string' ? op.replace('_', ' ') : op;
-            var extractSubSelect = function (input) {
-                if (Array.isArray(input) && input.length >= 2 && input[0] === C6C.SUBSELECT) {
-                    return input[1];
-                }
-                if (input && typeof input === 'object' && C6C.SUBSELECT in input) {
-                    return input[C6C.SUBSELECT];
+    ConditionBuilder.prototype.normalizeOperatorKey = function (op) {
+        if (typeof op !== 'string')
+            return undefined;
+        return this.OPERATOR_ALIASES.get(op);
+    };
+    ConditionBuilder.prototype.formatOperator = function (op) {
+        var normalized = this.normalizeOperatorKey(op);
+        if (!normalized) {
+            throw new Error("Invalid or unsupported SQL operator detected: '".concat(op, "'"));
+        }
+        switch (normalized) {
+            case 'NOT LIKE':
+            case 'NOT IN':
+            case 'IS NOT':
+            case 'NOT BETWEEN':
+                return normalized;
+            case C6C.MATCH_AGAINST:
+                return C6C.MATCH_AGAINST;
+            default:
+                return normalized;
+        }
+    };
+    ConditionBuilder.prototype.isOperator = function (op) {
+        return !!this.normalizeOperatorKey(op);
+    };
+    ConditionBuilder.prototype.looksLikeSafeFunctionExpression = function (value) {
+        if (typeof value !== 'string')
+            return false;
+        var trimmed = value.trim();
+        if (trimmed.length === 0)
+            return false;
+        if (trimmed.includes(';') || trimmed.includes('--') || trimmed.includes('/*') || trimmed.includes('*/')) {
+            return false;
+        }
+        if (!trimmed.includes('(') || !trimmed.endsWith(')')) {
+            return false;
+        }
+        var functionMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s*\(/);
+        if (!functionMatch) {
+            return false;
+        }
+        var allowedCharacters = /^[A-Za-z0-9_().,'"\s-]+$/;
+        if (!allowedCharacters.test(trimmed)) {
+            return false;
+        }
+        var depth = 0;
+        for (var _i = 0, trimmed_1 = trimmed; _i < trimmed_1.length; _i++) {
+            var char = trimmed_1[_i];
+            if (char === '(') {
+                depth += 1;
+            }
+            else if (char === ')') {
+                depth -= 1;
+                if (depth < 0) {
+                    return false;
                 }
-                return undefined;
-            };
-            var rightSubSelectPayload = extractSubSelect(valueNorm);
-            var buildSubSelect = function (payload) {
-                if (!payload)
-                    return undefined;
-                var builder = _this.buildScalarSubSelect;
+            }
+        }
+        return depth === 0;
+    };
+    ConditionBuilder.prototype.ensureWrapped = function (expression) {
+        var trimmed = expression.trim();
+        if (!trimmed)
+            return trimmed;
+        if (trimmed.startsWith('(') && trimmed.endsWith(')')) {
+            return trimmed;
+        }
+        return "(".concat(trimmed, ")");
+    };
+    ConditionBuilder.prototype.joinBooleanParts = function (parts, operator) {
+        if (parts.length === 0)
+            return '';
+        if (parts.length === 1) {
+            return parts[0];
+        }
+        return parts
+            .map(function (part) {
+            var trimmed = part.trim();
+            var upper = trimmed.toUpperCase();
+            var containsAnd = upper.includes(' AND ');
+            var containsOr = upper.includes(' OR ');
+            var needsWrap = (operator === 'AND' && containsOr) ||
+                (operator === 'OR' && containsAnd);
+            return needsWrap ? "(".concat(trimmed, ")") : trimmed;
+        })
+            .join(" ".concat(operator, " "));
+    };
+    ConditionBuilder.prototype.normalizeFunctionField = function (field, params) {
+        var _this = this;
+        if (field instanceof Map) {
+            field = Object.fromEntries(field);
+        }
+        if (Array.isArray(field)) {
+            if (field.length === 0)
+                return field;
+            var fn = field[0], args = field.slice(1);
+            var normalizedArgs = args.map(function (arg) { return _this.normalizeFunctionField(arg, params); });
+            return tslib.__spreadArray([fn], normalizedArgs, true);
+        }
+        if (field && typeof field === 'object') {
+            if (C6C.SUBSELECT in field) {
+                var builder = this.buildScalarSubSelect;
                 if (typeof builder !== 'function') {
                     throw new Error('Scalar subselect handling requires JoinBuilder context.');
                 }
-                return builder.call(_this, payload, params);
-            };
-            var rightSubSelectSql = buildSubSelect(rightSubSelectPayload);
-            // Support function-based expressions like [C6C.ST_DISTANCE_SPHERE, col1, col2]
-            if (typeof column === 'string' &&
-                _this.OPERATORS.has(column) &&
-                Array.isArray(op)) {
-                // Helper to serialize operand which may be a qualified identifier or a nested function array
-                var serializeOperand = function (arg) {
-                    var identifierPathRegex = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
-                    if (Array.isArray(arg)) {
-                        // Delegate to aggregate builder to handle nested functions/params
-                        // @ts-ignore - buildAggregateField is defined upstream in AggregateBuilder
-                        return _this.buildAggregateField(arg, params);
-                    }
-                    if (typeof arg === 'string') {
-                        if (identifierPathRegex.test(arg)) {
-                            _this.assertValidIdentifier(arg, 'WHERE argument');
-                            return arg;
-                        }
-                        return arg;
-                    }
-                    return String(arg);
-                };
-                if (column === C6C.ST_DISTANCE_SPHERE) {
-                    var col1 = op[0], col2 = op[1];
-                    var threshold = Array.isArray(value) ? value[0] : value;
-                    var left = serializeOperand(col1);
-                    var right = serializeOperand(col2);
-                    return "ST_Distance_Sphere(".concat(left, ", ").concat(right, ") < ").concat(_this.addParam(params, '', threshold));
-                }
-                if ([
-                    C6C.ST_CONTAINS,
-                    C6C.ST_INTERSECTS,
-                    C6C.ST_WITHIN,
-                    C6C.ST_CROSSES,
-                    C6C.ST_DISJOINT,
-                    C6C.ST_EQUALS,
-                    C6C.ST_OVERLAPS,
-                    C6C.ST_TOUCHES
-                ].includes(column)) {
-                    var geom1 = op[0], geom2 = op[1];
-                    var left = serializeOperand(geom1);
-                    var right = serializeOperand(geom2);
-                    return "".concat(column, "(").concat(left, ", ").concat(right, ")");
+                return builder.call(this, field[C6C.SUBSELECT], params);
+            }
+            var entries = Object.entries(field);
+            if (entries.length === 1) {
+                var _a = entries[0], key = _a[0], value = _a[1];
+                if (this.isOperator(key)) {
+                    return this.buildOperatorExpression(key, value, params);
                 }
+                return this.buildFunctionCall(key, value, params);
             }
-            var leftIsCol = _this.isColumnRef(column);
-            var leftIsRef = _this.isTableReference(column);
-            var rightIsCol = typeof value === 'string' && _this.isColumnRef(value);
-            if (!leftIsCol && !leftIsRef && !rightIsCol && !rightSubSelectSql) {
-                throw new Error("Potential SQL injection detected: '".concat(column, " ").concat(op, " ").concat(value, "'"));
+        }
+        return field;
+    };
+    ConditionBuilder.prototype.buildFunctionCall = function (fn, value, params) {
+        var args = Array.isArray(value) ? value : [value];
+        var normalized = this.normalizeFunctionField(tslib.__spreadArray([fn], args, true), params);
+        return this.buildAggregateField(normalized, params);
+    };
+    ConditionBuilder.prototype.serializeOperand = function (operand, params, contextColumn) {
+        var _a;
+        var _this = this;
+        var asParam = function (val) { return _this.addParam(params, contextColumn !== null && contextColumn !== void 0 ? contextColumn : '', val); };
+        if (operand === C6C.NULL) {
+            operand = null;
+        }
+        if (operand === null || typeof operand === 'number' || typeof operand === 'boolean') {
+            return { sql: asParam(operand), isReference: false, isExpression: false, isSubSelect: false };
+        }
+        if (typeof operand === 'string') {
+            if (this.isTableReference(operand) || this.isColumnRef(operand)) {
+                return { sql: operand, isReference: true, isExpression: false, isSubSelect: false };
             }
-            _this.validateOperator(op);
-            if (op === C6C.MATCH_AGAINST && Array.isArray(value)) {
-                var search = value[0], mode = value[1];
-                var paramName = _this.useNamedParams ? "param".concat(Object.keys(params).length) : null;
-                if (_this.useNamedParams) {
-                    params[paramName] = search;
-                }
-                else {
-                    params.push(search);
-                }
-                var againstClause = void 0;
-                switch ((mode || '').toUpperCase()) {
-                    case 'BOOLEAN':
-                        againstClause = _this.useNamedParams ? "AGAINST(:".concat(paramName, " IN BOOLEAN MODE)") : "AGAINST(? IN BOOLEAN MODE)";
-                        break;
-                    case 'WITH QUERY EXPANSION':
-                        againstClause = _this.useNamedParams ? "AGAINST(:".concat(paramName, " WITH QUERY EXPANSION)") : "AGAINST(? WITH QUERY EXPANSION)";
-                        break;
-                    default: // NATURAL or undefined
-                        againstClause = _this.useNamedParams ? "AGAINST(:".concat(paramName, ")") : "AGAINST(?)";
-                        break;
-                }
-                if (!leftIsCol) {
-                    throw new Error("MATCH_AGAINST requires a table reference as the left operand. Column '".concat(column, "' is not a valid table reference."));
+            if (this.looksLikeSafeFunctionExpression(operand)) {
+                return { sql: operand.trim(), isReference: false, isExpression: true, isSubSelect: false };
+            }
+            return { sql: asParam(operand), isReference: false, isExpression: false, isSubSelect: false };
+        }
+        if (Array.isArray(operand)) {
+            var normalized = this.normalizeFunctionField(operand, params);
+            var sql = this.buildAggregateField(normalized, params);
+            return { sql: sql, isReference: false, isExpression: true, isSubSelect: false };
+        }
+        if (operand instanceof Map) {
+            operand = Object.fromEntries(operand);
+        }
+        if (typeof operand === 'object' && operand !== null) {
+            if (C6C.SUBSELECT in operand) {
+                var builder = this.buildScalarSubSelect;
+                if (typeof builder !== 'function') {
+                    throw new Error('Scalar subselect handling requires JoinBuilder context.');
                 }
-                var matchClause = "(MATCH(".concat(column, ") ").concat(againstClause, ")");
-                _this.config.verbose && console.log("[MATCH_AGAINST] ".concat(matchClause));
-                return matchClause;
+                var subSql = builder.call(this, operand[C6C.SUBSELECT], params);
+                return { sql: subSql, isReference: false, isExpression: true, isSubSelect: true };
             }
-            if ((op === C6C.IN || op === C6C.NOT_IN) && Array.isArray(value)) {
-                if (rightSubSelectSql) {
-                    if (!leftIsRef) {
-                        throw new Error("IN operator requires a table reference as the left operand. Column '".concat(column, "' is not a valid table reference."));
-                    }
-                    var normalized_1 = op.replace('_', ' ');
-                    return "( ".concat(column, " ").concat(normalized_1, " ").concat(rightSubSelectSql, " )");
+            var entries = Object.entries(operand);
+            if (entries.length === 1) {
+                var _b = entries[0], key = _b[0], value = _b[1];
+                if (this.isOperator(key)) {
+                    var sql_1 = this.buildOperatorExpression(key, value, params);
+                    return { sql: this.ensureWrapped(sql_1), isReference: false, isExpression: true, isSubSelect: false };
                 }
-                var placeholders = value.map(function (v) {
-                    return _this.isColumnRef(v) ? v : _this.addParam(params, column, v);
-                }).join(', ');
-                var normalized = op.replace('_', ' ');
-                if (!leftIsRef) {
-                    throw new Error("IN operator requires a table reference as the left operand. Column '".concat(column, "' is not a valid table reference."));
+                if (this.BOOLEAN_OPERATORS.has(key)) {
+                    var sql_2 = this.buildBooleanExpression((_a = {}, _a[key] = value, _a), params, 'AND');
+                    return { sql: this.ensureWrapped(sql_2), isReference: false, isExpression: true, isSubSelect: false };
                 }
-                return "( ".concat(column, " ").concat(normalized, " (").concat(placeholders, ") )");
+                var sql = this.buildFunctionCall(key, value, params);
+                return { sql: sql, isReference: false, isExpression: true, isSubSelect: false };
             }
-            if (op === C6C.BETWEEN || op === 'NOT BETWEEN') {
-                if (!Array.isArray(value) || value.length !== 2) {
-                    throw new Error("BETWEEN operator requires an array of two values");
+        }
+        throw new Error('Unsupported operand type in SQL expression.');
+    };
+    ConditionBuilder.prototype.buildOperatorExpression = function (op, rawOperands, params, contextColumn) {
+        var _a, _b;
+        var _this = this;
+        var operator = this.formatOperator(op);
+        if (operator === C6C.MATCH_AGAINST) {
+            if (!Array.isArray(rawOperands) || rawOperands.length !== 2) {
+                throw new Error('MATCH_AGAINST requires an array of two operands.');
+            }
+            var left = rawOperands[0], right = rawOperands[1];
+            var leftInfo_1 = this.serializeOperand(left, params, contextColumn);
+            if (!leftInfo_1.isReference) {
+                throw new Error('MATCH_AGAINST requires the left operand to be a table reference.');
+            }
+            if (!Array.isArray(right) || right.length === 0) {
+                throw new Error('MATCH_AGAINST expects an array [search, mode?].');
+            }
+            var search = right[0], mode = right[1];
+            var placeholder = this.addParam(params, leftInfo_1.sql, search);
+            var againstClause = void 0;
+            switch (typeof mode === 'string' ? mode.toUpperCase() : '') {
+                case 'BOOLEAN':
+                    againstClause = "AGAINST(".concat(placeholder, " IN BOOLEAN MODE)");
+                    break;
+                case 'WITH QUERY EXPANSION':
+                    againstClause = "AGAINST(".concat(placeholder, " WITH QUERY EXPANSION)");
+                    break;
+                case 'NATURAL LANGUAGE MODE':
+                    againstClause = "AGAINST(".concat(placeholder, " IN NATURAL LANGUAGE MODE)");
+                    break;
+                default:
+                    againstClause = "AGAINST(".concat(placeholder, ")");
+                    break;
+            }
+            var clause = "(MATCH(".concat(leftInfo_1.sql, ") ").concat(againstClause, ")");
+            this.config.verbose && console.log("[MATCH_AGAINST] ".concat(clause));
+            return clause;
+        }
+        var operands = Array.isArray(rawOperands) ? rawOperands : [rawOperands];
+        if (operator === C6C.IN || operator === 'NOT IN') {
+            if (operands.length < 2) {
+                throw new Error("".concat(operator, " requires two operands."));
+            }
+            var leftRaw = operands[0], rest = operands.slice(1);
+            var left_1 = leftRaw;
+            var right = rest.length <= 1 ? rest[0] : rest;
+            var leftInfo_2 = this.serializeOperand(left_1, params, typeof left_1 === 'string' ? left_1 : contextColumn);
+            if (!leftInfo_2.isReference) {
+                throw new Error("".concat(operator, " requires the left operand to be a table reference."));
+            }
+            if (Array.isArray(right)) {
+                if (right.length === 0) {
+                    throw new Error("".concat(operator, " requires at least one value."));
                 }
-                var start = value[0], end = value[1];
-                if (!leftIsRef) {
-                    throw new Error("BETWEEN operator requires a table reference as the left operand. Column '".concat(column, "' is not a valid table reference."));
+                if (right.length === 2 && right[0] === C6C.SUBSELECT) {
+                    var sub = this.serializeOperand(right, params, typeof left_1 === 'string' ? left_1 : contextColumn);
+                    return "( ".concat(leftInfo_2.sql, " ").concat(operator, " ").concat(sub.sql, " )");
                 }
-                return "(".concat(column, ") ").concat(op.replace('_', ' '), " ").concat(_this.addParam(params, column, start), " AND ").concat(_this.addParam(params, column, end));
+                var placeholders = right.map(function (item) {
+                    if (typeof item === 'string' && _this.isTableReference(item)) {
+                        return item;
+                    }
+                    var sql = _this.serializeOperand(item, params, typeof left_1 === 'string' ? left_1 : contextColumn).sql;
+                    return sql;
+                });
+                return "( ".concat(leftInfo_2.sql, " ").concat(operator, " (").concat(placeholders.join(', '), ") )");
             }
-            var rightIsRef = rightSubSelectSql ? false : _this.isTableReference(value);
-            if (leftIsRef && rightIsRef) {
-                return "(".concat(column, ") ").concat(displayOp, " ").concat(value);
+            var rightInfo_1 = this.serializeOperand(right, params, typeof left_1 === 'string' ? left_1 : contextColumn);
+            if (!rightInfo_1.isSubSelect) {
+                throw new Error("".concat(operator, " requires an array of values or a subselect."));
             }
-            if (leftIsRef && rightSubSelectSql) {
-                return "(".concat(column, ") ").concat(displayOp, " ").concat(rightSubSelectSql);
+            return "( ".concat(leftInfo_2.sql, " ").concat(operator, " ").concat(rightInfo_1.sql, " )");
+        }
+        if (operator === C6C.BETWEEN || operator === 'NOT BETWEEN') {
+            var left = void 0;
+            var start = void 0;
+            var end = void 0;
+            if (operands.length === 3) {
+                left = operands[0], start = operands[1], end = operands[2];
             }
-            if (leftIsRef && !rightIsRef) {
-                return "(".concat(column, ") ").concat(displayOp, " ").concat(_this.addParam(params, column, valueNorm));
+            else if (operands.length === 2 && Array.isArray(operands[1]) && operands[1].length === 2) {
+                _a = operands, left = _a[0], _b = _a[1], start = _b[0], end = _b[1];
             }
-            if (rightIsRef) {
-                return "(".concat(_this.addParam(params, column, column), ") ").concat(displayOp, " ").concat(value);
+            else {
+                throw new Error("".concat(operator, " requires three operands."));
             }
-            throw new Error("Neither operand appears to be a table reference (".concat(column, ") or (").concat(value, ")"));
-        };
-        var parts = [];
-        var buildFromObject = function (obj, mode) {
-            var subParts = [];
-            var entries = Object.entries(obj);
-            var nonNumeric = entries.filter(function (_a) {
-                var k = _a[0];
-                return isNaN(Number(k));
-            });
-            var numeric = entries.filter(function (_a) {
-                var k = _a[0];
-                return !isNaN(Number(k));
-            });
-            var processEntry = function (k, v) {
-                // Operator-as-key handling, e.g., { [C6C.ST_DISTANCE_SPHERE]: [arg1, arg2, threshold] }
-                if (typeof k === 'string' && _this.OPERATORS.has(k) && Array.isArray(v)) {
-                    if (k === C6C.ST_DISTANCE_SPHERE) {
-                        // Accept either [arg1, arg2, threshold] or [[arg1, arg2], threshold]
-                        var args = void 0;
-                        var threshold = void 0;
-                        if (Array.isArray(v[0]) && v.length >= 2) {
-                            args = v[0];
-                            threshold = v[1];
-                        }
-                        else {
-                            args = v.slice(0, 2);
-                            threshold = v[2];
-                        }
-                        subParts.push(addCondition(k, args, threshold));
-                        return;
-                    }
-                }
-                if (typeof v === 'object' && v !== null && Object.keys(v).length === 1) {
-                    var _a = Object.entries(v)[0], op = _a[0], val = _a[1];
-                    subParts.push(addCondition(k, op, val));
+            var leftInfo_3 = this.serializeOperand(left, params, typeof left === 'string' ? left : contextColumn);
+            if (!leftInfo_3.isReference) {
+                throw new Error("".concat(operator, " requires the left operand to be a table reference."));
+            }
+            var startInfo = this.serializeOperand(start, params, typeof left === 'string' ? left : contextColumn);
+            var endInfo = this.serializeOperand(end, params, typeof left === 'string' ? left : contextColumn);
+            var betweenOperator = operator === 'NOT BETWEEN' ? 'NOT BETWEEN' : 'BETWEEN';
+            return "".concat(this.ensureWrapped(leftInfo_3.sql), " ").concat(betweenOperator, " ").concat(startInfo.sql, " AND ").concat(endInfo.sql);
+        }
+        if (operands.length !== 2) {
+            throw new Error("".concat(operator, " requires two operands."));
+        }
+        var leftOperand = operands[0], rightOperand = operands[1];
+        var leftInfo = this.serializeOperand(leftOperand, params, typeof leftOperand === 'string' ? leftOperand : contextColumn);
+        var rightInfo = this.serializeOperand(rightOperand, params, typeof leftOperand === 'string' ? leftOperand : contextColumn);
+        if (!leftInfo.isReference && !leftInfo.isExpression && !rightInfo.isReference && !rightInfo.isExpression) {
+            throw new Error("Potential SQL injection detected: '".concat(operator, "' with non-reference operands."));
+        }
+        var leftSql = leftInfo.isExpression ? leftInfo.sql : this.ensureWrapped(leftInfo.sql);
+        var rightSql = rightInfo.isExpression ? rightInfo.sql : rightInfo.sql;
+        return "".concat(leftSql, " ").concat(operator, " ").concat(rightSql);
+    };
+    ConditionBuilder.prototype.buildLegacyColumnCondition = function (column, value, params) {
+        var _a;
+        var _this = this;
+        if (value instanceof Map) {
+            value = Object.fromEntries(value);
+        }
+        if (Array.isArray(value)) {
+            if (value.length >= 2 && typeof value[0] === 'string') {
+                var op = value[0], rest = value.slice(1);
+                return this.buildOperatorExpression(op, tslib.__spreadArray([column], rest, true), params, column);
+            }
+            if (value.length === 3 && typeof value[0] === 'string' && typeof value[1] === 'string') {
+                return this.buildOperatorExpression(value[1], [value[0], value[2]], params, value[0]);
+            }
+        }
+        if (typeof value === 'object' && value !== null) {
+            var entries = Object.entries(value);
+            if (entries.length === 1) {
+                var _b = entries[0], op = _b[0], operand = _b[1];
+                if (this.isOperator(op)) {
+                    return this.buildOperatorExpression(op, [column, operand], params, column);
                 }
-                else if (Array.isArray(v) && v.length >= 2 && typeof v[0] === 'string') {
-                    var _b = v, op = _b[0], val = _b[1];
-                    subParts.push(addCondition(k, op, val));
+                if (this.BOOLEAN_OPERATORS.has(op)) {
+                    var expression = this.buildBooleanExpression((_a = {}, _a[op] = operand, _a), params, 'AND');
+                    return expression;
                 }
-                else if (typeof v === 'object' && v !== null) {
-                    var sub = _this.buildBooleanJoinedConditions(v, mode, params);
-                    if (sub)
-                        subParts.push(sub);
+            }
+            var subParts = entries.map(function (_a) {
+                var _b;
+                var op = _a[0], operand = _a[1];
+                if (_this.isOperator(op)) {
+                    return _this.buildOperatorExpression(op, [column, operand], params, column);
                 }
-                else {
-                    subParts.push(addCondition(k, '=', v));
+                return _this.buildBooleanExpression((_b = {}, _b[op] = operand, _b), params, 'AND');
+            }).filter(Boolean);
+            return this.joinBooleanParts(subParts, 'AND');
+        }
+        return this.buildOperatorExpression(C6C.EQUAL, [column, value], params, column);
+    };
+    ConditionBuilder.prototype.buildBooleanExpression = function (node, params, defaultOperator) {
+        var _this = this;
+        if (node === null || node === undefined) {
+            return '';
+        }
+        if (Array.isArray(node)) {
+            if (node.length === 0)
+                return '';
+            if (node.length === 3 && typeof node[0] === 'string' && typeof node[1] === 'string') {
+                return this.buildOperatorExpression(node[1], [node[0], node[2]], params, node[0]);
+            }
+            var parts_1 = node
+                .map(function (item) { return _this.buildBooleanExpression(item, params, 'OR'); })
+                .filter(Boolean);
+            return this.joinBooleanParts(parts_1, 'OR');
+        }
+        if (node instanceof Map) {
+            node = Object.fromEntries(node);
+        }
+        if (typeof node !== 'object') {
+            throw new Error('Invalid WHERE clause structure.');
+        }
+        var entries = Object.entries(node);
+        if (entries.length === 0)
+            return '';
+        if (entries.length === 1) {
+            var _a = entries[0], key = _a[0], value = _a[1];
+            if (this.BOOLEAN_OPERATORS.has(key)) {
+                if (!Array.isArray(value)) {
+                    throw new Error("".concat(key, " expects an array of expressions."));
                 }
-            };
-            // Process non-numeric keys first to preserve intuitive insertion order for params
-            for (var _i = 0, nonNumeric_1 = nonNumeric; _i < nonNumeric_1.length; _i++) {
-                var _a = nonNumeric_1[_i], k = _a[0], v = _a[1];
-                processEntry(k, v);
+                var op_1 = this.BOOLEAN_OPERATORS.get(key);
+                var parts_2 = value
+                    .map(function (item) { return _this.buildBooleanExpression(item, params, op_1); })
+                    .filter(Boolean);
+                return this.joinBooleanParts(parts_2, op_1);
             }
-            // Then process numeric keys (treated as grouped OR conditions)
-            for (var _b = 0, numeric_1 = numeric; _b < numeric_1.length; _b++) {
-                var _c = numeric_1[_b]; _c[0]; var v = _c[1];
-                var sub = _this.buildBooleanJoinedConditions(v, false, params);
-                if (sub)
-                    subParts.push(sub);
+            if (this.isOperator(key)) {
+                return this.buildOperatorExpression(key, value, params);
             }
-            return subParts.join(" ".concat(mode ? 'AND' : 'OR', " "));
-        };
-        if (Array.isArray(set)) {
-            // Detect a single condition triple: [column, op, value]
-            if (set.length === 3 && typeof set[0] === 'string' && typeof set[1] === 'string') {
-                var _a = set, column = _a[0], rawOp = _a[1], rawVal = _a[2];
-                var op = rawOp;
-                var value = rawVal === C6C.NULL ? null : rawVal;
-                var sub = addCondition(column, op, value);
-                if (sub)
-                    parts.push(sub);
+            if (!isNaN(Number(key))) {
+                return this.buildBooleanExpression(value, params, 'OR');
             }
-            else {
-                for (var _i = 0, set_1 = set; _i < set_1.length; _i++) {
-                    var item = set_1[_i];
-                    var sub = this.buildBooleanJoinedConditions(item, false, params);
-                    if (sub)
-                        parts.push(sub);
+        }
+        var parts = [];
+        var nonNumeric = entries.filter(function (_a) {
+            var k = _a[0];
+            return isNaN(Number(k));
+        });
+        var numeric = entries.filter(function (_a) {
+            var k = _a[0];
+            return !isNaN(Number(k));
+        });
+        var _loop_1 = function (key, value) {
+            if (this_1.BOOLEAN_OPERATORS.has(key)) {
+                var op_2 = this_1.BOOLEAN_OPERATORS.get(key);
+                if (!Array.isArray(value)) {
+                    throw new Error("".concat(key, " expects an array of expressions."));
+                }
+                var nested = value
+                    .map(function (item) { return _this.buildBooleanExpression(item, params, op_2); })
+                    .filter(Boolean);
+                if (nested.length) {
+                    parts.push(this_1.joinBooleanParts(nested, op_2));
                 }
+                return "continue";
             }
+            if (this_1.isOperator(key)) {
+                parts.push(this_1.buildOperatorExpression(key, value, params));
+                return "continue";
+            }
+            parts.push(this_1.buildLegacyColumnCondition(key, value, params));
+        };
+        var this_1 = this;
+        for (var _i = 0, nonNumeric_1 = nonNumeric; _i < nonNumeric_1.length; _i++) {
+            var _b = nonNumeric_1[_i], key = _b[0], value = _b[1];
+            _loop_1(key, value);
         }
-        else if (typeof set === 'object' && set !== null) {
-            var sub = buildFromObject(set, andMode);
-            if (sub)
-                parts.push(sub);
+        for (var _c = 0, numeric_1 = numeric; _c < numeric_1.length; _c++) {
+            var _d = numeric_1[_c], value = _d[1];
+            var nested = this.buildBooleanExpression(value, params, 'OR');
+            if (nested) {
+                parts.push(nested);
+            }
         }
-        var clause = parts.join(" ".concat(booleanOperator, " "));
-        return clause ? "(".concat(clause, ")") : '';
+        return this.joinBooleanParts(parts, defaultOperator);
+    };
+    ConditionBuilder.prototype.buildBooleanJoinedConditions = function (set, andMode, params) {
+        if (andMode === void 0) { andMode = true; }
+        if (params === void 0) { params = []; }
+        var expression = this.buildBooleanExpression(set, params, andMode ? 'AND' : 'OR');
+        if (!expression)
+            return '';
+        return this.ensureWrapped(expression);
     };
     ConditionBuilder.prototype.buildWhereClause = function (whereArg, params) {
         var clause = this.buildBooleanJoinedConditions(whereArg, true, params);
         if (!clause)
             return '';
-        var trimmed = clause.replace(/^\((.*)\)$/, '$1');
+        var trimmed = clause.trim();
+        var upper = trimmed.toUpperCase();
+        if (!upper.includes(' AND ') && !upper.includes(' OR ')) {
+            if (trimmed.startsWith('(') && trimmed.endsWith(')')) {
+                var inner = trimmed.substring(1, trimmed.length - 1);
+                var innerUpper = inner.toUpperCase();
+                var requiresOuterWrap = innerUpper.includes(' IN ') ||
+                    innerUpper.includes(' BETWEEN ') ||
+                    innerUpper.includes(' SELECT ');
+                if (requiresOuterWrap) {
+                    trimmed = "( ".concat(inner.trim(), " )");
+                }
+                else {
+                    trimmed = inner.trim();
+                }
+            }
+        }
         this.config.verbose && console.log("[WHERE] ".concat(trimmed));
         return " WHERE ".concat(trimmed);
     };
@@ -1824,24 +2047,29 @@ var JoinBuilder = /** @class */ (function (_super) {
     };
     JoinBuilder.prototype.buildJoinClauses = function (joinArgs, params) {
         var sql = '';
-        var _loop_1 = function (joinType) {
-            var joinKind = joinType.replace('_', ' ').toUpperCase();
+        var joinTypeEntries = joinArgs instanceof Map
+            ? Array.from(joinArgs.entries()).map(function (_a) {
+                var key = _a[0], value = _a[1];
+                return [String(key), value];
+            })
+            : Object.keys(joinArgs).map(function (key) { return [key, joinArgs[key]]; });
+        var _loop_1 = function (joinTypeRaw, joinSection) {
+            var joinKind = joinTypeRaw.replace('_', ' ').toUpperCase();
             var entries = [];
-            var joinSection = joinArgs[joinType];
             if (joinSection instanceof Map) {
                 joinSection.forEach(function (value, key) {
                     entries.push([key, value]);
                 });
             }
             else {
-                for (var raw in joinSection) {
+                Object.keys(joinSection).forEach(function (raw) {
                     entries.push([raw, joinSection[raw]]);
-                }
+                });
             }
-            for (var _i = 0, entries_1 = entries; _i < entries_1.length; _i++) {
-                var _a = entries_1[_i], rawKey = _a[0], conditions = _a[1];
+            for (var _b = 0, entries_1 = entries; _b < entries_1.length; _b++) {
+                var _c = entries_1[_b], rawKey = _c[0], conditions = _c[1];
                 var raw = typeof rawKey === 'string' ? rawKey : String(rawKey);
-                var _b = raw.trim().split(/\s+/, 2), table = _b[0], aliasCandidate = _b[1];
+                var _d = raw.trim().split(/\s+/, 2), table = _d[0], aliasCandidate = _d[1];
                 if (!table)
                     continue;
                 if (isDerivedTableKey(table)) {
@@ -1865,7 +2093,7 @@ var JoinBuilder = /** @class */ (function (_super) {
                         throw new Error('Derived table subselects require a base table defined with C6C.FROM.');
                     }
                     var subBuilder = this_1.createSelectBuilder(subRequest);
-                    var _c = subBuilder.build(fromTable, true), subSql = _c.sql, subParams = _c.params;
+                    var _e = subBuilder.build(fromTable, true), subSql = _e.sql, subParams = _e.params;
                     var normalizedSql = this_1.integrateSubSelectParams(subSql, subParams, params);
                     var formatted = normalizedSql.trim().split('\n').map(function (line) { return "  ".concat(line); }).join('\n');
                     var joinSql = "(\n".concat(formatted, "\n) AS `").concat(alias, "`");
@@ -1890,8 +2118,9 @@ var JoinBuilder = /** @class */ (function (_super) {
             }
         };
         var this_1 = this;
-        for (var joinType in joinArgs) {
-            _loop_1(joinType);
+        for (var _i = 0, joinTypeEntries_1 = joinTypeEntries; _i < joinTypeEntries_1.length; _i++) {
+            var _a = joinTypeEntries_1[_i], joinTypeRaw = _a[0], joinSection = _a[1];
+            _loop_1(joinTypeRaw, joinSection);
         }
         this.config.verbose && console.log("[JOIN] ".concat(sql.trim()));
         return sql;