@carbonorm/carbonnode 3.0.0 → 3.0.1

package/src/api/types/dynamicFetching.ts

@@ -0,0 +1,10 @@
+export enum eFetchDependencies {
+    NONE = 0,
+    REFERENCED = 0b1,
+    CHILDREN = 0b1,
+    REFERENCES = 0b10,
+    PARENTS = 0b10,
+    ALL = 0b11,
+    C6ENTITY = 0b100,
+    RECURSIVE = 0b1000,
+}

package/src/api/types/modifyTypes.ts

@@ -0,0 +1,25 @@
+// if you can get away with modify over modifyDeep, use modify. The editor will be happier.
+export type Modify<T, R> = Omit<T, keyof R> & R;
+
+// @link https://stackoverflow.com/questions/41285211/overriding-interface-property-type-defined-in-typescript-d-ts-file/55032655#55032655
+export type ModifyDeep<A, B extends DeepPartialAny<A>> = {
+    [K in keyof A | keyof B]?:          // For all keys in A and B:
+    K extends keyof A                // ───┐
+        ? K extends keyof B            // ───┼─ key K exists in both A and B
+            ? A[K] extends AnyObject     //    │  ┴──┐
+                ? B[K] extends AnyObject   //    │  ───┼─ both A and B are objects
+                    ? ModifyDeep<A[K], B[K]> //    │     │  └─── We need to go deeper (recursively)
+                    : B[K]                   //    │     ├─ B is a primitive 🠆 use B as the final type (new type)
+                : B[K]                     //    │     └─ A is a primitive 🠆 use B as the final type (new type)
+            : A[K]                       //    ├─ key only exists in A 🠆 use A as the final type (original type)
+        : B[K]                         //    └─ key only exists in B 🠆 use B as the final type (new type)
+}
+
+type AnyObject = Record<string, any>
+
+// This type is here only for some intellisense for the overrides object
+type DeepPartialAny<T> = {
+    /** Makes each property optional and turns each leaf property into any, allowing for type overrides by narrowing any. */
+    [P in keyof T]?: T[P] extends AnyObject ? DeepPartialAny<T[P]> : any
+}
+

package/src/api/types/mysqlTypes.ts

@@ -0,0 +1,33 @@
+
+// ========================
+// 🔧 SQL Operator & Helpers
+// ========================
+
+export type SQLFunction =
+    | 'COUNT'
+    | 'GROUP_CONCAT'
+    | 'MAX'
+    | 'MIN'
+    | 'SUM'
+    | 'DISTINCT';
+
+export type SQLComparisonOperator =
+    | '='
+    | '!='
+    | '<'
+    | '<='
+    | '>'
+    | '>='
+    | 'IN'
+    | 'NOT IN'
+    | 'LIKE'
+    | 'IS NULL'
+    | 'IS NOT NULL'
+    | 'BETWEEN'
+    | 'LESS_THAN'
+    | 'GREATER_THAN';
+
+export type JoinType = 'INNER' | 'LEFT_OUTER' | 'RIGHT_OUTER';
+
+export type OrderDirection = 'ASC' | 'DESC';
+

package/src/api/types/ormInterfaces.ts

