@carbonorm/carbonnode 6.0.14 → 6.0.18

package/src/__tests__/sakila-db/sqlResponses/C6.language.post.json

@@ -5,8 +5,8 @@
   "sql": {
     "sql": "INSERT INTO `language` (\n            `name`, `last_update`\n         ) VALUES\n            (?, ?)",
     "values": [
-      "name_1770597283831",
-      "2026-02-09 00:34:43"
+      "name_1770934052102",
+      "2026-02-12 22:07:32"
     ]
   }
 }

package/src/__tests__/sakila-db/sqlResponses/C6.language.post.latest.json

@@ -2,8 +2,8 @@
   "rest": [
     {
       "language_id": 7,
-      "name": "name_1770597283831",
-      "last_update": "2026-02-09T00:34:43.000Z"
+      "name": "name_1770934052102",
+      "last_update": "2026-02-12T22:07:32.000Z"
     }
   ],
   "sql": {

package/src/__tests__/sakila-db/sqlResponses/C6.language.put.json

@@ -5,7 +5,7 @@
   "sql": {
     "sql": "UPDATE `language` SET `name` = ? WHERE (language.language_id) = ?",
     "values": [
-      "name_updated_1770597",
+      "name_updated_1770934",
       7
     ]
   }

package/src/__tests__/sakila-db/sqlResponses/C6.language.put.lookup.json

@@ -2,8 +2,8 @@
   "rest": [
     {
       "language_id": 7,
-      "name": "name_updated_1770597",
-      "last_update": "2026-02-09T00:34:43.000Z"
+      "name": "name_updated_1770934",
+      "last_update": "2026-02-12T22:07:32.000Z"
     }
   ],
   "sql": {

package/src/__tests__/sakila-db/sqlResponses/C6.payment.post.json

@@ -9,8 +9,8 @@
       1,
       1,
       1,
-      "2026-02-09 00:34:43",
-      "2026-02-09 00:34:43"
+      "2026-02-12 22:07:32",
+      "2026-02-12 22:07:32"
     ]
   }
 }

package/src/__tests__/sakila-db/sqlResponses/C6.payment.post.latest.json

@@ -6,8 +6,8 @@
       "staff_id": 1,
       "rental_id": 1,
       "amount": "1.00",
