@carbonorm/carbonnode 3.8.4 → 3.9.2

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

@@ -1,7 +1,28 @@
 import { describe, it, expect } from 'vitest';
 import { C6C } from '../api/C6Constants';
 import { SelectQueryBuilder } from '../api/orm/queries/SelectQueryBuilder';
-import { buildTestConfig } from './fixtures/c6.fixture';
+import { derivedTable, F } from '../api/orm/queryHelpers';
+import { buildParcelConfig, buildTestConfig } from './fixtures/c6.fixture';
+
+const Property_Units = {
+  TABLE_NAME: 'property_units',
+  UNIT_ID: 'property_units.unit_id',
+  LOCATION: 'property_units.location',
+  PARCEL_ID: 'property_units.parcel_id',
+} as const;
+
+const Parcel_Sales = {
+  TABLE_NAME: 'parcel_sales',
+  PARCEL_ID: 'parcel_sales.parcel_id',
+  SALE_PRICE: 'parcel_sales.sale_price',
+  SALE_TYPE: 'parcel_sales.sale_type',
+  SALE_DATE: 'parcel_sales.sale_date',
+} as const;
+
+const Parcel_Building_Details = {
+  TABLE_NAME: 'parcel_building_details',
+  PARCEL_ID: 'parcel_building_details.parcel_id',
+} as const;
 
 /**
  * Complex SELECT coverage focused on WHERE operators, JOIN chains, ORDER, and pagination.
@@ -157,4 +178,263 @@ describe('SQL Builders - Complex SELECTs', () => {
     expect(sql).toMatch(/\(actor\.last_name\) IS NOT \?/);
     expect(params).toEqual([null]);
   });
+
+  it('serializes derived table joins with parameter hoisting and alias scoping', () => {
+    const config = buildParcelConfig();
+    const unitIdParam = 42;
+    const ALLOWED_SALE_TYPES = ['A', 'B', 'C', 'D', 'E', 'F'];
+    const parsedDateRanges = [
+      { start: '2023-01-01', end: '2023-01-31' },
+      { start: '2023-02-01', end: '2023-02-28' },
+    ];
+
+    const puTarget = derivedTable({
+      [C6C.SUBSELECT]: {
+        [C6C.SELECT]: [Property_Units.LOCATION],
+        [C6C.FROM]: Property_Units.TABLE_NAME,
+        [C6C.WHERE]: { [Property_Units.UNIT_ID]: [C6C.EQUAL, unitIdParam] },
+        [C6C.LIMIT]: 1,
+      },
+      [C6C.AS]: 'pu_target',
+    });
+
+    const innerJoin: any = {
+      'parcel_sales ps': {
+        'ps.parcel_id': [C6C.EQUAL, Property_Units.PARCEL_ID],
+      },
+      'parcel_building_details pbd': {
+        'pbd.parcel_id': [C6C.EQUAL, Property_Units.PARCEL_ID],
+      },
+      [puTarget as any]: {},
+    };
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [
+        Property_Units.UNIT_ID,
+        Property_Units.LOCATION,
+        F(Property_Units.LOCATION, 'pu_target'),
+      ],
+      [C6C.JOIN]: {
+        [C6C.INNER]: innerJoin,
+      },
+      [C6C.WHERE]: {
+        [Property_Units.UNIT_ID]: [C6C.NOT_EQUAL, unitIdParam],
+        [Parcel_Sales.SALE_PRICE]: [C6C.NOT_EQUAL, 0],
+        [Parcel_Sales.SALE_TYPE]: { [C6C.IN]: ALLOWED_SALE_TYPES },
+        0: parsedDateRanges.map(({ start, end }) => ({
+          [Parcel_Sales.SALE_DATE]: [C6C.BETWEEN, [start, end]],
+        })),
+      },
+      [C6C.PAGINATION]: {
+        [C6C.LIMIT]: 200,
+        [C6C.ORDER]: {
+          [C6C.ST_DISTANCE_SPHERE]: [
+            Property_Units.LOCATION,
+            F(Property_Units.LOCATION, 'pu_target'),
+          ],
+        },
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build(Property_Units.TABLE_NAME);
+
+    expect(sql).toContain('SELECT property_units.unit_id, property_units.location, pu_target.location FROM `property_units`');
+    expect(sql).toContain('INNER JOIN `parcel_sales` AS `ps`');
+    expect(sql).toContain('INNER JOIN `parcel_building_details` AS `pbd`');
+    expect(sql).toMatch(/INNER JOIN \(\s+SELECT property_units\.location/);
+    expect(sql).toContain('WHERE (property_units.unit_id) <> ?');
+    expect(sql).toContain('AND (parcel_sales.sale_price) <> ?');
+    expect(sql).toContain('ORDER BY ST_Distance_Sphere(property_units.location, pu_target.location)');
+    expect(sql.trim().endsWith('LIMIT 200')).toBe(true);
+
+    expect(params).toEqual([
+      unitIdParam,
+      unitIdParam,
+      0,
+      ...ALLOWED_SALE_TYPES,
+      parsedDateRanges[0].start,
+      parsedDateRanges[0].end,
+      parsedDateRanges[1].start,
+      parsedDateRanges[1].end,
+    ]);
+  });
+
+  it('supports derived joins with ON clauses referencing the alias', () => {
+    const config = buildParcelConfig();
+
+    const recentSales = derivedTable({
+      [C6C.SUBSELECT]: {
+        [C6C.SELECT]: [Parcel_Sales.PARCEL_ID],
+        [C6C.FROM]: Parcel_Sales.TABLE_NAME,
+        [C6C.WHERE]: { [Parcel_Sales.SALE_PRICE]: [C6C.GREATER_THAN, 50000] },
+        [C6C.LIMIT]: 1,
+      },
+      [C6C.AS]: 'recent_sales',
+    });
+
+    const innerJoin: any = {
+      [recentSales as any]: {
+        'recent_sales.parcel_id': [C6C.EQUAL, Property_Units.PARCEL_ID],
+      },
+    };
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [Property_Units.UNIT_ID],
+      [C6C.JOIN]: { [C6C.INNER]: innerJoin },
+      [C6C.WHERE]: { [Property_Units.UNIT_ID]: [C6C.GREATER_THAN, 1] },
+    } as any, false);
+
+    const { sql, params } = qb.build(Property_Units.TABLE_NAME);
+
+    expect(sql).toMatch(/INNER JOIN \(\s+SELECT parcel_sales\.parcel_id/);
+    expect(sql).toContain('ON ((recent_sales.parcel_id) = property_units.parcel_id)');
+    expect(params[0]).toBe(50000);
+  });
+
+  it('throws when referencing an unknown alias in SELECT expressions', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [F(Property_Units.LOCATION, 'missing_alias')],
+    } as any, false);
+
+    expect(() => qb.build(Property_Units.TABLE_NAME)).toThrowError(/Unknown table or alias 'missing_alias'/);
+  });
+
+  it('orders by distance to a literal ST_Point with numeric string coords', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [Property_Units.UNIT_ID],
+      [C6C.PAGINATION]: {
+        [C6C.LIMIT]: 200,
+        [C6C.ORDER]: {
+          [C6C.ST_DISTANCE_SPHERE]: [
+            Property_Units.LOCATION,
+            [C6C.ST_POINT, ['-104.8967729', '39.3976764']],
+          ],
+        },
+      },
+    } as any, false);
+
+    const { sql } = qb.build(Property_Units.TABLE_NAME);
+    expect(sql).toContain('ORDER BY ST_Distance_Sphere(property_units.location, ST_POINT(-104.8967729, 39.3976764))');
+  });
+
+  it('orders by distance to ST_SRID(ST_Point(lng, lat), 4326)', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [Property_Units.UNIT_ID],
+      [C6C.PAGINATION]: {
+        [C6C.LIMIT]: 50,
+        [C6C.ORDER]: {
+          [C6C.ST_DISTANCE_SPHERE]: [
+            Property_Units.LOCATION,
+            [C6C.ST_SRID, [C6C.ST_POINT, [10, 20]], 4326],
+          ],
+        },
+      },
+    } as any, false);
+
+    const { sql } = qb.build(Property_Units.TABLE_NAME);
+    expect(sql).toContain('ORDER BY ST_Distance_Sphere(property_units.location, ST_SRID(ST_POINT(10, 20), 4326))');
+  });
+
+  it('orders by distance using placeholders via PARAM inside nested ST_Point', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [Property_Units.UNIT_ID],
+      [C6C.PAGINATION]: {
+        [C6C.LIMIT]: 25,
+        [C6C.ORDER]: {
+          [C6C.ST_DISTANCE_SPHERE]: [
+            Property_Units.LOCATION,
+            [C6C.ST_SRID, [C6C.ST_POINT, [[C6C.PARAM, 10], [C6C.PARAM, 20]]], 4326],
+          ],
+        },
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build(Property_Units.TABLE_NAME);
+    expect(sql).toContain('ORDER BY ST_Distance_Sphere(property_units.location, ST_SRID(ST_POINT(?, ?), 4326))');
+    expect(params.slice(-2)).toEqual([10, 20]);
+  });
+
+  it('orders by distance using named params via PARAM inside nested ST_Point', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [Property_Units.UNIT_ID],
+      [C6C.PAGINATION]: {
+        [C6C.LIMIT]: 25,
+        [C6C.ORDER]: {
+          [C6C.ST_DISTANCE_SPHERE]: [
+            Property_Units.LOCATION,
+            [C6C.ST_SRID, [C6C.ST_POINT, [[C6C.PARAM, 10], [C6C.PARAM, 20]]], 4326],
+          ],
+        },
+      },
+    } as any, true);
+
+    const { sql, params } = qb.build(Property_Units.TABLE_NAME);
+    expect(sql).toMatch(/ST_SRID\(ST_POINT\(:param0, :param1\), 4326\)/);
+    expect(params).toEqual({ param0: 10, param1: 20 });
+  });
+
+  it('leaves normal table joins unaffected', () => {
+    const config = buildTestConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: ['actor.actor_id'],
+      [C6C.JOIN]: {
+        [C6C.INNER]: {
+          'film_actor fa': { 'fa.actor_id': [C6C.EQUAL, 'actor.actor_id'] },
+        },
+      },
+    } as any, false);
+
+    const { sql } = qb.build('actor');
+    expect(sql).toContain('INNER JOIN `film_actor` AS `fa` ON ((fa.actor_id) = actor.actor_id)');
+  });
+
+  it('supports scalar subselects in SELECT and WHERE clauses', () => {
+    const config = buildParcelConfig();
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: [
+        Property_Units.UNIT_ID,
+        [
+          C6C.SUBSELECT,
+          {
+            [C6C.SELECT]: [[C6C.COUNT, Parcel_Sales.PARCEL_ID]],
+            [C6C.FROM]: Parcel_Sales.TABLE_NAME,
+            [C6C.WHERE]: { [Parcel_Sales.SALE_PRICE]: [C6C.GREATER_THAN, 0] },
+          },
+          C6C.AS,
+          'sale_count',
+        ],
+      ],
+      [C6C.WHERE]: {
+        [Property_Units.UNIT_ID]: [
+          C6C.IN,
+          [
+            C6C.SUBSELECT,
+            {
+              [C6C.SELECT]: [Parcel_Sales.PARCEL_ID],
+              [C6C.FROM]: Parcel_Sales.TABLE_NAME,
+              [C6C.WHERE]: { [Parcel_Sales.SALE_PRICE]: [C6C.GREATER_THAN, 5000] },
+            },
+          ],
+        ],
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build(Property_Units.TABLE_NAME);
+
+    expect(sql).toContain('SELECT property_units.unit_id, (SELECT COUNT(parcel_sales.parcel_id)');
+    expect(sql).toContain('WHERE ( property_units.unit_id IN (SELECT parcel_sales.parcel_id');
+    expect(params).toContain(5000);
+  });
 });

package/src/api/C6Constants.ts

@@ -62,6 +62,7 @@ export const C6Constants = {
     INTERVAL: 'INTERVAL',
 
     JOIN: 'JOIN',
+    FROM: 'FROM',
 
     LEFT: 'LEFT',
     LEFT_OUTER: 'LEFT_OUTER',
@@ -99,6 +100,8 @@ export const C6Constants = {
     SECOND: 'SECOND',
     SECOND_MICROSECOND: 'SECOND_MICROSECOND',
     SELECT: 'SELECT',
+    SUBSELECT: 'SUBSELECT',
+    PARAM: 'PARAM',
 
     // MySQL Spatial Functions
     ST_AREA: 'ST_Area',
@@ -186,4 +189,4 @@ export const C6Constants = {
 };
 
 
-export const C6C = C6Constants;
+export const C6C = C6Constants;

package/src/api/orm/builders/AggregateBuilder.ts

@@ -1,11 +1,19 @@
 import {Executor} from "../../executors/Executor";
 import {OrmGenerics} from "../../types/ormGenerics";
+import {C6C} from "../../C6Constants";
 
 export abstract class AggregateBuilder<G extends OrmGenerics> extends Executor<G>{
     protected selectAliases: Set<string> = new Set<string>();
 
-    buildAggregateField(field: string | any[]): string {
+    // Overridden in ConditionBuilder where alias tracking is available.
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    protected assertValidIdentifier(_identifier: string, _context: string): void {
+        // 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;
         }
 
@@ -13,6 +21,19 @@ export abstract class AggregateBuilder<G extends OrmGenerics> extends Executor<G
             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(', ');
+        }
+
         let [fn, ...args] = field;
         let alias: string | undefined;
 
@@ -22,8 +43,55 @@ export abstract class AggregateBuilder<G extends OrmGenerics> extends Executor<G
         }
 
         const F = String(fn).toUpperCase();
+
+        // 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 (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}`;
+            }
+
+            this.config.verbose && console.log(`[SELECT] ${expr}`);
+
+            return expr;
+        }
+
+        const identifierPathRegex = /^[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/;
+
         const argList = args
-            .map(arg => Array.isArray(arg) ? this.buildAggregateField(arg) : arg)
+            .map(arg => {
+                if (Array.isArray(arg)) return this.buildAggregateField(arg, params);
+                if (typeof arg === 'string') {
+                    if (identifierPathRegex.test(arg)) {
+                        this.assertValidIdentifier(arg, 'SELECT expression');
+                        return arg;
+                    }
+                    // Treat numeric-looking strings as literals, not identifier paths
+                    if (isNumericString(arg)) return arg;
+                    return arg;
+                }
+                return String(arg);
+            })
             .join(', ');
 
         let expr: string;

package/src/api/orm/builders/ConditionBuilder.ts

@@ -3,31 +3,57 @@ import {OrmGenerics} from "../../types/ormGenerics";
 import {DetermineResponseDataType} from "../../types/ormInterfaces";
 import {convertHexIfBinary, SqlBuilderResult} from "../utils/sqlUtils";
 import {AggregateBuilder} from "./AggregateBuilder";
+import {isDerivedTableKey} from "../queryHelpers";
 
 export abstract class ConditionBuilder<
     G extends OrmGenerics
 > extends AggregateBuilder<G> {
 
     protected aliasMap: Record<string, string> = {};
+    protected derivedAliases: Set<string> = new Set<string>();
 
     protected initAlias(baseTable: string, joins?: any): void {
         this.aliasMap = { [baseTable]: baseTable };
+        this.derivedAliases = new Set<string>();
 
         if (!joins) return;
 
         for (const joinType in joins) {
             for (const raw in joins[joinType]) {
-                const [table, alias] = raw.split(' ');
-                this.aliasMap[alias || table] = table;
+                const [table, alias] = raw.trim().split(/\s+/, 2);
+                if (!table) continue;
+                this.registerAlias(alias || table, table);
             }
         }
     }
 
+    protected registerAlias(alias: string, table: string): void {
+        this.aliasMap[alias] = table;
+        if (isDerivedTableKey(table)) {
+            this.derivedAliases.add(alias);
+        }
+    }
+
+    protected assertValidIdentifier(identifier: string, context: string): void {
+        if (typeof identifier !== 'string') return;
+        if (!identifier.includes('.')) return;
+
+        const [alias] = identifier.split('.', 2);
+        if (!(alias in this.aliasMap)) {
+            throw new Error(`Unknown table or alias '${alias}' referenced in ${context}: '${identifier}'.`);
+        }
+    }
+
     protected isColumnRef(ref: string): boolean {
         if (typeof ref !== 'string' || !ref.includes('.')) return false;
 
         const [prefix, column] = ref.split('.', 2);
         const tableName = this.aliasMap[prefix] || prefix;
+
+        if (isDerivedTableKey(tableName) || this.derivedAliases.has(prefix)) {
+            return true;
+        }
+
         const table = this.config.C6?.TABLES?.[tableName];
         if (!table) return false;
 
@@ -77,6 +103,9 @@ export abstract class ConditionBuilder<
         }
         const [prefix, column] = val.split('.');
         const tableName = this.aliasMap[prefix] ?? prefix;
+        if (isDerivedTableKey(tableName) || this.derivedAliases.has(prefix)) {
+            return true;
+        }
         const table = this.config.C6?.TABLES?.[tableName];
         if (!table || !table.COLUMNS) return false;
 
@@ -130,6 +159,28 @@ export abstract class ConditionBuilder<
             // Normalize common variants
             const valueNorm = (value === C6C.NULL) ? null : value;
             const displayOp = typeof op === 'string' ? op.replace('_', ' ') : op;
+
+            const extractSubSelect = (input: any): any | undefined => {
+                if (Array.isArray(input) && input.length >= 2 && input[0] === C6C.SUBSELECT) {
+                    return input[1];
+                }
+                if (input && typeof input === 'object' && C6C.SUBSELECT in input) {
+                    return input[C6C.SUBSELECT];
+                }
+                return undefined;
+            };
+
+            const rightSubSelectPayload = extractSubSelect(valueNorm);
+            const buildSubSelect = (payload: any): string | undefined => {
+                if (!payload) return undefined;
+                const builder = (this as any).buildScalarSubSelect;
+                if (typeof builder !== 'function') {
+                    throw new Error('Scalar subselect handling requires JoinBuilder context.');
+                }
+                return builder.call(this, payload, params);
+            };
+            const rightSubSelectSql = buildSubSelect(rightSubSelectPayload);
+
             // Support function-based expressions like [C6C.ST_DISTANCE_SPHERE, col1, col2]
             if (
                 typeof column === 'string' &&
@@ -160,7 +211,7 @@ export abstract class ConditionBuilder<
             const leftIsRef = this.isTableReference(column);
             const rightIsCol = typeof value === 'string' && this.isColumnRef(value);
 
-            if (!leftIsCol && !leftIsRef && !rightIsCol) {
+            if (!leftIsCol && !leftIsRef && !rightIsCol && !rightSubSelectSql) {
                 throw new Error(`Potential SQL injection detected: '${column} ${op} ${value}'`);
             }
 
@@ -198,6 +249,13 @@ export abstract class ConditionBuilder<
             }
 
             if ((op === C6C.IN || op === C6C.NOT_IN) && Array.isArray(value)) {
+                if (rightSubSelectSql) {
+                    if (!leftIsRef) {
+                        throw new Error(`IN operator requires a table reference as the left operand. Column '${column}' is not a valid table reference.`);
+                    }
+                    const normalized = op.replace('_', ' ');
+                    return `( ${column} ${normalized} ${rightSubSelectSql} )`;
+                }
                 const placeholders = value.map(v =>
                     this.isColumnRef(v) ? v : this.addParam(params, column, v)
                 ).join(', ');
@@ -219,12 +277,16 @@ export abstract class ConditionBuilder<
                 return `(${column}) ${op.replace('_', ' ')} ${this.addParam(params, column, start)} AND ${this.addParam(params, column, end)}`;
             }
 
-            const rightIsRef: boolean = this.isTableReference(value);
+            const rightIsRef: boolean = rightSubSelectSql ? false : this.isTableReference(value);
 
             if (leftIsRef && rightIsRef) {
                 return `(${column}) ${displayOp} ${value}`;
             }
 
+            if (leftIsRef && rightSubSelectSql) {
+                return `(${column}) ${displayOp} ${rightSubSelectSql}`;
+            }
+
             if (leftIsRef && !rightIsRef) {
                 return `(${column}) ${displayOp} ${this.addParam(params, column, valueNorm)}`;
             }