@questwork/q-utilities 0.1.32 → 0.1.34

package/dist/q-utilities.d.ts

@@ -103,6 +103,33 @@ export declare function changeCreatorOwner(that: any, { source, target }: {
     target: any;
 }): any;
 
+export declare class CheckResult {
+    dataSets: DataSet[];
+    constructor(opts?: CheckResultOptions);
+    addDataSet(dataSet: DataSet): void;
+    getDataSetByName(name: string): DataSet | undefined;
+    getSummary(): DataSetSummaryItem[];
+    getDuplicatedDetails(): DetailsResultItem[];
+    getIgnoredDetails(): DetailsResultItem[];
+    getInvalidDetails(): DetailsResultItem[];
+    getValidDetails(): Record<string, DataWrapper[]>;
+    hasInvalidData(): boolean;
+}
+
+declare interface CheckResultConfig {
+    hidden?: boolean;
+}
+
+declare interface CheckResultOptions {
+    dataSets: DataSet[] | undefined;
+    getDataSetByName(name: string): DataSet | undefined;
+    getSummary(): DataSetSummaryItem[];
+    getIgnoredDetails(): DetailsResultItem[];
+    getInvalidDetails(): DetailsResultItem[];
+    getDuplicatedDetails(): DetailsResultItem[];
+    getValidDetails(): Record<string, DataWrapper[]>;
+}
+
 export declare function concatStringByArray(arrTemplate: any, data: any): any;
 
 export declare class ConsoleLog extends QLog {
@@ -122,6 +149,103 @@ declare function customHandler({ responseHelper, handler, ignoreError }: {
     ignoreError?: boolean;
 }): (reqOrCtx: any, resOrNext: any, nextInExpress: any) => Promise<any>;
 
+declare class DataSet {
+    name: string;
+    data?: Array<DataWrapper>;
+    checkResultConfig: CheckResultConfig;
+    saveResultConfig: SaveResultConfig;
+    constructor(opts?: any);
+    add(data: DataWrapper): DataSetOptions;
+    getExistedData(): Array<DataWrapper>;
+    getInvalidData(): Array<DataWrapper>;
+    getNotExistedData(): Array<DataWrapper>;
+}
+
+declare interface DataSetOptions {
+    name: string;
+    data?: Array<DataWrapper>;
+    checkResultConfig?: CheckResultConfig;
+    saveResultConfig?: SaveResultConfig;
+}
+
+declare interface DataSetSummary {
+    total: number;
+    ignored: number;
+    valid: number;
+    invalid: number;
+    duplicated: number;
+}
+
+declare interface DataSetSummaryItem {
+    name: string;
+    hidden: boolean;
+    summary: DataSetSummary;
+}
+
+declare interface DataSourceConfig {
+    name?: string;
+    checkExisted?: (params: {
+        dataSet: DataSet;
+        ctx: Record<string, any>;
+    }) => Promise<DataSet>;
+    converter?: (value: any) => any;
+    isIgnore?: (value: any) => any;
+    primaryKeys?: string[];
+    notExistBehavior: 'INSERT' | 'SKIP';
+    existBehavior: 'UPDATE' | 'SKIP';
+    handleData?: (params: {
+        dataSet: DataSet;
+        dataSource: DataSourceConfig;
+        ctx: Record<string, any>;
+    }) => Promise<DataSet>;
+    headerConfigs: HeaderConfig[];
+    checkResultConfig?: CheckResultConfig;
+    saveResultConfig?: SaveResultConfig;
+}
+
+declare class DataWrapper {
+    data: Record<string, any>;
+    errorLogs?: Array<Log>;
+    ignoreLog?: Log;
+    rawData: Record<string, any>;
+    rowIndex: number;
+    status?: Status_2;
+    transformedData: Record<string, any>;
+    constructor(opts: DataWrapperOptions);
+    addError(detail: Log): DataWrapper;
+    addInsertError(msg: string): DataWrapper;
+    addUpdateError(msg: string): DataWrapper;
+    isValid(): boolean;
+    setIgnoreLog(detail: Log): DataWrapper;
+    setData(data: Record<string, any>): DataWrapper;
+    setExisted(): DataWrapper;
+    setFailed(): DataWrapper;
+    setInserted(): DataWrapper;
+    setRawData(rawData: Record<string, any>): DataWrapper;
+    setSkipped(): DataWrapper;
+    setStatus(status: keyof typeof DATAWRAPPER_STATUS): DataWrapper;
+    setTransformedData(transformedData: Record<string, any>): DataWrapper;
+    setUpdated(): DataWrapper;
+}
+
+declare const DATAWRAPPER_STATUS: {
+    EXISTED: string;
+    FAILED: string;
+    INSERTED: string;
+    SKIPPED: string;
+    UPDATED: string;
+};
+
+declare interface DataWrapperOptions {
+    data?: Record<string, any>;
+    errorLogs?: Array<Log>;
+    ignoreLog?: Log;
+    rawData?: Record<string, any>;
+    rowIndex: number;
+    status?: Status_2;
+    transformedData?: Record<string, any>;
+}
+
 declare const _default: {
     ApiResponse: typeof models.ApiResponse;
     makeApiResponse: typeof models.makeApiResponse;
@@ -219,6 +343,8 @@ declare const _default: {
     displayName(user: any, options: any): any;
     downloadFileByUrl: typeof helpers.downloadFileByUrl;
     escapeRegex(string: any): string;
+    ExcelImportHelper: typeof helpers.ExcelImportHelper;
+    CheckResult: typeof helpers.CheckResult;
     expressHelper: {
         customHandler: customHandler;
         findAllResult: findAllResult;
@@ -292,6 +418,12 @@ declare const _default: {
 };
 export default _default;
 
+declare interface DetailsResultItem {
+    name: string;
+    hidden: boolean;
+    logs: Log[];
+}
+
 /**
  * Detects and reports hidden/control characters in a string without modifying it.
  * @param {string} input - The string to analyze.
@@ -339,6 +471,36 @@ export declare interface ErrorDetailOptions {
 
 export declare function escapeRegex(string: any): string;
 
+declare interface ExcelDataItem {
+    worksheetName: string;
+    headers: string[];
+    data: ExcelDataRow[];
+}
+
+declare interface ExcelDataRow {
+    [key: string]: any;
+}
+
+export declare class ExcelImportHelper {
+    static check(params: {
+        config: ImportConfig;
+        excelData: ExcelDataItem[];
+        context?: Record<string, any>;
+    }): Promise<CheckResultOptions>;
+    private static createExcelRow;
+    private static getRawDataFromHeaders;
+    private static isIgnore;
+    private static checkDuplicated;
+    private static transform;
+    private static convert;
+    static save(params: {
+        result?: CheckResult;
+        config?: ImportConfig;
+        data?: ExcelDataItem[];
+        context?: Record<string, any>;
+    }): Promise<SaveResult>;
+}
+
 export declare namespace expressHelper {
     export { customHandler };
     export { findAllResult };
@@ -386,6 +548,12 @@ export declare function getValueByKeys(keys: any, data: any): any;
 
 export declare function groupArrayByKey(arr: any, key: any): any;
 
+declare interface HeaderConfig {
+    name: string;
+    required?: boolean;
+    transform?: (value: any) => any;
+}
+
 declare namespace helpers {
     export {
         authorize,
@@ -399,6 +567,8 @@ declare namespace helpers {
         displayName,
         downloadFileByUrl,
         escapeRegex,
+        ExcelImportHelper,
+        CheckResult,
         expressHelper,
         extractEmails,
         formatDate,
@@ -434,6 +604,13 @@ declare function hideSensitiveFields(aggregation: any, { query }?: {
     query?: {};
 }): void;
 
+declare interface ImportConfig {
+    beforeCheck?: (value: any) => any;
+    beforeSave?: (value: any) => any;
+    name: string;
+    worksheets: WorksheetConfig[];
+}
+
 export declare function init(_class: any, options: any): any;
 
 export declare function initFromArray(_class: any, arr: any): any[];
@@ -482,6 +659,13 @@ export declare class KeyValueObject {
 
 declare type KnownErrorCode = keyof typeof ERROR_CODES;
 
+declare interface Log {
+    rowIndex: number;
+    column: string;
+    message: string;
+    type: string;
+}
+
 export declare class LogRecord {
     constructor(options?: {});
     data: any;
@@ -757,6 +941,51 @@ export declare function sanitizeText(input: string, options?: {
     debug?: boolean;
 }): string;
 
+declare class SaveResult {
+    dataSets: DataSet[];
+    constructor(opt?: any);
+    addDataSet(dataSet: DataSet): this;
+    getSaveDetails(): SaveResultDetailItem[];
+    getSaveSummary(): SaveResultSummaryItem[];
+}
+
+declare interface SaveResultConfig {
+    hidden?: boolean;
+    returnDetail?: {
+        failed: boolean;
+        skipped: boolean;
+        inserted: boolean;
+        updated: boolean;
+    };
+}
+
+declare interface SaveResultDetail {
+    failed: DataWrapper[] | null;
+    inserted: DataWrapper[] | null;
+    skipped: DataWrapper[] | null;
+    updated: DataWrapper[] | null;
+}
+
+declare interface SaveResultDetailItem {
+    name: string;
+    hidden: boolean;
+    details: SaveResultDetail;
+}
+
+declare interface SaveResultSummary {
+    failed: number;
+    inserted: number;
+    skipped: number;
+    total: number;
+    updated: number;
+}
+
+declare interface SaveResultSummaryItem {
+    name: string;
+    hidden: boolean;
+    summary: SaveResultSummary;
+}
+
 export declare class Service {
     static get _classname(): string;
     static get _superclass(): string;
@@ -814,6 +1043,14 @@ export declare class Status {
     update(update: any): this;
 }
 
+declare interface Status_2 {
+    existed?: number;
+    failed?: number;
+    inserted?: number;
+    skipped?: number;
+    updated?: number;
+}
+
 export declare class StatusDocument extends Status {
     archived: any;
     completed: any;
@@ -1032,4 +1269,12 @@ declare interface WebAppResponseOptions {
     success?: boolean;
 }
 
+declare interface WorksheetConfig {
+    name: string;
+    headerRow?: number;
+    dataStartRow?: number;
+    dataEndRow?: number;
+    dataSources: DataSourceConfig[];
+}
+
 export { }