@carbonorm/carbonnode 6.0.12 → 6.0.13

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

@@ -3,14 +3,14 @@
   "insertId": 16050,
   "rest": [],
   "sql": {
-    "sql": "INSERT INTO `rental` (\n            `rental_date`, `inventory_id`, `customer_id`, `return_date`, `staff_id`, `last_update`\n         ) VALUES (\n            ?, ?, ?, ?, ?, ?\n        )",
+    "sql": "INSERT INTO `rental` (\n            `rental_date`, `inventory_id`, `customer_id`, `return_date`, `staff_id`, `last_update`\n         ) VALUES\n            (?, ?, ?, ?, ?, ?)",
     "values": [
-      "2026-02-07 21:44:43",
+      "2026-02-08 19:33:00",
       1,
       1,
-      "2026-02-07 21:44:43",
+      "2026-02-08 19:33:00",
       1,
-      "2026-02-07 21:44:43"
+      "2026-02-08 19:33:00"
     ]
   }
 }

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

@@ -2,12 +2,12 @@
   "rest": [
     {
       "rental_id": 16050,
-      "rental_date": "2026-02-07T21:44:43.000Z",
+      "rental_date": "2026-02-08T19:33:00.000Z",
       "inventory_id": 1,
       "customer_id": 1,
-      "return_date": "2026-02-07T21:44:43.000Z",
+      "return_date": "2026-02-08T19:33:00.000Z",
       "staff_id": 1,
-      "last_update": "2026-02-07T21:44:43.000Z"
+      "last_update": "2026-02-08T19:33:00.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-07 21:44:43",
+      "2026-02-08 19:33:00",
       16050
     ]
   }

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

