@carbonorm/carbonnode 3.10.0 → 4.0.0

package/src/api/orm/builders/JoinBuilder.ts

@@ -5,12 +5,159 @@ import {resolveDerivedTable, isDerivedTableKey} from "../queryHelpers";
 
 export abstract class JoinBuilder<G extends OrmGenerics> extends ConditionBuilder<G>{
 
+    private indexHintCache?: Map<string, string>;
+
     protected createSelectBuilder(
         _request: any
     ): { build(table: string, isSubSelect: boolean): { sql: string; params: any[] | Record<string, any> } } {
         throw new Error('Subclasses must implement createSelectBuilder to support derived table serialization.');
     }
 
+    protected resetIndexHints(): void {
+        this.indexHintCache = undefined;
+    }
+
+    private normalizeIndexHintKey(key: string): string {
+        return key
+            .replace(/`/g, '')
+            .replace(/_/g, ' ')
+            .trim()
+            .replace(/\s+/g, ' ')
+            .toUpperCase();
+    }
+
+    private normalizeHintTargetKey(target: string): string {
+        return target.replace(/`/g, '').trim();
+    }
+
+    private hasIndexHintKeys(obj: Record<string, any>): boolean {
+        const keys = Object.keys(obj ?? {});
+        if (!keys.length) return false;
+
+        const forceKey = this.normalizeIndexHintKey(C6C.FORCE_INDEX);
+        const useKey = this.normalizeIndexHintKey(C6C.USE_INDEX);
+        const ignoreKey = this.normalizeIndexHintKey(C6C.IGNORE_INDEX);
+
+        return keys.some(key => {
+            const normalized = this.normalizeIndexHintKey(key);
+            return normalized === forceKey || normalized === useKey || normalized === ignoreKey;
+        });
+    }
+
+    private normalizeHintSpec(spec: any): Record<string, any> | undefined {
+        if (spec instanceof Map) {
+            spec = Object.fromEntries(spec);
+        }
+
+        if (Array.isArray(spec) || typeof spec === 'string') {
+            return { [C6C.FORCE_INDEX]: spec } as Record<string, any>;
+        }
+
+        if (!spec || typeof spec !== 'object') {
+            return undefined;
+        }
+
+        if (!this.hasIndexHintKeys(spec as Record<string, any>)) {
+            return undefined;
+        }
+
+        return spec as Record<string, any>;
+    }
+
+    private formatIndexHintClause(spec: any): string {
+        const normalizedSpec = this.normalizeHintSpec(spec);
+        if (!normalizedSpec) return '';
+
+        const clauses: string[] = [];
+        const forceKey = this.normalizeIndexHintKey(C6C.FORCE_INDEX);
+        const useKey = this.normalizeIndexHintKey(C6C.USE_INDEX);
+        const ignoreKey = this.normalizeIndexHintKey(C6C.IGNORE_INDEX);
+
+        const pushClause = (keyword: string, rawValue: any) => {
+            const values = Array.isArray(rawValue) ? rawValue : [rawValue];
+            const indexes = values
+                .map(value => String(value ?? '').trim())
+                .filter(Boolean)
+                .map(value => `\`${value.replace(/`/g, '``')}\``);
+            if (!indexes.length) return;
+            clauses.push(`${keyword} (${indexes.join(', ')})`);
+        };
+
+        for (const [key, rawValue] of Object.entries(normalizedSpec)) {
+            const normalizedKey = this.normalizeIndexHintKey(key);
+            if (normalizedKey === forceKey) {
+                pushClause('FORCE INDEX', rawValue);
+            } else if (normalizedKey === useKey) {
+                pushClause('USE INDEX', rawValue);
+            } else if (normalizedKey === ignoreKey) {
+                pushClause('IGNORE INDEX', rawValue);
+            }
+        }
+
+        return clauses.join(' ');
+    }
+
+    private normalizeIndexHints(raw: any): Map<string, string> | undefined {
+        if (raw instanceof Map) {
+            raw = Object.fromEntries(raw);
+        }
+
+        const cache = new Map<string, string>();
+
+        const addEntry = (target: string, spec: any) => {
+            const clause = this.formatIndexHintClause(spec);
+            if (!clause) return;
+            const normalizedTarget = target === '__base__'
+                ? '__base__'
+                : this.normalizeHintTargetKey(target);
+            cache.set(normalizedTarget, clause);
+        };
+
+        if (Array.isArray(raw) || typeof raw === 'string') {
+            addEntry('__base__', raw);
+        } else if (raw && typeof raw === 'object') {
+            if (this.hasIndexHintKeys(raw as Record<string, any>)) {
+                addEntry('__base__', raw);
+            } else {
+                for (const [key, value] of Object.entries(raw as Record<string, any>)) {
+                    const normalizedKey = this.normalizeHintTargetKey(key);
+                    if (!normalizedKey) continue;
+                    addEntry(normalizedKey, value);
+                }
+            }
+        }
+
+        return cache.size ? cache : undefined;
+    }
+
+    protected getIndexHintClause(table: string, alias?: string): string {
+        if (!this.indexHintCache) {
+            const rawHints = (this.request as unknown as Record<string, any> | undefined)?.[C6C.INDEX_HINTS];
+            this.indexHintCache = this.normalizeIndexHints(rawHints);
+        }
+
+        const hints = this.indexHintCache;
+        if (!hints || hints.size === 0) return '';
+
+        const normalizedTable = this.normalizeHintTargetKey(table);
+        const normalizedAlias = alias ? this.normalizeHintTargetKey(alias) : undefined;
+
+        const candidates = [
+            normalizedAlias,
+            normalizedAlias ? `${normalizedTable} ${normalizedAlias}` : undefined,
+            normalizedTable,
+            '__base__',
+        ];
+
+        for (const candidate of candidates) {
+            if (!candidate) continue;
+            const clause = hints.get(candidate);
+            if (clause) return clause;
+        }
+
+        return '';
+    }
+
     buildJoinClauses(joinArgs: any, params: any[] | Record<string, any>): string {
         let sql = '';
 
@@ -79,7 +226,9 @@ export abstract class JoinBuilder<G extends OrmGenerics> extends ConditionBuilde
                     if (alias) {
                         this.registerAlias(alias, table);
                     }
-                    const joinSql = alias ? `\`${table}\` AS \`${alias}\`` : `\`${table}\``;
+                    const hintClause = this.getIndexHintClause(table, alias);
+                    const baseJoinSql = alias ? `\`${table}\` AS \`${alias}\`` : `\`${table}\``;
+                    const joinSql = hintClause ? `${baseJoinSql} ${hintClause}` : baseJoinSql;
                     const onClause = this.buildBooleanJoinedConditions(conditions, true, params);
                     sql += ` ${joinKind} JOIN ${joinSql}`;
                     if (onClause) {

package/src/api/orm/queries/PostQueryBuilder.ts

@@ -18,13 +18,15 @@ export class PostQueryBuilder<G extends OrmGenerics> extends ConditionBuilder<G>
         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 params: any[] = []
+        const params: any[] | Record<string, any> = this.useNamedParams ? {} : [];
         const placeholders: string[] = []
 
 
         for (const key of keys) {
             const value = body[key];
-            const placeholder = this.addParam(params, key, value);
+            const trimmed = this.trimTablePrefix(table, key);
+            const qualified = `${table}.${trimmed}`;
+            const placeholder = this.serializeUpdateValue(value, params, qualified);
             placeholders.push(placeholder);
         }
 

package/src/api/orm/queries/SelectQueryBuilder.ts

@@ -16,6 +16,7 @@ export class SelectQueryBuilder<G extends OrmGenerics> extends PaginationBuilder
         // reset any previously collected SELECT aliases (from AggregateBuilder)
         // @ts-ignore
         if (this.selectAliases && this.selectAliases.clear) this.selectAliases.clear();
+        this.resetIndexHints();
         const args = this.request;
         this.initAlias(table, args.JOIN);
         const params = this.useNamedParams ? {} : [];
@@ -25,6 +26,10 @@ export class SelectQueryBuilder<G extends OrmGenerics> extends PaginationBuilder
             .join(', ');
 
         let sql = `SELECT ${selectFields} FROM \`${table}\``;
+        const baseIndexHint = this.getIndexHintClause(table);
+        if (baseIndexHint) {
+            sql += ` ${baseIndexHint}`;
+        }
 
         if (args.JOIN) {
             sql += this.buildJoinClauses(args.JOIN, params);

package/src/api/orm/queries/UpdateQueryBuilder.ts

@@ -39,7 +39,9 @@ export class UpdateQueryBuilder<G extends OrmGenerics> extends PaginationBuilder
             .map(([col, val]) => {
                 const trimmed = this.trimTablePrefix(table, col);
                 const qualified = `${table}.${trimmed}`;
-                return `\`${trimmed}\` = ${this.addParam(params, qualified, val)}`;
+                this.assertValidIdentifier(qualified, 'UPDATE SET');
+                const rightSql = this.serializeUpdateValue(val, params, qualified);
+                return `\`${trimmed}\` = ${rightSql}`;
             });
 
         sql += ` SET ${setClauses.join(', ')}`;

package/src/api/types/ormInterfaces.ts

@@ -97,7 +97,13 @@ export type RequestQueryBody<
 export interface iCacheAPI<ResponseDataType = any> {
     requestArgumentsSerialized: string;
     request: AxiosPromise<ResponseDataType>;
-    response?: AxiosResponse;
+    response?: AxiosResponse & {
+        __carbonTiming?: {
+            start: number;
+            end: number;
+            duration: number;
+        }
+    },
     final?: boolean;
 }
 
@@ -105,40 +111,48 @@ export interface iChangeC6Data {
     rowCount: number;
 }
 
-export interface iDeleteC6RestResponse<RestData = any, RequestData = any> extends iChangeC6Data, iC6RestResponse<RestData> {
+// New discriminated REST response type based on HTTP method
+export type C6RestResponse<
+    Method extends iRestMethods,
+    RestData extends { [key: string]: any },
+    Overrides = {}
+> = {
+    rest: Method extends 'GET' ? Modify<RestData, Overrides>[] : Modify<RestData, Overrides>;
+    session?: any;
+    sql?: any;
+} & (Method extends 'GET'
+    ? { next?: () => Promise<DetermineResponseDataType<'GET', RestData, Overrides>> }
+    : {});
+
+export interface iC6RestResponse<RestData> {
+    // Backwards compatibility: base interface for rest/sql/session (singular)
+    rest: RestData;
+    session?: any;
+    sql?: any;
+}
+
+export interface iDeleteC6RestResponse<RestData extends { [key: string]: any; }, RequestData = any> extends iChangeC6Data, C6RestResponse<'DELETE', RestData> {
     deleted: boolean | number | string | RequestData;
 }
 
-export interface iPostC6RestResponse<RestData = any> extends iC6RestResponse<RestData> {
+export interface iPostC6RestResponse<RestData extends { [key: string]: any; }> extends C6RestResponse<'POST', RestData> {
     created: boolean | number | string;
 }
 
-export interface iPutC6RestResponse<RestData = any, RequestData = any> extends iChangeC6Data, iC6RestResponse<RestData> {
+export interface iPutC6RestResponse<RestData extends { [key: string]: any; }, RequestData = any> extends iChangeC6Data, C6RestResponse<'PUT', RestData> {
     updated: boolean | number | string | RequestData;
 }
 
-export interface iC6RestResponse<RestData> {
-    rest: RestData;
-    session?: any;
-    sql?: any;
-}
-
 export interface iGetC6RestResponse<
     ResponseDataType extends { [key: string]: any },
     ResponseDataOverrides = {}
-> extends iC6RestResponse<
-    // TODO - We removed Modify<ResponseDataType, ResponseDataOverrides> |
-    Modify<ResponseDataType, ResponseDataOverrides>[]
-> {
-    next?: () => Promise<DetermineResponseDataType<"GET", ResponseDataType, ResponseDataOverrides>>;
-}
+> extends C6RestResponse<'GET', ResponseDataType, ResponseDataOverrides> {}
 
 export type DetermineResponseDataType<
     Method extends iRestMethods,
     RestTableInterface extends { [key: string]: any },
     ResponseDataOverrides = {}
-> = null |
-    (Method extends 'POST'
+> = (Method extends 'POST'
         ? iPostC6RestResponse<RestTableInterface>
         : Method extends 'GET'
             ? iGetC6RestResponse<RestTableInterface, ResponseDataOverrides>

package/src/api/utils/cacheManager.ts

@@ -1,46 +1,87 @@
-import {AxiosPromise} from "axios";
+import { AxiosPromise } from "axios";
 import { iCacheAPI } from "../types/ormInterfaces";
 
-// do not remove entries from this array. It is used to track the progress of API requests.
-// position in array is important. Do not sort. To not add to begging.
-export let apiRequestCache: iCacheAPI[] = [];
-
-export let userCustomClearCache: (() => void)[] = [];
-
-interface iClearCache {
-    ignoreWarning: boolean
-}
-
-export function clearCache(props?: iClearCache) {
-
-    if (false === props?.ignoreWarning) {
-
-        console.warn('The rest api clearCache should only be used with extreme care! Avoid using this in favor of using `cacheResults : boolean`.')
-
+// -----------------------------------------------------------------------------
+// Cache Storage
+// -----------------------------------------------------------------------------
+export const apiRequestCache = new Map<string, iCacheAPI>();
+export const userCustomClearCache: (() => void)[] = [];
+
+// -----------------------------------------------------------------------------
+// Cache Key Generator (safe, fixed-size ~40 chars)
+// -----------------------------------------------------------------------------
+// -----------------------------------------------------------------------------
+// Browser-safe deterministic hash (FNV-1a)
+// -----------------------------------------------------------------------------
+function fnv1a(str: string): string {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = (h * 0x01000193) >>> 0;
     }
-
-    userCustomClearCache.map((f) => 'function' === typeof f && f());
-
-    userCustomClearCache = apiRequestCache = []
-
+    return h.toString(16);
 }
 
-export function checkCache<ResponseDataType = any, RestShortTableNames = string>(cacheResult: iCacheAPI<ResponseDataType>, requestMethod: string, tableName: RestShortTableNames | RestShortTableNames[], request: any): false | AxiosPromise<ResponseDataType> {
-
-    if (undefined === cacheResult) {
-
-        return false;
+function makeCacheKey(
+    method: string,
+    tableName: string | string[],
+    requestData: unknown,
+): string {
+    const raw = JSON.stringify([method, tableName, requestData]);
+    return fnv1a(raw);
+}
 
+// -----------------------------------------------------------------------------
+// Clear Cache (no shared-array bugs)
+// -----------------------------------------------------------------------------
+export function clearCache(props?: { ignoreWarning?: boolean }): void {
+    if (!props?.ignoreWarning) {
+        console.warn(
+            "The REST API clearCache should only be used with extreme care!",
+        );
     }
 
-    console.groupCollapsed('%c API: The request on (' + tableName + ') is in cache. Returning the request Promise!', 'color: #0c0')
-
-    console.log('%c ' + requestMethod + ' ' + tableName, 'color: #0c0')
-
-    console.log('%c Request Data (note you may see the success and/or error prompt):', 'color: #0c0', request)
+    for (const fn of userCustomClearCache) {
+        try {
+            fn();
+        } catch {}
+    }
 
-    console.groupEnd()
+    apiRequestCache.clear();
+}
 
-    return cacheResult.request;
+// -----------------------------------------------------------------------------
+// Check Cache (dedupe via hashed key)
+// -----------------------------------------------------------------------------
+export function checkCache<ResponseDataType = any>(
+    method: string,
+    tableName: string | string[],
+    requestData: any,
+): AxiosPromise<ResponseDataType> | false {
+    const key = makeCacheKey(method, tableName, requestData);
+    const cached = apiRequestCache.get(key);
+
+    if (!cached) return false;
+
+    console.groupCollapsed(
+        `%c API cache hit for ${method} ${tableName}`,
+        "color:#0c0",
+    );
+    console.log("Request Data:", requestData);
+    console.groupEnd();
+
+    return cached.request;
+}
 
+// -----------------------------------------------------------------------------
+// Store Cache Entry (drop-in compatible)
+// -----------------------------------------------------------------------------
+export function setCache<ResponseDataType = any>(
+    method: string,
+    tableName: string | string[],
+    requestData: any,
+    cacheEntry: iCacheAPI<ResponseDataType>,
+): void {
+    const key = makeCacheKey(method, tableName, requestData);
+    apiRequestCache.set(key, cacheEntry);
 }

package/src/api/utils/testHelpers.ts

@@ -2,13 +2,15 @@ import {apiRequestCache} from "./cacheManager";
 
 export function checkAllRequestsComplete(): true | (string[]) {
 
-    const stillRunning = apiRequestCache.filter((cache) => undefined === cache.response)
+    const cacheEntries = Array.from(apiRequestCache.values())
+
+    const stillRunning = cacheEntries.filter((cache) => undefined === cache.response)
 
     if (stillRunning.length !== 0) {
 
         if (document === null || document === undefined) {
 
-            throw new Error('document is undefined while waiting for API requests to complete (' + JSON.stringify(apiRequestCache) + ')')
+            throw new Error('document is undefined while waiting for API requests to complete (' + JSON.stringify(cacheEntries) + ')')
 
         }
 
@@ -21,4 +23,4 @@ export function checkAllRequestsComplete(): true | (string[]) {
 
     return true
 
-}
+}

package/src/variables/isNode.ts

@@ -1,12 +1,5 @@
 const isNode =  () => {
-
-    console.log('Checking if running in Node.js environment...');
-
-    const isNodeEnv = typeof process !== 'undefined' && !!process.versions?.node;
-
-    console.log(`Is Node.js environment: ${isNodeEnv}`);
-
-    return isNodeEnv;
+    return typeof process !== 'undefined' && !!process.versions?.node;
 }
 
 export default isNode;