@qrunio/qqq-frontend-core 1.0.0

package/lib/controllers/QController.d.ts

@@ -0,0 +1,217 @@
+import { AxiosResponse } from "axios";
+import FormData from "form-data";
+import { QException } from "../exceptions/QException";
+import { QAuthenticationMetaData } from "../model/metaData/QAuthenticationMetaData";
+import { QInstance } from "../model/metaData/QInstance";
+import { QProcessMetaData } from "../model/metaData/QProcessMetaData";
+import { QTableMetaData } from "../model/metaData/QTableMetaData";
+import { QTableVariant } from "../model/metaData/QTableVariant";
+import { QJobComplete } from "../model/processes/QJobComplete";
+import { QJobError } from "../model/processes/QJobError";
+import { QJobRunning } from "../model/processes/QJobRunning";
+import { QJobStarted } from "../model/processes/QJobStarted";
+import { QPossibleValue } from "../model/QPossibleValue";
+import { QRecord } from "../model/QRecord";
+import { QQueryFilter } from "../model/query/QQueryFilter";
+import { QueryJoin } from "../model/query/QueryJoin";
+export type PossibleValueParams = {
+    tableName?: string | null;
+    processName?: string | null;
+    fieldNameOrPossibleValueSourceName: string;
+    searchTerm?: string | null;
+    ids?: any[] | null;
+    labels?: any[] | null;
+    values?: Map<string, any> | null;
+    useCase?: string | null;
+    possibleValueSourceFilter?: QQueryFilter | null;
+};
+/*******************************************************************************
+ ** Controller for interacting with a QQQ backend.
+ *******************************************************************************/
+export declare class QController {
+    private axiosInstance;
+    private exceptionHandler;
+    static STEP_TIMEOUT_MILLIS_PARAM_NAME: string;
+    private static metaDataPromise?;
+    private static tableMetaDataPromises;
+    private static processMetaDataPromises;
+    private static authenticationMetaDataLocalStorageKey;
+    private static awaitAuthenticationPromise;
+    private static gotAuthentication;
+    private static widgetAbortControllerMap;
+    /*******************************************************************************
+     **
+     *******************************************************************************/
+    constructor(baseUrl: string, exceptionHandler?: (error: QException) => any);
+    /*******************************************************************************
+     ** Useful for development (e.g., to be able to use the axios instance, to test
+     ** things we probably want to keep in this class, without having to re-install
+     ** this module for the testing cycle), but probably not meant for main-line usage.
+     *******************************************************************************/
+    getAxiosInstance(): any;
+    /*******************************************************************************
+     ** clear memoized promises
+     *******************************************************************************/
+    static clearMemoization(): void;
+    /*******************************************************************************
+     ** Function to be called by an app after it's authenticated the user.  This will
+     ** allow the awaitAuthenticationPromise to resolve, so that other requests can continue.
+     *******************************************************************************/
+    setGotAuthentication(): void;
+    /*******************************************************************************
+     ** Clear the authentication meta data from local storage
+     *******************************************************************************/
+    clearAuthenticationMetaDataLocalStorage(): void;
+    /*******************************************************************************
+     ** Fetch the authentication meta data from local storage or the server.
+     *******************************************************************************/
+    getAuthenticationMetaData(): Promise<QAuthenticationMetaData>;
+    /*******************************************************************************
+     ** create or update a user session
+     *******************************************************************************/
+    manageSession(accessToken: string, uuid?: string, more?: {
+        [name: string]: any;
+    }): Promise<{
+        uuid: string;
+        values: {
+            [key: string]: any;
+        };
+    }>;
+    /*******************************************************************************
+     ** Fetch the top-level meta data for a qqq instance.
+     *******************************************************************************/
+    loadMetaData(): Promise<QInstance>;
+    /*******************************************************************************
+     ** Fetch the full meta data for a specific table.
+     *******************************************************************************/
+    loadTableMetaData(tableName: string): Promise<QTableMetaData>;
+    /*******************************************************************************
+     ** Fetch the full meta data for a specific process.
+     *******************************************************************************/
+    loadProcessMetaData(processName: string): Promise<QProcessMetaData>;
+    /*******************************************************************************
+     ** Make a count request to the backend
+     *******************************************************************************/
+    count(tableName: string, queryFilter?: QQueryFilter, queryJoins?: QueryJoin[] | null, includeDistinct?: boolean, tableVariant?: QTableVariant | null): Promise<[number, number]>;
+    /*******************************************************************************
+     ** Make a query request to the backend
+     *******************************************************************************/
+    query(tableName: string, queryFilter?: QQueryFilter, queryJoins?: QueryJoin[] | null, tableVariant?: QTableVariant | null): Promise<QRecord[]>;
+    /*******************************************************************************
+     ** Make a request to the backend for a single record
+     *******************************************************************************/
+    get(tableName: string, primaryKey: any, tableVariant?: QTableVariant | null, includeAssociations?: boolean, queryJoins?: QueryJoin[] | null): Promise<QRecord>;
+    /*******************************************************************************
+     ** Make a request to the backend for a single record's developer mode data
+     *******************************************************************************/
+    getRecordDeveloperMode(tableName: string, primaryKey: any): Promise<any>;
+    /*******************************************************************************
+     ** Make a request to the backend to save a new version of a record's associated script
+     *******************************************************************************/
+    storeRecordAssociatedScript(tableName: string, primaryKey: any, fieldName: string, code: string, commitMessage: string): Promise<any>;
+    /*******************************************************************************
+     ** Make a request to the backend to get script logs for an associated script
+     *******************************************************************************/
+    getRecordAssociatedScriptLogs(tableName: string, primaryKey: any, fieldName: string, scriptRevisionId: number): Promise<any>;
+    /*******************************************************************************
+     ** Make a request to the backend to test a script
+     *******************************************************************************/
+    testScript(tableName: string, primaryKey: any, fieldName: string, code: string, inputValues: Map<string, any>): Promise<any>;
+    /*******************************************************************************
+     ** Make a backend call to create a single record
+     **
+     *******************************************************************************/
+    create(tableName: string, data: {
+        [key: string]: any;
+    }): Promise<QRecord>;
+    /*******************************************************************************
+     ** Convert a javascript object of form data to a "FormData" object for multipart posting.
+     *******************************************************************************/
+    private dataObjectToFormData;
+    /*******************************************************************************
+     ** Make a backend call to update a single record
+     **
+     *******************************************************************************/
+    update(tableName: string, id: any, data: {
+        [key: string]: any;
+    }): Promise<QRecord>;
+    /*******************************************************************************
+     ** Make a backend call to delete a single record
+     **
+     *******************************************************************************/
+    delete(tableName: string, id: any): Promise<number>;
+    /*******************************************************************************
+     ** Common logic to parse a process-related server response into an appropriate object.
+     *******************************************************************************/
+    parseProcessResponse(response: AxiosResponse): QJobStarted | QJobRunning | QJobComplete | QJobError;
+    /*******************************************************************************
+     ** Initialize a process
+     *******************************************************************************/
+    processInit(processName: string, formDataOrQueryString?: string | FormData, formDataHeaders?: FormData.Headers): Promise<QJobStarted | QJobComplete | QJobError>;
+    /*******************************************************************************
+     ** Fully run a process (i.e., not stopping for frontend steps)
+     *******************************************************************************/
+    processRun(processName: string, formDataOrQueryString?: string | FormData, formDataHeaders?: FormData.Headers, dontGoAsyncOnBackend?: boolean): Promise<QJobStarted | QJobComplete | QJobError>;
+    /*******************************************************************************
+     ** Helper function for the process init & step functions, as well as bulk functions
+     ** which may run async.
+     *******************************************************************************/
+    private postWithQueryStringToPossibleAsyncBackendJob;
+    /*******************************************************************************
+     ** Proceed to the next step in a process
+     *******************************************************************************/
+    processStep(processName: string, processUUID: string, step: string, formDataOrQueryString?: string | FormData, formDataHeaders?: FormData.Headers): Promise<QJobStarted | QJobComplete | QJobError>;
+    /*******************************************************************************
+     ** Proceed to the next step in a process
+     *******************************************************************************/
+    processStepOrInit(url: string, formDataOrQueryString?: string | FormData, formDataHeaders?: FormData.Headers, dontGoAsyncOnBackend?: boolean): Promise<QJobStarted | QJobComplete | QJobError>;
+    /*******************************************************************************
+     ** Get the status for a currently executing job within a process (init or step)
+     *******************************************************************************/
+    processJobStatus(processName: string, processUUID: string, jobUUID: string): Promise<QJobRunning | QJobComplete | QJobError>;
+    /*******************************************************************************
+     ** Get records from a process's state
+     *******************************************************************************/
+    processRecords(processName: string, processUUID: string, skip?: number, limit?: number): Promise<{
+        totalRecords: number;
+        records: QRecord[];
+    }>;
+    /*******************************************************************************
+     ** Handle a user clicking cancel on a process
+     *******************************************************************************/
+    processCancel(processName: string, processUUID: string): Promise<boolean>;
+    /*******************************************************************************
+     ** Fetch the data for a specific widget.
+     *******************************************************************************/
+    tableVariants(tableName: string): Promise<QTableVariant[]>;
+    /*******************************************************************************
+     ** Fetch the data for a specific widget.
+     *******************************************************************************/
+    widget(widgetName: string, urlParams?: string): Promise<any>;
+    /***************************************************************************
+     * overload 1 of possibleValues function - this is its "original" signature
+     * that took several params, many optional, and kept evolving and getting
+     * messier and messier.
+     ***************************************************************************/
+    possibleValues(tableName: string | null, processName: string | null, fieldNameOrPossibleValueSourceName: string, searchTerm?: string, ids?: any[], labels?: any[], values?: Map<string, any>, useCase?: string): Promise<QPossibleValue[]>;
+    /***************************************************************************
+     * overload 2 of possibleValues function - this is a "new" signature
+     * that takes an object, to make evolution (addition of new params) easier
+     * over time (e.g., backward compatible).
+     ***************************************************************************/
+    possibleValues(params: PossibleValueParams): Promise<QPossibleValue[]>;
+    /***************************************************************************
+     ** Let an app piggyback on our axiosInstance and handleException methods
+     ** to issue ad-hock requests.
+     ***************************************************************************/
+    axiosRequest(config: any): Promise<any>;
+    /*******************************************************************************
+     **
+     *******************************************************************************/
+    defaultMultipartFormDataHeaders(): FormData.Headers;
+    /*******************************************************************************
+     ** exception handler which will marshal axios error into a QException and
+     *  send that the exception handler provided to this class
+     *******************************************************************************/
+    private handleException;
+}