@carbonorm/carbonnode 3.10.0 → 4.0.0

package/src/__tests__/cacheManager.test.ts

@@ -0,0 +1,67 @@
+import type { AxiosPromise } from "axios";
+import { describe, it, expect, beforeEach } from "vitest";
+import {
+  apiRequestCache,
+  checkCache,
+  clearCache,
+  setCache,
+} from "../api/utils/cacheManager";
+import { checkAllRequestsComplete } from "../api/utils/testHelpers";
+
+describe("cacheManager with map storage", () => {
+  const requestData = { id: 1 } as const;
+
+  beforeEach(() => {
+    clearCache({ ignoreWarning: true });
+  });
+
+  it("stores and returns cached requests", () => {
+    const mockRequest = Promise.resolve({ data: { rest: [] } }) as AxiosPromise;
+
+    setCache("GET", "table", requestData, {
+      requestArgumentsSerialized: "serialized",
+      request: mockRequest,
+    });
+
+    const cached = checkCache("GET", "table", { ...requestData });
+    expect(cached).toBe(mockRequest);
+  });
+
+  it("clears cache entries", () => {
+    const mockRequest = Promise.resolve({ data: { rest: [] } }) as AxiosPromise;
+
+    setCache("GET", "table", requestData, {
+      requestArgumentsSerialized: "serialized",
+      request: mockRequest,
+    });
+
+    clearCache({ ignoreWarning: true });
+
+    expect(apiRequestCache.size).toBe(0);
+    expect(checkCache("GET", "table", requestData)).toBe(false);
+  });
+
+  it("reports pending and completed requests via helper", () => {
+    const originalDocument = (global as any).document;
+    (global as any).document = {};
+
+    setCache("GET", "table", requestData, {
+      requestArgumentsSerialized: "pending",
+      request: Promise.resolve({ data: null }) as AxiosPromise,
+    });
+
+    expect(checkAllRequestsComplete()).toEqual(["pending"]);
+
+    setCache("GET", "table", requestData, {
+      requestArgumentsSerialized: "pending",
+      request: Promise.resolve({ data: null }) as AxiosPromise,
+      response: {} as any,
+      final: true,
+    });
+
+    expect(checkAllRequestsComplete()).toBe(true);
+
+    (global as any).document = originalDocument;
+  });
+});
+

package/src/__tests__/expressServer.e2e.test.ts

@@ -2,7 +2,7 @@ import mysql from "mysql2/promise";
 import axios from "axios";
 import { AddressInfo } from "net";
 import {describe, it, expect, beforeAll, afterAll} from "vitest";
-import {Actor, C6, GLOBAL_REST_PARAMETERS} from "./sakila-db/C6.js";
+import {Actor, C6, Film_Actor, GLOBAL_REST_PARAMETERS} from "./sakila-db/C6.js";
 import {C6C} from "../api/C6Constants";
 import createTestServer from "./fixtures/createTestServer";
 
