@questwork/q-utilities 0.1.33 → 0.1.35

package/dist/q-utilities.d.ts

@@ -103,6 +103,51 @@ export declare function changeCreatorOwner(that: any, { source, target }: {
     target: any;
 }): any;
 
+export declare class CheckResult {
+    dataSets: DataSet[];
+    constructor(opts?: CheckResultOptions);
+    static init(opts?: CheckResultOptions): CheckResult | null;
+    static initFromArray(arr?: any[]): Array<CheckResult>;
+    static initOnlyValidFromArray(arr?: any[]): Array<CheckResult>;
+    addDataSet(dataSet: DataSet): void;
+    getDataSetByName(name: string): DataSet | undefined;
+    getAllSummary(): {
+        summary: DataSetSummaryItem[];
+    };
+    getSummary(): DataSetSummaryItem[];
+    getDuplicatedDetails(): DetailsResultItem[];
+    getIgnoredDetails(): DetailsResultItem[];
+    getInvalidDetails(): DetailsResultItem[];
+    getValidDetails(): Record<string, DataWrapper[]>;
+    getAllDetails(): {
+        details: {
+            ignoredDetails: DetailsResultItem[];
+            invalidDetails: DetailsResultItem[];
+            duplicatedDetails: DetailsResultItem[];
+        };
+    };
+    getDetails(): {
+        ignoredDetails: DetailsResultItem[];
+        invalidDetails: DetailsResultItem[];
+        duplicatedDetails: DetailsResultItem[];
+    };
+    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 +167,136 @@ declare function customHandler({ responseHelper, handler, ignoreError }: {
     ignoreError?: boolean;
 }): (reqOrCtx: any, resOrNext: any, nextInExpress: any) => Promise<any>;
 
+declare class DataSet {
+    name: string;
+    data?: Array<DataWrapper>;
+    orphanData: Array<DataWrapper>;
+    checkResultConfig: CheckResultConfig;
+    saveResultConfig: SaveResultConfig;
+    orphanBehavior?: 'DELETE' | 'KEEP' | null;
+    notExistBehavior?: 'INSERT' | 'SKIP';
+    existBehavior?: 'UPDATE' | 'SKIP';
+    constructor(opts?: any);
+    static init(opts?: DataSet): DataSet | null;
+    static initFromArray(arr?: any[]): Array<DataSet>;
+    static initOnlyValidFromArray(arr?: any[]): Array<DataSet>;
+    add(data: DataWrapper): DataSetOptions;
+    getExistedData(): Array<DataWrapper>;
+    getInvalidData(): Array<DataWrapper>;
+    getNotExistedData(): Array<DataWrapper>;
+    getSkipData(): Array<DataWrapper>;
+    addOrphan(data: Record<string, any>): DataSet;
+    getOrphanData(): Array<DataWrapper>;
+}
+
+declare interface DataSetOptions {
+    name: string;
+    data?: Array<DataWrapper>;
+    checkResultConfig?: CheckResultConfig;
+    saveResultConfig?: SaveResultConfig;
+    orphanBehavior?: 'DELETE' | 'KEEP' | null;
+    notExistBehavior?: 'INSERT' | 'SKIP';
+    existBehavior?: 'UPDATE' | 'SKIP';
+}
+
+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>;
+    checkOrphans?: (params: {
+        dataSet: DataSet;
+        ctx: Record<string, any>;
+    }) => Promise<void>;
+    converter?: (value: any) => any;
+    isIgnore?: (value: any) => any;
+    primaryKeys?: string[];
+    notExistBehavior: 'INSERT' | 'SKIP';
+    existBehavior: 'UPDATE' | 'SKIP';
+    orphanBehavior?: 'DELETE' | 'KEEP';
+    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>;
+    logs: Array<Log>;
+    rawData: Record<string, any>;
+    rowIndex: number;
+    status?: Status_2;
+    transformedData: Record<string, any>;
+    constructor(opts: DataWrapperOptions);
+    static init(opts?: DataWrapperOptions): DataWrapper | null;
+    static initFromArray(arr?: any[]): Array<DataWrapper>;
+    static initOnlyValidFromArray(arr?: any[]): Array<DataWrapper>;
+    get errorLogs(): Array<Log>;
+    get ignoreLog(): Log | undefined;
+    addLog(detail: LogInput): DataWrapper;
+    addError(detail: LogInput): DataWrapper;
+    addOrphanDeleteError(msg?: string): DataWrapper;
+    addInsertError(msg?: string): DataWrapper;
+    addUpdateError(msg?: string): DataWrapper;
+    addDuplicatedLog(msg?: string): DataWrapper;
+    addSkippedLog(msg?: string): DataWrapper;
+    addIgnoreLog(msg?: string): DataWrapper;
+    addInsertedLog(msg?: string): DataWrapper;
+    addUpdatedLog(msg?: string): DataWrapper;
+    addOrphanDeletedLog(msg?: string): DataWrapper;
+    isCheckValid(): boolean;
+    isIgnored(): boolean;
+    isDuplicated(): boolean;
+    hasErrors(): boolean;
+    setStatus(status: keyof typeof DATAWRAPPER_STATUS): DataWrapper;
+    setExisted(): DataWrapper;
+    setFailed(): DataWrapper;
+    setInserted(): DataWrapper;
+    setSkipped(): DataWrapper;
+    setUpdated(): DataWrapper;
+    setOrphanDeleted(): DataWrapper;
+    setData(data: Record<string, any>): DataWrapper;
+    setRawData(rawData: Record<string, any>): DataWrapper;
+    setTransformedData(transformedData: Record<string, any>): DataWrapper;
+}
+
+declare const DATAWRAPPER_STATUS: {
+    ORPHAN_DELETED: string;
+    EXISTED: string;
+    FAILED: string;
+    INSERTED: string;
+    SKIPPED: string;
+    UPDATED: string;
+};
+
+declare interface DataWrapperOptions {
+    data?: Record<string, any>;
+    logs?: Array<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;
@@ -178,7 +353,9 @@ declare const _default: {
     QMeta: typeof models.QMeta;
     Repo: typeof models.Repo;
     makeService: typeof models.makeService;
+    makeServiceBulkWrite: typeof models.makeServiceBulkWrite;
     Service: typeof models.Service;
+    ServiceBulkWrite: typeof models.ServiceBulkWrite;
     ActionRecord: typeof models.ActionRecord;
     Status: typeof models.Status;
     StatusDocument: typeof models.StatusDocument;
@@ -219,6 +396,22 @@ 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;
+    LOG_TYPE: {
+        readonly IGNORE: "IGNORE";
+        readonly DUPLICATED: "DUPLICATED";
+        readonly REQUIRED_ERROR: "REQUIRED_ERROR";
+        readonly TRANSFORM_ERROR: "TRANSFORM_ERROR";
+        readonly CONVERT_ERROR: "CONVERT_ERROR";
+        readonly ORPHAN_DELETE_ERROR: "ORPHAN_DELETE_ERROR";
+        readonly INSERT_ERROR: "INSERT_ERROR";
+        readonly UPDATE_ERROR: "UPDATE_ERROR";
+        readonly SKIPPED: "SKIPPED";
+        readonly INSERTED: "INSERTED";
+        readonly UPDATED: "UPDATED";
+        readonly ORPHAN_DELETED: "ORPHAN_DELETED";
+    };
     expressHelper: {
         customHandler: customHandler;
         findAllResult: findAllResult;
@@ -292,6 +485,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 +538,37 @@ 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 checkRequired;
+    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 +616,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 +635,9 @@ declare namespace helpers {
         displayName,
         downloadFileByUrl,
         escapeRegex,
+        ExcelImportHelper,
+        CheckResult,
+        LOG_TYPE,
         expressHelper,
         extractEmails,
         formatDate,
@@ -434,6 +673,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 +728,34 @@ export declare class KeyValueObject {
 
 declare type KnownErrorCode = keyof typeof ERROR_CODES;
 
+declare interface Log {
+    rowIndex: number;
+    column: string;
+    message: string;
+    type: LogType;
+}
+
+export declare const LOG_TYPE: {
+    readonly IGNORE: "IGNORE";
+    readonly DUPLICATED: "DUPLICATED";
+    readonly REQUIRED_ERROR: "REQUIRED_ERROR";
+    readonly TRANSFORM_ERROR: "TRANSFORM_ERROR";
+    readonly CONVERT_ERROR: "CONVERT_ERROR";
+    readonly ORPHAN_DELETE_ERROR: "ORPHAN_DELETE_ERROR";
+    readonly INSERT_ERROR: "INSERT_ERROR";
+    readonly UPDATE_ERROR: "UPDATE_ERROR";
+    readonly SKIPPED: "SKIPPED";
+    readonly INSERTED: "INSERTED";
+    readonly UPDATED: "UPDATED";
+    readonly ORPHAN_DELETED: "ORPHAN_DELETED";
+};
+
+declare interface LogInput {
+    column: string;
+    message: string;
+    type: LogType;
+}
+
 export declare class LogRecord {
     constructor(options?: {});
     data: any;
@@ -495,6 +769,8 @@ export declare class LogRecord {
     serialize(): any;
 }
 
+declare type LogType = typeof LOG_TYPE[keyof typeof LOG_TYPE];
+
 export declare function makeApiResponse({ repo, result }: {
     repo: any;
     result: any;
@@ -504,6 +780,10 @@ export declare function makeService({ repo }: {
     repo: any;
 }): Service;
 
+export declare function makeServiceBulkWrite({ repo }: {
+    repo: any;
+}): ServiceBulkWrite;
+
 export declare function mergeArraysByKey(arr1: any, arr2: any): {
     key: any;
     value: any;
@@ -529,7 +809,9 @@ declare namespace models {
         QMeta,
         Repo,
         makeService,
+        makeServiceBulkWrite,
         Service,
+        ServiceBulkWrite,
         ActionRecord,
         Status,
         StatusDocument,
@@ -555,6 +837,17 @@ export declare namespace objectHelper {
     export { set };
 }
 
+declare interface OrphanDetail {
+    deleted: DataWrapper[];
+    failed: DataWrapper[];
+}
+
+declare interface OrphanSummary {
+    total: number;
+    deleted: number;
+    failed: number;
+}
+
 export declare function padZeros(num: any, minLength?: number): any;
 
 export declare function pMap(iterable: any, mapper: any, { concurrency, stopOnError, signal, }?: {
@@ -715,6 +1008,11 @@ export declare class Repo {
     get queryOptions(): any;
     get saveOptions(): any;
     init(options: any): any;
+    bulkWriteDocs({ operations, config, systemLog }: {
+        operations: any;
+        config: any;
+        systemLog: any;
+    }): Promise<any>;
     deleteOne({ id }: {
         id: any;
     }): Promise<any>;
@@ -757,6 +1055,156 @@ export declare function sanitizeText(input: string, options?: {
     debug?: boolean;
 }): string;
 
+declare class SaveResult {
+    dataSets: DataSet[];
+    constructor(opt?: any);
+    addDataSet(dataSet: DataSet): this;
+    getAllDetails(): {
+        details: {
+            failed: {
+                name: string;
+                hidden: boolean;
+                logs: any[];
+            }[];
+            skipped: {
+                name: string;
+                hidden: boolean;
+                logs: any[];
+            }[];
+            inserted: {
+                name: string;
+                hidden: boolean;
+                logs: any[];
+            }[];
+            updated: {
+                name: string;
+                hidden: boolean;
+                logs: any[];
+            }[];
+        };
+        orphanDetails: {
+            deleted: any[];
+            failed: any[];
+        };
+    };
+    getDetails(): {
+        failed: {
+            name: string;
+            hidden: boolean;
+            logs: any[];
+        }[];
+        skipped: {
+            name: string;
+            hidden: boolean;
+            logs: any[];
+        }[];
+        inserted: {
+            name: string;
+            hidden: boolean;
+            logs: any[];
+        }[];
+        updated: {
+            name: string;
+            hidden: boolean;
+            logs: any[];
+        }[];
+    };
+    getFailedDetails(): {
+        name: string;
+        hidden: boolean;
+        logs: any[];
+    }[];
+    getSkippedDetails(): {
+        name: string;
+        hidden: boolean;
+        logs: any[];
+    }[];
+    getInsertedDetails(): {
+        name: string;
+        hidden: boolean;
+        logs: any[];
+    }[];
+    getUpdatedDetails(): {
+        name: string;
+        hidden: boolean;
+        logs: any[];
+    }[];
+    getOrphanDetails(): {
+        deleted: any[];
+        failed: any[];
+    };
+    getOrphanFailedDetails(): any[];
+    getOrphanDeletedDetails(): any[];
+    getSaveDetails(): SaveResultDetailItem[];
+    getSaveSummary(): SaveResultSummaryItem[];
+    getAllSummary(): {
+        summary: {
+            name: string;
+            hidden: boolean;
+            summary: {
+                total: number;
+                failed: number;
+                inserted: number;
+                skipped: number;
+                updated: number;
+            };
+        }[];
+        orphanSummary: any[];
+    };
+    getSummary(): {
+        name: string;
+        hidden: boolean;
+        summary: {
+            total: number;
+            failed: number;
+            inserted: number;
+            skipped: number;
+            updated: number;
+        };
+    }[];
+    getOrphanSummary(): any[];
+}
+
+declare interface SaveResultConfig {
+    hidden?: boolean;
+    returnDetail?: {
+        failed: boolean;
+        skipped: boolean;
+        inserted: boolean;
+        updated: boolean;
+        orphanDeleted?: boolean;
+    };
+}
+
+declare interface SaveResultDetail {
+    failed: DataWrapper[] | null;
+    inserted: DataWrapper[] | null;
+    skipped: DataWrapper[] | null;
+    updated: DataWrapper[] | null;
+}
+
+declare interface SaveResultDetailItem {
+    name: string;
+    hidden: boolean;
+    orphanDetails: OrphanDetail | null;
+    details: SaveResultDetail;
+}
+
+declare interface SaveResultSummary {
+    failed: number;
+    inserted: number;
+    skipped: number;
+    total: number;
+    updated: number;
+}
+
+declare interface SaveResultSummaryItem {
+    name: string;
+    hidden: boolean;
+    orphanSummary: OrphanSummary | null;
+    summary: SaveResultSummary;
+}
+
 export declare class Service {
     static get _classname(): string;
     static get _superclass(): string;
@@ -792,6 +1240,13 @@ export declare class Service {
     }>;
 }
 
+export declare class ServiceBulkWrite extends Service {
+    bulkWriteDocs({ operations, config }: {
+        operations: any;
+        config: any;
+    }): Promise<any>;
+}
+
 export declare function setId(id: any): any;
 
 export declare function shuffleArray(array: any): any[];
@@ -814,6 +1269,15 @@ export declare class Status {
     update(update: any): this;
 }
 
+declare interface Status_2 {
+    orphanDeleted?: number;
+    existed?: number;
+    failed?: number;
+    inserted?: number;
+    skipped?: number;
+    updated?: number;
+}
+
 export declare class StatusDocument extends Status {
     archived: any;
     completed: any;
@@ -1032,4 +1496,13 @@ declare interface WebAppResponseOptions {
     success?: boolean;
 }
 
+declare interface WorksheetConfig {
+    name: string;
+    headerRow?: number;
+    dataStartRow?: number;
+    dataEndRow?: number;
+    dataSources: DataSourceConfig[];
+    rowIndexKey?: string;
+}
+
 export { }