@carbonorm/carbonnode 6.0.20 → 6.1.0

package/src/orm/builders/ConditionBuilder.ts

@@ -65,6 +65,29 @@ export abstract class ConditionBuilder<
         return false;
     }
 
+    protected override isReferenceExpression(value: string): boolean {
+        const trimmed = value.trim();
+        if (trimmed === '*') {
+            return true;
+        }
+
+        if (trimmed.includes('.')) {
+            if (/^[A-Za-z_][A-Za-z0-9_]*\.\*$/.test(trimmed)) {
+                return true;
+            }
+            if (this.isTableReference(trimmed) || this.isColumnRef(trimmed)) {
+                return true;
+            }
+            if (/^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed)) {
+                this.assertValidIdentifier(trimmed, 'SQL reference');
+                return true;
+            }
+            return false;
+        }
+
+        return super.isReferenceExpression(trimmed);
+    }
+
     abstract build(table: string): SqlBuilderResult;
 
     execute(): Promise<DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>> {
@@ -200,45 +223,6 @@ export abstract class ConditionBuilder<
         return !!this.normalizeOperatorKey(op);
     }
 
-    private looksLikeSafeFunctionExpression(value: string): boolean {
-        if (typeof value !== 'string') return false;
-
-        const 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;
-        }
-
-        const functionMatch = trimmed.match(/^([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\s*\(/);
-        if (!functionMatch) {
-            return false;
-        }
-
-        const allowedCharacters = /^[A-Za-z0-9_().,'"\s-]+$/;
-        if (!allowedCharacters.test(trimmed)) {
-            return false;
-        }
-
-        let depth = 0;
-        for (const char of trimmed) {
-            if (char === '(') {
-                depth += 1;
-            } else if (char === ')') {
-                depth -= 1;
-                if (depth < 0) {
-                    return false;
-                }
-            }
-        }
-
-        return depth === 0;
-    }
-
     private ensureWrapped(expression: string): string {
         const trimmed = expression.trim();
         if (!trimmed) return trimmed;
@@ -268,46 +252,6 @@ export abstract class ConditionBuilder<
             .join(` ${operator} `);
     }
 
-    private normalizeFunctionField(field: any, params: any[] | Record<string, any>): any {
-        if (field instanceof Map) {
-            field = Object.fromEntries(field);
-        }
-
-        if (Array.isArray(field)) {
-            if (field.length === 0) return field;
-            const [fn, ...args] = field;
-            const normalizedArgs = args.map(arg => this.normalizeFunctionField(arg, params));
-            return [fn, ...normalizedArgs];
-        }
-
-        if (field && typeof field === 'object') {
-            if (C6C.SUBSELECT in field) {
-                const builder = (this as any).buildScalarSubSelect;
-                if (typeof builder !== 'function') {
-                    throw new Error('Scalar subselect handling requires JoinBuilder context.');
-                }
-                return builder.call(this, field[C6C.SUBSELECT], params);
-            }
-
-            const entries = Object.entries(field);
-            if (entries.length === 1) {
-                const [key, value] = entries[0];
-                if (this.isOperator(key)) {
-                    return this.buildOperatorExpression(key, value, params);
-                }
-                return this.buildFunctionCall(key, value, params);
-            }
-        }
-
-        return field;
-    }
-
-    private buildFunctionCall(fn: string, value: any, params: any[] | Record<string, any>): string {
-        const args = Array.isArray(value) ? value : [value];
-        const normalized = this.normalizeFunctionField([fn, ...args], params);
-        return this.buildAggregateField(normalized, params);
-    }
-
     private serializeOperand(
         operand: any,
         params: any[] | Record<string, any>,
@@ -328,19 +272,15 @@ export abstract class ConditionBuilder<
         }
 
         if (typeof operand === 'string') {
-            if (this.isTableReference(operand) || this.isColumnRef(operand)) {
-                return { sql: operand, isReference: true, isExpression: false, isSubSelect: false };
-            }
-            if (this.looksLikeSafeFunctionExpression(operand)) {
-                return { sql: operand.trim(), isReference: false, isExpression: true, isSubSelect: false };
+            const trimmed = operand.trim();
+            if (this.isReferenceExpression(trimmed) || this.isTableReference(trimmed) || this.isColumnRef(trimmed)) {
+                return { sql: trimmed, isReference: true, isExpression: false, isSubSelect: false };
             }
-            return { sql: asParam(operand), isReference: false, isExpression: false, isSubSelect: false };
+            throw new Error(`Bare string '${operand}' is not a reference. Wrap literal strings with [C6C.LIT, value].`);
         }
 
         if (Array.isArray(operand)) {
-            const normalized = this.normalizeFunctionField(operand, params);
-            const sql = this.buildAggregateField(normalized, params);
-            return { sql, isReference: false, isExpression: true, isSubSelect: false };
+            return this.serializeExpression(operand, params, 'SQL expression', contextColumn);
         }
 
         if (operand instanceof Map) {
@@ -371,16 +311,33 @@ export abstract class ConditionBuilder<
                     return { sql: this.ensureWrapped(sql), isReference: false, isExpression: true, isSubSelect: false };
                 }
 
-                const sql = this.buildFunctionCall(key, value, params);
-                return { sql, isReference: false, isExpression: true, isSubSelect: false };
+                throw new Error('Object-rooted expressions are not supported. Use tuple syntax instead.');
             }
         }
 
         throw new Error('Unsupported operand type in SQL expression.');
     }
 
+    private isExpressionTuple(value: any): boolean {
+        if (!Array.isArray(value) || value.length === 0 || typeof value[0] !== 'string') {
+            return false;
+        }
+
+        const token = String(value[0]).toUpperCase();
+        return (
+            token === C6C.AS
+            || token === C6C.DISTINCT
+            || token === C6C.CALL
+            || token === C6C.LIT
+            || token === C6C.PARAM
+            || token === C6C.SUBSELECT
+            || this.isKnownFunction(value[0])
+        );
+    }
+
     private isPlainArrayLiteral(value: any, allowColumnRefs = false): boolean {
         if (!Array.isArray(value)) return false;
+        if (this.isExpressionTuple(value)) return false;
         return value.every(item => {
             if (item === null) return true;
             const type = typeof item;
@@ -444,6 +401,19 @@ export abstract class ConditionBuilder<
             return this.addParam(params, contextColumn ?? '', JSON.stringify(normalized));
         }
 
+        if (
+            normalized === C6C.NULL
+            || normalized === null
+            || typeof normalized === 'string'
+            || typeof normalized === 'number'
+            || typeof normalized === 'boolean'
+            || normalized instanceof Date
+            || (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(normalized))
+        ) {
+            const scalar = normalized === C6C.NULL ? null : normalized;
+            return this.addParam(params, contextColumn ?? '', scalar);
+        }
+
         let sql: string;
         let isReference: boolean;
         let isExpression: boolean;
@@ -546,7 +516,9 @@ export abstract class ConditionBuilder<
 
         const payload = this.ensurePlainObject(payloadRaw);
         let subSelect: any;
-        if (payload && typeof payload === 'object' && C6C.SUBSELECT in payload) {
+        if (Array.isArray(payload) && payload.length === 2 && String(payload[0]).toUpperCase() === C6C.SUBSELECT) {
+            subSelect = this.ensurePlainObject(payload[1]);
+        } else if (payload && typeof payload === 'object' && C6C.SUBSELECT in payload) {
             subSelect = this.ensurePlainObject(payload[C6C.SUBSELECT]);
         } else if (payload && typeof payload === 'object') {
             subSelect = payload;
@@ -664,7 +636,11 @@ export abstract class ConditionBuilder<
             }
 
             const [search, mode] = right;
-            const placeholder = this.addParam(params, leftInfo.sql, search);
+            const searchInfo = this.serializeOperand(search, params, leftInfo.sql);
+            if (searchInfo.isReference || searchInfo.isExpression || searchInfo.isSubSelect) {
+                throw new Error('MATCH_AGAINST search payload must be a literal value (wrap strings with [C6C.LIT, value]).');
+            }
+            const placeholder = searchInfo.sql;
             let againstClause: string;
             switch (typeof mode === 'string' ? mode.toUpperCase() : '') {
                 case 'BOOLEAN':
@@ -784,7 +760,7 @@ export abstract class ConditionBuilder<
                 if (!Array.isArray(value)) {
                     throw new Error(`${column} expects an array of arguments.`);
                 }
-                return this.buildFunctionCall(column, value, params);
+                return this.serializeExpression([column, ...value], params, `WHERE function ${column}`, column).sql;
             }
         }
 

package/src/orm/builders/ExpressionSerializer.ts

@@ -0,0 +1,275 @@
+import {C6C} from "../../constants/C6Constants";
+
+export type tSqlParams = any[] | Record<string, any>;
+
+export interface iSerializedExpression {
+    sql: string;
+    isReference: boolean;
+    isExpression: boolean;
+    isSubSelect: boolean;
+}
+
+export interface iExpressionSerializerHooks {
+    assertValidIdentifier(identifier: string, context: string): void;
+    isReference(value: string): boolean;
+    addParam?: (params: tSqlParams, column: string, value: any) => string;
+    buildScalarSubSelect?: (subRequest: any, params: tSqlParams) => string;
+    onAlias?: (alias: string) => void;
+    isKnownFunction?: (functionName: string) => boolean;
+}
+
+export interface iExpressionSerializerOptions {
+    hooks: iExpressionSerializerHooks;
+    params?: tSqlParams;
+    context: string;
+    contextColumn?: string;
+}
+
+const IDENTIFIER_REGEX = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+const isFiniteNumber = (value: any): value is number =>
+    typeof value === 'number' && Number.isFinite(value);
+
+const normalizeToken = (token: string): string => token.trim();
+
+const ensureParams = (opts: iExpressionSerializerOptions): tSqlParams => {
+    if (!opts.params) {
+        throw new Error(`${opts.context} requires parameter tracking for literal bindings.`);
+    }
+    if (!opts.hooks.addParam) {
+        throw new Error(`${opts.context} requires addParam support for literal bindings.`);
+    }
+    return opts.params;
+};
+
+const serializeStringReference = (
+    raw: string,
+    opts: iExpressionSerializerOptions,
+): iSerializedExpression => {
+    const value = raw.trim();
+
+    if (value === '*') {
+        return {
+            sql: value,
+            isReference: true,
+            isExpression: false,
+            isSubSelect: false,
+        };
+    }
+
+    if (!opts.hooks.isReference(value)) {
+        throw new Error(
+            `Bare string '${raw}' is not a reference in ${opts.context}. Wrap literal strings with [C6C.LIT, value].`,
+        );
+    }
+
+    if (value.includes('.')) {
+        opts.hooks.assertValidIdentifier(value, opts.context);
+    }
+
+    return {
+        sql: value,
+        isReference: true,
+        isExpression: false,
+        isSubSelect: false,
+    };
+};
+
+const serializeLiteralValue = (
+    value: any,
+    opts: iExpressionSerializerOptions,
+): iSerializedExpression => {
+    if (value === null || value === C6C.NULL) {
+        return {
+            sql: 'NULL',
+            isReference: false,
+            isExpression: false,
+            isSubSelect: false,
+        };
+    }
+
+    if (isFiniteNumber(value)) {
+        return {
+            sql: String(value),
+            isReference: false,
+            isExpression: false,
+            isSubSelect: false,
+        };
+    }
+
+    if (typeof value === 'boolean') {
+        return {
+            sql: value ? 'TRUE' : 'FALSE',
+            isReference: false,
+            isExpression: false,
+            isSubSelect: false,
+        };
+    }
+
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(value)) {
+        const params = ensureParams(opts);
+        return {
+            sql: opts.hooks.addParam!(params, opts.contextColumn ?? '', value),
+            isReference: false,
+            isExpression: false,
+            isSubSelect: false,
+        };
+    }
+
+    throw new Error(`Unsupported literal value in ${opts.context}. Use [C6C.LIT, value] for non-reference strings or complex values.`);
+};
+
+const validateAlias = (aliasRaw: any, context: string): string => {
+    if (typeof aliasRaw !== 'string' || aliasRaw.trim() === '') {
+        throw new Error(`[C6C.AS] in ${context} expects a non-empty alias string.`);
+    }
+
+    const alias = aliasRaw.trim();
+    if (!IDENTIFIER_REGEX.test(alias)) {
+        throw new Error(`[C6C.AS] alias '${alias}' in ${context} must be a valid SQL identifier.`);
+    }
+
+    return alias;
+};
+
+const validateFunctionName = (nameRaw: any, context: string): string => {
+    if (typeof nameRaw !== 'string' || nameRaw.trim() === '') {
+        throw new Error(`[C6C.CALL] in ${context} expects the custom function name as a non-empty string.`);
+    }
+
+    const name = normalizeToken(nameRaw);
+    if (!IDENTIFIER_REGEX.test(name)) {
+        throw new Error(`[C6C.CALL] function '${name}' in ${context} must be a valid SQL identifier.`);
+    }
+
+    return name;
+};
+
+const serializeFunctionArgs = (
+    args: any[],
+    opts: iExpressionSerializerOptions,
+): string => args
+    .map((arg) => serializeSqlExpression(arg, opts).sql)
+    .join(', ');
+
+export const serializeSqlExpression = (
+    value: any,
+    opts: iExpressionSerializerOptions,
+): iSerializedExpression => {
+    if (value instanceof Map) {
+        value = Object.fromEntries(value);
+    }
+
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            throw new Error(`Invalid empty expression array in ${opts.context}.`);
+        }
+
+        const [headRaw, ...tail] = value;
+        if (typeof headRaw !== 'string') {
+            throw new Error(`Expression arrays in ${opts.context} must start with a string token.`);
+        }
+
+        const head = normalizeToken(headRaw);
+        const token = head.toUpperCase();
+
+        if (token === C6C.AS) {
+            if (tail.length !== 2) {
+                throw new Error(`[C6C.AS] in ${opts.context} expects [C6C.AS, expression, alias].`);
+            }
+            const inner = serializeSqlExpression(tail[0], opts);
+            const alias = validateAlias(tail[1], opts.context);
+            opts.hooks.onAlias?.(alias);
+
+            return {
+                sql: `${inner.sql} AS ${alias}`,
+                isReference: false,
+                isExpression: true,
+                isSubSelect: inner.isSubSelect,
+            };
+        }
+
+        if (token === C6C.DISTINCT) {
+            if (tail.length !== 1) {
+                throw new Error(`[C6C.DISTINCT] in ${opts.context} expects [C6C.DISTINCT, expression].`);
+            }
+
+            const inner = serializeSqlExpression(tail[0], opts);
+            return {
+                sql: `DISTINCT ${inner.sql}`,
+                isReference: false,
+                isExpression: true,
+                isSubSelect: inner.isSubSelect,
+            };
+        }
+
+        if (token === C6C.LIT || token === C6C.PARAM) {
+            if (tail.length !== 1) {
+                throw new Error(`[${head}] in ${opts.context} expects [${head}, value].`);
+            }
+
+            const params = ensureParams(opts);
+            return {
+                sql: opts.hooks.addParam!(params, opts.contextColumn ?? '', tail[0]),
+                isReference: false,
+                isExpression: false,
+                isSubSelect: false,
+            };
+        }
+
+        if (token === C6C.SUBSELECT) {
+            if (tail.length !== 1) {
+                throw new Error(`[C6C.SUBSELECT] in ${opts.context} expects [C6C.SUBSELECT, payload].`);
+            }
+            if (!opts.hooks.buildScalarSubSelect) {
+                throw new Error(`Scalar subselects in ${opts.context} require subselect builder support.`);
+            }
+            const params = ensureParams(opts);
+            const subSql = opts.hooks.buildScalarSubSelect(tail[0], params);
+            return {
+                sql: subSql,
+                isReference: false,
+                isExpression: true,
+                isSubSelect: true,
+            };
+        }
+
+        if (token === C6C.CALL) {
+            const [fnNameRaw, ...args] = tail;
+            const fnName = validateFunctionName(fnNameRaw, opts.context);
+            const sqlArgs = serializeFunctionArgs(args, opts);
+            return {
+                sql: `${fnName}(${sqlArgs})`,
+                isReference: false,
+                isExpression: true,
+                isSubSelect: false,
+            };
+        }
+
+        if (tail.length >= 2 && String(tail[tail.length - 2]).toUpperCase() === C6C.AS) {
+            throw new Error(`Legacy positional AS syntax is not supported in ${opts.context}. Use [C6C.AS, expression, alias].`);
+        }
+
+        if (opts.hooks.isKnownFunction && !opts.hooks.isKnownFunction(head)) {
+            throw new Error(`Unknown SQL function '${head}' in ${opts.context}. Use [C6C.CALL, 'FUNCTION_NAME', ...args] for custom functions.`);
+        }
+
+        const sqlArgs = serializeFunctionArgs(tail, opts);
+        return {
+            sql: `${token}(${sqlArgs})`,
+            isReference: false,
+            isExpression: true,
+            isSubSelect: false,
+        };
+    }
+
+    if (typeof value === 'string') {
+        return serializeStringReference(value, opts);
+    }
+
+    if (value && typeof value === 'object') {
+        throw new Error(`Object-rooted expressions are not supported in ${opts.context}. Use tuple syntax instead.`);
+    }
+
+    return serializeLiteralValue(value, opts);
+};

