@carbonorm/carbonnode 6.0.10 → 6.0.13

package/src/executors/SqlExecutor.ts

@@ -6,13 +6,19 @@ import { OrmGenerics } from "../types/ormGenerics";
 import { C6Constants as C6C } from "../constants/C6Constants";
 import {
     DetermineResponseDataType,
+    iCacheResponse,
+    iRestLifecycleResponse,
+    iRestMethods,
+    iRestSqlExecutionContext,
     iRestWebsocketPayload,
 } from "../types/ormInterfaces";
 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";
 
@@ -24,12 +30,20 @@ export class SqlExecutor<
         const { TABLE_NAME } = this.config.restModel;
         const method = this.config.requestMethod;
 
+        await this.runLifecycleHooks<"beforeProcessing">(
+            "beforeProcessing",
+            {
+                config: this.config,
+                request: this.request,
+            },
+        );
+
         // Normalize singular T-shaped requests into complex ORM shape (GET/PUT/DELETE)
         try {
             this.request = normalizeSingularRequest(
-                method as any,
-                this.request as any,
-                this.config.restModel as any,
+                method,
+                this.request,
+                this.config.restModel,
                 undefined
             ) as typeof this.request;
         } catch (e) {
@@ -52,40 +66,55 @@ export class SqlExecutor<
             this.request,
         );
 
+        let response:
+            | DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+
         switch (method) {
             case 'GET': {
                 const rest = await this.runQuery();
                 if (this.config.reactBootstrap) {
+                    const getResponse =
+                        rest as unknown as DetermineResponseDataType<'GET', G['RestTableInterface']>;
+                    const restRows = Array.isArray(getResponse.rest)
+                        ? getResponse.rest
+                        : [getResponse.rest];
                     this.config.reactBootstrap.updateRestfulObjectArrays({
-                        dataOrCallback: (rest as any).rest,
+                        dataOrCallback: restRows,
                         stateKey: this.config.restModel.TABLE_NAME,
-                        uniqueObjectId: this.config.restModel.PRIMARY_SHORT as any,
+                        uniqueObjectId:
+                            this.config.restModel.PRIMARY_SHORT as unknown as (keyof G['RestTableInterface'])[],
                     });
                 }
-                return rest as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                response = rest as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                break;
             }
 
             case 'POST': {
                 const result = await this.runQuery();
                 await this.broadcastWebsocketIfConfigured(result);
-                return result as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                response = result as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                break;
             }
 
             case 'PUT': {
                 const result = await this.runQuery();
                 await this.broadcastWebsocketIfConfigured(result);
-                return result as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                response = result as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                break;
             }
 
             case 'DELETE': {
                 const result = await this.runQuery();
                 await this.broadcastWebsocketIfConfigured(result);
-                return result as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                response = result as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                break;
             }
 
             default:
                 throw new Error(`Unsupported request method: ${method}`);
         }
+
+        return response;
     }
 
     private async withConnection<T>(cb: (conn: PoolConnection) => Promise<T>): Promise<T> {
@@ -222,7 +251,7 @@ export class SqlExecutor<
         const sources = [request, (where && typeof where === "object" && !Array.isArray(where)) ? where : undefined];
         const columns = this.config.restModel.COLUMNS as Record<string, string>;
         const primaryShorts = this.config.restModel.PRIMARY_SHORT ?? [];
-        const primaryFulls = (this.config.restModel as any).PRIMARY ?? [];
+        const primaryFulls = this.config.restModel.PRIMARY ?? [];
         const pkValues: Record<string, any> = {};
 
         for (const pkShort of primaryShorts) {
@@ -272,7 +301,7 @@ export class SqlExecutor<
 
         for (const pk of pkShorts) {
             if (pk in row) {
-                pkValues[pk] = (row as any)[pk];
+                pkValues[pk] = (row as Record<string, any>)[pk];
                 continue;
             }
 
@@ -281,7 +310,7 @@ export class SqlExecutor<
             );
 
             if (fullKey && fullKey in row) {
-                pkValues[pk] = (row as any)[fullKey];
+                pkValues[pk] = (row as Record<string, any>)[fullKey];
             }
         }
 
@@ -454,39 +483,95 @@ export class SqlExecutor<
         }
     }
     async runQuery(): Promise<DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>> {
-        const { TABLE_NAME } = this.config.restModel;
         const method = this.config.requestMethod;
-        let builder: SelectQueryBuilder<G> | UpdateQueryBuilder<G> | DeleteQueryBuilder<G> | PostQueryBuilder<G>;
+        const tableName = this.config.restModel.TABLE_NAME;
+        const logContext = getLogContext(this.config, this.request);
+        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;
+            }
+        }
 