@@ -0,0 +1,287 @@
+import restRequest from "api/restRequest";
+import {AxiosInstance, AxiosPromise, AxiosResponse} from "axios";
+import {Pool} from "mysql2/promise";
+import {eFetchDependencies} from "./dynamicFetching";
+import {Modify} from "./modifyTypes";
+import {JoinType, OrderDirection, SQLComparisonOperator, SQLFunction} from "./mysqlTypes";
+
+export interface stringMap {
+    [key: string]: string;
+}
+
+export interface stringNumberMap {
+    [key: string]: string | number;
+}
+
+export interface RegExpMap {
+    [key: string]: RegExp | RegExpMap;
+}
+
+export interface complexMap {
+    [key: string]: stringMap | stringNumberMap | stringMap[] | RegExpMap;
+}
+
+export interface iTypeValidation {
+    MYSQL_TYPE: string,
+    MAX_LENGTH: string,
+    AUTO_INCREMENT: boolean,
+    SKIP_COLUMN_IN_POST: boolean
+}
+
+export type iRestReactiveLifecycle<T extends RequestGetPutDeleteBody> = {
+    beforeProcessing?: (args: { request: T[]; requestMeta?: any }) => void | Promise<void>;
+    beforeExecution?: (args: { request: T[]; requestMeta?: any }) => void | Promise<void>;
+    afterExecution?: (args: { response: T[]; request: T[]; responseMeta?: any }) => void | Promise<void>;
+    afterCommit?: (args: { response: T[]; request: T[]; responseMeta?: any }) => void | Promise<void>;
+};
+
+export interface iConstraint {
+    TABLE: string,
+    COLUMN: string,
+    CONSTRAINT: string
+}
+
+export interface iC6RestfulModel<RestShortTableNames extends string = string> {
+    TABLE_NAME: RestShortTableNames,
+    PRIMARY: string[],
+    PRIMARY_SHORT: string[],
+    COLUMNS: stringMap,
+    LIFECYCLE_HOOKS: iRestReactiveLifecycle<RequestGetPutDeleteBody>[],
+    REGEX_VALIDATION: RegExpMap,
+    TYPE_VALIDATION: { [key: string]: iTypeValidation },
+    TABLE_REFERENCES: { [columnName: string]: iConstraint[] },
+    TABLE_REFERENCED_BY: { [columnName: string]: iConstraint[] },
+}
+
+export interface iRestApiFunctions<RestData = any> {
+    Delete: (request?: (iAPI<any> & any)) => apiReturn<iDeleteC6RestResponse<RestData>>;
+    Post: (request?: (iAPI<any> & any)) => apiReturn<iPostC6RestResponse<RestData>>;
+    Get: (request?: (iAPI<any> & any)) => apiReturn<iGetC6RestResponse<RestData>>;
+    Put: (request?: (iAPI<any> & any)) => apiReturn<iPutC6RestResponse<RestData>>,
+}
+
+export interface iDynamicApiImport<RestData = any> {
+    default: iRestApiFunctions<RestData>
+    // the methods below are optional
+    postState?: (response: AxiosResponse<iPostC6RestResponse<RestData>>, request: iAPI<any>, id: string | number | boolean) => void,
+    deleteState?: (response: AxiosResponse<iDeleteC6RestResponse<RestData>>, request: iAPI<any>) => void,
+    putState?: (response: AxiosResponse<iPutC6RestResponse<RestData>>, request: iAPI<any>) => void
+}
+
+export interface tC6Tables { [key: string]: (iC6RestfulModel & { [key: string]: any }) }
+
+export interface tC6RestApi {
+    [key: string]: {
+        REST: iRestApiFunctions,
+        PUT: Function;
+        POST: Function;
+        DELETE: Function;
+    };
+}
+
+// todo - I don't like that these essentially become reserved words.
+export type iAPI<RestTableInterfaces extends { [key: string]: any }> = RestTableInterfaces & {
+    dataInsertMultipleRows?: RestTableInterfaces[],
+    cacheResults?: boolean, // aka ignoreCache
+    // todo - this should really only be used for get requests - add this to the Get interface or throw error (im actually inclined to ts ignore the function and add to iGetC6 atm; back later)
+    fetchDependencies?: number | eFetchDependencies | Awaited<apiReturn<iGetC6RestResponse<any>>>[],
+    debug?: boolean,
+    success?: string | ((r: AxiosResponse) => (string | void)),
+    error?: string | ((r: AxiosResponse) => (string | void)),
+}
+
+export interface iCacheAPI<ResponseDataType = any> {
+    requestArgumentsSerialized: string,
+    request: AxiosPromise<ResponseDataType>,
+    response?: AxiosResponse,
+    final?: boolean,
+}
+
+
+
+/**
+ * the first argument ....
+ *
+ * Our api returns a zero argument function iff the method is get and the previous request reached the predefined limit.
+ * This function can be aliased as GetNextPageOfResults(). If the end is reached undefined will be returned.
+ *
+ *
+ * For POST, PUT, and DELETE requests one can expect the primary key of the new or modified index, or a boolean success
+ * indication if no primary key exists.
+ **/
+export const POST = 'POST';
+export const PUT = 'PUT';
+export const GET = 'GET';
+export const DELETE = 'DELETE';
+
+
+export type iRestMethods = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+// ========================
+// 📦 SELECT
+// ========================
+
+export type SubSelect<T = any> = {
+    subSelect: true;
+    table: string; // could be enum’d to known table names
+    args: RequestGetPutDeleteBody<T>;
+    alias: string;
+};
+
+export type SelectField<T = any> =
+    | keyof T
+    | [keyof T, 'AS', string]
+    | [SQLFunction, keyof T]
+    | [SQLFunction, keyof T, string] // With alias
+    | SubSelect<T>; // Fully nested sub-select
+
+
+// ========================
+// 🧠 WHERE (Recursive)
+// ========================
+
+export type WhereClause<T = any> =
+    | Partial<T>
+    | LogicalGroup<T>
+    | ComparisonClause<T>;
+
+export type LogicalGroup<T = any> = {
+    [logicalGroup: string]: Array<WhereClause<T>>;
+};
+
+export type ComparisonClause<T = any> = [keyof T, SQLComparisonOperator, any];
+
+
+// ========================
+// 🔗 JOIN
+// ========================
+
+export type JoinTableCondition<T = any> =
+    | Partial<T>
+    | WhereClause<T>[]
+    | ComparisonClause<T>[];
+
+export type JoinClause<T = any> = {
+    [table: string]: JoinTableCondition<T>;
+};
+
+export type Join<T = any> = {
+    [K in JoinType]?: JoinClause<T>;
+};
+
+
+// ========================
+// 📄 PAGINATION
+// ========================
+
+export type Pagination<T = any> = {
+    PAGE?: number;
+    LIMIT?: number | null;
+    ORDER?: Partial<Record<keyof T, OrderDirection>>;
+};
+
+
+// ========================
+// 🌐 MAIN API TYPE
+// ========================
+
+export type RequestGetPutDeleteBody<T = any> = {
+    SELECT?: SelectField<T>[];
+    UPDATE?: Partial<T>;
+    DELETE?: boolean;
+    WHERE?: WhereClause<T>;
+    JOIN?: Join<T>;
+    PAGINATION?: Pagination<T>;
+};
+
+
+export type RequestQueryBody<RestTableInterfaces extends { [key: string]: any }> =
+    iAPI<RestTableInterfaces>
+    | RequestGetPutDeleteBody;
+
+export function isPromise(x) {
+    return Object(x).constructor === Promise
+}
+
+interface iC6RestResponse<RestData> {
+    rest: RestData,
+    session?: any,
+    sql?: any
+}
+
+
+interface iChangeC6Data {
+    rowCount: number,
+}
+
+export interface iDeleteC6RestResponse<RestData = any, RequestData = any> extends iChangeC6Data, iC6RestResponse<RestData> {
+    deleted: boolean | number | string | RequestData,
+}
+
+export interface iPostC6RestResponse<RestData = any> extends iC6RestResponse<RestData> {
+    created: boolean | number | string,
+}
+
+export interface iPutC6RestResponse<RestData = any, RequestData = any> extends iChangeC6Data, iC6RestResponse<RestData> {
+    updated: boolean | number | string | RequestData,
+}
+
+export interface iC6Object {
+    C6VERSION: string,
+    TABLES: {
+        [key: string]: iC6RestfulModel &
+            { [key: string]: string | number }
+    },
+    PREFIX: string,
+    IMPORT: (tableName: string) => Promise<iDynamicApiImport>,
+
+    [key: string]: any
+}
+
+// todo - I'm not sure that Modify<ResponseDataType, ResponseDataOverrides>[]> is needed?
+export type iGetC6RestResponse<ResponseDataType, ResponseDataOverrides = {}> = iC6RestResponse<Modify<ResponseDataType, ResponseDataOverrides> | Modify<ResponseDataType, ResponseDataOverrides>[]>
+
+// returning undefined means no more results are available, thus we've queried everything possible
+// null means the request is currently being executed
+// https://www.typescriptlang.org/docs/handbook/2/conditional-types.html
+export type apiReturn<Response> =
+    null
+    | undefined
+    | AxiosPromise<Response>
+    | (Response extends iPutC6RestResponse | iDeleteC6RestResponse | iPostC6RestResponse ? null : (() => apiReturn<Response>))
+
+
+export interface iRest<
+    CustomAndRequiredFields extends { [key: string]: any },
+    RestTableInterfaces extends { [key: string]: any },
+    RequestTableOverrides = { [key in keyof RestTableInterfaces]: any },
+    ResponseDataType = any,
+    RestShortTableNames extends string = any
+> {
+    C6: iC6Object,
+    axios?: AxiosInstance,
+    restURL?: string,
+    mysqlPool?: Pool;
+    withCredentials?: boolean,
+    tableName: RestShortTableNames | RestShortTableNames[],
+    requestMethod: iRestMethods,
+    clearCache?: () => void,
+    skipPrimaryCheck?: boolean,
+    queryCallback: RequestQueryBody<Modify<RestTableInterfaces, RequestTableOverrides>> | ((request: iAPI<Modify<RestTableInterfaces, RequestTableOverrides>> & CustomAndRequiredFields) => (null | undefined | RequestQueryBody<Modify<RestTableInterfaces, RequestTableOverrides>>)),
+    responseCallback?: (response: AxiosResponse<ResponseDataType>,
+                        request: iAPI<Modify<RestTableInterfaces, RequestTableOverrides>> & CustomAndRequiredFields,
+                        success: (ResponseDataType extends iPutC6RestResponse | iDeleteC6RestResponse ? RequestQueryBody<Modify<RestTableInterfaces, RequestTableOverrides>> : string) | string | number | boolean) => any // keep this set to any, it allows easy arrow functions and the results unused here
+}
+
+export function extendedTypeHints<RestTableInterfaces extends {
+    [key: string]: any
+}, RestShortTableNames extends string>() {
+    return <CustomAndRequiredFields extends {
+        [key: string]: any
+    } = any, RequestTableTypes extends RestTableInterfaces = any, RequestTableOverrides extends {
+        [key: string]: any
+    } = any, ResponseDataType extends {
+        [key: string]: any
+    } = any>(argv) => restRequest<CustomAndRequiredFields, RequestTableTypes, RequestTableOverrides, ResponseDataType, RestShortTableNames>(argv)
+}
+

