@carbonorm/carbonnode 3.0.0 → 3.0.2

package/src/api/executors/HttpExecutor.ts

@@ -0,0 +1,794 @@
+import {AxiosPromise, AxiosResponse} from "axios";
+import {toast} from "react-toastify";
+import isLocal from "../../variables/isLocal";
+import isTest from "../../variables/isTest";
+import isVerbose from "../../variables/isVerbose";
+import convertForRequestBody from "../convertForRequestBody";
+import {eFetchDependencies} from "../types/dynamicFetching";
+import {Modify} from "../types/modifyTypes";
+import {apiReturn, DELETE, GET, iCacheAPI, iConstraint, iGetC6RestResponse, POST, PUT, RequestQueryBody} from "../types/ormInterfaces";
+import {removePrefixIfExists, TestRestfulResponse} from "../utils/apiHelpers";
+import {apiRequestCache, checkCache, userCustomClearCache} from "../utils/cacheManager";
+import {sortAndSerializeQueryObject} from "../utils/sortAndSerializeQueryObject";
+import {Executor} from "./Executor";
+import {toastOptions, toastOptionsDevs } from "variables/toastOptions";
+
+export class HttpExecutor<
+    RestShortTableName extends string = any,
+    RestTableInterface extends { [key: string]: any } = any,
+    PrimaryKey extends Extract<keyof RestTableInterface, string> = Extract<keyof RestTableInterface, string>,
+    CustomAndRequiredFields extends { [key: string]: any } = any,
+    RequestTableOverrides extends { [key: string]: any; } = { [key in keyof RestTableInterface]: any },
+    ResponseDataType = any
+>
+    extends Executor<
+        RestShortTableName,
+        RestTableInterface,
+        PrimaryKey,
+        CustomAndRequiredFields,
+        RequestTableOverrides,
+        ResponseDataType
+    > {
+
+    public async execute() : Promise<apiReturn<ResponseDataType>> {
+
+        const {
+            C6,
+            axios,
+            restURL,
+            withCredentials,
+            restModel,
+            requestMethod,
+            queryCallback,
+            responseCallback,
+            skipPrimaryCheck,
+            clearCache,
+        } = this.config
+
+        const tableName = restModel.TABLE_NAME;
+
+        const fullTableList = Array.isArray(tableName) ? tableName : [tableName];
+
+        const operatingTableFullName = fullTableList[0];
+
+        const operatingTable = removePrefixIfExists(operatingTableFullName, C6.PREFIX);
+
+        const tables = fullTableList.join(',')
+
+        switch (requestMethod) {
+            case GET:
+            case POST:
+            case PUT:
+            case DELETE:
+                break;
+            default:
+                throw Error('Bad request method passed to getApi')
+        }
+
+        if (null !== clearCache || undefined !== clearCache) {
+
+            userCustomClearCache[tables + requestMethod] = clearCache;
+
+        }
+
+        console.groupCollapsed('%c API: (' + requestMethod + ') Request for (' + tableName + ')', 'color: #0c0')
+
+        console.log('request', this.request)
+
+        console.groupEnd()
+
+        // an undefined query would indicate queryCallback returned undefined,
+        // thus the request shouldn't fire as is in custom cache
+        let query: RequestQueryBody<Modify<RestTableInterface, RequestTableOverrides>> | undefined | null;
+
+        if ('function' === typeof queryCallback) {
+
+            query = queryCallback(this.request); // obj or obj[]
+
+        } else {
+
+            query = queryCallback;
+
+        }
+
+        if (undefined === query || null === query) {
+
+            if (this.request.debug && isLocal) {
+
+                toast.warning("DEV: queryCallback returned undefined, signaling in Custom Cache. (returning null)", toastOptionsDevs)
+
+            }
+
+            console.groupCollapsed('%c API: (' + requestMethod + ') Request Query for (' + tableName + ') undefined, returning null (will not fire ajax)!', 'color: #c00')
+
+            console.log('%c Returning (undefined|null) for a query would indicate a custom cache hit (outside API.tsx), thus the request should not fire.', 'color: #c00')
+
+            console.trace();
+
+            console.groupEnd()
+
+            return null;
+
+        }
+
+        if (C6.GET === requestMethod) {
+
+            if (undefined === query[C6.PAGINATION]) {
+
+                query[C6.PAGINATION] = {}
+
+            }
+
+            query[C6.PAGINATION][C6.PAGE] = query[C6.PAGINATION][C6.PAGE] || 1;
+
+            query[C6.PAGINATION][C6.LIMIT] = query[C6.PAGINATION][C6.LIMIT] || 100;
+
+        }
+
+        // this could return itself with a new page number, or undefined if the end is reached
+        const apiRequest = async (): Promise<apiReturn<ResponseDataType>> => {
+
+            const {
+                debug,
+                cacheResults = (C6.GET === requestMethod),
+                dataInsertMultipleRows,
+                success,
+                fetchDependencies = eFetchDependencies.NONE,
+                error =  "An unexpected API error occurred!"
+            } = this.request
+
+            if (C6.GET === requestMethod
+                && undefined !== query?.[C6.PAGINATION]?.[C6.PAGE]
+                && 1 !== query[C6.PAGINATION][C6.PAGE]) {
+
+                console.groupCollapsed('Request on table (' + tableName + ') is firing for page (' + query[C6.PAGINATION][C6.PAGE] + '), please wait!')
+
+                console.log('Request Data (note you may see the success and/or error prompt):', this.request)
+
+                console.trace();
+
+                console.groupEnd()
+
+            }
+
+            // The problem with creating cache keys with a stringified object is the order of keys matters and it's possible for the same query to be stringified differently.
+            // Here we ensure the key order will be identical between two of the same requests. https://stackoverflow.com/questions/5467129/sort-javascript-object-by-key
+
+            // 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, query ?? {});
+
+            let cacheResult: iCacheAPI | undefined = apiRequestCache.find(cache => cache.requestArgumentsSerialized === querySerialized);
+
+            let cachingConfirmed = false;
+
+            // determine if we need to paginate.
+            if (requestMethod === C6.GET) {
+
+                if (undefined === query?.[C6.PAGINATION]) {
+
+                    if (undefined === query || null === query) {
+
+                        query = {}
+
+                    }
+
+                    query[C6.PAGINATION] = {}
+
+                }
+
+                query[C6.PAGINATION][C6.PAGE] = query[C6.PAGINATION][C6.PAGE] || 1;
+
+                query[C6.PAGINATION][C6.LIMIT] = query[C6.PAGINATION][C6.LIMIT] || 100;
+
+                // this will evaluate true most the time
+                if (true === cacheResults) {
+
+                    // just find the next, non-fetched, page and return a function to request it
+                    if (undefined !== cacheResult) {
+
+                        do {
+
+                            const cacheCheck = checkCache<ResponseDataType>(cacheResult, requestMethod, tableName, this.request);
+
+                            if (false !== cacheCheck) {
+
+                                return cacheCheck;
+
+                            }
+
+                            // this line incrementing page is why we return recursively
+                            ++query[C6.PAGINATION][C6.PAGE];
+
+                            // this json stringify is to capture the new page number
+                            querySerialized = sortAndSerializeQueryObject(tables, query ?? {});
+
+                            cacheResult = apiRequestCache.find(cache => cache.requestArgumentsSerialized === querySerialized)
+
+                        } while (undefined !== cacheResult)
+
+                        if (debug && isLocal) {
+
+                            toast.warning("DEVS: Request in cache. (" + apiRequestCache.findIndex(cache => cache.requestArgumentsSerialized === querySerialized) + "). Returning function to request page (" + query[C6.PAGINATION][C6.PAGE] + ")", toastOptionsDevs);
+
+                        }
+
+                        // @ts-ignore - this is an incorrect warning on TS, it's well typed
+                        return apiRequest;
+
+                    }
+
+                    cachingConfirmed = true;
+
+                } else {
+
+                    if (debug && isLocal) {
+
+                        toast.info("DEVS: Ignore cache was set to true.", toastOptionsDevs);
+
+                    }
+
+                }
+
+                if (debug && isLocal) {
+
+                    toast.success("DEVS: Request not in cache." + (requestMethod === C6.GET ? "Page (" + query[C6.PAGINATION][C6.PAGE] + ")." : '') + " Logging cache 2 console.", toastOptionsDevs);
+
+                }
+
+            } else if (cacheResults) { // if we are not getting, we are updating, deleting, or inserting
+
+                if (cacheResult) {
+                    const cacheCheck = checkCache<ResponseDataType>(cacheResult, requestMethod, tableName, this.request);
+
+                    if (false !== cacheCheck) {
+
+                        return cacheCheck;
+
+                    }
+                }
+
+                cachingConfirmed = true;
+                // push to cache so we do not repeat the request
+
+            }
+
+            let addBackPK: (() => void) | undefined;
+
+            let apiResponse: RestTableInterface[PrimaryKey] | string | boolean | number | undefined;
+
+            let returnGetNextPageFunction = false;
+
+            let restRequestUri: string = restURL + operatingTable + '/';
+
+            const needsConditionOrPrimaryCheck = (PUT === requestMethod || DELETE === requestMethod)
+                && false === skipPrimaryCheck;
+
+            const TABLES = C6.TABLES;
+
+            // todo - aggregate primary key check with condition check
+            // check if PK exists in query, clone so pop does not affect the real data
+            const primaryKey = structuredClone(TABLES[operatingTable]?.PRIMARY)?.pop()?.split('.')?.pop();
+
+            if (needsConditionOrPrimaryCheck) {
+
+                if (undefined === primaryKey) {
+
+                    if (null === query
+                        || undefined === query
+                        || undefined === query?.[C6.WHERE]
+                        || (true === Array.isArray(query[C6.WHERE])
+                            || query[C6.WHERE].length === 0)
+                        || (Object.keys(query?.[C6.WHERE]).length === 0)
+                    ) {
+
+                        console.error(query)
+
+                        throw Error('Failed to parse primary key information. Query: (' + JSON.stringify(query) + ') Primary Key: (' + JSON.stringify(primaryKey) + ') TABLES[operatingTable]?.PRIMARY: (' + JSON.stringify(TABLES[operatingTable]?.PRIMARY) + ') for operatingTable (' + operatingTable + ').')
+
+                    }
+
+                } else {
+
+                    if (undefined === query
+                        || null === query
+                        || false === primaryKey in query) {
+
+                        if (true === debug && isLocal) {
+
+                            toast.error('DEVS: The primary key (' + primaryKey + ') was not provided!!')
+
+                        }
+
+                        throw Error('You must provide the primary key (' + primaryKey + ') for table (' + operatingTable + '). Request (' + JSON.stringify(this.request, undefined, 4) + ') Query (' + JSON.stringify(query) + ')');
+
+                    }
+
+                    if (undefined === query?.[primaryKey]
+                        || null === query?.[primaryKey]) {
+
+                        toast.error('The primary key (' + primaryKey + ') provided is undefined or null explicitly!!')
+
+                        throw Error('The primary key (' + primaryKey + ') provided in the request was exactly equal to undefined.');
+
+                    }
+
+                }
+
+            }
+
+            // A part of me exists that wants to remove this, but it's a good feature
+            // this allows developers the ability to cache requests based on primary key
+            // for tables like `photos` this can be a huge performance boost
+            if (undefined !== query
+                && null !== query
+                && undefined !== primaryKey
+                && primaryKey in query) {
+
+                restRequestUri += query[primaryKey] + '/'
+
+                const removedPkValue = query[primaryKey];
+
+                addBackPK = () => {
+                    query ??= {}
+                    query[primaryKey] = removedPkValue
+                }
+
+                delete query[primaryKey]
+
+                console.log('query', query, 'primaryKey', primaryKey, 'removedPkValue', removedPkValue)
+
+            } else {
+
+                console.log('query', query)
+
+            }
+
+            try {
+
+                console.groupCollapsed('%c API: (' + requestMethod + ') Request Query for (' + operatingTable + ') is about to fire, will return with promise!', 'color: #A020F0')
+
+                console.log(this.request)
+
+                console.log('%c If this is the first request for this datatype; thus the value being set is currently undefined, please remember to update the state to null.', 'color: #A020F0')
+
+                console.log('%c Remember undefined indicated the request has not fired, null indicates the request is firing, an empty array would signal no data was returned for the sql stmt.', 'color: #A020F0')
+
+                console.trace()
+
+                console.groupEnd()
+
+                const axiosActiveRequest: AxiosPromise<ResponseDataType> = axios![requestMethod.toLowerCase()]<ResponseDataType>(
+                    restRequestUri,
+                    ...((() => {
+
+                        // @link - https://axios-http.com/docs/instance
+                        // How configuration vs data is passed is variable, use documentation above for reference
+                        if (requestMethod === GET) {
+
+                            return [{
+                                withCredentials: withCredentials,
+                                params: query
+                            }]
+
+                        } else if (requestMethod === POST) {
+
+                            if (undefined !== dataInsertMultipleRows) {
+
+                                return [
+                                    dataInsertMultipleRows.map(data =>
+                                        convertForRequestBody<typeof data>(data, fullTableList, C6, (message) => toast.error(message, toastOptions))),
+                                    {
+                                        withCredentials: withCredentials,
+                                    }
+                                ]
+
+                            }
+
+                            return [
+                                convertForRequestBody<RestTableInterface>(query as RestTableInterface, fullTableList, C6, (message) => toast.error(message, toastOptions)),
+                                {
+                                    withCredentials: withCredentials,
+                                }
+                            ]
+
+                        } else if (requestMethod === PUT) {
+
+                            return [
+                                convertForRequestBody<RestTableInterface>(query as RestTableInterface, fullTableList, C6, (message) => toast.error(message, toastOptions)),
+                                {
+                                    withCredentials: withCredentials,
+                                }
+                            ]
+                        } else if (requestMethod === DELETE) {
+
+                            return [{
+                                withCredentials: withCredentials,
+                                data: convertForRequestBody<RestTableInterface>(query as RestTableInterface, fullTableList, C6, (message) => toast.error(message, toastOptions))
+                            }]
+
+                        } else {
+
+                            throw new Error('The request method (' + requestMethod + ') was not recognized.')
+
+                        }
+
+                    })())
+                );
+
+                if (cachingConfirmed) {
+
+                    // push to cache so we do not repeat the request
+                    apiRequestCache.push({
+                        requestArgumentsSerialized: querySerialized,
+                        request: axiosActiveRequest
+                    });
+
+                }
+
+                // todo - wip verify this works
+                // we had removed the value from the request to add to the URI.
+                addBackPK?.();  // adding back so post-processing methods work
+
+                // returning the promise with this then is important for tests. todo - we could make that optional.
+                // https://rapidapi.com/guides/axios-async-await
+                return axiosActiveRequest.then(async (response): Promise<AxiosResponse<ResponseDataType, any>> => {
+
+                        if (typeof response.data === 'string') {
+
+                            if (isTest) {
+
+                                console.trace()
+
+                                throw new Error('The response data was a string this typically indicated html was sent. Make sure all cookies (' + JSON.stringify(response.config.headers) + ') needed are present! (' + response.data + ')')
+
+                            }
+
+                            return Promise.reject(response);
+
+                        }
+
+                        if (cachingConfirmed) {
+
+                            const cacheIndex = apiRequestCache.findIndex(cache => cache.requestArgumentsSerialized === querySerialized);
+
+                            apiRequestCache[cacheIndex].final = false === returnGetNextPageFunction
+
+                            // only cache get method requests
+                            apiRequestCache[cacheIndex].response = response
+
+                        }
+
+                        apiResponse = TestRestfulResponse(response, success, error)
+
+                        if (false === apiResponse) {
+
+                            if (debug && isLocal) {
+
+                                toast.warning("DEVS: TestRestfulResponse returned false for (" + operatingTable + ").", toastOptionsDevs);
+
+                            }
+
+                            return response;
+
+                        }
+
+                        // stateful operations are done in the response callback - its leverages rest generated functions
+                        if (responseCallback) {
+
+                            responseCallback(response, this.request, apiResponse)
+
+                        }
+
+                        if (C6.GET === requestMethod) {
+
+                            const responseData = response.data as iGetC6RestResponse<any>;
+
+                            returnGetNextPageFunction = 1 !== query?.[C6.PAGINATION]?.[C6.LIMIT] &&
+                                query?.[C6.PAGINATION]?.[C6.LIMIT] === responseData.rest.length
+
+                            if (false === isTest || true === isVerbose) {
+
+                                console.groupCollapsed('%c API: Response (' + requestMethod + ' ' + tableName + ') returned length (' + responseData.rest?.length + ') of possible (' + query?.[C6.PAGINATION]?.[C6.LIMIT] + ') limit!', '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', this.request)
+
+                                console.log('%c Response Data:', 'color: #0c0', responseData.rest)
+
+                                console.log('%c Will return get next page function:' + (1 !== query?.[C6.PAGINATION]?.[C6.LIMIT] ? '' : ' (Will not return with explicit limit 1 set)'), 'color: #0c0', true === returnGetNextPageFunction)
+
+                                console.trace();
+
+                                console.groupEnd()
+
+                            }
+
+                            if (false === returnGetNextPageFunction
+                                && true === debug
+                                && isLocal) {
+
+                                toast.success("DEVS: Response returned length (" + responseData.rest?.length + ") less than limit (" + query?.[C6.PAGINATION]?.[C6.LIMIT] + ").", toastOptionsDevs);
+
+                            }
+
+
+                            if (fetchDependencies
+                                && 'number' === typeof fetchDependencies
+                                && responseData.rest.length > 0) {
+
+                                console.groupCollapsed('%c API: Fetch Dependencies segment (' + requestMethod + ' ' + tableName + ')'
+                                    + (fetchDependencies & eFetchDependencies.CHILDREN ? ' | (CHILDREN|REFERENCED) ' : '')
+                                    + (fetchDependencies & eFetchDependencies.PARENTS ? ' | (PARENTS|REFERENCED_BY)' : '')
+                                    + (fetchDependencies & eFetchDependencies.C6ENTITY ? ' | (C6ENTITY)' : '')
+                                    + (fetchDependencies & eFetchDependencies.RECURSIVE ? ' | (RECURSIVE)' : ''), 'color: #33ccff')
+
+                                console.groupCollapsed('Collapsed JS Trace');
+                                console.trace(); // hidden in collapsed group
+                                console.groupEnd();
+
+                                // noinspection JSBitwiseOperatorUsage
+                                let dependencies: {
+                                    [key: string]: iConstraint[]
+                                } = {};
+
+                                if (fetchDependencies & eFetchDependencies.C6ENTITY) {
+
+                                    dependencies = operatingTable.endsWith("carbon_carbons")
+                                        ? {
+                                            // the context of the entity system is a bit different
+                                            ...fetchDependencies & eFetchDependencies.CHILDREN // REFERENCED === CHILDREN
+                                                ? C6.TABLES[operatingTable].TABLE_REFERENCED_BY
+                                                : {},
+                                            ...fetchDependencies & eFetchDependencies.PARENTS // REFERENCES === PARENTS
+                                                ? C6.TABLES[operatingTable].TABLE_REFERENCES
+                                                : {}
+                                        } : {
+                                            // the context of the entity system is a bit different
+                                            ...fetchDependencies & eFetchDependencies.CHILDREN // REFERENCED === CHILDREN
+                                                ? {
+                                                    ...Object.keys(C6.TABLES[operatingTable].TABLE_REFERENCES).reduce((accumulator, columnName) => {
+
+                                                        if (!C6.TABLES[operatingTable].PRIMARY_SHORT.includes(columnName)) {
+                                                            accumulator[columnName] = C6.TABLES[operatingTable].TABLE_REFERENCES[columnName]
+                                                        }
+
+                                                        return accumulator
+                                                    }, {}),
+                                                    ...C6.TABLES[operatingTable].TABLE_REFERENCED_BY // it is unlikely that a C6 table will have any TABLE_REFERENCED_BY
+                                                }
+                                                : {},
+                                            ...fetchDependencies & eFetchDependencies.PARENTS // REFERENCES === PARENTS
+                                                ? C6.TABLES[operatingTable].PRIMARY_SHORT.reduce((accumulator, primaryKey) => {
+                                                    if (primaryKey in C6.TABLES[operatingTable].TABLE_REFERENCES) {
+                                                        accumulator[primaryKey] = C6.TABLES[operatingTable].TABLE_REFERENCES[primaryKey]
+                                                    }
+                                                    return accumulator
+                                                }, {})
+                                                : {}
+                                        }
+
+                                } else {
+
+                                    // this is the natural mysql context
+                                    dependencies = {
+                                        ...fetchDependencies & eFetchDependencies.REFERENCED // REFERENCED === CHILDREN
+                                            ? C6.TABLES[operatingTable].TABLE_REFERENCED_BY
+                                            : {},
+                                        ...fetchDependencies & eFetchDependencies.REFERENCES // REFERENCES === PARENTS
+                                            ? C6.TABLES[operatingTable].TABLE_REFERENCES
+                                            : {}
+                                    };
+
+                                }
+
+                                let fetchReferences: {
+                                    [externalTable: string]: {
+                                        [column: string]: string[]
+                                    }
+                                } = {}
+
+                                let apiRequestPromises: Array<apiReturn<iGetC6RestResponse<any>>> = []
+
+                                console.log('%c Dependencies', 'color: #005555', dependencies)
+
+                                Object.keys(dependencies)
+                                    .forEach(column => dependencies[column]
+                                        .forEach((constraint) => {
+
+                                            const columnValues = responseData.rest[column] ?? responseData.rest.map((row) => {
+
+                                                if (operatingTable.endsWith("carbons")
+                                                    && 'entity_tag' in row
+                                                    && !constraint.TABLE.endsWith(row['entity_tag'].split('\\').pop().toLowerCase())) {
+
+                                                    return false; // map
+
+                                                }
+
+                                                if (!(column in row)) {
+                                                    return false
+                                                }
+
+                                                // todo - row[column] is a FK value, we should optionally remove values that are already in state
+                                                // this could be any column in the table constraint.TABLE, not just the primary key
+
+                                                return row[column]
+
+                                            }).filter(n => n) ?? [];
+
+                                            if (columnValues.length === 0) {
+
+                                                return; // forEach
+
+                                            }
+
+                                            fetchReferences[constraint.TABLE] ??= {};
+
+                                            fetchReferences[constraint.TABLE][constraint.COLUMN] ??= []
+
+                                            fetchReferences[constraint.TABLE][constraint.COLUMN].push(columnValues)
+
+                                        }));
+
+                                console.log('fetchReferences', fetchReferences)
+
+                                for (const tableToFetch in fetchReferences) {
+
+                                    if (fetchDependencies & eFetchDependencies.C6ENTITY
+                                        && 'string' === typeof tableName
+                                        && tableName.endsWith("carbon_carbons")) {
+
+                                        // todo - rethink the table ref entity system - when tables are renamed? no hooks exist in mysql
+                                        // since were already filtering on column, we can assume the first row constraint is the same as the rest
+
+                                        const referencesTables: string[] = responseData.rest.reduce((accumulator: string[], row: {
+                                            [x: string]: string;
+                                        }) => {
+                                            if ('entity_tag' in row && !accumulator.includes(row['entity_tag'])) {
+                                                accumulator.push(row['entity_tag']);
+                                            }
+                                            return accumulator;
+                                        }, []).map((entityTag) => entityTag.split('\\').pop().toLowerCase());
+
+                                        const shouldContinue = referencesTables.find((referencesTable) => tableToFetch.endsWith(referencesTable))
+
+                                        if (!shouldContinue) {
+
+                                            console.log('%c C6ENTITY: The constraintTableName (' + tableToFetch + ') did not end with any value in referencesTables', 'color: #c00', referencesTables)
+
+                                            continue;
+
+                                        }
+
+                                        console.log('%c C6ENTITY: The constraintTableName (' + tableToFetch + ') will be fetched.', 'color: #0c0')
+
+                                    }
+
+                                    const fetchTable = await C6.IMPORT(tableToFetch)
+
+                                    const RestApi = fetchTable.default
+
+                                    console.log('%c Fetch Dependencies will select (' + tableToFetch + ') using GET request', 'color: #33ccff')
+
+                                    let nextFetchDependencies = eFetchDependencies.NONE
+
+                                    if (fetchDependencies & eFetchDependencies.RECURSIVE) {
+
+                                        if (fetchDependencies & eFetchDependencies.ALL) {
+
+                                            throw Error('Recursive fetch dependencies with both PARENT and CHILD reference will result in an infin1ite loop. As there is not real ending condition, this is not supported.')
+
+                                        }
+
+                                        nextFetchDependencies = fetchDependencies
+
+                                    } else if (fetchDependencies & eFetchDependencies.C6ENTITY) {
+
+                                        if (tableToFetch === "carbon_carbons") {
+
+                                            nextFetchDependencies = fetchDependencies
+
+                                        } else {
+
+                                            nextFetchDependencies = fetchDependencies ^ eFetchDependencies.C6ENTITY
+
+                                        }
+
+                                    }
+
+                                    console.log('fetchReferences', fetchReferences[tableToFetch], "Current fetchDependencies for (" + operatingTable + "):", fetchDependencies, "New fetchDependencies for (" + tableToFetch + "): ", nextFetchDependencies)
+
+                                    // todo - filter out ids that exist in state?!? note - remember that this does not necessarily mean the pk, but only known is its an FK to somewhere
+                                    // it not certain that they are using carbons' entities either
+
+                                    // this is a dynamic call to the rest api, any generated table may resolve with (RestApi)
+                                    // todo - using value to avoid joins.... but. maybe this should be a parameterizable option -- think race conditions; its safer to join
+                                    apiRequestPromises.push(RestApi.Get({
+                                            [C6.WHERE]: {
+                                                0: Object.keys(fetchReferences[tableToFetch]).reduce((sum, column) => {
+
+                                                    fetchReferences[tableToFetch][column] = fetchReferences[tableToFetch][column].flat(Infinity)
+
+                                                    if (0 === fetchReferences[tableToFetch][column].length) {
+
+                                                        console.warn('The column (' + column + ') was not found in the response data. We will not fetch.', responseData)
+
+                                                        return false;
+
+                                                    }
+
+                                                    sum[column] = fetchReferences[tableToFetch][column].length === 1
+                                                        ? fetchReferences[tableToFetch][column][0]
+                                                        : [
+                                                            C6.IN, fetchReferences[tableToFetch][column]
+                                                        ]
+
+                                                    return sum
+
+                                                }, {})
+                                            },
+                                            fetchDependencies: nextFetchDependencies
+                                        }
+                                    ));
+
+                                }
+
+                                console.groupEnd()
+
+                                await Promise.all(apiRequestPromises)
+
+                                apiRequestPromises.map(async (promise) => {
+                                    if (!Array.isArray(this.request.fetchDependencies)) {
+                                        // to reassign value we must ref the root
+                                        this.request.fetchDependencies = [];
+                                    }
+                                    this.request.fetchDependencies.push(await promise)
+                                })
+
+                            }
+
+
+                        }
+
+                        if (debug && isLocal) {
+
+                            toast.success("DEVS: (" + requestMethod + ") request complete.", toastOptionsDevs);
+
+                        }
+
+                        return response;
+
+                    }
+                );
+
+            } catch (throwableError) {
+
+                if (isTest) {
+
+                    throw new Error(JSON.stringify(throwableError))
+
+                }
+
+                console.groupCollapsed('%c API: An error occurred in the try catch block. returning null!', 'color: #ff0000')
+
+                console.log('%c ' + requestMethod + ' ' + tableName, 'color: #A020F0')
+
+                console.warn(throwableError)
+
+                console.trace()
+
+                console.groupEnd()
+
+                TestRestfulResponse(throwableError, success, error)
+
+                return null;
+
+            }
+
+        }
+
+        return await apiRequest()
+
+    }
+}