@aitianyu.cn/types 0.0.2 → 0.0.3

package/dist/lib/utilities/core/Errors.js

@@ -1,8 +1,9 @@
 "use strict";
 /**@format */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ObjectCloneFunctionNotSupportException = exports.ArgumentNullOrEmptyException = void 0;
+exports.ObjectDiffMergeFailedException = exports.ObjectDiffApplyInvalidStatusException = exports.ObjectMergeStatusCheckFailedException = exports.ObjectCloneFunctionNotSupportException = exports.ArgumentNullOrEmptyException = void 0;
 const Exception_1 = require("../../types/Exception");
+/** Argument null exception */
 class ArgumentNullOrEmptyException extends Exception_1.Exception {
     constructor(msg) {
         super(msg);
@@ -12,6 +13,11 @@ class ArgumentNullOrEmptyException extends Exception_1.Exception {
     }
 }
 exports.ArgumentNullOrEmptyException = ArgumentNullOrEmptyException;
+/**
+ * Object Clone:
+ * Function type is not supported.
+ * Exception will be thrown if try to clone a function type object
+ */
 class ObjectCloneFunctionNotSupportException extends Exception_1.Exception {
     constructor() {
         super();
@@ -21,3 +27,60 @@ class ObjectCloneFunctionNotSupportException extends Exception_1.Exception {
     }
 }
 exports.ObjectCloneFunctionNotSupportException = ObjectCloneFunctionNotSupportException;
+/**
+ * Object Clone:
+ * Object different status could not be matched.
+ * Exception will be thrown if the object diff could not to be merged
+ */
+class ObjectMergeStatusCheckFailedException extends Exception_1.Exception {
+    status;
+    path;
+    constructor(path, status) {
+        super();
+        this.path = path;
+        this.status = status === "add" ? "新增" : status === "del" ? "删除" : "修改";
+    }
+    toString() {
+        return `错误的合并状态 - ${this.status} 路径 ${this.path} 前后状态不一致`;
+    }
+}
+exports.ObjectMergeStatusCheckFailedException = ObjectMergeStatusCheckFailedException;
+/**
+ * Object Clone:
+ * Object different status could not be applied.
+ * Exception will be thrown if the object diff could not to be applied
+ */
+class ObjectDiffApplyInvalidStatusException extends Exception_1.Exception {
+    value;
+    constructor(value) {
+        super();
+        this.value = value;
+    }
+    toString() {
+        let v2s = "";
+        try {
+            v2s = JSON.stringify(this.value);
+        }
+        finally {
+            v2s = v2s || `[${(typeof this.value).toString()}]`;
+        }
+        return `无效的状态 - 值 ${v2s} 不能应用指定的状态`;
+    }
+}
+exports.ObjectDiffApplyInvalidStatusException = ObjectDiffApplyInvalidStatusException;
+/**
+ * Object Clone:
+ * Object different merge failed.
+ * Exception will be thrown if the object element could not be accessed
+ */
+class ObjectDiffMergeFailedException extends Exception_1.Exception {
+    path;
+    constructor(path) {
+        super();
+        this.path = path;
+    }
+    toString() {
+        return `对象合并遇到问题 - 路径 ${this.path} 存在无法访问的对象`;
+    }
+}
+exports.ObjectDiffMergeFailedException = ObjectDiffMergeFailedException;

package/dist/lib/utilities/core/Language.js

@@ -536,10 +536,23 @@ function _areaCodeToString(eArea) {
             return "zh_CN";
     }
 }
+/**
+ * Parse area code to general string
+ *
+ * @param eArea the area code
+ * @returns return the general string of specified area code
+ */
 function parseAreaCode(eArea) {
     return _areaCodeToString(eArea);
 }
 exports.parseAreaCode = parseAreaCode;
+/**
+ * Convert the string to area code
+ *
+ * @param areaStr the source string
+ * @param forceArea a boolean value indicates whether needs to have a strict check for the source string. (That means if in strict mode and the string could not be converted, an unkonwn will be returned.)
+ * @returns return the area code
+ */
 function parseAreaString(areaStr, forceArea) {
     return _parseAreaString(areaStr, forceArea);
 }

package/dist/lib/utilities/core/Log.js

@@ -99,7 +99,9 @@ function _endPerf(recorder, console) {
     }
     return perfTime;
 }