package/src/api/utils/apiHelpers.ts

@@ -0,0 +1,83 @@
+// When we capture DropExceptions and display them as a custom page, this will change.
+import {toast} from "react-toastify";
+import isTest from "../../variables/isTest";
+import { AxiosResponse } from "axios";
+import {toastOptions} from "../../variables/toastOptions";
+import {iC6RestfulModel} from "../types/ormInterfaces";
+
+export function TestRestfulResponse(response: AxiosResponse | any, success: ((r: AxiosResponse) => (string | void)) | string | undefined, error: ((r: AxiosResponse) => (string | void)) | string | undefined): string | boolean | number {
+
+    if (undefined === response.data?.['ERROR TYPE']
+        && (undefined !== response?.data?.rest
+            || undefined !== response.data?.created
+            || undefined !== response.data?.updated
+            || undefined !== response.data?.deleted)) {
+
+        let successReturn: string | undefined | void = 'function' === typeof success ? success?.(response) : success;
+
+        if (typeof successReturn === 'string') {
+
+            toast.success(successReturn, toastOptions);
+
+        }
+
+        // this could end up with bad results for deleting id's === 0
+        return response.data.created ?? response.data.updated ?? response.data.deleted ?? true;
+
+    }
+
+    let errorReturn: string | undefined | void = 'function' === typeof error ? error?.(response) : error;
+
+    if (typeof errorReturn === 'string') {
+
+        toast.error(errorReturn, toastOptions);
+
+    }
+
+    return false;
+
+
+}
+
+export function removePrefixIfExists(tableName: string, prefix: string): string {
+    if (tableName.startsWith(prefix.toLowerCase())) {
+        return tableName.slice(prefix.length);
+    }
+    return tableName;
+}
+
+export function removeInvalidKeys<iRestObject>(request: any, c6Tables: {
+    [key: string]: (iC6RestfulModel & { [key: string]: any })
+}): iRestObject {
+
+    let intersection: iRestObject = {} as iRestObject
+
+    let restfulObjectKeys: string[] = [];
+
+    const tableList = Object.values(c6Tables)
+
+    tableList.forEach(table => Object.values(table.COLUMNS).forEach(column => {
+
+        if (false === restfulObjectKeys.includes(column)) {
+
+            restfulObjectKeys.push(column)
+
+        }
+
+    }))
+
+    Object.keys(request).forEach(key => {
+
+        if (restfulObjectKeys.includes(key)) {
+
+            intersection[key] = request[key]
+
+        }
+
+    });
+
+    isTest || console.log('intersection', intersection)
+
+    return intersection
+
+}