package/src/orm/builders/PaginationBuilder.ts

@@ -10,12 +10,10 @@ export abstract class PaginationBuilder<G extends OrmGenerics> extends JoinBuild
      *
      * Accepted structures:
      * ```ts
-     * ORDER: {
-     *   // simple column with direction
-     *   [property_units.UNIT_ID]: "DESC",
-     *	 // function call (array of arguments)
-     *   [C6Constants.ST_DISTANCE_SPHERE]: [property_units.LOCATION, F(property_units.LOCATION, "pu_target")]
-     * }
+     * ORDER: [
+     *   [property_units.UNIT_ID, "DESC"],
+     *   [[C6Constants.ST_DISTANCE_SPHERE, property_units.LOCATION, F(property_units.LOCATION, "pu_target")], "ASC"],
+     * ]
      * ```
      */
     buildPaginationClause(pagination: any, params?: any[] | Record<string, any>): string {
@@ -25,35 +23,27 @@ export abstract class PaginationBuilder<G extends OrmGenerics> extends JoinBuild
         if (pagination?.[C6Constants.ORDER]) {
             const orderParts: string[] = [];
 
-            for (const [key, val] of Object.entries(pagination[C6Constants.ORDER])) {
-                if (typeof key === 'string' && key.includes('.')) {
-                    this.assertValidIdentifier(key, 'ORDER BY');
-                }
-                // FUNCTION CALL: val is an array of args
-                if (Array.isArray(val)) {
-                    const identifierPathRegex = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
-                    const isNumericString = (s: string) => /^-?\d+(?:\.\d+)?$/.test(s.trim());
-                    const args = val
-                        .map((arg) => {
-                            if (Array.isArray(arg)) return this.buildAggregateField(arg, params);
-                            if (typeof arg === 'string') {
-                                if (identifierPathRegex.test(arg)) {
-                                    this.assertValidIdentifier(arg, 'ORDER BY argument');
-                                    return arg;
-                                }
-                                // numeric-looking strings should be treated as literals
-                                if (isNumericString(arg)) return arg;
-                                return arg;
-                            }
-                            return String(arg);
-                        })
-                        .join(", ");
-                    orderParts.push(`${key}(${args})`);
-                }
-                // SIMPLE COLUMN + DIR (ASC/DESC)
-                else {
-                    orderParts.push(`${key} ${String(val).toUpperCase()}`);
+            const orderSpec = pagination[C6Constants.ORDER];
+            if (!Array.isArray(orderSpec)) {
+                throw new Error('PAGINATION.ORDER expects an array of terms using [expression, direction?] syntax.');
+            }
+
+            for (const rawTerm of orderSpec) {
+                let expression = rawTerm;
+                let direction: string = C6Constants.ASC;
+
+                if (
+                    Array.isArray(rawTerm)
+                    && rawTerm.length === 2
+                    && typeof rawTerm[1] === 'string'
+                    && (String(rawTerm[1]).toUpperCase() === C6Constants.ASC || String(rawTerm[1]).toUpperCase() === C6Constants.DESC)
+                ) {
+                    expression = rawTerm[0];
+                    direction = String(rawTerm[1]).toUpperCase();
                 }
+
+                const serialized = this.serializeExpression(expression, params, 'ORDER BY expression');
+                orderParts.push(`${serialized.sql} ${direction}`);
             }
 
             if (orderParts.length) sql += ` ORDER BY ${orderParts.join(", ")}`;

package/src/orm/queryHelpers.ts

@@ -1,5 +1,6 @@
 // Alias a table name with a given alias
 import {C6C} from "../constants/C6Constants";
+import {OrderDirection, OrderTerm, SQLExpression, SQLKnownFunction} from "../types/mysqlTypes";
 
 type DerivedTableSpec = Record<string, any> & {
     [C6C.SUBSELECT]?: Record<string, any>;
@@ -90,3 +91,31 @@ export const bbox = (minLng: number, minLat: number, maxLng: number, maxLat: num
 // ST_Contains for map envelope/shape queries
 export const stContains = (envelope: string, shape: string): any[] =>
     [C6C.ST_CONTAINS, envelope, shape];
+
+// Strongly-typed known function helper.
+export const fn = <Fn extends SQLKnownFunction>(
+    functionName: Fn,
+    ...args: SQLExpression[]
+): [Fn, ...SQLExpression[]] => [functionName, ...args];
+
+// Escape hatch for custom function names.
+export const call = (
+    functionName: string,
+    ...args: SQLExpression[]
+): [typeof C6C.CALL, string, ...SQLExpression[]] => [C6C.CALL as typeof C6C.CALL, functionName, ...args];
+
+export const alias = (
+    expression: SQLExpression,
+    aliasName: string,
+): [typeof C6C.AS, SQLExpression, string] => [C6C.AS as typeof C6C.AS, expression, aliasName];
+
+export const distinct = (
+    expression: SQLExpression,
+): [typeof C6C.DISTINCT, SQLExpression] => [C6C.DISTINCT as typeof C6C.DISTINCT, expression];
+
+export const lit = (value: any): [typeof C6C.LIT, any] => [C6C.LIT as typeof C6C.LIT, value];
+
+export const order = (
+    expression: SQLExpression,
+    direction: OrderDirection = C6C.ASC as OrderDirection,
+): OrderTerm => [expression, direction];