-      "payment_date": "2026-02-09T00:34:43.000Z",
-      "last_update": "2026-02-09T00:34:43.000Z"
+      "payment_date": "2026-02-12T22:07:32.000Z",
+      "last_update": "2026-02-12T22:07:32.000Z"
     }
   ],
   "sql": {

package/src/__tests__/sakila-db/sqlResponses/C6.payment.put.lookup.json

@@ -6,8 +6,8 @@
       "staff_id": 1,
       "rental_id": 1,
       "amount": "1.00",
-      "payment_date": "2026-02-09T00:34:43.000Z",
-      "last_update": "2026-02-09T00:34:43.000Z"
+      "payment_date": "2026-02-12T22:07:32.000Z",
+      "last_update": "2026-02-12T22:07:32.000Z"
     }
   ],
   "sql": {

package/src/__tests__/sakila-db/sqlResponses/C6.rental.join.json

@@ -1,18 +1,18 @@
 {
   "rest": [
     {
-      "rental_id": 76,
-      "rental_date": "2005-05-25T11:30:37.000Z",
-      "inventory_id": 3021,
-      "customer_id": 1,
-      "return_date": "2005-06-03T12:00:37.000Z",
-      "staff_id": 2,
+      "rental_id": 1,
+      "rental_date": "2005-05-24T22:53:30.000Z",
+      "inventory_id": 367,
+      "customer_id": 130,
+      "return_date": "2005-05-26T22:04:30.000Z",
+      "staff_id": 1,
       "last_update": "2006-02-15T04:57:20.000Z",
       "store_id": 1,
-      "first_name": "MARY",
-      "last_name": "SMITH",
-      "email": "MARY.SMITH@sakilacustomer.org",
-      "address_id": 5,
+      "first_name": "CHARLOTTE",
+      "last_name": "HUNTER",
+      "email": "CHARLOTTE.HUNTER@sakilacustomer.org",
+      "address_id": 134,
       "active": 1,
       "create_date": "2006-02-14T22:04:36.000Z"
     }

package/src/__tests__/sakila-db/sqlResponses/C6.rental.post.json

@@ -5,12 +5,12 @@
   "sql": {
     "sql": "INSERT INTO `rental` (\n            `rental_date`, `inventory_id`, `customer_id`, `return_date`, `staff_id`, `last_update`\n         ) VALUES\n            (?, ?, ?, ?, ?, ?)",
     "values": [
-      "2026-02-09 00:34:43",
+      "2026-02-12 22:07:32",
       1,
       1,
-      "2026-02-09 00:34:43",
+      "2026-02-12 22:07:32",
       1,
-      "2026-02-09 00:34:43"
+      "2026-02-12 22:07:32"
     ]
   }
 }

package/src/__tests__/sakila-db/sqlResponses/C6.rental.post.latest.json

@@ -2,12 +2,12 @@
   "rest": [
     {
       "rental_id": 16050,
-      "rental_date": "2026-02-09T00:34:43.000Z",
+      "rental_date": "2026-02-12T22:07:32.000Z",
       "inventory_id": 1,
       "customer_id": 1,
-      "return_date": "2026-02-09T00:34:43.000Z",
+      "return_date": "2026-02-12T22:07:32.000Z",
       "staff_id": 1,
-      "last_update": "2026-02-09T00:34:43.000Z"
+      "last_update": "2026-02-12T22:07:32.000Z"
     }
   ],
   "sql": {

package/src/__tests__/sakila-db/sqlResponses/C6.rental.put.json

@@ -5,7 +5,7 @@
   "sql": {
     "sql": "UPDATE `rental` SET `rental_date` = ? WHERE (rental.rental_id) = ?",
     "values": [
-      "2026-02-09 00:34:43",
+      "2026-02-12 22:07:32",
       16050
     ]
   }

package/src/__tests__/sakila-db/sqlResponses/C6.rental.put.lookup.json

@@ -2,12 +2,12 @@
   "rest": [
     {
       "rental_id": 16050,
-      "rental_date": "2026-02-09T00:34:43.000Z",
+      "rental_date": "2026-02-12T22:07:32.000Z",
       "inventory_id": 1,
       "customer_id": 1,
-      "return_date": "2026-02-09T00:34:43.000Z",
+      "return_date": "2026-02-12T22:07:32.000Z",
       "staff_id": 1,
-      "last_update": "2026-02-09T00:34:43.000Z"
+      "last_update": "2026-02-12T22:07:32.000Z"
     }
   ],
   "sql": {

package/src/__tests__/sqlAllowList.test.ts

@@ -119,10 +119,110 @@ describe("SQL allowlist", () => {
       await expect(
         Actor.Get({
           [C6.PAGINATION]: {[C6.LIMIT]: 1},
+          cacheResults: false,
         } as any)
       ).rejects.toThrow("SQL statement is not permitted");
     } finally {
       restoreGlobals(originalGlobals);
     }
   });
+
+  it("normalizes multi-row VALUES with variable row counts", () => {
+    const oneRow = `
+      INSERT INTO \`valuation_report_comparables\` (\`report_id\`, \`unit_id\`, \`subject_unit_id\`)
+      VALUES (?, ?, ?)
+      ON DUPLICATE KEY UPDATE \`subject_unit_id\` = VALUES(\`subject_unit_id\`)
+    `;
+    const manyRows = `
+      INSERT INTO \`valuation_report_comparables\` (\`report_id\`, \`unit_id\`, \`subject_unit_id\`)
+      VALUES (?, ?, ?), (?, ?, ?), (?, ?, ?), (?, ?, ?)
+      ON DUPLICATE KEY UPDATE \`subject_unit_id\` = VALUES(\`subject_unit_id\`)
+    `;
+
+    expect(normalizeSql(oneRow)).toContain("VALUES (? ×3) ×*");
+    expect(normalizeSql(manyRows)).toContain("VALUES (? ×3) ×*");
+    expect(normalizeSql(oneRow)).toBe(normalizeSql(manyRows));
+  });
+
+  it("normalizes IN bind list cardinality", () => {
+    const smallIn = "SELECT * FROM `geometries` WHERE ( geometries.geometry_id IN (?, ?, ?) ) LIMIT 100";
+    const largeIn = "SELECT * FROM `geometries` WHERE ( geometries.geometry_id IN (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) ) LIMIT 250";
+
+    const normalizedSmall = normalizeSql(smallIn);
+    const normalizedLarge = normalizeSql(largeIn);
+
+    expect(normalizedSmall).toContain("IN (? ×*)");
+    expect(normalizedLarge).toContain("IN (? ×*)");
+    expect(normalizedSmall).toContain("LIMIT ?");
+    expect(normalizedLarge).toContain("LIMIT ?");
+    expect(normalizedSmall).toBe(normalizedLarge);
+  });
+
+  it("normalizes LIMIT and OFFSET numeric literals", () => {
+    expect(normalizeSql("SELECT * FROM `actor` LIMIT 100")).toBe(
+      normalizeSql("SELECT * FROM `actor` LIMIT 25"),
+    );
+    expect(normalizeSql("SELECT * FROM `actor` LIMIT 10, 50")).toBe(
+      "SELECT * FROM `actor` LIMIT ?, ?",
+    );
+    expect(normalizeSql("SELECT * FROM `actor` LIMIT 50 OFFSET 100")).toBe(
+      "SELECT * FROM `actor` LIMIT ? OFFSET ?",
+    );
+  });
+
+  it("normalizes variable ST_GEOMFROMTEXT POINT and POLYGON literals", () => {
+    const q1 = `
+      SELECT * FROM \`property_units\`
+      WHERE MBRCONTAINS(
+        ST_GEOMFROMTEXT('POLYGON((39.1 -105.1, 39.2 -105.1, 39.2 -105.0, 39.1 -105.0, 39.1 -105.1))', 4326),
+        property_units.location
+      )
+      ORDER BY ST_DISTANCE_SPHERE(
+        property_units.location,
+        ST_GEOMFROMTEXT('POINT(39.15 -105.05)', 4326)
+      )
+      LIMIT 100
+    `;
+    const q2 = `
+      SELECT * FROM \`property_units\`
+      WHERE MBRCONTAINS(
+        ST_GEOMFROMTEXT('POLYGON((39.3 -105.3, 39.7 -105.3, 39.7 -104.8, 39.3 -104.8, 39.3 -105.3))', 4326),
+        property_units.location
+      )
+      ORDER BY ST_DISTANCE_SPHERE(
+        property_units.location,
+        ST_GEOMFROMTEXT('POINT(39.5321821 -105.0035613)', 4326)
+      )
+      LIMIT 250
+    `;
+
+    const normalized1 = normalizeSql(q1);
+    const normalized2 = normalizeSql(q2);
+
+    expect(normalized1).toContain("ST_GEOMFROMTEXT('POLYGON((?))', ?)");
+    expect(normalized1).toContain("ST_GEOMFROMTEXT('POINT(? ?)', ?)");
+    expect(normalized1).toContain("ST_DISTANCE_SPHERE(");
+    expect(normalized1).toContain("LIMIT ?");
+    expect(normalized1).toBe(normalized2);
+  });
+
+  it("normalizes geo function casing and FORCE INDEX spacing", () => {
+    const a =
+      "SELECT * FROM `property_units` FORCE INDEX (`idx_county_id`,`idx_property_units_location`) WHERE ST_Distance_Sphere(property_units.location, ST_GeomFromText('POINT(39.5 -105.0)', 4326)) <= 50 LIMIT 100";
+    const b =
+      "SELECT * FROM `property_units` FORCE INDEX (`idx_county_id`, `idx_property_units_location`) WHERE st_distance_sphere(property_units.location, st_geomfromtext('POINT(39.7 -104.9)', 4326)) <= 25 LIMIT 25";
+
+    const normalizedA = normalizeSql(a);
+    const normalizedB = normalizeSql(b);
+
+    expect(normalizedA).toContain("FORCE INDEX (`idx_county_id`, `idx_property_units_location`)");
+    expect(normalizedA).toContain("ST_DISTANCE_SPHERE");
+    expect(normalizedA).toContain("ST_GEOMFROMTEXT('POINT(? ?)', ?)");
+    expect(normalizedA).toContain("LIMIT ?");
+    expect(normalizedB).toContain("FORCE INDEX (`idx_county_id`, `idx_property_units_location`)");
+    expect(normalizedB).toContain("ST_DISTANCE_SPHERE");
+    expect(normalizedB).toContain("ST_GEOMFROMTEXT('POINT(? ?)', ?)");
+    expect(normalizedB).toContain("LIMIT ?");
+  });
+
 });

package/src/__tests__/sqlBuilders.test.ts

@@ -5,7 +5,6 @@ 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 { version } from '../../package.json';
 
 describe('SQL Builders', () => {
   it('builds SELECT with JOIN, WHERE, GROUP BY, HAVING and default LIMIT', () => {
@@ -44,11 +43,11 @@ describe('SQL Builders', () => {
     expect(params).toEqual(['%A%', 10, 1]);
   });
 
-  it('logs SELECT statements with package version', () => {
+  it('logs SELECT aggregate expressions at DEBUG level', () => {
     const config = buildTestConfig();
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
     const qb = new SelectQueryBuilder(config as any, {
-      SELECT: ['actor.first_name'],
+      SELECT: [[C6C.COUNT, 'actor.actor_id', C6C.AS, 'cnt']],
     } as any, false);
 
     qb.build('actor');
@@ -59,7 +58,7 @@ describe('SQL Builders', () => {
     const selectLine = logLines.find((line) => line.includes('[SELECT]'));
 
     expect(selectLine).toBeDefined();
-    expect(selectLine).toContain(`[${version}]`);
+    expect(selectLine).toContain('COUNT(actor.actor_id) AS cnt');
     logSpy.mockRestore();
   });
 

package/src/__tests__/sqlExecutor.cacheEviction.test.ts

@@ -0,0 +1,79 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { restOrm } from "../api/restOrm";
+import { apiRequestCache, clearCache } from "../utils/cacheManager";
+import { buildTestConfig } from "./fixtures/c6.fixture";
+
+describe("SqlExecutor cache eviction", () => {
+  const rows = [
+    {
+      actor_id: 1,
+      first_name: "ALICE",
+      last_name: "ONE",
+    },
+  ];
+
+  const buildOrm = () => {
+    const conn: any = {
+      beginTransaction: vi.fn(async () => undefined),
+      query: vi.fn(async () => [rows, []]),
+      commit: vi.fn(async () => undefined),
+      rollback: vi.fn(async () => undefined),
+      release: vi.fn(),
+    };
+
+    const baseConfig = buildTestConfig() as any;
+
+    const actorSql = restOrm<any>(() => ({
+      ...baseConfig,
+      mysqlPool: {
+        getConnection: vi.fn(async () => conn),
+      },
+      verbose: false,
+    }));
+
+    return {
+      actorSql,
+      conn,
+    };
+  };
+
+  beforeEach(() => {
+    clearCache({ ignoreWarning: true });
+  });
+
+  it("adds evictFromCache for cached GET responses", async () => {
+    const { actorSql, conn } = buildOrm();
+
+    const response = await actorSql.Get({ actor_id: 1, cacheResults: true } as any);
+
+    expect(conn.query).toHaveBeenCalledTimes(1);
+    expect(typeof response.evictFromCache).toBe("function");
+    expect(apiRequestCache.size).toBe(1);
+
+    expect(response.evictFromCache?.()).toBe(true);
+    expect(apiRequestCache.size).toBe(0);
+    expect(response.evictFromCache?.()).toBe(false);
+  });
+
+  it("does not add evictFromCache when cacheResults is false", async () => {
+    const { actorSql, conn } = buildOrm();
+
+    const response = await actorSql.Get({ actor_id: 1, cacheResults: false } as any);
+
+    expect(conn.query).toHaveBeenCalledTimes(1);
+    expect(response.evictFromCache).toBeUndefined();
+    expect(apiRequestCache.size).toBe(0);
+  });
+
+  it("keeps evictFromCache on cache hits", async () => {
+    const { actorSql, conn } = buildOrm();
+
+    await actorSql.Get({ actor_id: 1, cacheResults: true } as any);
+    const cached = await actorSql.Get({ actor_id: 1, cacheResults: true } as any);
+
+    expect(conn.query).toHaveBeenCalledTimes(1);
+    expect(typeof cached.evictFromCache).toBe("function");
+    expect(cached.evictFromCache?.()).toBe(true);
+    expect(apiRequestCache.size).toBe(0);
+  });
+});

package/src/executors/HttpExecutor.ts

@@ -13,7 +13,7 @@ import {
     PUT, RequestQueryBody
 } from "../types/ormInterfaces";
 import {removeInvalidKeys, removePrefixIfExists, TestRestfulResponse} from "../utils/apiHelpers";
-import {checkCache, setCache, userCustomClearCache} from "../utils/cacheManager";
+import {checkCache, evictCacheEntry, setCache, userCustomClearCache} from "../utils/cacheManager";
 import {sortAndSerializeQueryObject} from "../utils/sortAndSerializeQueryObject";
 import {notifyToast} from "../utils/toastRuntime";
 import {Executor} from "./Executor";
@@ -254,17 +254,29 @@ export class HttpExecutor<
                 G['RequestTableOverrides']
             >;
 
+            const evictFromCache =
+                requestMethod === GET && cacheResults
+                    ? () => evictCacheEntry(requestMethod, tableName, cacheRequestData)
+                    : undefined;
+
             // literally impossible for query to be undefined or null here but the editor is too busy licking windows to understand that
             let querySerialized: string = sortAndSerializeQueryObject(tables, cacheRequestData ?? {});
 
             let cachedRequest: Promise<{ data: ResponseDataType }> | false = false;
 
             if (cacheResults) {
-                cachedRequest = checkCache<ResponseDataType>(requestMethod, tableName, cacheRequestData);
+                cachedRequest = checkCache<ResponseDataType>(requestMethod, tableName, cacheRequestData, logContext);
             }
 
             if (cachedRequest) {
-                return (await cachedRequest).data;
+                const cachedData = (await cachedRequest).data;
+                if (evictFromCache
+                    && cachedData
+                    && typeof cachedData === "object"
+                    && Array.isArray((cachedData as C6RestResponse<'GET', G['RestTableInterface']>).rest)) {
+                    (cachedData as C6RestResponse<'GET', G['RestTableInterface']>).evictFromCache = evictFromCache;
+                }
+                return cachedData;
             }
 
             if (cacheResults) {
@@ -544,7 +556,7 @@ export class HttpExecutor<
                             callback();
                         }
 
-                        if (C6.GET === requestMethod && this.isRestResponse(response)) {
+                        if (requestMethod === GET && this.isRestResponse(response)) {
 
                             const responseData =
                                 response.data as DetermineResponseDataType<'GET', G['RestTableInterface']>;
@@ -562,6 +574,10 @@ export class HttpExecutor<
                                 responseData.next = undefined;    // short page => done
                             }
 
+                            if (cachingConfirmed && evictFromCache) {
+                                responseData.evictFromCache = evictFromCache;
+                            }
+
                             if (cachingConfirmed) {
                                 setCache<ResponseDataType>(requestMethod, tableName, cacheRequestData, {
                                     requestArgumentsSerialized: querySerialized,