+/** Tianyu Log Instance */
 exports.Log = _log;
+/** Tianyu Performance Instance */
 exports.Performance = {
     startPerf: _startPerf,
     endPerf: _endPerf,

package/dist/lib/utilities/core/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**@format */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectHelper = exports.ObjectCalculater = exports.Performance = exports.Log = exports.parseAreaString = exports.parseAreaCode = exports.ObjectDiffMergeFailedException = exports.ObjectDiffApplyInvalidStatusException = exports.ObjectMergeStatusCheckFailedException = exports.ObjectCloneFunctionNotSupportException = exports.ArgumentNullOrEmptyException = void 0;
+var Errors_1 = require("./Errors");
+Object.defineProperty(exports, "ArgumentNullOrEmptyException", { enumerable: true, get: function () { return Errors_1.ArgumentNullOrEmptyException; } });
+Object.defineProperty(exports, "ObjectCloneFunctionNotSupportException", { enumerable: true, get: function () { return Errors_1.ObjectCloneFunctionNotSupportException; } });
+Object.defineProperty(exports, "ObjectMergeStatusCheckFailedException", { enumerable: true, get: function () { return Errors_1.ObjectMergeStatusCheckFailedException; } });
+Object.defineProperty(exports, "ObjectDiffApplyInvalidStatusException", { enumerable: true, get: function () { return Errors_1.ObjectDiffApplyInvalidStatusException; } });
+Object.defineProperty(exports, "ObjectDiffMergeFailedException", { enumerable: true, get: function () { return Errors_1.ObjectDiffMergeFailedException; } });
+var Language_1 = require("./Language");
+Object.defineProperty(exports, "parseAreaCode", { enumerable: true, get: function () { return Language_1.parseAreaCode; } });
+Object.defineProperty(exports, "parseAreaString", { enumerable: true, get: function () { return Language_1.parseAreaString; } });
+var Log_1 = require("./Log");
+Object.defineProperty(exports, "Log", { enumerable: true, get: function () { return Log_1.Log; } });
+Object.defineProperty(exports, "Performance", { enumerable: true, get: function () { return Log_1.Performance; } });
+//// object
+var Calculater_1 = require("./object/Calculater");
+Object.defineProperty(exports, "ObjectCalculater", { enumerable: true, get: function () { return Calculater_1.ObjectCalculater; } });
+var Helper_1 = require("./object/Helper");
+Object.defineProperty(exports, "ObjectHelper", { enumerable: true, get: function () { return Helper_1.ObjectHelper; } });

package/dist/lib/utilities/core/object/Calculater.js

@@ -0,0 +1,230 @@
+"use strict";
+/**@format */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectCalculater = void 0;
+const TMap_1 = require("../../../types/TMap");
+const PathBase_1 = require("../../../types/PathBase");
+const Helper_1 = require("./Helper");
+const Errors_1 = require("../Errors");
+class ObjectDiffCalculation {
+    preObj;
+    nextObj;
+    objStack;
+    diffs;
+    constructor(pre, next) {
+        this.preObj = pre;
+        this.nextObj = next;
+        this.objStack = [];
+        this.diffs = new TMap_1.TMap();
+    }
+    calculate() {
+        this._calculate(this.preObj, this.nextObj);
+        return this.diffs;
+    }
+    _calculate(pre, next) {
+        const isPreSimple = Helper_1.ObjectHelper.isSimpleDataType(pre);
+        const isNextSimple = Helper_1.ObjectHelper.isSimpleDataType(next);
+        // 如果是基本数据类型
+        if (isPreSimple && isNextSimple) {
+            // 如果数据不相同，则记录
+            if (pre !== next) {
+                const path = new PathBase_1.PathBase(this.objStack);
+                this.diffs.set(path, {
+                    path: path.toString(),
+                    old: Helper_1.ObjectHelper.clone(pre),
+                    new: Helper_1.ObjectHelper.clone(next),
+                });
+            }
+            // 直接返回
+            return;
+        }
+        // 获取新老对象是否为数组类型
+        const isPreArray = Array.isArray(pre);
+        const isNextArray = Array.isArray(next);
+        if (isPreArray || isNextArray) {
+            const path = new PathBase_1.PathBase(this.objStack);
+            if (isPreArray && isNextArray) {
+                // Pre为数组 Next为数组
+                const isSame = Helper_1.ObjectHelper.compareObjects(pre, next);
+                if (isSame === "different") {
+                    this.diffs.set(path, {
+                        path: path.toString(),
+                        old: Helper_1.ObjectHelper.clone(pre),
+                        new: Helper_1.ObjectHelper.clone(next),
+                    });
+                }
+            }
+            else {
+                // Pre或Next为数组，另外一个为object类型
+                // Pre为简单对象 & Next为数组
+                // Pre为数组 & Next为简单对象
+                this.diffs.set(path, {
+                    path: path.toString(),
+                    old: Helper_1.ObjectHelper.clone(pre),
+                    new: Helper_1.ObjectHelper.clone(next),
+                });
+            }
+            return;
+        }
+        // 新老对象都是Object类型，按照Object类型进行比对
+        this._calculateObject(pre, next);
+    }
+    _calculateObject(pre, next) {
+        const preKeys = Object.keys(pre);
+        const nextKeys = Object.keys(next);
+        const sameItems = [];
+        // 寻找已经删除的
+        for (const key of preKeys) {
+            if (nextKeys.includes(key)) {
+                sameItems.push(key);
+            }
+            else {
+                // 已经被删除的对象，储存下来
+                this.objStack.push(key);
+                const path = new PathBase_1.PathBase(this.objStack);
+                this.diffs.set(path, {
+                    path: path.toString(),
+                    old: Helper_1.ObjectHelper.clone(pre[key]),
+                    new: undefined,
+                    deleted: true,
+                });
+                this.objStack.pop();
+            }
+        }
+        // 寻找新加的元素
+        for (const key of nextKeys) {
+            if (!preKeys.includes(key)) {
+                // 老的对象中不存在，新加的状态储存下来
+                this.objStack.push(key);
+                const path = new PathBase_1.PathBase(this.objStack);
+                this.diffs.set(path, {
+                    path: path.toString(),
+                    old: undefined,
+                    new: Helper_1.ObjectHelper.clone(next[key]),
+                    added: true,
+                });
+                this.objStack.pop();
+            }
+        }
+        // 依次遍历所有相同的元素，判断其是否存在改变
+        for (const key of sameItems) {
+            this.objStack.push(key);
+            this._calculate(pre[key], next[key]);
+            this.objStack.pop();
+        }
+    }
+}
+function __checkOldAndNewStatus(pre, next) {
+    return Helper_1.ObjectHelper.compareObjects(pre, next) === "same";
+}
+/** Object Calculation Manager of Tianyu to provide data changes delta calculation and merge */
+class ObjectCalculater {
+    /**
+     * Compare two objects and get the delta changes between the two objects
+     *
+     * @param previous the previous object
+     * @param newest the newest object
+     * @returns return the defferents map
+     */
+    static calculateDiff(previous, newest) {
+        const calculationEntity = new ObjectDiffCalculation(previous, newest);
+        return calculationEntity.calculate();
+    }
+    /**
+     * Merge the object value status from one to another one following with the object different maps
+     *
+     * @param value the raw value(status)
+     * @param diffs the value changed status map array, contains multiply status maps and the status merge will be one by one.
+     * @param strict a boolean value used to whether the program needs a strict status check to avoid some data errors
+     * @returns return a new value status
+     */
+    static mergeDiff(value, diffs, strict) {
+        const resultObj = { root: Helper_1.ObjectHelper.clone(value) };
+        if (0 === diffs.length) {
+            return resultObj.root;
+        }
+        for (const diff of diffs) {
+            const rootPathDiff = diff.get(new PathBase_1.PathBase([]));
+            if (rootPathDiff) {
+                if (strict && diff.size() > 1) {
+                    throw new Errors_1.ObjectDiffApplyInvalidStatusException(resultObj.root);
+                }
+                if (strict && !__checkOldAndNewStatus(resultObj.root, rootPathDiff.old)) {
+                    throw new Errors_1.ObjectMergeStatusCheckFailedException("", rootPathDiff.deleted ? "del" : rootPathDiff.added ? "add" : "modify");
+                }
+                // 直接设置新值
+                resultObj.root = Helper_1.ObjectHelper.clone(rootPathDiff.new);
+                // 原始值为简单数据类型 或 数组类型 需要根目录修改
+            }
+            else if (Helper_1.ObjectHelper.isSimpleDataType(resultObj.root) || Array.isArray(resultObj.root)) {
+                throw new Errors_1.ObjectDiffApplyInvalidStatusException(resultObj.root);
+            }
+            else {
+                // 没有根目录修改
+                // 并且对象不是简单类型
+                // 按照复杂值递归进行更改
+                // 依次遍历所有的路径
+                for (const [path, info] of diff) {
+                    // 此处不应该进入条件
+                    if (!!!path || !!!info)
+                        continue;
+                    // 获取路径并预处理
+                    const pathDir = path.getDirs();
+                    const endDir = pathDir.pop();
+                    // 此处不应该进入条件
+                    if (!!!endDir)
+                        continue;
+                    const mergeType = info.added ? "add" : info.deleted ? "del" : "modify";
+                    // 依次查询元素路径
+                    // 检查父元素是否不存在（error）
+                    let obj = resultObj.root;
+                    for (const key of pathDir) {
+                        if (!!!obj[key]) {
+                            // 如果父对象不存在 在严格模式下抛出异常
+                            if (strict) {
+                                throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
+                            }
+                            else {
+                                obj[key] = {};
+                            }
+                        }
+                        // 目标点向下移动
+                        obj = obj[key];
+                    }
+                    // 再次检查对象状态 （理论上不应该进入此判断）
+                    if (!!!obj)
+                        throw new Errors_1.ObjectDiffMergeFailedException(info.path);
+                    if (info.added) {
+                        // 新增一个元素
+                        // 严格模式下 不允许新增对象存在
+                        if (strict && obj[endDir]) {
+                            throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
+                        }
+                        // 执行拷贝
+                        obj[endDir] = Helper_1.ObjectHelper.clone(info.new);
+                    }
+                    else if (info.deleted) {
+                        // 删除一个元素
+                        // 严格模式下 不允许删除对象不存在
+                        if (strict && !!!obj[endDir]) {
+                            throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
+                        }
+                        // 执行删除（如果对象存在）
+                        !!obj[endDir] && delete obj[endDir];
+                    }
+                    else {
+                        // 修改一个元素
+                        // 严格模式下 不允许修改对象不存在
+                        if (strict && (!!!obj[endDir] || __checkOldAndNewStatus(info.old, obj[endDir]))) {
+                            throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
+                        }
+                        // 执行修改
+                        obj[endDir] = Helper_1.ObjectHelper.clone(info.new);
+                    }
+                }
+            }
+        }
+        return resultObj.root;
+    }
+}
+exports.ObjectCalculater = ObjectCalculater;

package/dist/lib/utilities/core/{ObjectHelper.js → object/Helper.js}

@@ -2,7 +2,7 @@
 /**@format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObjectHelper = void 0;
-const Errors_1 = require("./Errors");
+const Errors_1 = require("../Errors");
 /** Object Helper of Tianyu to provide data type checking, objects comparing, validation, data clone and other functions */
 class ObjectHelper {
     /**

package/dist/lib/utilities/security/Guid.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.guid = void 0;
 const perf_hooks_1 = require("perf_hooks");
+/** Generate a Guid value string */
 function guid() {
     let d = new Date().getTime();
     d += perf_hooks_1.performance.now(); //use high-precision timer if available

package/dist/lib/utilities/security/Hash.js

@@ -2,6 +2,7 @@
 /**@format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hash = void 0;
+/** Generate a hash code number of the string */
 function hash(source) {
     let length = source.length;
     let hashCode = 0;

package/dist/lib/utilities/security/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**@format */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hash = exports.guid = void 0;
+var Guid_1 = require("./Guid");
+Object.defineProperty(exports, "guid", { enumerable: true, get: function () { return Guid_1.guid; } });
+var Hash_1 = require("./Hash");
+Object.defineProperty(exports, "hash", { enumerable: true, get: function () { return Hash_1.hash; } });

package/dist/types/index.d.ts

@@ -1,15 +1,18 @@
 /**@format */
 export { AreaCode } from "./types/AreaCode";
-export { type PathTargetType, type IPath } from "./types/Coding";
 export { Exception } from "./types/Exception";
 export { LogLevel, type ILog, type IPerfRecorder } from "./types/Logs";
+export { type IObjectDiffInfo, type ObjectDiffMap } from "./types/Object";
+export { PathBase } from "./types/PathBase";
 export { EncryptOption, type ICipher } from "./types/Security";
-export { type MapOfBoolean, type MapOfStrings, type MapOfString, type MapOfType, type CallbackAction, type CallbackActionT, } from "./types/Types";
-export { PathProcessorSourceLostException, PathDirectoryValidationFailException } from "./utilities/coding/Error";
-export { PathProcessor } from "./utilities/coding/PathProcessor";
-export { ArgumentNullOrEmptyException, ObjectCloneFunctionNotSupportException } from "./utilities/core/Errors";
+export { TMap } from "./types/TMap";
+export { type MapOfBoolean, type MapOfStrings, type MapOfString, type MapOfType, type CallbackAction, type CallbackActionT, type IComparable, } from "./types/Types";
+export { PathProcessorSourceLostException, PathDirectoryValidationFailException, PathDirAndFileConvertInvaild, } from "./utilities/coding/Error";
+export { type PathTargetType, Path } from "./utilities/coding/Path";
+export { ArgumentNullOrEmptyException, ObjectCloneFunctionNotSupportException, ObjectMergeStatusCheckFailedException, ObjectDiffApplyInvalidStatusException, ObjectDiffMergeFailedException, } from "./utilities/core/Errors";
 export { parseAreaCode, parseAreaString } from "./utilities/core/Language";
 export { Log, Performance } from "./utilities/core/Log";
-export { ObjectHelper } from "./utilities/core/ObjectHelper";
+export { ObjectCalculater } from "./utilities/core/object/Calculater";
+export { ObjectHelper } from "./utilities/core/object/Helper";
 export { guid } from "./utilities/security/Guid";
 export { hash } from "./utilities/security/Hash";

package/dist/types/types/AreaCode.d.ts

@@ -1,4 +1,5 @@
 /**@format */
+/** International Area name and its code */
 export declare enum AreaCode {
     unknown = 0,
     af_ZA = 1078,

package/dist/types/types/Exception.d.ts

@@ -1,5 +1,11 @@
 /**@format */
+/** Exception base class */
 export declare class Exception extends Error {
     constructor(msg?: string, options?: ErrorOptions);
+    /**
+     * Get a string of the Exception object
+     *
+     * @returns return an error message
+     */
     toString(): string;
 }

package/dist/types/types/Logs.d.ts

@@ -1,21 +1,64 @@
 /**@format */
+/** Tianyu Log Level */
 export declare enum LogLevel {
+    /** Debug mode log */
     DEBUG = 0,
+    /** error msg */
     ERROR = 1,
+    /** fatal error msg */
     FATAL = 2,
+    /** info log */
     INFO = 3,
+    /** warning log */
     WARNING = 4,
+    /** default log */
     LOG = 5
 }
+/** Tianyu Log Interface */
 export interface ILog {
+    /**
+     * Write a console log with specified log level
+     *
+     * @param msg the message body
+     * @param level the console log level, if not be specified, to print as default log
+     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     */
     log(msg: string, level?: LogLevel, timer?: boolean): void;
+    /**
+     * Write a console info log
+     * @param msg the message body
+     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     */
     info(msg: string, timer?: boolean): void;
+    /**
+     * Write a console warning log
+     * @param msg the message body
+     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     */
     warn(msg: string, timer?: boolean): void;
+    /**
+     * Write a console debug log
+     * @param msg the message body
+     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     */
     debug(msg: string, timer?: boolean): void;
+    /**
+     * Write a console error message
+     * @param msg the message body
+     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     */
     error(msg: string, timer?: boolean): void;
+    /**
+     * Write a console fatal message
+     * @param msg the message body
+     * @param timer a boolean value indicates whether needs to add a timestamp for the log
+     */
     fatal(msg: string, timer?: boolean): void;
 }
+/** Tianyu Performance recorder */
 export interface IPerfRecorder {
+    /** the recording id */
     id: string;
+    /** the start time number */
     start: number;
 }

package/dist/types/types/Object.d.ts

@@ -0,0 +1,18 @@
+/**@format */
+import { TMap } from "./TMap";
+import { PathBase } from "./PathBase";
+/** Tianyu Object calculated different item */
+export interface IObjectDiffInfo {
+    /** different item path */
+    path: string;
+    /** the old value of this path */
+    old: any;
+    /** the new value of this path */
+    new: any;
+    /** does the change be deletion */
+    deleted?: true;
+    /** does the change be adding */
+    added?: true;
+}
+/** Different items map */
+export type ObjectDiffMap = TMap<PathBase, IObjectDiffInfo>;

package/dist/types/types/PathBase.d.ts

@@ -0,0 +1,76 @@
+/**@format */
+import { IComparable } from "./Types";
+/** Path base class */
+export declare class PathBase implements IComparable {
+    protected _dirs: string[];
+    /**
+     * Create a Path instance by specified dirs
+     *
+     * @param dirs the specified directories
+     */
+    constructor(dirs?: string[]);
+    /**
+     * Convert the path instance to string
+     *
+     * @returns return the fromatted string
+     */
+    toString(): string;
+    /**
+     * Iterator of path directories
+     *
+     * @returns return an iterator
+     */
+    [Symbol.iterator](): {
+        next: () => {
+            done: boolean;
+            value: string;
+        };
+    };
+    /**
+     * Get a directories array deep copy
+     *
+     * @returns return directories
+     */
+    getDirs(): string[];
+    /**
+     * Get a number that indicates the directories count
+     *
+     * @returns return the directories count
+     */
+    length(): number;
+    /**
+     * Append a new directory to the end of path
+     *
+     * @param dir the new directory name
+     * @returns return the new directories count
+     */
+    append(dir: string): number;
+    /**
+     * Clean all the pathes
+     */
+    clear(): void;
+    /**
+     * Remove the end directory of the path instance and return it
+     *
+     * @returns return the end of directory
+     */
+    pop(): string | undefined;
+    /**
+     * Remove the first directory of the path instance and return it
+     *
+     * @returns return the first directory
+     */
+    shift(): string | undefined;
+    /**
+     * Convert the path instance to string for object comparing
+     *
+     * @returns return the comparable string
+     */
+    getString(): string;
+    /**
+     * Get the hashcode of current path
+     *
+     * @returns always return 0
+     */
+    getHashCode(): number;
+}

package/dist/types/types/Security.d.ts

@@ -1,9 +1,23 @@
 /**@format */
+/** Encrypt Option Type */
 export declare enum EncryptOption {
     Encryption = 0,
     Decryption = 1
 }
+/** An Interface of the Cipher */
 export interface ICipher {
+    /**
+     * To encode the source value
+     *
+     * @param source the source value
+     * @returns return the encoded value
+     */
     encryption(source: number[]): number[];
+    /**
+     * To decode the encoded value
+     *
+     * @param source the encoded value
+     * @returns return the decoded value
+     */
     decryption(source: number[]): number[];
 }