@carbonorm/carbonnode 6.0.20 → 6.1.1

package/src/orm/utils/sqlUtils.ts

@@ -1,6 +1,3 @@
-
-
-
 export interface SqlBuilderResult {
     sql: string;
     params: any[] | { [key: string]: any };  // params can be an array or an object for named placeholders
@@ -16,9 +13,180 @@ export function convertHexIfBinary(
         typeof val === 'string' &&
         /^[0-9a-fA-F]{32}$/.test(val) &&
         typeof columnDef === 'object' &&
-        columnDef.MYSQL_TYPE.toUpperCase().includes('BINARY')
+        String(columnDef.MYSQL_TYPE ?? '').toUpperCase().includes('BINARY')
     ) {
         return Buffer.from(val, 'hex');
     }
     return val;
 }
+
+type TemporalMysqlType = 'date' | 'datetime' | 'timestamp' | 'time' | 'year';
+
+const TEMPORAL_TYPES = new Set<TemporalMysqlType>([
+    'date',
+    'datetime',
+    'timestamp',
+    'time',
+    'year',
+]);
+
+const MYSQL_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
+const MYSQL_DATETIME_REGEX = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}(?:\.\d{1,6})?$/;
+const MYSQL_TIME_REGEX = /^-?\d{2,3}:\d{2}:\d{2}(?:\.\d{1,6})?$/;
+const ISO_DATETIME_REGEX = /^(\d{4}-\d{2}-\d{2})[Tt](\d{2}:\d{2}:\d{2})(\.\d{1,6})?([zZ]|[+-]\d{2}:\d{2})?$/;
+
+const pad2 = (value: number): string => value.toString().padStart(2, '0');
+
+function trimFraction(value: string, precision: number): string {
+    const [base, fractionRaw] = value.split('.', 2);
+    if (precision <= 0 || !fractionRaw) return base;
+    return `${base}.${fractionRaw.slice(0, precision).padEnd(precision, '0')}`;
+}
+
+function normalizeFraction(raw: string | undefined, precision: number): string {
+    if (precision <= 0) return '';
+    if (!raw) return '';
+    const digits = raw.startsWith('.') ? raw.slice(1) : raw;
+    return `.${digits.slice(0, precision).padEnd(precision, '0')}`;
+}
+
+function formatDateUtc(value: Date): string {
+    return `${value.getUTCFullYear()}-${pad2(value.getUTCMonth() + 1)}-${pad2(value.getUTCDate())}`;
+}
+
+function formatTimeUtc(value: Date, precision: number): string {
+    const base = `${pad2(value.getUTCHours())}:${pad2(value.getUTCMinutes())}:${pad2(value.getUTCSeconds())}`;
+    if (precision <= 0) return base;
+
+    const millis = value.getUTCMilliseconds().toString().padStart(3, '0');
+    const fraction = millis.slice(0, Math.min(precision, 3)).padEnd(precision, '0');
+    return `${base}.${fraction}`;
+}
+
+function formatDateTimeUtc(value: Date, precision: number): string {
+    return `${formatDateUtc(value)} ${formatTimeUtc(value, precision)}`;
+}
+
+function parseEpochNumber(value: number): Date | undefined {
+    if (!Number.isFinite(value)) return undefined;
+    const abs = Math.abs(value);
+    if (abs >= 1e12) {
+        const date = new Date(value);
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
+    if (abs >= 1e9) {
+        const date = new Date(value * 1000);
+        return Number.isNaN(date.getTime()) ? undefined : date;
+    }
+    return undefined;
+}
+
+function parseTemporalType(columnDef?: any): { baseType?: TemporalMysqlType; precision: number } {
+    const raw = String(columnDef?.MYSQL_TYPE ?? '').trim().toLowerCase();
+    if (!raw) return { baseType: undefined, precision: 0 };
+
+    const base = raw.split(/[\s(]/, 1)[0] as TemporalMysqlType;
+    if (!TEMPORAL_TYPES.has(base)) return { baseType: undefined, precision: 0 };
+
+    const precisionMatch = raw.match(/^(?:datetime|timestamp|time)\((\d+)\)/);
+    if (!precisionMatch) return { baseType: base, precision: 0 };
+    const parsed = Number.parseInt(precisionMatch[1], 10);
+    if (!Number.isFinite(parsed)) return { baseType: base, precision: 0 };
+    return { baseType: base, precision: Math.max(0, Math.min(6, parsed)) };
+}
+
+function normalizeTemporalString(
+    value: string,
+    baseType: TemporalMysqlType,
+    precision: number,
+): string {
+    const trimmed = value.trim();
+    if (!trimmed) return value;
+
+    if (baseType === 'date') {
+        if (MYSQL_DATE_REGEX.test(trimmed)) return trimmed;
+        const iso = trimmed.match(ISO_DATETIME_REGEX);
+        if (iso) {
+            const [, datePart, , , timezonePart] = iso;
+            if (!timezonePart) return datePart;
+            const parsed = new Date(trimmed);
+            return Number.isNaN(parsed.getTime()) ? value : formatDateUtc(parsed);
+        }
+        const parsed = new Date(trimmed);
+        return Number.isNaN(parsed.getTime()) ? value : formatDateUtc(parsed);
+    }
+
+    if (baseType === 'time') {
+        if (MYSQL_TIME_REGEX.test(trimmed)) return trimFraction(trimmed, precision);
+        const iso = trimmed.match(ISO_DATETIME_REGEX);
+        if (iso) {
+            const [, , timePart, fractionPart, timezonePart] = iso;
+            if (!timezonePart) {
+                return `${timePart}${normalizeFraction(fractionPart, precision)}`;
+            }
+            const parsed = new Date(trimmed);
+            return Number.isNaN(parsed.getTime()) ? value : formatTimeUtc(parsed, precision);
+        }
+        const parsed = new Date(trimmed);
+        return Number.isNaN(parsed.getTime()) ? value : formatTimeUtc(parsed, precision);
+    }
+
+    if (baseType === 'year') {
+        if (/^\d{2,4}$/.test(trimmed)) return trimmed;
+        const parsed = new Date(trimmed);
+        return Number.isNaN(parsed.getTime()) ? value : String(parsed.getUTCFullYear());
+    }
+
+    if (MYSQL_DATETIME_REGEX.test(trimmed)) return trimFraction(trimmed, precision);
+    const iso = trimmed.match(ISO_DATETIME_REGEX);
+    if (iso) {
+        const [, datePart, timePart, fractionPart, timezonePart] = iso;
+        if (!timezonePart) {
+            return `${datePart} ${timePart}${normalizeFraction(fractionPart, precision)}`;
+        }
+        const parsed = new Date(trimmed);
+        return Number.isNaN(parsed.getTime()) ? value : formatDateTimeUtc(parsed, precision);
+    }
+
+    const parsed = new Date(trimmed);
+    return Number.isNaN(parsed.getTime()) ? value : formatDateTimeUtc(parsed, precision);
+}
+
+function convertTemporalIfNeeded(value: any, columnDef?: any): any {
+    const { baseType, precision } = parseTemporalType(columnDef);
+    if (!baseType) return value;
+
+    if (value === null || value === undefined) return value;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer && Buffer.isBuffer(value)) return value;
+
+    if (value instanceof Date) {
+        if (baseType === 'date') return formatDateUtc(value);
+        if (baseType === 'time') return formatTimeUtc(value, precision);
+        if (baseType === 'year') return String(value.getUTCFullYear());
+        return formatDateTimeUtc(value, precision);
+    }
+
+    if (typeof value === 'number') {
+        const parsed = parseEpochNumber(value);
+        if (!parsed) return value;
+        if (baseType === 'date') return formatDateUtc(parsed);
+        if (baseType === 'time') return formatTimeUtc(parsed, precision);
+        if (baseType === 'year') return String(parsed.getUTCFullYear());
+        return formatDateTimeUtc(parsed, precision);
+    }
+
+    if (typeof value === 'string') {
+        return normalizeTemporalString(value, baseType, precision);
+    }
+
+    return value;
+}
+
+export function convertSqlValueForColumn(
+    col: string,
+    val: any,
+    columnDef?: any
+): any {
+    const binaryConverted = convertHexIfBinary(col, val, columnDef);
+    return convertTemporalIfNeeded(binaryConverted, columnDef);
+}

package/src/types/mysqlTypes.ts

@@ -1,15 +1,119 @@
-
 // ========================
-// 🔧 SQL Operator & Helpers
+// SQL Operators & Expressions
 // ========================
 
-export type SQLFunction =
-    | 'COUNT'
-    | 'GROUP_CONCAT'
-    | 'MAX'
-    | 'MIN'
-    | 'SUM'
-    | 'DISTINCT';
+export const SQL_KNOWN_FUNCTIONS = [
+    'ADDDATE',
+    'ADDTIME',
+    'CONCAT',
+    'CONVERT_TZ',
+    'COUNT',
+    'COUNT_ALL',
+    'CURRENT_DATE',
+    'CURRENT_TIMESTAMP',
+    'DAY',
+    'DAY_HOUR',
+    'DAY_MICROSECOND',
+    'DAY_MINUTE',
+    'DAY_SECOND',
+    'DAYNAME',
+    'DAYOFMONTH',
+    'DAYOFWEEK',
+    'DAYOFYEAR',
+    'DATE',
+    'DATE_ADD',
+    'DATEDIFF',
+    'DATE_SUB',
+    'DATE_FORMAT',
+    'EXTRACT',
+    'FROM_DAYS',
+    'FROM_UNIXTIME',
+    'GET_FORMAT',
+    'GROUP_CONCAT',
+    'HEX',
+    'HOUR',
+    'HOUR_MICROSECOND',
+    'HOUR_MINUTE',
+    'HOUR_SECOND',
+    'INTERVAL',
+    'LOCALTIME',
+    'LOCALTIMESTAMP',
+    'MAKEDATE',
+    'MAKETIME',
+    'MAX',
+    'MBRContains',
+    'MICROSECOND',
+    'MIN',
+    'MINUTE',
+    'MINUTE_MICROSECOND',
+    'MINUTE_SECOND',
+    'MONTH',
+    'MONTHNAME',
+    'NOW',
+    'POINT',
+    'POLYGON',
+    'SECOND',
+    'SECOND_MICROSECOND',
+    'ST_Area',
+    'ST_AsBinary',
+    'ST_AsText',
+    'ST_Buffer',
+    'ST_Contains',
+    'ST_Crosses',
+    'ST_Difference',
+    'ST_Dimension',
+    'ST_Disjoint',
+    'ST_Distance',
+    'ST_Distance_Sphere',
+    'ST_EndPoint',
+    'ST_Envelope',
+    'ST_Equals',
+    'ST_GeomFromGeoJSON',
+    'ST_GeomFromText',
+    'ST_GeomFromWKB',
+    'ST_Intersects',
+    'ST_Length',
+    'ST_MakeEnvelope',
+    'ST_Overlaps',
+    'ST_Point',
+    'ST_SetSRID',
+    'ST_SRID',
+    'ST_StartPoint',
+    'ST_SymDifference',
+    'ST_Touches',
+    'ST_Union',
+    'ST_Within',
+    'ST_X',
+    'ST_Y',
+    'STR_TO_DATE',
+    'SUBDATE',
+    'SUBTIME',
+    'SUM',
+    'SYSDATE',
+    'TIME',
+    'TIME_FORMAT',
+    'TIME_TO_SEC',
+    'TIMEDIFF',
+    'TIMESTAMP',
+    'TIMESTAMPADD',
+    'TIMESTAMPDIFF',
+    'TO_DAYS',
+    'TO_SECONDS',
+    'TRANSACTION_TIMESTAMP',
+    'UNHEX',
+    'UNIX_TIMESTAMP',
+    'UTC_DATE',
+    'UTC_TIME',
+    'UTC_TIMESTAMP',
+    'WEEKDAY',
+    'WEEKOFYEAR',
+    'YEARWEEK',
+] as const;
+
+export type SQLKnownFunction = typeof SQL_KNOWN_FUNCTIONS[number];
+
+// Backwards alias for existing public import name.
+export type SQLFunction = SQLKnownFunction;
 
 export type SQLComparisonOperator =
     | '='
@@ -31,3 +135,20 @@ export type JoinType = 'INNER' | 'LEFT_OUTER' | 'RIGHT_OUTER';
 
 export type OrderDirection = 'ASC' | 'DESC';
 
+export type SQLExpression =
+    | string
+    | number
+    | boolean
+    | null
+    | SQLExpressionTuple;
+
+export type SQLExpressionTuple =
+    | ['AS', SQLExpression, string]
+    | ['DISTINCT', SQLExpression]
+    | ['CALL', string, ...SQLExpression[]]
+    | ['LIT', any]
+    | ['PARAM', any]
+    | ['SUBSELECT', Record<string, any>]
+    | [SQLKnownFunction, ...SQLExpression[]];
+
+export type OrderTerm = [SQLExpression, OrderDirection?];

package/src/types/ormInterfaces.ts

@@ -2,7 +2,7 @@ import type {AxiosInstance, AxiosResponse} from "axios";
 import type {Pool} from "mysql2/promise";
 import {eFetchDependencies} from "./dynamicFetching";
 import {Modify} from "./modifyTypes";
-import {JoinType, OrderDirection, SQLComparisonOperator, SQLFunction} from "./mysqlTypes";
+import {JoinType, OrderTerm, SQLComparisonOperator, SQLExpression} from "./mysqlTypes";
 import type {CarbonReact, iStateAdapter} from "@carbonorm/carbonreact";
 import type {OrmGenerics} from "./ormGenerics";
 import {restOrm} from "../api/restOrm";
@@ -49,9 +49,7 @@ export type SubSelect<T extends { [key: string]: any } = any> = {
 
 export type SelectField<T extends { [key: string]: any } = any> =
     | keyof T
-    | [keyof T, 'AS', string]
-    | [SQLFunction, keyof T]
-    | [SQLFunction, keyof T, string]
+    | SQLExpression
     | SubSelect<T>;
 
 export type WhereClause<T = any> = Partial<T> | LogicalGroup<T> | ComparisonClause<T>;
@@ -62,10 +60,10 @@ export type JoinTableCondition<T = any> = Partial<T> | WhereClause<T>[] | Compar
 export type JoinClause<T = any> = { [table: string]: JoinTableCondition<T>; };
 export type Join<T = any> = { [K in JoinType]?: JoinClause<T>; };
 
-export type Pagination<T = any> = {
+export type Pagination = {
     PAGE?: number;
     LIMIT?: number | null;
-    ORDER?: Partial<Record<keyof T, OrderDirection>>;
+    ORDER?: OrderTerm[];
 };
 
 export type RequestGetPutDeleteBody<T extends { [key: string]: any } = any> = T | {
@@ -74,7 +72,7 @@ export type RequestGetPutDeleteBody<T extends { [key: string]: any } = any> = T
     DELETE?: boolean;
     WHERE?: WhereClause<T>;
     JOIN?: Join<T>;
-    PAGINATION?: Pagination<T>;
+    PAGINATION?: Pagination;
 };
 
 export type RequestPostBody<T extends { [key: string]: any } = any> = T | {
@@ -85,6 +83,7 @@ export type RequestPostBody<T extends { [key: string]: any } = any> = T | {
 export type iAPI<T extends { [key: string]: any }> = T & {
     dataInsertMultipleRows?: T[];
     cacheResults?: boolean;
+    skipReactBootstrap?: boolean;
     fetchDependencies?: number | eFetchDependencies | Awaited<iGetC6RestResponse<any>>[];
     debug?: boolean;
     success?: string | ((r: AxiosResponse) => string | void);
@@ -236,6 +235,7 @@ export interface iRest<
     logLevel?: number;
     verbose?: boolean;
     sqlAllowListPath?: string;
+    sqlQueryNormalizer?: (sql: string) => string;
 }
 
 export interface iConstraint {

package/src/utils/normalizeSingularRequest.ts

@@ -19,7 +19,7 @@ export function normalizeSingularRequest<
 ): RequestQueryBody<Method, T, Custom, Overrides> {
   if (request == null || typeof request !== 'object') return request;
 
-  const specialKeys = new Set([
+  const specialKeys: Set<string> = new Set([
     C6C.SELECT,
     C6C.UPDATE,
     C6C.DELETE,
@@ -88,6 +88,7 @@ export function normalizeSingularRequest<
   const {
     dataInsertMultipleRows,
     cacheResults,
+    skipReactBootstrap,
     fetchDependencies,
     debug,
     success,
@@ -103,10 +104,13 @@ export function normalizeSingularRequest<
   const pkFullValues = Object.fromEntries(
     Object.entries(pkValues).map(([k, v]) => [shortToFull[k] ?? k, v])
   );
+  const pkWhereExpressions = Object.fromEntries(
+    Object.entries(pkFullValues).map(([column, value]) => [column, [C6C.EQUAL, [C6C.LIT, value]]]),
+  );
 
   if (requestMethod === C6C.GET) {
     const normalized: any = {
-      WHERE: { ...pkFullValues },
+      WHERE: { ...pkWhereExpressions },
     };
     // Preserve pagination if any was added previously
     if ((request as any)[C6C.PAGINATION]) {
@@ -116,6 +120,7 @@ export function normalizeSingularRequest<
       ...normalized,
       dataInsertMultipleRows,
       cacheResults,
+      skipReactBootstrap,
       fetchDependencies,
       debug,
       success,
@@ -126,12 +131,13 @@ export function normalizeSingularRequest<
   if (requestMethod === C6C.DELETE) {
     const normalized: any = {
       [C6C.DELETE]: true,
-      WHERE: { ...pkFullValues },
+      WHERE: { ...pkWhereExpressions },
     };
     return {
       ...normalized,
       dataInsertMultipleRows,
       cacheResults,
+      skipReactBootstrap,
       fetchDependencies,
       debug,
       success,
@@ -154,13 +160,14 @@ export function normalizeSingularRequest<
 
   const normalized: any = {
     [C6C.UPDATE]: updateBody,
-    WHERE: { ...pkFullValues },
+    WHERE: { ...pkWhereExpressions },
   };
 
   return {
     ...normalized,
     dataInsertMultipleRows,
     cacheResults,
+    skipReactBootstrap,
     fetchDependencies,
     debug,
     success,

package/src/utils/sqlAllowList.ts

@@ -6,7 +6,12 @@ type AllowListCacheEntry = {
     size: number;
 };
 
-const allowListCache = new Map<string, AllowListCacheEntry>();
+export type SqlQueryNormalizer = (sql: string) => string;
+
+const DEFAULT_NORMALIZER_CACHE_KEY = "__default__";
+type AllowListCacheKey = SqlQueryNormalizer | typeof DEFAULT_NORMALIZER_CACHE_KEY;
+
+const allowListCache = new Map<string, Map<AllowListCacheKey, AllowListCacheEntry>>();
 
 const ANSI_ESCAPE_REGEX = /\x1b\[[0-9;]*m/g;
 const COLLAPSED_BIND_ROW_REGEX = /\(\?\s*×\d+\)/g;
@@ -91,7 +96,26 @@ export const normalizeSql = (sql: string): string => {
     return normalized.replace(/\s+/g, " ").trim();
 };
 
-const parseAllowList = (raw: string, sourcePath: string): string[] => {
+export const normalizeSqlWith = (
+    sql: string,
+    sqlQueryNormalizer?: SqlQueryNormalizer,
+): string => {
+    const normalized = normalizeSql(sql);
+    if (!sqlQueryNormalizer) return normalized;
+
+    const customized = sqlQueryNormalizer(normalized);
+    if (typeof customized !== "string") {
+        throw new Error("sqlQueryNormalizer must return a string.");
+    }
+
+    return customized.replace(/\s+/g, " ").trim();
+};
+
+const parseAllowList = (
+    raw: string,
+    sourcePath: string,
+    sqlQueryNormalizer?: SqlQueryNormalizer,
+): string[] => {
     let parsed: unknown;
     try {
         parsed = JSON.parse(raw);
@@ -105,7 +129,7 @@ const parseAllowList = (raw: string, sourcePath: string): string[] => {
 
     const sqlEntries = parsed
         .filter((entry): entry is string => typeof entry === "string")
-        .map(normalizeSql)
+        .map((entry) => normalizeSqlWith(entry, sqlQueryNormalizer))
         .filter((entry) => entry.length > 0);
 
     if (sqlEntries.length !== parsed.length) {
@@ -115,7 +139,10 @@ const parseAllowList = (raw: string, sourcePath: string): string[] => {
     return sqlEntries;
 };
 
-export const loadSqlAllowList = async (allowListPath: string): Promise<Set<string>> => {
+export const loadSqlAllowList = async (
+    allowListPath: string,
+    sqlQueryNormalizer?: SqlQueryNormalizer,
+): Promise<Set<string>> => {
     if (!isNode()) {
         throw new Error("SQL allowlist validation requires a Node runtime.");
     }
@@ -129,7 +156,10 @@ export const loadSqlAllowList = async (allowListPath: string): Promise<Set<strin
         throw new Error(`SQL allowlist file not found at ${allowListPath}.`);
     }
 
-    const cached = allowListCache.get(allowListPath);
+    const pathCache = allowListCache.get(allowListPath)
+        ?? new Map<AllowListCacheKey, AllowListCacheEntry>();
+    const cacheKey: AllowListCacheKey = sqlQueryNormalizer ?? DEFAULT_NORMALIZER_CACHE_KEY;
+    const cached = pathCache.get(cacheKey);
     if (
         cached &&
         cached.mtimeMs === fileStat.mtimeMs &&
@@ -145,13 +175,14 @@ export const loadSqlAllowList = async (allowListPath: string): Promise<Set<strin
         throw new Error(`SQL allowlist file not found at ${allowListPath}.`);
     }
 
-    const sqlEntries = parseAllowList(raw, allowListPath);
+    const sqlEntries = parseAllowList(raw, allowListPath, sqlQueryNormalizer);
     const allowList = new Set(sqlEntries);
-    allowListCache.set(allowListPath, {
+    pathCache.set(cacheKey, {
         allowList,
         mtimeMs: fileStat.mtimeMs,
         size: fileStat.size,
     });
+    allowListCache.set(allowListPath, pathCache);
     return allowList;
 };
 
@@ -186,10 +217,11 @@ export const extractSqlEntries = (payload: unknown): string[] => {
 
 export const collectSqlAllowListEntries = (
     payload: unknown,
-    entries: Set<string> = new Set<string>()
+    entries: Set<string> = new Set<string>(),
+    sqlQueryNormalizer?: SqlQueryNormalizer,
 ): Set<string> => {
     const sqlEntries = extractSqlEntries(payload)
-        .map(normalizeSql)
+        .map((entry) => normalizeSqlWith(entry, sqlQueryNormalizer))
         .filter((entry) => entry.length > 0);
 
     sqlEntries.forEach((entry) => entries.add(entry));
@@ -199,7 +231,8 @@ export const collectSqlAllowListEntries = (
 
 export const compileSqlAllowList = async (
     allowListPath: string,
-    entries: Iterable<string>
+    entries: Iterable<string>,
+    sqlQueryNormalizer?: SqlQueryNormalizer,
 ): Promise<string[]> => {
     if (!isNode()) {
         throw new Error("SQL allowlist compilation requires a Node runtime.");
@@ -212,7 +245,7 @@ export const compileSqlAllowList = async (
 
     const compiled = Array.from(new Set(
         Array.from(entries)
-            .map(normalizeSql)
+            .map((entry) => normalizeSqlWith(entry, sqlQueryNormalizer))
             .filter((entry) => entry.length > 0)
     )).sort();