+        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(
+        method: iRestMethods,
+    ): SelectQueryBuilder<G> | UpdateQueryBuilder<G> | DeleteQueryBuilder<G> | PostQueryBuilder<G> {
         switch (method) {
-            case 'GET':
-                builder = new SelectQueryBuilder(this.config, this.request);
-                break;
-            case 'PUT':
-                builder = new UpdateQueryBuilder(this.config, this.request);
-                break;
-            case 'DELETE':
-                builder = new DeleteQueryBuilder(this.config, this.request);
-                break;
-            case 'POST':
-                builder = new PostQueryBuilder(this.config, this.request);
-                break;
+            case C6C.GET:
+                return new SelectQueryBuilder(this.config, this.request);
+            case C6C.PUT:
+                return new UpdateQueryBuilder(this.config, this.request);
+            case C6C.DELETE:
+                return new DeleteQueryBuilder(this.config, this.request);
+            case C6C.POST:
+                return new PostQueryBuilder(this.config, this.request);
             default:
                 throw new Error(`Unsupported query method: ${method}`);
         }
+    }
 
-        const QueryResult = builder.build(TABLE_NAME);
+    private buildSqlExecutionContext(
+        method: iRestMethods,
+        tableName: string,
+        logContext: ReturnType<typeof getLogContext>,
+    ): iRestSqlExecutionContext {
+        const builder = this.getQueryBuilder(method);
+        const queryResult = builder.build(tableName);
 
-        const logContext = getLogContext(this.config, this.request);
         logWithLevel(
             LogLevel.DEBUG,
             logContext,
             console.log,
             `[SQL EXECUTOR] 🧠 Generated ${method.toUpperCase()} SQL:`,
-            QueryResult,
+            queryResult,
         );
 
-        const formatted = this.formatSQLWithParams(QueryResult.sql, QueryResult.params);
+        const formatted = this.formatSQLWithParams(queryResult.sql, queryResult.params);
         logWithLevel(
             LogLevel.DEBUG,
             logContext,
@@ -496,34 +581,152 @@ export class SqlExecutor<
         );
 
         const toUnnamed = namedPlaceholders();
-        const [sql, values] = toUnnamed(QueryResult.sql, QueryResult.params);
+        const [sql, values] = toUnnamed(queryResult.sql, queryResult.params);
+        return { sql, values };
+    }
+
+    private createResponseFromQueryResult(
+        method: iRestMethods,
+        result: any,
+        sqlExecution: iRestSqlExecutionContext,
+        logContext: ReturnType<typeof getLogContext>,
+    ): DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']> {
+        if (method === C6C.GET) {
+            return {
+                rest: result.map(this.serialize),
+                sql: { sql: sqlExecution.sql, values: sqlExecution.values },
+            } as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+        }
+
+        logWithLevel(
+            LogLevel.DEBUG,
+            logContext,
+            console.log,
+            `[SQL EXECUTOR] ✏️ Rows affected:`,
+            result.affectedRows,
+        );
+
+        return {
+            affected: result.affectedRows as number,
+            insertId: result.insertId as number,
+            rest: [],
+            sql: { sql: sqlExecution.sql, values: sqlExecution.values },
+        } as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+    }
 
