@carbonorm/carbonnode 3.0.12 → 3.0.15

package/src/api/builders/sqlBuilder.ts

@@ -5,7 +5,7 @@ import {iRestMethods} from "../types/ormInterfaces";
 
 interface QueryResult {
     sql: string;
-    params: any[];
+    params: any[] | { [key: string]: any };  // params can be an array or an object for named placeholders
 }
 
 export abstract class SqlBuilder<
@@ -23,201 +23,432 @@ export abstract class SqlBuilder<
     CustomAndRequiredFields,
     RequestTableOverrides
 > {
-    /** Generate nested WHERE/JOIN conditions with parameter binding */
+    /** Flag to determine if named placeholders should be used */
+    protected useNamedParams: boolean = false;
+
+    private convertHexIfBinary(col: string, val: any): any {
+        const columnDef = this.config.C6.TABLES[this.config.restModel.TABLE_NAME].TYPE_VALIDATION?.[col];
+
+        if (
+            typeof val === 'string' &&
+            /^[0-9a-fA-F]{32}$/.test(val) &&
+            typeof columnDef === 'object' &&
+            columnDef.MYSQL_TYPE.toUpperCase().includes('BINARY')
+        ) {
+            return Buffer.from(val, 'hex');
+        }
+        return val;
+    }
+
+
+    /** Generate nested WHERE/ON conditions with parameter binding (supports AND/OR/NOT) */
     protected buildBooleanJoinedConditions(
         set: any,
-        andMode = true,
-        params: any[] = []
+        andMode: boolean = true,
+        params: any[] | { [key: string]: any } = []
     ): string {
         const booleanOperator = andMode ? 'AND' : 'OR';
-        const OPERATORS = ['=', '!=', '<', '<=', '>', '>=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'IS', 'IS NOT'];
+        const OPERATORS = [
+            '=', '!=', '<', '<=', '>', '>=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'IS', 'IS NOT',
+            'BETWEEN', 'NOT BETWEEN', C6Constants.MATCH_AGAINST];
 
-        const isAggregateArray = (value: any) =>
-            Array.isArray(value) && typeof value[0] === 'string' && OPERATORS.includes(value[0]);
         const isNumericKeyed = (obj: any) =>
             Array.isArray(obj) && Object.keys(obj).every(k => /^\d+$/.test(k));
 
+        // Helper to add a single condition with proper parameter binding
         const addCondition = (column: string, op: string, value: any): string => {
             let clause: string;
-            /*if (Buffer.isBuffer(value)) { // TODO - I want this as a parameterized option, for now default to faster
-                params.push(value.toString('hex')); // Or use UNHEX(?) in SQL
-                clause = `(${column} = UNHEX(?))`;
-            } else {*/
-                params.push(value);
-                clause = `( ${column} ${op} ? )`;
-            //}
-            isVerbose() && console.log(`[WHERE] ➕ ${clause} ->`, value);
+            // If using named parameters, generate a unique key; otherwise use positional placeholder
+            const addParam = (val: any): string => {
+                if (Array.isArray(params)) {
+                    // Positional (unnamed) parameter
+                    params.push(this.convertHexIfBinary(column, val));
+                    return '?';
+                } else {
+                    // Named parameter mode
+                    const key = `param${Object.keys(params).length}`;
+                    (params as { [key: string]: any })[key] = this.convertHexIfBinary(column, val);
+                    return `:${key}`;
+                }
+            };
+
+            if ((op === 'IN' || op === 'NOT IN') && Array.isArray(value)) {
+                if (value.length === 0) {
+                    // Edge case: empty IN list - use a condition that's always false
+                    clause = `( ${column} ${op} (NULL) )`;
+                    isVerbose() && console.warn(`[WHERE] Empty list for ${op} on ${column}`);
+                } else {
+                    const placeholders = value.map(val => addParam(val)).join(', ');
+                    clause = `( ${column} ${op} (${placeholders}) )`;
+                }
+            } else if ((op === 'BETWEEN' || op === 'NOT BETWEEN') && Array.isArray(value) && value.length === 2) {
+                // BETWEEN expects exactly two values [min, max]
+                const [minVal, maxVal] = value;
+                const ph1 = addParam(minVal);
+                const ph2 = addParam(maxVal);
+                clause = `( ${column} ${op} ${ph1} AND ${ph2} )`;
+            } else {
+                // Default case for single-value operators (including IS, IS NOT, =, etc.)
+                // Note: If value is null and op is 'IS' or 'IS NOT', the placeholder will safely bind null.
+                const ph = addParam(value);
+                clause = `( ${column} ${op} ${ph} )`;
+            }
+            isVerbose() && console.log(`[WHERE] ➕ ${clause}`);
             return clause;
         };
 
         let sql: string;
         if (isNumericKeyed(set)) {
-            isVerbose() && console.log(`[WHERE] Numeric keyed condition:`, set);
-            switch (set.length) {
-                case 2:
-                    sql = addCondition(set[0], '=', set[1]);
-                    break;
-                case 3:
-                    if (!OPERATORS.includes(set[1])) throw new Error(`Invalid operator: ${set[1]}`);
-                    sql = addCondition(set[0], set[1], set[2]);
-                    break;
-                default:
-                    throw new Error(`Invalid array condition: ${JSON.stringify(set)}`);
+            // Array of conditions, use opposite boolean mode for combining (AND/OR swap)
+            isVerbose() && console.log(`[WHERE] Grouping conditions (array) in ${andMode ? 'AND' : 'OR'} mode:`, set);
+            if (set.length === 0) {
+                sql = '';  // no conditions
+            } else if (set.length === 1) {
+                // Single element array, just build it normally (no boolean operator needed)
+                sql = this.buildBooleanJoinedConditions(set[0], true, params);
+            } else {
+                // Multiple conditions: join them with the opposite of current mode
+                const subClauses = set.map(item => this.buildBooleanJoinedConditions(item, true, params));
+                const op = andMode ? 'OR' : 'AND';
+                sql = subClauses.map(sc => `(${sc})`).join(` ${op} `);
             }
-        } else {
+        } else if (typeof set === 'object') {
             const parts: string[] = [];
             for (const [key, value] of Object.entries(set)) {
                 if (/^\d+$/.test(key)) {
+                    // Numeric object keys (should not happen because numeric arrays handled above)
                     parts.push(this.buildBooleanJoinedConditions(value, !andMode, params));
-                } else if (!Array.isArray(value) || isAggregateArray(value)) {
-                    parts.push(addCondition(key, '=', value));
+                } else if (key.toUpperCase() === 'NOT') {
+                    // NOT operator: negate the inner condition(s)
+                    const negated = this.buildBooleanJoinedConditions(value, true, params);
+                    parts.push(`NOT (${negated})`);
+                    isVerbose() && console.log(`[WHERE] NOT block: (${negated})`);
+                } else if (!Array.isArray(value)) {
+                    if (typeof value === 'object' && value !== null && Object.keys(value).length === 1) {
+                        const [op, val] = Object.entries(value)[0];
+                        if (OPERATORS.includes(op.toUpperCase())) {
+
+                            if (
+                                value !== null &&
+                                C6Constants.MATCH_AGAINST in value &&
+                                Array.isArray(value[C6Constants.MATCH_AGAINST])
+                            ) {
+                                const [search, mode] = value[C6Constants.MATCH_AGAINST];
+                                const paramName = `param${Object.keys(params).length}`;
+                                params[paramName] = search;
+
+                                let againstClause: string;
+
+                                switch (mode?.toUpperCase()) {
+                                    case 'BOOLEAN':
+                                        againstClause = `AGAINST(:${paramName} IN BOOLEAN MODE)`;
+                                        break;
+                                    case 'WITH QUERY EXPANSION':
+                                        againstClause = `AGAINST(:${paramName} WITH QUERY EXPANSION)`;
+                                        break;
+                                    case 'NATURAL':
+                                    case undefined:
+                                    case null:
+                                        againstClause = `AGAINST(:${paramName})`; // default natural language mode
+                                        break;
+                                    default:
+                                        throw new Error(`Unsupported MATCH_AGAINST mode: ${mode}`);
+                                }
+
+                                parts.push(`(MATCH(${key}) ${againstClause})`);
+                                continue;
+                            }
+
+                            parts.push(addCondition(key, op.toUpperCase(), val));
+
+                        } else {
+                            throw new Error(`Unsupported operator '${op}' for key '${key}'`);
+                        }
+                    } else {
+                        // Fallback: treat as simple equality
+                        parts.push(addCondition(key, '=', value));
+                    }
                 } else if (value.length === 2 && OPERATORS.includes(value[0])) {
+                    // Two-element array, first is an operator (like ['>', 5])
                     parts.push(addCondition(key, value[0], value[1]));
+                } else if (value.length === 3 && OPERATORS.includes(value[0])) {
+                    // Three-element array, e.g. ['BETWEEN', min, max]
+                    parts.push(addCondition(key, value[0], value.slice(1)));
                 } else {
                     throw new Error(`Invalid condition for ${key}: ${JSON.stringify(value)}`);
                 }
             }
-            sql = parts.join(` ${booleanOperator} `);
+            sql = parts.length ? parts.join(` ${booleanOperator} `) : '';
+        } else {
+            // Primitive type (should not happen normally), treat it as a boolean expression string
+            sql = String(set);
         }
 
-        isVerbose() && console.log(`[WHERE] Final: (${sql})`);
-        return `(${sql})`;
+        // Wrap the final combined condition in parentheses to maintain correct precedence
+        return sql ? `(${sql})` : '';
     }
 
-    /** Translate array or function calls into SQL expressions */
+    /** Translate array or function call definitions into SQL expressions (supports nested calls) */
     protected buildAggregateField(field: string | any[]): string {
-        if (typeof field === 'string') return field;
-        if (!Array.isArray(field)) throw new Error('Invalid SELECT entry');
+        if (typeof field === 'string') {
+            return field;
+        }
+        if (!Array.isArray(field) || field.length === 0) {
+            throw new Error('Invalid SELECT field entry');
+        }
 
+        // e.g. field = [ 'ROUND', [ 'SQRT', 'age' ], 2, 'AS', 'roundedRootAge' ]
         let [fn, ...args] = field;
         let alias: string | undefined;
-        if (args.length >= 2 && args[args.length - 2] === 'AS') {
-            alias = String(args.pop());
-            args.pop();
+        // Handle alias if present in array (e.g. ... 'AS', 'aliasName')
+        if (args.length >= 2 && String(args[args.length - 2]).toUpperCase() === 'AS') {
+            alias = String(args.pop());  // last element is alias name
+            args.pop();  // remove the 'AS'
         }
+
         const F = String(fn).toUpperCase();
-        const p = args.join(', ');
+        // Map each argument to SQL string, handling nested function arrays recursively
+        const argList = args.map(arg => {
+            if (Array.isArray(arg)) {
+                return this.buildAggregateField(arg);
+            } else {
+                return arg;
+            }
+        }).join(', ');
 
-        isVerbose() && console.log(`[SELECT] ${F}(${p})${alias ? ` AS ${alias}` : ''}`);
+        let expr: string;
         switch (F) {
             case 'DATE_ADD':
-                return `DATE_ADD(${args[0]}, ${args[1]})${alias ? ` AS ${alias}` : ''}`;
             case 'DATE_SUB':
-                return `DATE_SUB(${args[0]}, ${args[1]})${alias ? ` AS ${alias}` : ''}`;
+                // Functions with comma-separated interval, assume args like [ date, interval_expression ]
+                expr = `${F}(${argList})`;
+                break;
             case 'YEAR':
-                return `YEAR(${args[0]})${alias ? ` AS ${alias}` : ''}`;
             case 'MONTH':
-                return `MONTH(${args[0]})${alias ? ` AS ${alias}` : ''}`;
             case 'DAY':
-                return `DAY(${args[0]})${alias ? ` AS ${alias}` : ''}`;
             case 'ROUND':
             case 'CEIL':
             case 'FLOOR':
             case 'ABS':
             case 'SQRT':
-                return `${F}(${p})${alias ? ` AS ${alias}` : ''}`;
+            case 'UPPER':
+            case 'LOWER':
+            case 'COALESCE':
+            case 'CONCAT':
+            case 'IFNULL':
+            case 'IF':
+            case 'COUNT':
+            case 'SUM':
+            case 'MIN':
+            case 'MAX':
+            case 'AVG':
+                // Common SQL functions – just format as F(arg1, arg2, ...)
+                expr = `${F}(${argList})`;
+                break;
             case 'ST_DISTANCE':
-                return `ST_Distance(${p})${alias ? ` AS ${alias}` : ''}`;
+                expr = `ST_Distance(${argList})`;
+                break;
             default:
-                if (/^[A-Z_]+$/.test(F)) return `${F}(${p})${alias ? ` AS ${alias}` : ''}`;
-                throw new Error(`Unsupported function: ${F}`);
+                if (/^[A-Z_]+$/.test(F)) {
+                    // Allow any other SQL function by name (assuming it's a valid function)
+                    expr = `${F}(${argList})`;
+                } else {
+                    throw new Error(`Unsupported function: ${F}`);
+                }
+        }
+        if (alias) {
+            expr += ` AS ${alias}`;
+        }
+        isVerbose() && console.log(`[SELECT] ${expr}`);
+        return expr;
+    }
+
+
+    private buildJoinClauses(
+        joinArgs: any,
+        params: any[] | { [key: string]: any }
+    ): string {
+        let sql = '';
+        for (const joinType in joinArgs) {
+            const jk = joinType.replace('_', ' ').toUpperCase();
+            for (const joinTable in joinArgs[joinType]) {
+                const onConditions = joinArgs[joinType][joinTable];
+                const onClause = this.buildBooleanJoinedConditions(onConditions, true, params);
+                sql += ` ${jk} JOIN \`${joinTable}\` ON ${onClause}`;
+                isVerbose() && console.log(`[JOIN] ${jk} JOIN ${joinTable} ON ${onClause}`);
+            }
+        }
+        return sql;
+    }
+
+    private buildPaginationClause(
+        pagination: any,
+        _params: any[] | { [key: string]: any }
+    ): string {
+        let sql = '';
+        if (pagination?.[C6Constants.ORDER]) {
+            const orderParts = Object.entries(pagination[C6Constants.ORDER])
+                .map(([col, dir]) => `${col} ${String(dir).toUpperCase()}`);
+            sql += ` ORDER BY ${orderParts.join(', ')}`;
+            isVerbose() && console.log(`[ORDER BY] ${orderParts}`);
+        }
+
+        if (pagination?.[C6Constants.LIMIT] != null) {
+            const lim = parseInt(pagination[C6Constants.LIMIT], 10);
+            const page = parseInt(pagination[C6Constants.PAGE] ?? 1, 10);
+            const offset = (page - 1) * lim;
+            sql += ` LIMIT ${offset}, ${lim}`;
+            isVerbose() && console.log(`[LIMIT] ${offset}, ${lim}`);
+        }
+
+        return sql;
+    }
+
+    private buildWhereClause(
+        whereArg: any,
+        params: any[] | { [key: string]: any }
+    ): string {
+        const whereClause = this.buildBooleanJoinedConditions(whereArg, true, params);
+        if (whereClause) {
+            const trimmed = whereClause.replace(/^\((.*)\)$/, '$1');
+            isVerbose() && console.log(`[WHERE] ${trimmed}`);
+            return ` WHERE ${trimmed}`;
         }
+        return '';
     }
 
-    /** Compose a parameterized SELECT query with optional JOIN/WHERE/GROUP/HAVING/PAGINATION */
     protected buildSelectQuery<RestShortTableNames>(
         table: RestShortTableNames,
         primary: string | undefined,
         args: any,
-        isSubSelect = false
+        isSubSelect: boolean = false
     ): QueryResult {
         const model = this.config.C6.TABLES[table as string];
-        const params: any[] = [];
+        const params = this.useNamedParams ? {} : [];
 
-        // SELECT
         const selectList = args?.[C6Constants.SELECT] ?? ['*'];
         const selectFields = Array.isArray(selectList)
             ? selectList.map(f => this.buildAggregateField(f)).join(', ')
-            : '*';
+            : String(selectList);
         let sql = `SELECT ${selectFields} FROM ${table}`;
-        isVerbose() && console.log(`[SELECT]`, selectFields);
 
-        // JOIN
         if (args?.[C6Constants.JOIN]) {
-            for (const jt in args[C6Constants.JOIN]) {
-                const jk = jt.replace('_', ' ').toUpperCase();
-                for (const jn in args[C6Constants.JOIN][jt]) {
-                    const on = this.buildBooleanJoinedConditions(args[C6Constants.JOIN][jt][jn], true, params);
-                    sql += ` ${jk} JOIN \`${jn}\` ON ${on}`;
-                    isVerbose() && console.log(`[JOIN]`, jk, jn, on);
-                }
-            }
+            sql += this.buildJoinClauses(args[C6Constants.JOIN], params);
         }
 
-        // WHERE
         if (args?.[C6Constants.WHERE]) {
-            let wc = this.buildBooleanJoinedConditions(args[C6Constants.WHERE], true, params);
-            // Trim leading and trailing parentheses if they fully wrap the condition
-            while (wc.startsWith('(') && wc.endsWith(')')) {
-                wc = wc.slice(1, -1).trim();
-            }
-            sql += ` WHERE ${wc}`;
+            sql += this.buildWhereClause(args[C6Constants.WHERE], params);
         }
 
-        // GROUP BY
         if (args?.[C6Constants.GROUP_BY]) {
             const gb = Array.isArray(args[C6Constants.GROUP_BY])
                 ? args[C6Constants.GROUP_BY].join(', ')
                 : args[C6Constants.GROUP_BY];
             sql += ` GROUP BY ${gb}`;
-            isVerbose() && console.log(`[GROUP BY]`, gb);
+            isVerbose() && console.log(`[GROUP BY] ${gb}`);
         }
 
-        // HAVING
         if (args?.[C6Constants.HAVING]) {
-            const hc = this.buildBooleanJoinedConditions(args[C6Constants.HAVING], true, params);
-            sql += ` HAVING ${hc}`;
+            const havingClause = this.buildBooleanJoinedConditions(args[C6Constants.HAVING], true, params);
+            if (havingClause) {
+                sql += ` HAVING ${havingClause}`;
+            }
         }
 
-        // PAGINATION
         if (args?.[C6Constants.PAGINATION]) {
-            const p = args[C6Constants.PAGINATION];
-            if (p[C6Constants.ORDER]) {
-                const ord = Object.entries(p[C6Constants.ORDER]).map(([c, d]) => `${c} ${String(d).toUpperCase()}`);
-                sql += ` ORDER BY ${ord.join(', ')}`;
-                isVerbose() && console.log(`[ORDER BY]`, ord);
-            }
-            if (p[C6Constants.LIMIT] != null) {
-                const lim = parseInt(p[C6Constants.LIMIT], 10);
-                const pg = parseInt(p[C6Constants.PAGE] ?? 1, 10);
-                const off = (pg - 1) * lim;
-                sql += ` LIMIT ${off}, ${lim}`;
-                isVerbose() && console.log(`[LIMIT]`, off, lim);
-            }
-        }
-        // Fallback ORDER/LIMIT
-        else if (!isSubSelect) {
-            let ok: string | undefined;
-            if (primary) ok = primary;
-            else if (model?.PRIMARY_SHORT?.[0]) ok = model.PRIMARY_SHORT[0];
-            else for (const ts of ['created_at', 'updated_at']) {
+            sql += this.buildPaginationClause(args[C6Constants.PAGINATION], params);
+        } else if (!isSubSelect) {
+            let orderKey = primary || model?.PRIMARY_SHORT?.[0];
+            if (!orderKey) {
+                for (const ts of ['created_at', 'updated_at']) {
                     if (model?.COLUMNS?.[`${table}.${ts}`]) {
-                        ok = ts;
+                        orderKey = ts;
                         break;
                     }
                 }
-            if (ok) {
+            }
+            if (orderKey) {
                 const dir = primary ? 'ASC' : 'DESC';
-                const lim = primary ? 1 : 100;
-                sql += ` ORDER BY ${ok} ${dir} LIMIT ${lim}`;
-                isVerbose() && console.log(`[ORDER]`, ok, dir, lim);
+                sql += ` ORDER BY ${orderKey} ${dir} LIMIT ${primary ? 1 : 100}`;
+                isVerbose() && console.log(`[DEFAULT ORDER] ${orderKey} ${dir}`);
             } else {
                 sql += ` LIMIT 100`;
-                isVerbose() && console.warn(`[ORDER] fallback LIMIT 100`);
+                isVerbose() && console.warn(`[DEFAULT LIMIT] 100 (no order key found)`);
+            }
+        }
+
+        isVerbose() && console.log(`[SQL SELECT]`, sql, params);
+
+        return { sql, params };
+    }
+
+    protected buildUpdateQuery(
+        table: RestShortTableName,
+        data: Partial<RestTableInterface>,
+        args: any = {}
+    ): QueryResult {
+        const params = this.useNamedParams ? {} : [];
+        let sql = `UPDATE ${table}`;
+
+        if (args[C6Constants.JOIN]) {
+            sql += this.buildJoinClauses(args[C6Constants.JOIN], params);
+        }
+
+        const setClauses: string[] = [];
+        for (const [col, val] of Object.entries(data)) {
+            if (Array.isArray(val)) {
+                const expr = this.buildAggregateField(val);
+                setClauses.push(`\`${col}\` = ${expr}`);
+            } else {
+                const key = `param${Array.isArray(params) ? params.length : Object.keys(params).length}`;
+                if (Array.isArray(params)) {
+                    params.push(val);
+                    setClauses.push(`\`${col}\` = ?`);
+                } else {
+                    params[key] = val;
+                    setClauses.push(`\`${col}\` = :${key}`);
+                }
             }
         }
+        sql += ` SET ${setClauses.join(', ')}`;
+        isVerbose() && console.log(`[SET] ${setClauses}`);
 
-        isVerbose() && console.log(`[SQL]`, sql, params);
-        return {sql, params};
+        if (args[C6Constants.WHERE]) {
+            sql += this.buildWhereClause(args[C6Constants.WHERE], params);
+        }
+
+        if (args[C6Constants.PAGINATION]) {
+            sql += this.buildPaginationClause(args[C6Constants.PAGINATION], params);
+        }
+
+        isVerbose() && console.log(`[SQL UPDATE]`, sql, params);
+        return { sql, params };
     }
+
+    /** Compose a DELETE query with optional JOIN and WHERE clauses */
+    protected buildDeleteQuery(
+        table: RestShortTableName,
+        args: any = {}
+    ): QueryResult {
+        const params = this.useNamedParams ? {} : [];
+        let sql = args[C6Constants.JOIN]
+            ? `DELETE ${table} FROM ${table}`
+            : `DELETE FROM ${table}`;
+
+        if (args[C6Constants.JOIN]) {
+            sql += this.buildJoinClauses(args[C6Constants.JOIN], params);
+        }
+
+        if (args[C6Constants.WHERE]) {
+            sql += this.buildWhereClause(args[C6Constants.WHERE], params);
+        }
+
+        if (args[C6Constants.PAGINATION]) {
+            sql += this.buildPaginationClause(args[C6Constants.PAGINATION], params);
+        }
+
+        isVerbose() && console.log(`[SQL DELETE]`, sql, params);
+        return { sql, params };
+    }
+
 }