package/src/api/utils/cacheManager.ts

@@ -0,0 +1,67 @@
+import {AxiosPromise} from "axios";
+import isTest from "../../variables/isTest";
+import isVerbose from "../../variables/isVerbose";
+import { iCacheAPI } from "api/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`.')
+
+    }
+
+    userCustomClearCache.map((f) => 'function' === typeof f && f());
+
+    userCustomClearCache = apiRequestCache = []
+
+}
+
+export function checkCache<ResponseDataType = any, RestShortTableNames = string>(cacheResult: iCacheAPI<ResponseDataType>, requestMethod: string, tableName: RestShortTableNames | RestShortTableNames[], request: any): false | undefined | null | AxiosPromise<ResponseDataType> {
+
+    if (undefined === cacheResult?.response) {
+
+        console.groupCollapsed('%c API: The request on (' + tableName + ') is in cache and the response is undefined. The request has not finished. 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)
+
+        console.groupEnd()
+
+        return cacheResult.request;
+
+    }
+
+    if (true === cacheResult?.final) {
+
+        if (false === isTest || true === isVerbose) {
+
+            console.groupCollapsed('%c API: Rest api cache (' + requestMethod + '  ' + tableName + ') has reached the final result. Returning undefined!', 'color: #cc0')
+
+            console.log('%c ' + requestMethod + ' ' + tableName, 'color: #cc0')
+
+            console.log('%c Request Data (note you may see the success and/or error prompt):', 'color: #cc0', request)
+
+            console.log('%c Response Data:', 'color: #cc0', cacheResult?.response?.data?.rest || cacheResult?.response?.data || cacheResult?.response)
+
+            console.groupEnd()
+
+        }
+
+        return undefined;
+
+    }
+
+    return false;
+}

package/src/api/utils/logger.ts

@@ -0,0 +1,24 @@
+import isVerbose from "variables/isVerbose";
+
+/**
+ * Conditionally group a log if verbose.
+ */
+export function group(title: string, data?: any): void {
+    if (!isVerbose) return;
+    console.groupCollapsed(`%c${title}`, "color: #007acc");
+    if (data !== undefined) console.log(data);
+    console.groupEnd();
+}
+
+export function info(message: string, ...optional: any[]): void {
+    if (!isVerbose) return;
+    console.info(`%cINFO: ${message}`, "color: #0a0", ...optional);
+}
+
+export function warn(message: string, ...optional: any[]): void {
+    console.warn(`%cWARN: ${message}`, "color: #e90", ...optional);
+}
+
+export function error(message: string, ...optional: any[]): void {
+    console.error(`%cERROR: ${message}`, "color: #c00", ...optional);
+}

package/src/api/utils/sortAndSerializeQueryObject.ts

@@ -0,0 +1,12 @@
+
+export function sortAndSerializeQueryObject(tables: String, query: Object) {
+    const orderedQuery = Object.keys(query).sort().reduce(
+        (obj, key) => {
+            obj[key] = query[key];
+            return obj;
+        },
+        {}
+    );
+
+    return tables + ' ' + JSON.stringify(orderedQuery);
+}

package/src/api/utils/testHelpers.ts

@@ -0,0 +1,24 @@
+import {apiRequestCache} from "./cacheManager";
+
+export function checkAllRequestsComplete(): true | (string[]) {
+
+    const stillRunning = apiRequestCache.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) + ')')
+
+        }
+
+        // when requests return emtpy sets in full renders, it may not be possible to track their progress.
+        console.warn('stillRunning...', stillRunning)
+
+        return stillRunning.map((cache) => cache.requestArgumentsSerialized)
+
+    }
+
+    return true
+
+}