@@ -2,12 +2,12 @@
   "rest": [
     {
       "rental_id": 16050,
-      "rental_date": "2026-02-07T21:44:43.000Z",
+      "rental_date": "2026-02-08T19:33:00.000Z",
       "inventory_id": 1,
       "customer_id": 1,
-      "return_date": "2026-02-07T21:44:43.000Z",
+      "return_date": "2026-02-08T19:33:00.000Z",
       "staff_id": 1,
-      "last_update": "2026-02-07T21:44:43.000Z"
+      "last_update": "2026-02-08T19:33:00.000Z"
     }
   ],
   "sql": {

package/src/__tests__/sqlBuilders.test.ts

@@ -96,6 +96,52 @@ describe('SQL Builders', () => {
     expect(params).toEqual([JSON.stringify(payload)]);
   });
 
+  it('builds multi-row INSERT from dataInsertMultipleRows', () => {
+    const config = buildTestConfig();
+    const qb = new PostQueryBuilder(config as any, {
+      dataInsertMultipleRows: [
+        {
+          'actor.first_name': 'ALICE',
+          'actor.last_name': 'ONE',
+        },
+        {
+          'actor.first_name': 'BOB',
+          'actor.last_name': 'TWO',
+        },
+      ],
+    } as any, false);
+
+    const { sql, params } = qb.build('actor');
+
+    expect(sql).toContain('INSERT INTO `actor`');
+    expect(sql).toContain('`first_name`, `last_name`');
+    expect(sql).toContain(') VALUES');
+    expect(sql).toContain('),');
+    expect(params).toEqual(['ALICE', 'ONE', 'BOB', 'TWO']);
+  });
+
+  it('builds multi-row INSERT from direct array request syntax', () => {
+    const config = buildTestConfig();
+    const qb = new PostQueryBuilder(config as any, [
+      {
+        'actor.first_name': 'ALICE',
+        'actor.last_name': 'ONE',
+      },
+      {
+        'actor.first_name': 'BOB',
+        'actor.last_name': 'TWO',
+      },
+    ] as any, false);
+
+    const { sql, params } = qb.build('actor');
+
+    expect(sql).toContain('INSERT INTO `actor`');
+    expect(sql).toContain('`first_name`, `last_name`');
+    expect(sql).toContain(') VALUES');
+    expect(sql).toContain('),');
+    expect(params).toEqual(['ALICE', 'ONE', 'BOB', 'TWO']);
+  });
+
   it('stringifies dotted-key JSON payloads for JSON columns on UPDATE', () => {
     const config = buildTestConfig();
     const payload = { 'section1.preparedBy': 'Prepared by Assessorly, Co.' };

package/src/api/convertForRequestBody.ts

@@ -11,7 +11,11 @@ export default function <
     restfulObject: RequestQueryBody<RequestMethod, RestTableInterface, CustomAndRequiredFields, RequestTableOverrides>,
     tableName: string | string[],
     C6: iC6Object,
-    regexErrorHandler: (message: string) => void = alert
+    regexErrorHandler: (message: string) => void = (message: string) => {
+        if (typeof globalThis !== "undefined" && typeof (globalThis as any).alert === "function") {
+            (globalThis as any).alert(message);
+        }
+    }
 ) {
     const payload: Record<string, any> = {};
     const tableNames = Array.isArray(tableName) ? tableName : [tableName];
@@ -43,7 +47,8 @@ export default function <
                 C6Constants.DELETE,
                 C6Constants.WHERE,
                 C6Constants.JOIN,
-                C6Constants.PAGINATION
+                C6Constants.PAGINATION,
+                "cacheResults",
             ].includes(value)) {
                 const val = restfulObject[value];
                 if (Array.isArray(val)) {
@@ -52,6 +57,8 @@ export default function <
                     payload[value] = Object.keys(val)
                         .sort()
                         .reduce((acc, key) => ({ ...acc, [key]: val[key] }), {});
+                } else {
+                    payload[value] = val;
                 }
                 continue;
             }

package/src/api/restRequest.ts

@@ -34,6 +34,7 @@ export default function restRequest<
         const config = typeof configX === "function" ? configX() : configX;
 
         applyLogLevelDefaults(config, request);
+
         const logContext = getLogContext(config, request);
 
         if (!config.mysqlPool && !config.axios) {

package/src/executors/HttpExecutor.ts

@@ -257,7 +257,7 @@ export class HttpExecutor<
             // 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: AxiosPromise<ResponseDataType> | false = false;
+            let cachedRequest: Promise<{ data: ResponseDataType }> | false = false;
 
             if (cacheResults) {
                 cachedRequest = checkCache<ResponseDataType>(requestMethod, tableName, cacheRequestData);

package/src/executors/SqlExecutor.ts

@@ -6,6 +6,7 @@ import { OrmGenerics } from "../types/ormGenerics";
 import { C6Constants as C6C } from "../constants/C6Constants";
 import {
     DetermineResponseDataType,
+    iCacheResponse,
     iRestLifecycleResponse,
     iRestMethods,
     iRestSqlExecutionContext,
@@ -15,7 +16,9 @@ import namedPlaceholders from 'named-placeholders';
 import type { PoolConnection } from 'mysql2/promise';
 import { Buffer } from 'buffer';
 import { Executor } from "./Executor";
+import {checkCache, setCache} from "../utils/cacheManager";
 import { normalizeSingularRequest } from "../utils/normalizeSingularRequest";
+import {sortAndSerializeQueryObject} from "../utils/sortAndSerializeQueryObject";
 import { loadSqlAllowList, normalizeSql } from "../utils/sqlAllowList";
 import { getLogContext, LogLevel, logWithLevel } from "../utils/logLevel";
 
@@ -483,11 +486,56 @@ export class SqlExecutor<
         const method = this.config.requestMethod;
         const tableName = this.config.restModel.TABLE_NAME;
         const logContext = getLogContext(this.config, this.request);
-        const sqlExecution = this.buildSqlExecutionContext(method, tableName, logContext);
+        const cacheResults = method === C6C.GET
+            && !this.config.sqlAllowListPath
+            && (this.request as { cacheResults?: boolean })?.cacheResults !== false;
+
+        const cacheRequestData = cacheResults
+            ? JSON.parse(JSON.stringify(this.request ?? {}))
+            : undefined;
+
+        const requestArgumentsSerialized = cacheResults
+            ? sortAndSerializeQueryObject(tableName, cacheRequestData ?? {})
+            : undefined;
+
+        if (cacheResults) {
+            const cachedRequest = checkCache<DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>>(
+                method,
+                tableName,
+                cacheRequestData,
+            );
+            if (cachedRequest) {
+                return (await cachedRequest).data;
+            }
+        }
 
-        return await this.withConnection(async (conn) =>
+        const sqlExecution = this.buildSqlExecutionContext(method, tableName, logContext);
+        const queryPromise = this.withConnection(async (conn) =>
             this.executeQueryWithLifecycle(conn, method, sqlExecution, logContext),
         );
+
+        if (!cacheResults || !cacheRequestData || !requestArgumentsSerialized) {
+            return await queryPromise;
+        }
+
+        const cacheRequest = queryPromise.then((data) =>
+            this.createCacheResponseEnvelope(method, tableName, data),
+        );
+
+        setCache(method, tableName, cacheRequestData, {
+            requestArgumentsSerialized,
+            request: cacheRequest,
+        });
+
+        const cacheResponse = await cacheRequest;
+        setCache(method, tableName, cacheRequestData, {
+            requestArgumentsSerialized,
+            request: cacheRequest,
+            response: cacheResponse,
+            final: true,
+        });
+
+        return cacheResponse.data;
     }
 
     private getQueryBuilder(
@@ -573,6 +621,20 @@ export class SqlExecutor<
         return { data };
     }
 
+    private createCacheResponseEnvelope(
+        method: iRestMethods,
+        tableName: string,
+        data: DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>,
+    ): iCacheResponse<DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>> {
+        return {
+            data,
+            config: {
+                method: method.toLowerCase(),
+                url: `/rest/${tableName}`,
+            },
+        };
+    }
+
     private async executeQueryWithLifecycle(
         conn: PoolConnection,
         method: iRestMethods,

package/src/handlers/ExpressHandler.ts

@@ -1,42 +1,45 @@
-import type {Request, Response, NextFunction, Router} from "express";
-import type {Pool} from "mysql2/promise";
+import type {Request, Response, Router} from "express";
 import {C6C} from "../constants/C6Constants";
 import restRequest from "../api/restRequest";
-import type {iC6Object, iRestMethods, tWebsocketBroadcast} from "../types/ormInterfaces";
+import {iRest, iRestMethods} from "../types/ormInterfaces";
 import {LogLevel, logWithLevel} from "../utils/logLevel";
-
-type iExpressHandlerConfig = {
-    C6: iC6Object;
-    mysqlPool: Pool;
-    sqlAllowListPath?: string;
-    websocketBroadcast?: tWebsocketBroadcast;
-};
-
-type iRestExpressRequestConfig = iExpressHandlerConfig & {
-    router: Pick<Router, "all">;
-    routePath?: string;
-};
-
-export function restExpressRequest({
-    router,
-    routePath = "/rest/:table{/:primary}",
-    ...handlerConfig
-}: iRestExpressRequestConfig) {
-    router.all(routePath, ExpressHandler(handlerConfig));
+import {OrmGenerics} from "../types/ormGenerics";
+
+
+export function restExpressRequest<G extends OrmGenerics>(
+    routerConfig: {
+        router: Pick<Router, "all">;
+        routePath?: string;
+    } &
+        Omit<
+            iRest<G['RestShortTableName'], G['RestTableInterface']>,
+            "requestMethod" | "restModel"
+        >
+) {
+    const {router, routePath = "/rest/:table{/:primary}", ...handlerConfig} = routerConfig;
+
+    router.all(routePath, ExpressHandler<G>(handlerConfig));
 }
 
-
 // TODO - WE MUST make this a generic - optional, but helpful
 // note sure how it would help anyone actually...
-export function ExpressHandler({
-    C6,
-    mysqlPool,
-    sqlAllowListPath,
-    websocketBroadcast,
-}: iExpressHandlerConfig) {
-
-    return async (req: Request, res: Response, next: NextFunction) => {
+export function ExpressHandler<
+    G extends OrmGenerics
+>(configX: (() => Omit<
+    iRest<G['RestShortTableName'], G['RestTableInterface']>,
+    "requestMethod" | "restModel"
+>) | Omit<
+    iRest<G['RestShortTableName'], G['RestTableInterface']>,
+    "requestMethod" | "restModel"
+>) {
+
+    return async (req: Request, res: Response) => {
         try {
+            const config = typeof configX === "function" ? configX() : configX;
+            const {
+                C6
+            } = config;
+
             const incomingMethod = req.method.toUpperCase() as iRestMethods;
             const table = req.params.table;
             let primary = req.params.primary;
@@ -47,11 +50,21 @@ export function ExpressHandler({
             const treatAsGet = incomingMethod === 'POST' && methodOverride === 'GET';
 
             const method: iRestMethods = treatAsGet ? 'GET' : incomingMethod;
-            const payload: any = treatAsGet ? { ...(req.body as any) } : (method === 'GET' ? req.query : req.body);
+            const payload: any = treatAsGet ? {...(req.body as any)} : (method === 'GET' ? req.query : req.body);
+
+            // Query strings are text; coerce known boolean controls.
+            if (typeof payload?.cacheResults === "string") {
+                const normalized = payload.cacheResults.toLowerCase();
+                if (normalized === "false") payload.cacheResults = false;
+                if (normalized === "true") payload.cacheResults = true;
+            }
 
             // Remove transport-only METHOD flag so it never leaks into ORM parsing
             if (treatAsGet && 'METHOD' in payload) {
-                try { delete (payload as any).METHOD } catch { /* noop */ }
+                try {
+                    delete (payload as any).METHOD
+                } catch { /* noop */
+                }
             }
 
             // Warn for unsupported overrides but continue normally
@@ -121,10 +134,7 @@ export function ExpressHandler({
             }
 
             const response = await restRequest({
-                C6,
-                mysqlPool,
-                sqlAllowListPath,
-                websocketBroadcast,
+                ...config,
                 requestMethod: method,
                 restModel: C6.TABLES[table]
             })(payload);
@@ -132,8 +142,9 @@ export function ExpressHandler({
             res.status(200).json({success: true, ...response});
 
         } catch (err) {
-            res.status(500).json({success: false, error: err});
-            next(err);
+            const message = err instanceof Error ? err.message : String(err);
+            logWithLevel(LogLevel.ERROR, undefined, console.error, message);
+            res.status(500).json({success: false, error: message});
         }
     };
 }

package/src/orm/builders/ConditionBuilder.ts

@@ -444,9 +444,51 @@ export abstract class ConditionBuilder<
             return this.addParam(params, contextColumn ?? '', JSON.stringify(normalized));
         }
 
-        const { sql, isReference, isExpression, isSubSelect } = this.serializeOperand(normalized, params, contextColumn);
+        let sql: string;
+        let isReference: boolean;
+        let isExpression: boolean;
+        let isSubSelect: boolean;
+
+        const shouldStringifyObjectFallback = (candidate: any): boolean => {
+            if (
+                typeof candidate !== 'object'
+                || candidate === null
+                || candidate instanceof Date
+                || (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(candidate))
+            ) {
+                return false;
+            }
+
+            const normalizedCandidate = candidate instanceof Map
+                ? Object.fromEntries(candidate)
+                : candidate;
+            const entries = Object.entries(normalizedCandidate as Record<string, any>);
+
+            if (entries.length !== 1) {
+                return true;
+            }
+
+            const [key] = entries[0];
+            if (this.isOperator(key) || this.BOOLEAN_OPERATORS.has(key)) {
+                return false;
+            }
+
+            return true;
+        };
+
+        try {
+            ({ sql, isReference, isExpression, isSubSelect } = this.serializeOperand(normalized, params, contextColumn));
+        } catch (err) {
+            if (shouldStringifyObjectFallback(normalized)) {
+                return this.addParam(params, contextColumn ?? '', JSON.stringify(normalized));
+            }
+            throw err;
+        }
 
         if (!isReference && !isExpression && !isSubSelect && typeof normalized === 'object' && normalized !== null) {
+            if (shouldStringifyObjectFallback(normalized)) {
+                return this.addParam(params, contextColumn ?? '', JSON.stringify(normalized));
+            }
             throw new Error('Unsupported operand type in SQL expression.');
         }
 

package/src/orm/queries/PostQueryBuilder.ts

@@ -18,25 +18,37 @@ export class PostQueryBuilder<G extends OrmGenerics> extends ConditionBuilder<G>
     build(table: string) {
         this.aliasMap = {};
         const verb = C6C.REPLACE in this.request ? C6C.REPLACE : C6C.INSERT;
-        const body = verb in this.request ? this.request[verb] : this.request;
-        const keys = Object.keys(body);
+        const directRows = Array.isArray(this.request)
+            ? this.request
+            : [];
+        const rows: Record<string, any>[] = directRows.length > 0
+            ? directRows
+            : Array.isArray(this.request.dataInsertMultipleRows) &&
+            this.request.dataInsertMultipleRows.length > 0
+                ? this.request.dataInsertMultipleRows
+                : [verb in this.request ? this.request[verb] : this.request];
+        const keys = Object.keys(rows[0] ?? {});
         const params: any[] | Record<string, any> = this.useNamedParams ? {} : [];
-        const placeholders: string[] = []
+        const rowPlaceholders: string[] = [];
 
+        for (const row of rows) {
+            const placeholders: string[] = [];
 
-        for (const key of keys) {
-            const value = body[key];
-            const trimmed = this.trimTablePrefix(table, key);
-            const qualified = `${table}.${trimmed}`;
-            const placeholder = this.serializeUpdateValue(value, params, qualified);
-            placeholders.push(placeholder);
+            for (const key of keys) {
+                const value = row[key] ?? null;
+                const trimmed = this.trimTablePrefix(table, key);
+                const qualified = `${table}.${trimmed}`;
+                const placeholder = this.serializeUpdateValue(value, params, qualified);
+                placeholders.push(placeholder);
+            }
+
+            rowPlaceholders.push(`(${placeholders.join(', ')})`);
         }
 
         let sql = `${verb} INTO \`${table}\` (
             ${keys.map(k => `\`${this.trimTablePrefix(table, k)}\``).join(', ')}
-         ) VALUES (
-            ${placeholders.join(', ')}
-        )`;
+         ) VALUES
+            ${rowPlaceholders.join(',\n            ')}`;
 
         if (C6C.UPDATE in this.request) {
             const updateData = this.request[C6C.UPDATE];

package/src/types/ormInterfaces.ts

@@ -1,4 +1,4 @@
-import type {AxiosInstance, AxiosPromise, AxiosResponse} from "axios";
+import type {AxiosInstance, AxiosResponse} from "axios";
 import type {Pool} from "mysql2/promise";
 import {eFetchDependencies} from "./dynamicFetching";
 import {Modify} from "./modifyTypes";
@@ -101,10 +101,22 @@ export type RequestQueryBody<
     ? iAPI<RequestGetPutDeleteBody<Modify<T, Overrides> & Custom>>
     : iAPI<RequestPostBody<Modify<T, Overrides> & Custom>>;
 
+export interface iCacheRequestConfig {
+    method?: string;
+    url?: string;
+    headers?: any;
+}
+
+export interface iCacheResponse<ResponseDataType = any> {
+    data: ResponseDataType;
+    config?: iCacheRequestConfig;
+    [key: string]: any;
+}
+
 export interface iCacheAPI<ResponseDataType = any> {
     requestArgumentsSerialized: string;
-    request: AxiosPromise<ResponseDataType>;
-    response?: AxiosResponse & {
+    request: Promise<iCacheResponse<ResponseDataType>>;
+    response?: iCacheResponse<ResponseDataType> & {
         __carbonTiming?: {
             start: number;
             end: number;

package/src/utils/cacheManager.ts

@@ -1,5 +1,4 @@
-import type {AxiosPromise} from "axios";
-import type {iCacheAPI} from "../types/ormInterfaces";
+import type {iCacheAPI, iCacheResponse} from "../types/ormInterfaces";
 import {LogLevel, logWithLevel, shouldLog} from "./logLevel";
 
 // -----------------------------------------------------------------------------
@@ -61,13 +60,13 @@ export function checkCache<ResponseDataType = any>(
     method: string,
     tableName: string | string[],
     requestData: any,
-): AxiosPromise<ResponseDataType> | false {
+): Promise<iCacheResponse<ResponseDataType>> | false {
     const key = makeCacheKey(method, tableName, requestData);
     const cached = apiRequestCache.get(key);
 
     if (!cached) return false;
 
-    if (shouldLog(LogLevel.DEBUG, undefined)) {
+    if (shouldLog(LogLevel.INFO, undefined)) {
         console.groupCollapsed(
             `%c API cache hit for ${method} ${tableName}`,
             "color:#0c0",

package/src/utils/colorSql.ts

@@ -73,6 +73,23 @@ function collapseBinds(sql: string): string {
     );
 }
 
+/**
+ * ( ? ×9 ), ( ? ×9 ), ( ? ×9 )  ->  ( ? ×9 ) ×3
+ */
+function collapseRepeatedValueRows(sql: string): string {
+    const repeatedRowPattern =
+        /(\((?:\x1b\[[0-9;]*m)?\?\s*×\d+(?:\x1b\[[0-9;]*m)?\)|\(\s*(?:\?\s*,\s*)+\?\s*\))(?:\s*,\s*\1){2,}/g;
+
+    return sql.replace(repeatedRowPattern, (match, row: string) => {
+        const rowMatches = match.match(new RegExp(row.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "g"));
+        const count = rowMatches?.length ?? 1;
+        const normalizedRow = row.includes("×")
+            ? row
+            : `(${C.DIM}? ×${(row.match(/\?/g) ?? []).length}${RESET})`;
+        return `${normalizedRow} ${C.DIM}×${count}${RESET}`;
+    });
+}
+
 /* ---------- main formatter ---------- */
 
 export default function colorSql(sql: string): string {
@@ -80,6 +97,7 @@ export default function colorSql(sql: string): string {
 
     /* 1️⃣ collapse bind noise */
     s = collapseBinds(s);
+    s = collapseRepeatedValueRows(s);
 
     /* 2️⃣ table.column coloring (core visual grouping) */
     s = s.replace(