@carbonorm/carbonnode 6.0.20 → 6.1.1

package/src/__tests__/sqlBuilders.expressions.test.ts

@@ -30,22 +30,20 @@ describe('Explicit SQL expression grammar', () => {
         [C6C.OR]: [
           {
             [C6C.LESS_THAN_OR_EQUAL_TO]: [
-              {
-                [C6C.ST_DISTANCE_SPHERE]: [
-                  Property_Units.LOCATION,
-                  { [C6C.ST_GEOMFROMTEXT]: ['POINT(39.4972468 -105.0403593)', 4326] },
-                ],
-              },
+              [
+                C6C.ST_DISTANCE_SPHERE,
+                Property_Units.LOCATION,
+                [C6C.ST_GEOMFROMTEXT, [C6C.LIT, 'POINT(39.4972468 -105.0403593)'], 4326],
+              ],
               5000,
             ],
           },
           {
             [C6C.GREATER_THAN]: [
-              {
-                [C6C.ST_AREA]: [
-                  { [C6C.ST_GEOMFROMTEXT]: ['POLYGON((0 0,1 0,1 1,0 1,0 0))', 4326] },
-                ],
-              },
+              [
+                C6C.ST_AREA,
+                [C6C.ST_GEOMFROMTEXT, [C6C.LIT, 'POLYGON((0 0,1 0,1 1,0 1,0 0))'], 4326],
+              ],
               10000,
             ],
           },
@@ -56,12 +54,17 @@ describe('Explicit SQL expression grammar', () => {
     const { sql, params } = qb.build(Property_Units.TABLE_NAME);
 
     expect(sql).toContain('WHERE');
-    expect(sql).toMatch(/ST_DISTANCE_SPHERE\(property_units.location, ST_GEOMFROMTEXT\('/);
-    expect(sql).toMatch(/ST_AREA\(ST_GEOMFROMTEXT\('/);
+    expect(sql).toMatch(/ST_DISTANCE_SPHERE\(property_units.location, ST_GEOMFROMTEXT\(\?, 4326\)\)/);
+    expect(sql).toMatch(/ST_AREA\(ST_GEOMFROMTEXT\(\?, 4326\)\)/);
     expect(sql).toMatch(/<= \?/);
     expect(sql).toMatch(/> \?/);
     expect(sql).toContain('OR');
-    expect(params).toEqual([5000, 10000]);
+    expect(params).toEqual([
+      'POINT(39.4972468 -105.0403593)',
+      5000,
+      'POLYGON((0 0,1 0,1 1,0 1,0 0))',
+      10000,
+    ]);
   });
 
   it('supports operator-first 3-tuple conditions in WHERE', () => {
@@ -85,7 +88,7 @@ describe('Explicit SQL expression grammar', () => {
     const qb = new SelectQueryBuilder(config as any, {
       [C6C.SELECT]: [Property_Units.PARCEL_ID],
       [C6C.WHERE]: {
-        0: [[C6C.BETWEEN, Parcel_Sales.SALE_DATE, ['2021-01-01', '2021-12-31']]],
+        0: [[C6C.BETWEEN, Parcel_Sales.SALE_DATE, [[C6C.LIT, '2021-01-01'], [C6C.LIT, '2021-12-31']]]],
       },
     } as any, false);
 
@@ -94,30 +97,25 @@ describe('Explicit SQL expression grammar', () => {
     expect(params.slice(-2)).toEqual(['2021-01-01', '2021-12-31']);
   });
 
-  it('treats safe raw function expressions as SQL expressions', () => {
+  it('supports tuple-based function expressions with literal wrappers', () => {
     const config = buildParcelConfig();
 
     const qb = new SelectQueryBuilder(config as any, {
       [C6C.SELECT]: [Property_Units.PARCEL_ID],
       [C6C.WHERE]: {
-        0: [
-          [
-            "ST_Distance_Sphere(property_units.location, ST_GeomFromText('POINT(39.4972468 -105.0403593)', 4326))",
-            C6C.LESS_THAN_OR_EQUAL_TO,
-            5000,
-          ],
+        [C6C.LESS_THAN_OR_EQUAL_TO]: [
+          [C6C.ST_DISTANCE_SPHERE, Property_Units.LOCATION, [C6C.ST_GEOMFROMTEXT, [C6C.LIT, 'POINT(39.4972468 -105.0403593)'], 4326]],
+          5000,
         ],
       },
     } as any, false);
 
     const { sql, params } = qb.build(Property_Units.TABLE_NAME);
-    expect(sql).toMatch(
-      /ST_Distance_Sphere\(property_units\.location, ST_GeomFromText\('POINT\(39\.4972468 -105\.0403593\)', 4326\)\) <= \?/
-    );
-    expect(params.slice(-1)[0]).toBe(5000);
+    expect(sql).toMatch(/ST_DISTANCE_SPHERE\(property_units\.location, ST_GEOMFROMTEXT\(\?, 4326\)\) <= \?/);
+    expect(params).toEqual(['POINT(39.4972468 -105.0403593)', 5000]);
   });
 
-  it('rejects raw function expressions containing unsafe tokens', () => {
+  it('rejects raw function expression strings', () => {
     const config = buildParcelConfig();
 
     const qb = new SelectQueryBuilder(config as any, {
@@ -133,7 +131,37 @@ describe('Explicit SQL expression grammar', () => {
       },
     } as any, false);
 
-    expect(() => qb.build(Property_Units.TABLE_NAME)).toThrowError(/Potential SQL injection detected/);
+    expect(() => qb.build(Property_Units.TABLE_NAME)).toThrowError(/Bare string/);
+  });
+
+  it('rejects legacy positional AS syntax in function tuples', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [[C6C.COUNT, Property_Units.PARCEL_ID, C6C.AS, 'cnt']],
+    } as any, false);
+
+    expect(() => qb.build(Property_Units.TABLE_NAME)).toThrowError(/Legacy positional AS syntax/);
+  });
+
+  it('rejects legacy positional AS syntax in column tuples', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [[Property_Units.PARCEL_ID, C6C.AS, 'parcel_id_alias']],
+    } as any, false);
+
+    expect(() => qb.build(Property_Units.TABLE_NAME)).toThrowError(/Legacy positional AS syntax/);
+  });
+
+  it('rejects object-rooted function expressions', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [{ [C6C.COUNT]: [Property_Units.PARCEL_ID] }],
+    } as any, false);
+
+    expect(() => qb.build(Property_Units.TABLE_NAME)).toThrowError(/Object-rooted expressions are not supported/);
   });
 
   it('supports explicit AND groupings composed of nested OR clauses', () => {
@@ -146,8 +174,8 @@ describe('Explicit SQL expression grammar', () => {
           { [C6C.GREATER_THAN]: [Property_Units.PARCEL_ID, 100] },
           {
             [C6C.OR]: [
-              { [C6C.BETWEEN]: [Parcel_Sales.SALE_DATE, ['2021-01-01', '2022-06-30']] },
-              { [C6C.BETWEEN]: [Parcel_Sales.SALE_DATE, ['2023-01-01', '2024-06-30']] },
+              { [C6C.BETWEEN]: [Parcel_Sales.SALE_DATE, [[C6C.LIT, '2021-01-01'], [C6C.LIT, '2022-06-30']]] },
+              { [C6C.BETWEEN]: [Parcel_Sales.SALE_DATE, [[C6C.LIT, '2023-01-01'], [C6C.LIT, '2024-06-30']]] },
             ],
           },
         ],

package/src/__tests__/sqlBuilders.test.ts

@@ -4,14 +4,15 @@ import { SelectQueryBuilder } from '../orm/queries/SelectQueryBuilder';
 import { PostQueryBuilder } from '../orm/queries/PostQueryBuilder';
 import { UpdateQueryBuilder } from '../orm/queries/UpdateQueryBuilder';
 import { DeleteQueryBuilder } from '../orm/queries/DeleteQueryBuilder';
-import { buildTestConfig, buildBinaryTestConfig, buildBinaryTestConfigFqn } from './fixtures/c6.fixture';
+import { alias, call, distinct, fn, lit, order } from '../orm/queryHelpers';
+import { buildTestConfig, buildBinaryTestConfig, buildBinaryTestConfigFqn, buildTemporalTestConfig } from './fixtures/c6.fixture';
 
 describe('SQL Builders', () => {
   it('builds SELECT with JOIN, WHERE, GROUP BY, HAVING and default LIMIT', () => {
     const config = buildTestConfig();
     // named params disabled -> positional params array
     const qb = new SelectQueryBuilder(config as any, {
-      SELECT: ['actor.first_name', [C6C.COUNT, 'actor.actor_id', C6C.AS, 'cnt']],
+      SELECT: ['actor.first_name', [C6C.AS, [C6C.COUNT, 'actor.actor_id'], 'cnt']],
       JOIN: {
         [C6C.INNER]: {
           'film_actor fa': {
@@ -20,7 +21,7 @@ describe('SQL Builders', () => {
         }
       },
       WHERE: {
-        'actor.first_name': [C6C.LIKE, '%A%'],
+        'actor.first_name': [C6C.LIKE, [C6C.LIT, '%A%']],
         0: {
           'actor.actor_id': [C6C.GREATER_THAN, 10],
         }
@@ -47,7 +48,7 @@ describe('SQL Builders', () => {
     const config = buildTestConfig();
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
     const qb = new SelectQueryBuilder(config as any, {
-      SELECT: [[C6C.COUNT, 'actor.actor_id', C6C.AS, 'cnt']],
+      SELECT: [[C6C.AS, [C6C.COUNT, 'actor.actor_id'], 'cnt']],
     } as any, false);
 
     qb.build('actor');
@@ -62,6 +63,39 @@ describe('SQL Builders', () => {
     logSpy.mockRestore();
   });
 
+  it('supports custom functions through C6C.CALL and binds string literals', () => {
+    const config = buildTestConfig();
+    const qb = new SelectQueryBuilder(config as any, {
+      SELECT: [[C6C.AS, [C6C.CALL, 'COALESCE', [C6C.LIT, 'fallback'], 'actor.first_name'], 'resolved_name']],
+    } as any, false);
+
+    const { sql, params } = qb.build('actor');
+    expect(sql).toContain('COALESCE(?, actor.first_name) AS resolved_name');
+    expect(params).toEqual(['fallback']);
+  });
+
+  it('supports helper builders for fn/call/as/distinct/lit/order', () => {
+    const config = buildTestConfig();
+    const qb = new SelectQueryBuilder(config as any, {
+      SELECT: [
+        alias(distinct('actor.first_name'), 'distinct_name'),
+        alias(fn(C6C.COUNT, 'actor.actor_id'), 'cnt'),
+        call('COALESCE', lit('N/A'), 'actor.last_name'),
+      ],
+      PAGINATION: {
+        [C6C.ORDER]: [order(fn(C6C.COUNT, 'actor.actor_id'), 'DESC')],
+        [C6C.LIMIT]: 5,
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build('actor');
+    expect(sql).toContain('DISTINCT actor.first_name AS distinct_name');
+    expect(sql).toContain('COUNT(actor.actor_id) AS cnt');
+    expect(sql).toContain('COALESCE(?, actor.last_name)');
+    expect(sql).toContain('ORDER BY COUNT(actor.actor_id) DESC');
+    expect(params).toEqual(['N/A']);
+  });
+
   it('builds INSERT with ON DUPLICATE KEY UPDATE', () => {
     const config = buildTestConfig();
     const qb = new PostQueryBuilder(config as any, {
@@ -192,6 +226,36 @@ describe('SQL Builders', () => {
     expect(params).toEqual(['ALICE', 5]);
   });
 
+  it('supports expression tuples in UPDATE values', () => {
+    const config = buildTestConfig();
+    const qb = new UpdateQueryBuilder(config as any, {
+      [C6C.UPDATE]: {
+        'actor.first_name': [C6C.CONCAT, [C6C.LIT, 'Mr. '], 'actor.last_name'],
+      },
+      WHERE: {
+        'actor.actor_id': [C6C.EQUAL, 7],
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build('actor');
+    expect(sql).toContain('`first_name` = CONCAT(?, actor.last_name)');
+    expect(params).toEqual(['Mr. ', 7]);
+  });
+
+  it('supports expression tuples in INSERT values', () => {
+    const config = buildTestConfig();
+    const qb = new PostQueryBuilder(config as any, {
+      [C6C.INSERT]: {
+        'actor.first_name': [C6C.CONCAT, [C6C.LIT, 'HEL'], [C6C.LIT, 'LO']],
+        'actor.last_name': 'SMITH',
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build('actor');
+    expect(sql).toContain('CONCAT(?, ?)');
+    expect(params).toEqual(['HEL', 'LO', 'SMITH']);
+  });
+
   it('builds UPDATE when columns are fully qualified', () => {
     const config = buildTestConfig();
     const qb = new UpdateQueryBuilder(config as any, {
@@ -235,7 +299,7 @@ describe('SQL Builders', () => {
     const config = buildTestConfig();
     const qb = new SelectQueryBuilder(config as any, {
       WHERE: {
-        'actor.binarycol': [C6C.EQUAL, '0123456789abcdef0123456789abcdef']
+        'actor.binarycol': [C6C.EQUAL, [C6C.LIT, '0123456789abcdef0123456789abcdef']]
       }
     } as any, false);
 
@@ -317,4 +381,41 @@ describe('SQL Builders', () => {
     expect(Buffer.isBuffer(buf)).toBe(true);
     expect((buf as Buffer).length).toBe(16);
   });
+
+  it('serializes ISO-8601 strings for TIMESTAMP columns in INSERT params', () => {
+    const config = buildTemporalTestConfig();
+    const qb = new PostQueryBuilder(config as any, {
+      [C6C.INSERT]: {
+        'events.read_at': '2026-02-16T21:27:06.679Z'
+      }
+    } as any, false);
+
+    const { params } = qb.build('events');
+    expect(params).toEqual(['2026-02-16 21:27:06.679']);
+  });
+
+  it('serializes ISO-8601 strings for DATE columns in UPDATE params', () => {
+    const config = buildTemporalTestConfig();
+    const qb = new UpdateQueryBuilder(config as any, {
+      [C6C.UPDATE]: {
+        'events.read_on': '2026-02-16T21:27:06.679Z'
+      },
+      WHERE: { 'events.id': [C6C.EQUAL, 1] }
+    } as any, false);
+
+    const { params } = qb.build('events');
+    expect(params).toEqual(['2026-02-16', 1]);
+  });
+
+  it('serializes offset ISO-8601 strings for TIME columns in WHERE params', () => {
+    const config = buildTemporalTestConfig();
+    const qb = new SelectQueryBuilder(config as any, {
+      WHERE: {
+        'events.read_time': [C6C.EQUAL, [C6C.LIT, '2026-02-16T16:27:06.679-05:00']]
+      }
+    } as any, false);
+
+    const { params } = qb.build('events');
+    expect(params).toEqual(['21:27:06.679']);
+  });
 });

package/src/constants/C6Constants.ts

@@ -9,6 +9,7 @@ export const C6Constants = {
     BETWEEN: 'BETWEEN',
 
     CONCAT: 'CONCAT',
+    CALL: 'CALL',
     CONVERT_TZ: 'CONVERT_TZ',
     COUNT: 'COUNT',
     COUNT_ALL: 'COUNT_ALL',
@@ -71,6 +72,7 @@ export const C6Constants = {
     LESS_THAN: '<',
     LESS_THAN_OR_EQUAL_TO: '<=',
     LIKE: 'LIKE',
+    LIT: 'LIT',
     LIMIT: 'LIMIT',
     LOCALTIME: 'LOCALTIME',
     LOCALTIMESTAMP: 'LOCALTIMESTAMP',
@@ -198,7 +200,7 @@ export const C6Constants = {
     FINISH: 'FINISH',
     VALIDATE_C6_ENTITY_ID_REGEX: '#^([a-fA-F0-9]{20,35})$#',
 
-};
+} as const;
 
 
 export const C6C = C6Constants;

package/src/executors/HttpExecutor.ts

@@ -209,6 +209,7 @@ export class HttpExecutor<
             const {
                 debug,
                 cacheResults = (C6.GET === requestMethod),
+                skipReactBootstrap = false,
                 dataInsertMultipleRows,
                 success,
                 fetchDependencies = eFetchDependencies.NONE,
@@ -557,7 +558,7 @@ export class HttpExecutor<
                                 response
                             });
 
-                        if (undefined !== reactBootstrap && response) {
+                        if (undefined !== reactBootstrap && response && !skipReactBootstrap) {
                             switch (requestMethod) {
                                 case GET:
                                     response.data && reactBootstrap.updateRestfulObjectArrays<G['RestTableInterface']>({

package/src/executors/SqlExecutor.ts

@@ -22,7 +22,7 @@ import logSql, {
 } from "../utils/logSql";
 import { normalizeSingularRequest } from "../utils/normalizeSingularRequest";
 import {sortAndSerializeQueryObject} from "../utils/sortAndSerializeQueryObject";
-import { loadSqlAllowList, normalizeSql } from "../utils/sqlAllowList";
+import { loadSqlAllowList, normalizeSqlWith } from "../utils/sqlAllowList";
 import { getLogContext, LogLevel, logWithLevel } from "../utils/logLevel";
 
 const SQL_ALLOWLIST_BLOCKED_CODE = "SQL_ALLOWLIST_BLOCKED";
@@ -438,6 +438,7 @@ export class SqlExecutor<
             C6C.REPLACE,
             "dataInsertMultipleRows",
             "cacheResults",
+            "skipReactBootstrap",
             "fetchDependencies",
             "debug",
             "success",
@@ -530,7 +531,7 @@ export class SqlExecutor<
             }
 
             if (value !== undefined) {
-                pkValues[pkShort] = value;
+                pkValues[pkShort] = this.unwrapPrimaryKeyValue(value);
             }
         }
 
@@ -541,6 +542,29 @@ export class SqlExecutor<
         return Object.keys(pkValues).length > 0 ? pkValues : null;
     }
 
+    private unwrapPrimaryKeyValue(value: any): any {
+        if (!Array.isArray(value)) return value;
+
+        if (value.length === 2) {
+            const [head, tail] = value;
+            if (head === C6C.EQUAL) {
+                return this.unwrapPrimaryKeyValue(tail);
+            }
+            if (head === C6C.LIT || head === C6C.PARAM) {
+                return tail;
+            }
+        }
+
+        if (value.length === 3) {
+            const [, operator, right] = value;
+            if (operator === C6C.EQUAL) {
+                return this.unwrapPrimaryKeyValue(right);
+            }
+        }
+
+        return value;
+    }
+
     private extractPrimaryKeyValuesFromData(data: any): Record<string, any> | null {
         if (!data) return null;
         const row = Array.isArray(data) ? data[0] : data;
@@ -1046,8 +1070,9 @@ export class SqlExecutor<
             return "not verified";
         }
 
-        const allowList = await loadSqlAllowList(allowListPath);
-        const normalized = normalizeSql(sql);
+        const sqlQueryNormalizer = this.config.sqlQueryNormalizer;
+        const allowList = await loadSqlAllowList(allowListPath, sqlQueryNormalizer);
+        const normalized = normalizeSqlWith(sql, sqlQueryNormalizer);
         if (!allowList.has(normalized)) {
             throw createSqlAllowListBlockedError({
                 tableName:

package/src/index.ts

@@ -19,6 +19,7 @@ export * from "./handlers/ExpressHandler";
 export * from "./orm/queryHelpers";
 export * from "./orm/builders/AggregateBuilder";
 export * from "./orm/builders/ConditionBuilder";
+export * from "./orm/builders/ExpressionSerializer";
 export * from "./orm/builders/JoinBuilder";
 export * from "./orm/builders/PaginationBuilder";
 export * from "./orm/queries/DeleteQueryBuilder";

package/src/orm/builders/AggregateBuilder.ts

@@ -1,9 +1,18 @@
 import {Executor} from "../../executors/Executor";
 import {OrmGenerics} from "../../types/ormGenerics";
-import {C6C} from "../../constants/C6Constants";
+import {SQL_KNOWN_FUNCTIONS} from "../../types/mysqlTypes";
 import {getLogContext, LogLevel, logWithLevel} from "../../utils/logLevel";
+import {
+    iSerializedExpression,
+    serializeSqlExpression,
+    tSqlParams,
+} from "./ExpressionSerializer";
 
-export abstract class AggregateBuilder<G extends OrmGenerics> extends Executor<G>{
+const KNOWN_FUNCTION_LOOKUP = new Set(
+    SQL_KNOWN_FUNCTIONS.map((name) => String(name).toUpperCase()),
+);
+
+export abstract class AggregateBuilder<G extends OrmGenerics> extends Executor<G> {
     protected selectAliases: Set<string> = new Set<string>();
 
     // Overridden in ConditionBuilder where alias tracking is available.
@@ -12,130 +21,82 @@ export abstract class AggregateBuilder<G extends OrmGenerics> extends Executor<G
         // no-op placeholder for subclasses that do not implement alias validation
     }
 
-    buildAggregateField(field: string | any[], params?: any[] | Record<string, any>): string {
-        if (typeof field === 'string') {
-            this.assertValidIdentifier(field, 'SELECT field');
-            return field;
-        }
+    protected isReferenceExpression(value: string): boolean {
+        if (typeof value !== 'string') return false;
 
-        if (!Array.isArray(field) || field.length === 0) {
-            throw new Error('Invalid SELECT field entry');
-        }
-
-        // If the array represents a tuple/literal list (e.g., [lng, lat]) rather than a
-        // function call like [FN, ...args], serialize the list as a comma-separated
-        // literal sequence so parent calls (like ORDER BY FN(<here>)) can embed it.
-        const isNumericString = (s: string) => /^-?\d+(?:\.\d+)?$/.test(String(s).trim());
-        if (typeof field[0] !== 'string' || isNumericString(field[0])) {
-            return field
-                .map((arg) => {
-                    if (Array.isArray(arg)) return this.buildAggregateField(arg, params);
-                    return String(arg);
-                })
-                .join(', ');
-        }
+        const trimmed = value.trim();
+        if (trimmed.length === 0) return false;
 
-        let [fn, ...args] = field;
-        let alias: string | undefined;
+        if (trimmed === '*') return true;
 
-        if (args.length >= 2 && String(args[args.length - 2]).toUpperCase() === 'AS') {
-            alias = String(args.pop());
-            args.pop();
+        if (/^[A-Za-z_][A-Za-z0-9_]*\.\*$/.test(trimmed)) {
+            this.assertValidIdentifier(trimmed, 'SQL reference');
+            return true;
         }
 
-        const F = String(fn).toUpperCase();
-        const isGeomFromText = F === C6C.ST_GEOMFROMTEXT.toUpperCase();
-
-        if (args.length === 1 && Array.isArray(args[0])) {
-            args = args[0];
+        if (/^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed)) {
+            this.assertValidIdentifier(trimmed, 'SQL reference');
+            return true;
         }
 
-        // Parameter placeholder helper: [C6C.PARAM, value]
-        if (F === C6C.PARAM) {
-            if (!params) {
-                throw new Error('PARAM requires parameter tracking.');
-            }
-            const value = args[0];
-            // Use empty column context; ORDER/SELECT literals have no column typing.
-            // @ts-ignore addParam is provided by ConditionBuilder in our hierarchy.
-            return this.addParam(params, '', value);
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(trimmed) && this.selectAliases.has(trimmed)) {
+            return true;
         }
 
-        if (F === C6C.SUBSELECT) {
-            if (!params) {
-                throw new Error('Scalar subselects in SELECT require parameter tracking.');
-            }
-            const subRequest = args[0];
-            const subSql = (this as any).buildScalarSubSelect?.(subRequest, params);
-            if (!subSql) {
-                throw new Error('Failed to build scalar subselect.');
-            }
-
-            let expr = subSql;
-            if (alias) {
-                this.selectAliases.add(alias);
-                expr += ` AS ${alias}`;
-            }
-
-            logWithLevel(
-                LogLevel.DEBUG,
-                getLogContext(this.config, this.request),
-                console.log,
-                `[SELECT] ${expr}`,
-            );
-
-            return expr;
-        }
+        return false;
+    }
 
-        const identifierPathRegex = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+    protected isKnownFunction(functionName: string): boolean {
+        return KNOWN_FUNCTION_LOOKUP.has(functionName.trim().toUpperCase());
+    }
 
-        const argList = args
-            .map((arg, index) => {
-                if (Array.isArray(arg)) return this.buildAggregateField(arg, params);
-                if (typeof arg === 'string') {
-                    if (identifierPathRegex.test(arg)) {
-                        this.assertValidIdentifier(arg, 'SELECT expression');
-                        return arg;
+    protected serializeExpression(
+        expression: any,
+        params?: tSqlParams,
+        context: string = 'SQL expression',
+        contextColumn?: string,
+    ): iSerializedExpression {
+        return serializeSqlExpression(expression, {
+            params,
+            context,
+            contextColumn,
+            hooks: {
+                assertValidIdentifier: (identifier: string, hookContext: string) => {
+                    this.assertValidIdentifier(identifier, hookContext);
+                },
+                isReference: (value: string) => this.isReferenceExpression(value),
+                addParam: (target: tSqlParams, column: string, value: any) => {
+                    const addParam = (this as any).addParam;
+                    if (typeof addParam !== 'function') {
+                        throw new Error('Expression literal binding requires addParam support.');
                     }
-                    // Treat numeric-looking strings as literals, not identifier paths
-                    if (isNumericString(arg)) return arg;
-
-                    if (isGeomFromText && index === 0) {
-                        const trimmed = arg.trim();
-                        const alreadyQuoted = trimmed.startsWith("'") && trimmed.endsWith("'") && trimmed.length >= 2;
-                        if (alreadyQuoted) {
-                            return trimmed;
-                        }
-                        const escaped = arg.replace(/'/g, "''");
-                        return `'${escaped}'`;
+                    return addParam.call(this, target, column, value);
+                },
+                buildScalarSubSelect: (subRequest: any, target: tSqlParams) => {
+                    const builder = (this as any).buildScalarSubSelect;
+                    if (typeof builder !== 'function') {
+                        throw new Error('Scalar subselects require SelectQueryBuilder context.');
                     }
+                    return builder.call(this, subRequest, target);
+                },
+                onAlias: (alias: string) => {
+                    this.selectAliases.add(alias);
+                },
+                isKnownFunction: (functionName: string) => this.isKnownFunction(functionName),
+            },
+        });
+    }
 
-                    return arg;
-                }
-                return String(arg);
-            })
-            .join(', ');
-
-        let expr: string;
-
-        if (F === 'DISTINCT') {
-            expr = `DISTINCT ${argList}`;
-        } else {
-            expr = `${F}(${argList})`;
-        }
-
-        if (alias) {
-            this.selectAliases.add(alias);
-            expr += ` AS ${alias}`;
-        }
+    buildAggregateField(field: string | any[], params?: tSqlParams): string {
+        const serialized = this.serializeExpression(field, params, 'SELECT expression');
 
         logWithLevel(
             LogLevel.DEBUG,
             getLogContext(this.config, this.request),
             console.log,
-            `[SELECT] ${expr}`,
+            `[SELECT] ${serialized.sql}`,
         );
 
-        return expr;
+        return serialized.sql;
     }
 }