package/src/api/utils/toastNotifier.ts

@@ -0,0 +1,11 @@
+import { toast } from "react-toastify";
+import { toastOptions, toastOptionsDevs } from "variables/toastOptions";
+import isLocal from "variables/isLocal";
+
+export function onSuccess(message: string): void {
+    toast.success(message, isLocal ? toastOptionsDevs : toastOptions);
+}
+
+export function onError(message: string): void {
+    toast.error(message, isLocal ? toastOptionsDevs : toastOptions);
+}

package/src/index.ts

@@ -5,14 +5,26 @@
 export * from "./api/C6Constants";
 export { default as axiosInstance } from "./api/axiosInstance";
 export * from "./api/axiosInstance";
-export * from "./api/carbonSqlExecutor";
 export { default as convertForRequestBody } from "./api/convertForRequestBody";
 export * from "./api/convertForRequestBody";
 export { default as restRequest } from "./api/restRequest";
 export * from "./api/restRequest";
 export { default as timeout } from "./api/timeout";
 export * from "./api/timeout";
-export * from "./api/interfaces/ormInterfaces";
+export * from "./api/builders/sqlBuilder";
+export * from "./api/executors/Executor";
+export * from "./api/executors/HttpExecutor";
+export * from "./api/executors/SqlExecutor";
+export * from "./api/types/dynamicFetching";
+export * from "./api/types/modifyTypes";
+export * from "./api/types/mysqlTypes";
+export * from "./api/types/ormInterfaces";
+export * from "./api/utils/apiHelpers";
+export * from "./api/utils/cacheManager";
+export * from "./api/utils/logger";
+export * from "./api/utils/sortAndSerializeQueryObject";
+export * from "./api/utils/testHelpers";
+export * from "./api/utils/toastNotifier";
 export * from "./variables/getEnvVar";
 export { default as isLocal } from "./variables/isLocal";
 export * from "./variables/isLocal";