@@ -23,7 +23,12 @@ beforeAll(async () => {
     const {port} = server.address() as AddressInfo;
 
     GLOBAL_REST_PARAMETERS.restURL = `http://127.0.0.1:${port}/rest/`;
-    GLOBAL_REST_PARAMETERS.axios = axios;
+    const axiosClient = axios.create();
+    axiosClient.interceptors.response.use(
+        response => response,
+        error => Promise.reject(new Error(error?.message ?? 'Request failed')),
+    );
+    GLOBAL_REST_PARAMETERS.axios = axiosClient;
     GLOBAL_REST_PARAMETERS.verbose = false;
     // ensure HTTP executor is used
     // @ts-ignore
@@ -93,6 +98,79 @@ describe("ExpressHandler e2e", () => {
         expect(data?.rest.length).toBe(0);
     });
 
+    it("stringifies plain object values in PUT updates", async () => {
+        const first_name = `Json${Date.now()}`;
+        const last_name = `User${Date.now()}`;
+
+        await Actor.Post({
+            first_name,
+            last_name,
+        } as any);
+
+        const payload = { greeting: "hello", flags: [1, true] };
+
+        let data = await Actor.Get({
+            [C6C.WHERE]: { [Actor.FIRST_NAME]: first_name, [Actor.LAST_NAME]: last_name },
+            [C6C.PAGINATION]: { [C6C.LIMIT]: 1 },
+        } as any);
+
+        const actorId = data?.rest?.[0]?.actor_id;
+        expect(actorId).toBeTruthy();
+
+        await Actor.Put({
+            [C6C.WHERE]: { [Actor.ACTOR_ID]: actorId },
+            [C6C.UPDATE]: { first_name: payload },
+        } as any);
+
+        data = await Actor.Get({
+            [C6C.WHERE]: { [Actor.ACTOR_ID]: actorId },
+        } as any);
+
+        expect(data?.rest?.[0]?.first_name).toBe(JSON.stringify(payload));
+    });
+
+    it("rejects operator-like objects in PUT updates", async () => {
+        const first_name = `Invalid${Date.now()}`;
+        const last_name = `User${Date.now()}`;
+
+        await Actor.Post({
+            first_name,
+            last_name,
+        } as any);
+
+        const data = await Actor.Get({
+            [C6C.WHERE]: { [Actor.FIRST_NAME]: first_name, [Actor.LAST_NAME]: last_name },
+            [C6C.PAGINATION]: { [C6C.LIMIT]: 1 },
+        } as any);
+
+        const actorId = data?.rest?.[0]?.actor_id;
+        expect(actorId).toBeTruthy();
+
+        const operatorLike = { [C6C.GREATER_THAN]: "oops" } as any;
+
+        const prevRestUrl = GLOBAL_REST_PARAMETERS.restURL;
+        const prevAxios = GLOBAL_REST_PARAMETERS.axios;
+        GLOBAL_REST_PARAMETERS.mysqlPool = pool as any;
+        delete (GLOBAL_REST_PARAMETERS as any).restURL;
+        delete (GLOBAL_REST_PARAMETERS as any).axios;
+
+        try {
+            await Actor.Put({
+                [C6C.WHERE]: { [Actor.ACTOR_ID]: actorId },
+                [C6C.UPDATE]: { first_name: operatorLike },
+            } as any);
+            throw new Error('Expected PUT to reject for operator-like payload.');
+        } catch (error: any) {
+            const message = String(error?.message ?? error);
+            expect(message).toMatch(/operand/i);
+        } finally {
+            GLOBAL_REST_PARAMETERS.restURL = prevRestUrl;
+            GLOBAL_REST_PARAMETERS.axios = prevAxios;
+            // @ts-ignore
+            delete GLOBAL_REST_PARAMETERS.mysqlPool;
+        }
+    });
+
     it("respects METHOD=GET override on POST", async () => {
         const {restURL} = GLOBAL_REST_PARAMETERS;
         const table = Actor.TABLE_NAME;
@@ -121,4 +199,28 @@ describe("ExpressHandler e2e", () => {
         expect(response.status).toBe(200);
         expect(response.data?.success).toBeTruthy();
     });
+
+    it("allows composite keys when a URL primary is present", async () => {
+        const {restURL} = GLOBAL_REST_PARAMETERS;
+        const table = Film_Actor.TABLE_NAME;
+
+        const seed = await Film_Actor.Get({
+            [C6C.PAGINATION]: { [C6C.LIMIT]: 1 },
+        } as any);
+
+        const filmActor = seed.rest[0];
+        expect(filmActor).toBeTruthy();
+
+        const response = await axios.post(`${restURL}${table}/${filmActor.actor_id}?METHOD=GET`, {
+            [C6C.WHERE]: {
+                [Film_Actor.ACTOR_ID]: filmActor.actor_id,
+                [Film_Actor.FILM_ID]: filmActor.film_id,
+            },
+        });
+
+        expect(response.status).toBe(200);
+        expect(response.data?.rest).toHaveLength(1);
+        expect(response.data?.rest?.[0]?.actor_id).toBe(filmActor.actor_id);
+        expect(response.data?.rest?.[0]?.film_id).toBe(filmActor.film_id);
+    });
 });

package/src/__tests__/fixtures/c6.fixture.ts

@@ -43,6 +43,7 @@ export function buildTestConfig() {
     'actor.first_name': 'first_name',
     'actor.last_name': 'last_name',
     'actor.binarycol': 'binarycol',
+    'actor.json_data': 'json_data',
   } as const;
 
   const filmActorCols = {
@@ -62,6 +63,7 @@ export function buildTestConfig() {
 
   // Special-case: mark binary column as BINARY to test conversion
   C6.TABLES.actor.TYPE_VALIDATION['binarycol'].MYSQL_TYPE = 'BINARY(16)';
+  C6.TABLES.actor.TYPE_VALIDATION['json_data'].MYSQL_TYPE = 'JSON';
 
   const baseConfig: iRest<any, any, any> = {
     C6,
@@ -135,6 +137,7 @@ export function buildParcelConfig() {
     'property_units.unit_id': 'unit_id',
     'property_units.location': 'location',
     'property_units.parcel_id': 'parcel_id',
+    'property_units.county_id': 'county_id',
   } as const;
 
   const parcelSalesCols = {
@@ -146,6 +149,8 @@ export function buildParcelConfig() {
 
   const parcelBuildingCols = {
     'parcel_building_details.parcel_id': 'parcel_id',
+    'parcel_building_details.year_built': 'year_built',
+    'parcel_building_details.gla': 'gla',
   } as const;
 
   const C6 = {

package/src/__tests__/httpExecutorSingular.e2e.test.ts

@@ -23,7 +23,12 @@ beforeAll(async () => {
   const { port } = server.address() as AddressInfo;
 
   GLOBAL_REST_PARAMETERS.restURL = `http://127.0.0.1:${port}/rest/`;
-  GLOBAL_REST_PARAMETERS.axios = axios;
+  const axiosClient = axios.create();
+  axiosClient.interceptors.response.use(
+    response => response,
+    error => Promise.reject(new Error(error?.message ?? "Request failed")),
+  );
+  GLOBAL_REST_PARAMETERS.axios = axiosClient;
   GLOBAL_REST_PARAMETERS.verbose = false;
   // ensure HTTP executor is used
   // @ts-ignore
@@ -41,14 +46,14 @@ describe("HttpExecutor singular e2e", () => {
     const last_name = `User${Date.now()}`;
 
     // POST
-    const postRes = await Actor.Post({ first_name, last_name } as any);
-    expect(postRes.affected).toBe(1);
+    await Actor.Post({ first_name, last_name } as any);
 
     // Fetch inserted id using complex query
     let data = await Actor.Get({
       [C6C.WHERE]: { [Actor.FIRST_NAME]: first_name, [Actor.LAST_NAME]: last_name },
       [C6C.PAGINATION]: { [C6C.LIMIT]: 1 },
-    } as any);
+    });
+
     expect(data.rest).toHaveLength(1);
     const testId = data.rest[0].actor_id;
 
@@ -89,4 +94,30 @@ describe("HttpExecutor singular e2e", () => {
     expect(Array.isArray(data.rest)).toBe(true);
     expect(data.rest.length).toBe(0);
   });
+
+  it("exposes next when pagination continues", async () => {
+    const data = await Actor.Get({
+      [C6C.PAGINATION]: { [C6C.LIMIT]: 2 },
+    } as any);
+
+    expect(Array.isArray(data.rest)).toBe(true);
+    expect(data.rest).toHaveLength(2);
+    expect(typeof data.next).toBe("function");
+
+    const nextPage = await data.next?.();
+    expect(nextPage?.rest).toBeDefined();
+    expect(Array.isArray(nextPage?.rest)).toBe(true);
+    expect(nextPage?.rest?.length).toBeGreaterThan(0);
+  });
+
+  it("exposes limit 1 does not expose next", async () => {
+    const data = await Actor.Get({
+      [C6C.PAGINATION]: { [C6C.LIMIT]: 1 },
+    } as any);
+
+    expect(Array.isArray(data.rest)).toBe(true);
+    expect(data.rest).toHaveLength(1);
+    expect(typeof data.next).toBe("undefined");
+
+  });
 });

package/src/__tests__/sakila-db/C6.js

@@ -1342,7 +1342,7 @@ export const TABLES = {
 };
 export const C6 = {
     ...C6Constants,
-    C6VERSION: '3.10.0',
+    C6VERSION: '4.0.0',
     IMPORT: async (tableName) => {
         tableName = tableName.toLowerCase();
         // if tableName is not a key in the TABLES object then throw an error

package/src/__tests__/sakila-db/C6.ts

@@ -2009,7 +2009,7 @@ export type RestTableInterfaces = iActor
 
 export const C6 : iC6Object<RestTableInterfaces> = {
     ...C6Constants,
-    C6VERSION: '3.10.0',
+    C6VERSION: '4.0.0',
     IMPORT: async (tableName: string) : Promise<iDynamicApiImport> => {
 
         tableName = tableName.toLowerCase();

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

@@ -9,6 +9,7 @@ const Property_Units = {
   UNIT_ID: 'property_units.unit_id',
   LOCATION: 'property_units.location',
   PARCEL_ID: 'property_units.parcel_id',
+  COUNTY_ID: 'property_units.county_id',
 } as const;
 
 const Parcel_Sales = {
@@ -19,6 +20,13 @@ const Parcel_Sales = {
   SALE_DATE: 'parcel_sales.sale_date',
 } as const;
 
+const Parcel_Building_Details = {
+  TABLE_NAME: 'parcel_building_details',
+  PARCEL_ID: 'parcel_building_details.parcel_id',
+  YEAR_BUILT: 'parcel_building_details.year_built',
+  GLA: 'parcel_building_details.gla',
+} as const;
+
 /**
  * Complex SELECT coverage focused on WHERE operators, JOIN chains, ORDER, and pagination.
  */
@@ -479,4 +487,81 @@ describe('SQL Builders - Complex SELECTs', () => {
     expect(sql).toContain('WHERE ( property_units.unit_id IN (SELECT parcel_sales.parcel_id');
     expect(params).toContain(5000);
   });
+
+  it('serializes spatial filtering with FORCE INDEX and correlated EXISTS subqueries', () => {
+    const config = buildParcelConfig();
+    const polygon = 'POLYGON((39.5185659 -105.0142915, 39.5401859 -105.0142915, 39.5401859 -104.9862115, 39.5185659 -104.9862115, 39.5185659 -105.0142915))';
+    const point = [C6C.ST_GEOMFROMTEXT, ['POINT(39.5293759 -105.0002515)', 4326]];
+    const unitId = Buffer.from('11F0615D24861BE1ADD40AFFCF6A1F27', 'hex');
+    const countyId = Buffer.from('11F012CFF561A29DBB0E0AFFF25F1747', 'hex');
+
+    const qb = new SelectQueryBuilder(config as any, {
+      [C6C.SELECT]: ['property_units.*'],
+      [C6C.INDEX_HINTS]: {
+        [C6C.FORCE_INDEX]: ['idx_county_id', 'idx_property_units_location'],
+      },
+      [C6C.WHERE]: {
+        [Property_Units.UNIT_ID]: [C6C.NOT_EQUAL, unitId],
+        [Property_Units.COUNTY_ID]: countyId,
+        [C6C.MBRCONTAINS]: [
+          [C6C.ST_GEOMFROMTEXT, [polygon, 4326]],
+          Property_Units.LOCATION,
+        ],
+        [C6C.LESS_THAN_OR_EQUAL_TO]: [
+          [C6C.ST_DISTANCE_SPHERE, Property_Units.LOCATION, point],
+          1200,
+        ],
+        [C6C.EXISTS]: [
+          [
+            Property_Units.PARCEL_ID,
+            {
+              [C6C.SUBSELECT]: {
+                [C6C.SELECT]: [Parcel_Building_Details.PARCEL_ID],
+                [C6C.FROM]: Parcel_Building_Details.TABLE_NAME,
+                [C6C.WHERE]: {
+                  [Parcel_Building_Details.YEAR_BUILT]: [C6C.BETWEEN, [1988, 2008]],
+                  [Parcel_Building_Details.GLA]: [C6C.BETWEEN, [1876.5, 3127.5]],
+                },
+              },
+            },
+          ],
+          [
+            Property_Units.PARCEL_ID,
+            {
+              [C6C.SUBSELECT]: {
+                [C6C.SELECT]: [Parcel_Sales.PARCEL_ID],
+                [C6C.FROM]: Parcel_Sales.TABLE_NAME,
+                [C6C.WHERE]: {
+                  [Parcel_Sales.SALE_DATE]: [C6C.BETWEEN, ['2023-01-01', '2024-06-30']],
+                  [Parcel_Sales.SALE_PRICE]: [C6C.NOT_EQUAL, 0],
+                },
+              },
+            },
+          ],
+        ],
+      },
+      [C6C.PAGINATION]: {
+        [C6C.LIMIT]: 100,
+        [C6C.ORDER]: {
+          [C6C.ST_DISTANCE_SPHERE]: [Property_Units.LOCATION, point],
+        },
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build(Property_Units.TABLE_NAME);
+
+    expect(sql).toContain('FORCE INDEX (`idx_county_id`, `idx_property_units_location`)');
+    expect(sql).toMatch(/MBRCONTAINS\(ST_GEOMFROMTEXT\('POLYGON\(\(39\.5185659 -105\.0142915, 39\.5401859 -105\.0142915, 39\.5401859 -104\.9862115, 39\.5185659 -104\.9862115, 39\.5185659 -105\.0142915\)\)', 4326\), property_units\.location\)/);
+    expect(sql).toMatch(/ST_DISTANCE_SPHERE\(property_units\.location, ST_GEOMFROMTEXT\('POINT\(39\.5293759 -105\.0002515\)', 4326\)\) <= \?/);
+    expect(sql).toMatch(/\(parcel_building_details\.parcel_id\) = property_units\.parcel_id/);
+    expect(sql).toMatch(/\(parcel_sales\.parcel_id\) = property_units\.parcel_id/);
+    expect(sql).toMatch(/ORDER BY ST[_]Distance[_]Sphere\(property_units\.location, ST_GEOMFROMTEXT\('POINT\(39\.5293759 -105\.0002515\)', 4326\)\)/i);
+
+    expect(params).toHaveLength(10);
+    expect(params[0]).toEqual(unitId);
+    expect(params[1]).toEqual(countyId);
+    expect(params).toContain(1200);
+    expect(params.slice(3, 7)).toEqual([1988, 2008, 1876.5, 3127.5]);
+    expect(params.slice(7)).toEqual(['2023-01-01', '2024-06-30', 0]);
+  });
 });

package/src/__tests__/sqlBuilders.test.ts

@@ -61,6 +61,34 @@ describe('SQL Builders', () => {
     expect(params).toEqual(['BOB', 'SMITH']);
   });
 
+  it('stringifies plain object inserts for JSON columns', () => {
+    const config = buildTestConfig();
+    const payload = { hello: 'world', nested: { ok: true } };
+    const qb = new PostQueryBuilder(config as any, {
+      [C6C.INSERT]: {
+        'actor.json_data': payload,
+      },
+    } as any, false);
+
+    const { sql, params } = qb.build('actor');
+
+    expect(sql).toContain('`json_data`');
+    expect(params).toEqual([JSON.stringify(payload)]);
+  });
+
+  it('throws on operator-shaped insert payloads', () => {
+    const config = buildTestConfig();
+    const qb = new PostQueryBuilder(config as any, {
+      [C6C.INSERT]: {
+        'actor.first_name': {
+          [C6C.GREATER_THAN]: 'ALICE',
+        },
+      },
+    } as any, false);
+
+    expect(() => qb.build('actor')).toThrowError(/requires two operands/);
+  });
+
   it('builds UPDATE with WHERE and pagination', () => {
     const config = buildTestConfig();
     const qb = new UpdateQueryBuilder(config as any, {

package/src/api/C6Constants.ts

@@ -1,6 +1,4 @@
-
 export const C6Constants = {
-
     // try to 1=1 match the Rest abstract class
     ADDDATE: 'ADDDATE',
     ADDTIME: 'ADDTIME',
@@ -34,11 +32,13 @@ export const C6Constants = {
     DESC: 'DESC',
     DISTINCT: 'DISTINCT',
 
+    EXISTS: 'EXISTS',
     EXTRACT: 'EXTRACT',
     EQUAL: '=',
     EQUAL_NULL_SAFE: '<=>',
 
     FALSE: 'FALSE',
+    FORCE: 'FORCE',
     FULL_OUTER: 'FULL_OUTER',
     FROM_DAYS: 'FROM_DAYS',
     FROM_UNIXTIME: 'FROM_UNIXTIME',
@@ -57,6 +57,7 @@ export const C6Constants = {
     HOUR_MINUTE: 'HOUR_MINUTE',
 
     IN: 'IN',
+    INDEX: 'INDEX',
     IS: 'IS',
     IS_NOT: 'IS_NOT',
     INNER: 'INNER',
@@ -77,6 +78,7 @@ export const C6Constants = {
     MAKEDATE: 'MAKEDATE',
     MAKETIME: 'MAKETIME',
     MATCH_AGAINST: 'MATCH_AGAINST',
+    MBRCONTAINS: 'MBRContains',
     MONTHNAME: 'MONTHNAME',
     MICROSECOND: 'MICROSECOND',
     MINUTE: 'MINUTE',
@@ -95,8 +97,16 @@ export const C6Constants = {
     ORDER: 'ORDER',
     OR: 'OR',
 
+    INDEX_HINTS: 'INDEX_HINTS',
+
+    FORCE_INDEX: 'FORCE INDEX',
+    USE_INDEX: 'USE INDEX',
+    IGNORE_INDEX: 'IGNORE INDEX',
+
     PAGE: 'PAGE',
     PAGINATION: 'PAGINATION',
+    POLYGON: 'POLYGON',
+    POINT: 'POINT',
     RIGHT_OUTER: 'RIGHT_OUTER',
 
     SECOND: 'SECOND',

package/src/api/axiosInstance.ts

@@ -151,7 +151,36 @@ axiosInstance.interceptors.request.use((config) => {
         }
     }
 
+    (config as any).__carbonStart = performance.now();
+
     return config;
 });
 
+
+axiosInstance.interceptors.response.use(
+    (response) => {
+        const end = performance.now();
+        const start = (response.config as any).__carbonStart;
+        (response as any).__carbonTiming = {
+            start,
+            end,
+            duration: end - start,
+        };
+        return response;
+    },
+    (error) => {
+        if (error.config) {
+            const end = performance.now();
+            const start = (error.config as any).__carbonStart;
+            (error as any).__carbonTiming = {
+                start,
+                end,
+                duration: end - start,
+            };
+        }
+        throw error;
+    }
+);
+
+
 export default axiosInstance