-        await this.validateSqlAllowList(sql);
+    private createLifecycleHookResponse(
+        response: DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>,
+    ): iRestLifecycleResponse<G> {
+        const data = Object.assign({ success: true }, response);
+        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}`,
+            },
+        };
+    }
 
-        return await this.withConnection(async (conn) => {
-            const [result] = await conn.query<any>(sql, values);
+    private async executeQueryWithLifecycle(
+        conn: PoolConnection,
+        method: iRestMethods,
+        sqlExecution: iRestSqlExecutionContext,
+        logContext: ReturnType<typeof getLogContext>,
+    ): Promise<DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>> {
+        const useTransaction = method !== C6C.GET;
+        let committed = false;
 
-            if (method === 'GET') {
-                return {
-                    rest: result.map(this.serialize),
-                    sql: { sql, values }
-                } as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
-            } else {
+        try {
+            if (useTransaction) {
                 logWithLevel(
                     LogLevel.DEBUG,
                     logContext,
                     console.log,
-                    `[SQL EXECUTOR] ✏️ Rows affected:`,
-                    result.affectedRows,
+                    `[SQL EXECUTOR] 🧾 Beginning transaction`,
                 );
-                return {
-                    affected: result.affectedRows as number,
-                    insertId: result.insertId as number,
-                    rest: [], // TODO - remove rest empty array from non-GET responses?
-                    sql: { sql, values }
-                } as DetermineResponseDataType<G['RequestMethod'], G['RestTableInterface']>;
+                await conn.beginTransaction();
             }
-        });
+
+            await this.validateSqlAllowList(sqlExecution.sql);
+
+            await this.runLifecycleHooks<"beforeExecution">(
+                "beforeExecution",
+                {
+                    config: this.config,
+                    request: this.request,
+                    sqlExecution,
+                },
+            );
+            const [result] = await conn.query<any>(sqlExecution.sql, sqlExecution.values);
+
+            const response = this.createResponseFromQueryResult(
+                method,
+                result,
+                sqlExecution,
+                logContext,
+            );
+            const hookResponse = this.createLifecycleHookResponse(response);
+
+            await this.runLifecycleHooks<"afterExecution">(
+                "afterExecution",
+                {
+                    config: this.config,
+                    request: this.request,
+                    response: hookResponse,
+                },
+            );
+
+            if (useTransaction) {
+                await conn.commit();
+                committed = true;
+                logWithLevel(
+                    LogLevel.DEBUG,
+                    logContext,
+                    console.log,
+                    `[SQL EXECUTOR] 🧾 Transaction committed`,
+                );
+            }
+
+            await this.runLifecycleHooks<"afterCommit">(
+                "afterCommit",
+                {
+                    config: this.config,
+                    request: this.request,
+                    response: hookResponse,
+                },
+            );
+
+            return response;
+        } catch (err) {
+            if (useTransaction && !committed) {
+                try {
+                    await conn.rollback();
+                    logWithLevel(
+                        LogLevel.WARN,
+                        logContext,
+                        console.warn,
+                        `[SQL EXECUTOR] 🧾 Transaction rolled back`,
+                    );
+                } catch (rollbackErr) {
+                    logWithLevel(
+                        LogLevel.ERROR,
+                        logContext,
+                        console.error,
+                        `[SQL EXECUTOR] Rollback failed`,
+                        rollbackErr,
+                    );
+                }
+            }
+            throw err;
+        }
     }
 
     private async validateSqlAllowList(sql: string): Promise<void> {

package/src/handlers/ExpressHandler.ts

@@ -1,27 +1,45 @@
-import type {Request, Response, NextFunction} 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";
+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,
-}: {
-    C6: iC6Object;
-    mysqlPool: Pool;
-    sqlAllowListPath?: string;
-    websocketBroadcast?: tWebsocketBroadcast;
-}) {
-
-    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;
@@ -32,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
@@ -106,10 +134,7 @@ export function ExpressHandler({
             }
 
             const response = await restRequest({
-                C6,
-                mysqlPool,
-                sqlAllowListPath,
-                websocketBroadcast,
+                ...config,
                 requestMethod: method,
                 restModel: C6.TABLES[table]
             })(payload);
@@ -117,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];