@carbonorm/carbonnode 3.9.6 → 3.11.0

package/dist/index.esm.js

@@ -35,10 +35,12 @@ var C6Constants = {
     DATE_FORMAT: 'DATE_FORMAT',
     DESC: 'DESC',
     DISTINCT: 'DISTINCT',
+    EXISTS: 'EXISTS',
     EXTRACT: 'EXTRACT',
     EQUAL: '=',
     EQUAL_NULL_SAFE: '<=>',
     FALSE: 'FALSE',
+    FORCE: 'FORCE',
     FULL_OUTER: 'FULL_OUTER',
     FROM_DAYS: 'FROM_DAYS',
     FROM_UNIXTIME: 'FROM_UNIXTIME',
@@ -54,6 +56,7 @@ var C6Constants = {
     HOUR_SECOND: 'HOUR_SECOND',
     HOUR_MINUTE: 'HOUR_MINUTE',
     IN: 'IN',
+    INDEX: 'INDEX',
     IS: 'IS',
     IS_NOT: 'IS_NOT',
     INNER: 'INNER',
@@ -71,6 +74,7 @@ var C6Constants = {
     MAKEDATE: 'MAKEDATE',
     MAKETIME: 'MAKETIME',
     MATCH_AGAINST: 'MATCH_AGAINST',
+    MBRCONTAINS: 'MBRContains',
     MONTHNAME: 'MONTHNAME',
     MICROSECOND: 'MICROSECOND',
     MINUTE: 'MINUTE',
@@ -86,8 +90,14 @@ var C6Constants = {
     NULL: 'NULL',
     ORDER: 'ORDER',
     OR: 'OR',
+    INDEX_HINTS: 'INDEX_HINTS',
+    FORCE_INDEX: 'FORCE INDEX',
+    USE_INDEX: 'USE INDEX',
+    IGNORE_INDEX: 'IGNORE INDEX',
     PAGE: 'PAGE',
     PAGINATION: 'PAGINATION',
+    POLYGON: 'POLYGON',
+    POINT: 'POINT',
     RIGHT_OUTER: 'RIGHT_OUTER',
     SECOND: 'SECOND',
     SECOND_MICROSECOND: 'SECOND_MICROSECOND',
@@ -1448,7 +1458,8 @@ var stContains = function (envelope, shape) {
 var ConditionBuilder = /** @class */ (function (_super) {
     __extends(ConditionBuilder, _super);
     function ConditionBuilder() {
-        var _this = _super !== null && _super.apply(this, arguments) || this;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+        var _this = _super.apply(this, arguments) || this;
         _this.aliasMap = {};
         _this.derivedAliases = new Set();
         _this.BOOLEAN_OPERATORS = new Map([
@@ -1487,8 +1498,16 @@ var ConditionBuilder = /** @class */ (function (_super) {
             [C6C.BETWEEN, C6C.BETWEEN],
             ['BETWEEN', C6C.BETWEEN],
             ['NOT BETWEEN', 'NOT BETWEEN'],
+            [C6C.EXISTS, C6C.EXISTS],
+            ['EXISTS', C6C.EXISTS],
+            ['NOT EXISTS', 'NOT EXISTS'],
             [C6C.MATCH_AGAINST, C6C.MATCH_AGAINST],
         ]);
+        _this.BOOLEAN_FUNCTION_KEYS = new Set([
+            (_c = (_b = (_a = C6C.ST_CONTAINS) === null || _a === void 0 ? void 0 : _a.toUpperCase) === null || _b === void 0 ? void 0 : _b.call(_a)) !== null && _c !== void 0 ? _c : 'ST_CONTAINS',
+            (_f = (_e = (_d = C6C.ST_WITHIN) === null || _d === void 0 ? void 0 : _d.toUpperCase) === null || _e === void 0 ? void 0 : _e.call(_d)) !== null && _f !== void 0 ? _f : 'ST_WITHIN',
+            (_j = (_h = (_g = C6C.MBRCONTAINS) === null || _g === void 0 ? void 0 : _g.toUpperCase) === null || _h === void 0 ? void 0 : _h.call(_g)) !== null && _j !== void 0 ? _j : 'MBRCONTAINS',
+        ]);
         return _this;
     }
     ConditionBuilder.prototype.initAlias = function (baseTable, joins) {
@@ -1723,6 +1742,9 @@ var ConditionBuilder = /** @class */ (function (_super) {
         if (operand === null || typeof operand === 'number' || typeof operand === 'boolean') {
             return { sql: asParam(operand), isReference: false, isExpression: false, isSubSelect: false };
         }
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(operand)) {
+            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 };
@@ -1766,10 +1788,129 @@ var ConditionBuilder = /** @class */ (function (_super) {
         }
         throw new Error('Unsupported operand type in SQL expression.');
     };
+    ConditionBuilder.prototype.ensurePlainObject = function (value) {
+        if (value instanceof Map) {
+            return Object.fromEntries(value);
+        }
+        return value;
+    };
+    ConditionBuilder.prototype.resolveExistsInnerColumn = function (subRequest, provided) {
+        var _a, _b;
+        if (provided) {
+            if (typeof provided !== 'string' || provided.trim() === '') {
+                throw new Error('EXISTS correlation column must be a non-empty string.');
+            }
+            return provided;
+        }
+        var selectClause = this.ensurePlainObject(subRequest === null || subRequest === void 0 ? void 0 : subRequest[C6C.SELECT]);
+        if (Array.isArray(selectClause) && selectClause.length > 0) {
+            var candidate = selectClause[0];
+            if (typeof candidate === 'string' && candidate.trim() !== '') {
+                return candidate;
+            }
+        }
+        var fromTable = subRequest === null || subRequest === void 0 ? void 0 : subRequest[C6C.FROM];
+        if (typeof fromTable === 'string' && fromTable.trim() !== '') {
+            var table = (_b = (_a = this.config.C6) === null || _a === void 0 ? void 0 : _a.TABLES) === null || _b === void 0 ? void 0 : _b[fromTable.trim()];
+            var primary = table === null || table === void 0 ? void 0 : table.PRIMARY;
+            if (Array.isArray(primary) && primary.length > 0) {
+                return String(primary[0]);
+            }
+        }
+        throw new Error('EXISTS requires a correlation column to be provided or inferable from the subselect.');
+    };
+    ConditionBuilder.prototype.normalizeExistsSpec = function (spec) {
+        var normalized = this.ensurePlainObject(spec);
+        if (!Array.isArray(normalized) || normalized.length < 2) {
+            throw new Error('EXISTS expects an array like [outerColumn, subselect, innerColumn?].');
+        }
+        var outerRaw = normalized[0], payloadRaw = normalized[1], innerRaw = normalized[2];
+        if (typeof outerRaw !== 'string' || outerRaw.trim() === '') {
+            throw new Error('EXISTS requires the first element to be an outer column reference string.');
+        }
+        var payload = this.ensurePlainObject(payloadRaw);
+        var subSelect;
+        if (payload && typeof payload === 'object' && C6C.SUBSELECT in payload) {
+            subSelect = this.ensurePlainObject(payload[C6C.SUBSELECT]);
+        }
+        else if (payload && typeof payload === 'object') {
+            subSelect = payload;
+        }
+        else {
+            throw new Error('EXISTS requires a subselect payload as the second element.');
+        }
+        if (!subSelect || typeof subSelect !== 'object') {
+            throw new Error('EXISTS subselect payload must be an object.');
+        }
+        var innerColumn = typeof innerRaw === 'string' ? innerRaw : undefined;
+        return {
+            outerColumn: outerRaw,
+            subRequest: __assign({}, subSelect),
+            innerColumn: innerColumn,
+        };
+    };
+    ConditionBuilder.prototype.buildExistsExpression = function (spec, operator, params) {
+        var _a, _b, _c, _d;
+        var _this = this;
+        var _e;
+        var _f = this.normalizeExistsSpec(spec), outerColumn = _f.outerColumn, subRequest = _f.subRequest, innerColumn = _f.innerColumn;
+        var fromTableRaw = subRequest[C6C.FROM];
+        if (typeof fromTableRaw !== 'string' || fromTableRaw.trim() === '') {
+            throw new Error('EXISTS subselect requires a table specified with C6C.FROM.');
+        }
+        var fromTable = fromTableRaw.trim();
+        this.assertValidIdentifier(outerColumn, 'EXISTS correlation column');
+        var correlationColumn = this.resolveExistsInnerColumn(subRequest, innerColumn);
+        if (!this.isColumnRef(correlationColumn) && !this.isTableReference(correlationColumn)) {
+            throw new Error("Unknown column reference '".concat(correlationColumn, "' used in EXISTS subquery correlation column."));
+        }
+        var existingWhereRaw = this.ensurePlainObject(subRequest[C6C.WHERE]);
+        var correlationCondition = (_a = {}, _a[correlationColumn] = [C6C.EQUAL, outerColumn], _a);
+        var normalizedExistingWhere = existingWhereRaw && typeof existingWhereRaw === 'object'
+            ? Array.isArray(existingWhereRaw)
+                ? existingWhereRaw.slice()
+                : __assign({}, existingWhereRaw)
+            : existingWhereRaw;
+        var hasExistingWhere = Array.isArray(normalizedExistingWhere)
+            ? normalizedExistingWhere.length > 0
+            : normalizedExistingWhere && typeof normalizedExistingWhere === 'object'
+                ? Object.keys(normalizedExistingWhere).length > 0
+                : normalizedExistingWhere != null;
+        var whereClause;
+        if (!hasExistingWhere) {
+            whereClause = correlationCondition;
+        }
+        else if (normalizedExistingWhere && typeof normalizedExistingWhere === 'object' &&
+            Object.keys(normalizedExistingWhere).some(function (key) { return _this.BOOLEAN_OPERATORS.has(key); })) {
+            whereClause = (_b = {}, _b[C6C.AND] = [normalizedExistingWhere, correlationCondition], _b);
+        }
+        else if (normalizedExistingWhere && typeof normalizedExistingWhere === 'object') {
+            whereClause = __assign(__assign({}, normalizedExistingWhere), correlationCondition);
+        }
+        else {
+            whereClause = (_c = {}, _c[C6C.AND] = [normalizedExistingWhere, correlationCondition], _c);
+        }
+        var subRequestWithCorrelation = __assign(__assign({}, subRequest), (_d = {}, _d[C6C.FROM] = fromTable, _d[C6C.WHERE] = whereClause, _d[C6C.SELECT] = (_e = subRequest[C6C.SELECT]) !== null && _e !== void 0 ? _e : ['1'], _d));
+        var buildScalarSubSelect = this.buildScalarSubSelect;
+        if (typeof buildScalarSubSelect !== 'function') {
+            throw new Error('EXISTS operator requires SelectQueryBuilder context.');
+        }
+        var scalar = buildScalarSubSelect.call(this, subRequestWithCorrelation, params);
+        var keyword = operator === 'NOT EXISTS' ? 'NOT EXISTS' : C6C.EXISTS;
+        return "".concat(keyword, " ").concat(scalar);
+    };
     ConditionBuilder.prototype.buildOperatorExpression = function (op, rawOperands, params, contextColumn) {
         var _a, _b;
         var _this = this;
         var operator = this.formatOperator(op);
+        if (operator === C6C.EXISTS || operator === 'NOT EXISTS') {
+            var operands_1 = Array.isArray(rawOperands) ? rawOperands : [rawOperands];
+            if (!operands_1.length) {
+                throw new Error("".concat(operator, " requires at least one subselect specification."));
+            }
+            var clauses = operands_1.map(function (spec) { return _this.buildExistsExpression(spec, operator, params); });
+            return this.joinBooleanParts(clauses, 'AND');
+        }
         if (operator === C6C.MATCH_AGAINST) {
             if (!Array.isArray(rawOperands) || rawOperands.length !== 2) {
                 throw new Error('MATCH_AGAINST requires an array of two operands.');
@@ -1879,6 +2020,18 @@ var ConditionBuilder = /** @class */ (function (_super) {
         if (value instanceof Map) {
             value = Object.fromEntries(value);
         }
+        if (typeof column === 'string') {
+            var normalizedColumn = column.trim().toUpperCase();
+            if (this.BOOLEAN_FUNCTION_KEYS.has(normalizedColumn)) {
+                if (!Array.isArray(value)) {
+                    throw new Error("".concat(column, " expects an array of arguments."));
+                }
+                return this.buildFunctionCall(column, value, params);
+            }
+        }
+        if (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(value)) {
+            return this.buildOperatorExpression(C6C.EQUAL, [column, value], params, column);
+        }
         if (Array.isArray(value)) {
             if (value.length >= 2 && typeof value[0] === 'string') {
                 var op = value[0], rest = value.slice(1);
@@ -1920,8 +2073,17 @@ var ConditionBuilder = /** @class */ (function (_super) {
         if (Array.isArray(node)) {
             if (node.length === 0)
                 return '';
+            // Support both [left, operator, right] and [operator, left, right]
             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 opAsSecond = this.isOperator(node[1]);
+                var opAsFirst = this.isOperator(node[0]);
+                if (opAsSecond) {
+                    return this.buildOperatorExpression(node[1], [node[0], node[2]], params, node[0]);
+                }
+                if (opAsFirst) {
+                    return this.buildOperatorExpression(node[0], [node[1], node[2]], params, node[1]);
+                }
+                // fall-through to treat as grouped expressions
             }
             var parts_1 = node
                 .map(function (item) { return _this.buildBooleanExpression(item, params, 'OR'); })
@@ -2042,6 +2204,143 @@ var JoinBuilder = /** @class */ (function (_super) {
     JoinBuilder.prototype.createSelectBuilder = function (_request) {
         throw new Error('Subclasses must implement createSelectBuilder to support derived table serialization.');
     };
+    JoinBuilder.prototype.resetIndexHints = function () {
+        this.indexHintCache = undefined;
+    };
+    JoinBuilder.prototype.normalizeIndexHintKey = function (key) {
+        return key
+            .replace(/`/g, '')
+            .replace(/_/g, ' ')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .toUpperCase();
+    };
+    JoinBuilder.prototype.normalizeHintTargetKey = function (target) {
+        return target.replace(/`/g, '').trim();
+    };
+    JoinBuilder.prototype.hasIndexHintKeys = function (obj) {
+        var _this = this;
+        var keys = Object.keys(obj !== null && obj !== void 0 ? obj : {});
+        if (!keys.length)
+            return false;
+        var forceKey = this.normalizeIndexHintKey(C6C.FORCE_INDEX);
+        var useKey = this.normalizeIndexHintKey(C6C.USE_INDEX);
+        var ignoreKey = this.normalizeIndexHintKey(C6C.IGNORE_INDEX);
+        return keys.some(function (key) {
+            var normalized = _this.normalizeIndexHintKey(key);
+            return normalized === forceKey || normalized === useKey || normalized === ignoreKey;
+        });
+    };
+    JoinBuilder.prototype.normalizeHintSpec = function (spec) {
+        var _a;
+        if (spec instanceof Map) {
+            spec = Object.fromEntries(spec);
+        }
+        if (Array.isArray(spec) || typeof spec === 'string') {
+            return _a = {}, _a[C6C.FORCE_INDEX] = spec, _a;
+        }
+        if (!spec || typeof spec !== 'object') {
+            return undefined;
+        }
+        if (!this.hasIndexHintKeys(spec)) {
+            return undefined;
+        }
+        return spec;
+    };
+    JoinBuilder.prototype.formatIndexHintClause = function (spec) {
+        var normalizedSpec = this.normalizeHintSpec(spec);
+        if (!normalizedSpec)
+            return '';
+        var clauses = [];
+        var forceKey = this.normalizeIndexHintKey(C6C.FORCE_INDEX);
+        var useKey = this.normalizeIndexHintKey(C6C.USE_INDEX);
+        var ignoreKey = this.normalizeIndexHintKey(C6C.IGNORE_INDEX);
+        var pushClause = function (keyword, rawValue) {
+            var values = Array.isArray(rawValue) ? rawValue : [rawValue];
+            var indexes = values
+                .map(function (value) { return String(value !== null && value !== void 0 ? value : '').trim(); })
+                .filter(Boolean)
+                .map(function (value) { return "`".concat(value.replace(/`/g, '``'), "`"); });
+            if (!indexes.length)
+                return;
+            clauses.push("".concat(keyword, " (").concat(indexes.join(', '), ")"));
+        };
+        for (var _i = 0, _a = Object.entries(normalizedSpec); _i < _a.length; _i++) {
+            var _b = _a[_i], key = _b[0], rawValue = _b[1];
+            var normalizedKey = this.normalizeIndexHintKey(key);
+            if (normalizedKey === forceKey) {
+                pushClause('FORCE INDEX', rawValue);
+            }
+            else if (normalizedKey === useKey) {
+                pushClause('USE INDEX', rawValue);
+            }
+            else if (normalizedKey === ignoreKey) {
+                pushClause('IGNORE INDEX', rawValue);
+            }
+        }
+        return clauses.join(' ');
+    };
+    JoinBuilder.prototype.normalizeIndexHints = function (raw) {
+        var _this = this;
+        if (raw instanceof Map) {
+            raw = Object.fromEntries(raw);
+        }
+        var cache = new Map();
+        var addEntry = function (target, spec) {
+            var clause = _this.formatIndexHintClause(spec);
+            if (!clause)
+                return;
+            var normalizedTarget = target === '__base__'
+                ? '__base__'
+                : _this.normalizeHintTargetKey(target);
+            cache.set(normalizedTarget, clause);
+        };
+        if (Array.isArray(raw) || typeof raw === 'string') {
+            addEntry('__base__', raw);
+        }
+        else if (raw && typeof raw === 'object') {
+            if (this.hasIndexHintKeys(raw)) {
+                addEntry('__base__', raw);
+            }
+            else {
+                for (var _i = 0, _a = Object.entries(raw); _i < _a.length; _i++) {
+                    var _b = _a[_i], key = _b[0], value = _b[1];
+                    var normalizedKey = this.normalizeHintTargetKey(key);
+                    if (!normalizedKey)
+                        continue;
+                    addEntry(normalizedKey, value);
+                }
+            }
+        }
+        return cache.size ? cache : undefined;
+    };
+    JoinBuilder.prototype.getIndexHintClause = function (table, alias) {
+        var _a;
+        if (!this.indexHintCache) {
+            var rawHints = (_a = this.request) === null || _a === void 0 ? void 0 : _a[C6C.INDEX_HINTS];
+            this.indexHintCache = this.normalizeIndexHints(rawHints);
+        }
+        var hints = this.indexHintCache;
+        if (!hints || hints.size === 0)
+            return '';
+        var normalizedTable = this.normalizeHintTargetKey(table);
+        var normalizedAlias = alias ? this.normalizeHintTargetKey(alias) : undefined;
+        var candidates = [
+            normalizedAlias,
+            normalizedAlias ? "".concat(normalizedTable, " ").concat(normalizedAlias) : undefined,
+            normalizedTable,
+            '__base__',
+        ];
+        for (var _i = 0, candidates_1 = candidates; _i < candidates_1.length; _i++) {
+            var candidate = candidates_1[_i];
+            if (!candidate)
+                continue;
+            var clause = hints.get(candidate);
+            if (clause)
+                return clause;
+        }
+        return '';
+    };
     JoinBuilder.prototype.buildJoinClauses = function (joinArgs, params) {
         var sql = '';
         var joinTypeEntries = joinArgs instanceof Map
@@ -2105,7 +2404,9 @@ var JoinBuilder = /** @class */ (function (_super) {
                     if (alias) {
                         this_1.registerAlias(alias, table);
                     }
-                    var joinSql = alias ? "`".concat(table, "` AS `").concat(alias, "`") : "`".concat(table, "`");
+                    var hintClause = this_1.getIndexHintClause(table, alias);
+                    var baseJoinSql = alias ? "`".concat(table, "` AS `").concat(alias, "`") : "`".concat(table, "`");
+                    var joinSql = hintClause ? "".concat(baseJoinSql, " ").concat(hintClause) : baseJoinSql;
                     var onClause = this_1.buildBooleanJoinedConditions(conditions, true, params);
                     sql += " ".concat(joinKind, " JOIN ").concat(joinSql);
                     if (onClause) {
@@ -2259,6 +2560,7 @@ var SelectQueryBuilder = /** @class */ (function (_super) {
         // @ts-ignore
         if (this.selectAliases && this.selectAliases.clear)
             this.selectAliases.clear();
+        this.resetIndexHints();
         var args = this.request;
         this.initAlias(table, args.JOIN);
         var params = this.useNamedParams ? {} : [];
@@ -2267,6 +2569,10 @@ var SelectQueryBuilder = /** @class */ (function (_super) {
             .map(function (f) { return _this.buildAggregateField(f, params); })
             .join(', ');
         var sql = "SELECT ".concat(selectFields, " FROM `").concat(table, "`");
+        var baseIndexHint = this.getIndexHintClause(table);
+        if (baseIndexHint) {
+            sql += " ".concat(baseIndexHint);
+        }
         if (args.JOIN) {
             sql += this.buildJoinClauses(args.JOIN, params);
         }