@aitianyu.cn/types 0.1.2 → 0.1.3

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

@@ -6,27 +6,51 @@ const TMap_1 = require("../../types/TMap");
 const PathBase_1 = require("../../types/PathBase");
 const ObjectHelper_1 = require("./ObjectHelper");
 const Errors_1 = require("../Errors");
+/**
+ * Internal helper class that walks two object snapshots and collects
+ * all field-level differences into an ObjectDiffMap.
+ *
+ * 内部帮助类，遍历两个对象快照并将所有字段级差异收集到 ObjectDiffMap 中。
+ */
 class ObjectDiffCalculation {
     preObj;
     nextObj;
+    /** Stack of property names tracking the current traversal path. / 跟踪当前遍历路径的属性名堆栈。 */
     objStack;
     diffs;
+    /**
+     * @param pre the previous (old) object snapshot / 之前（旧）的对象快照
+     * @param next the next (new) object snapshot / 之后（新）的对象快照
+     */
     constructor(pre, next) {
         this.preObj = pre;
         this.nextObj = next;
         this.objStack = [];
         this.diffs = new TMap_1.TMap();
     }
+    /**
+     * Run the diff calculation and return the collected differences.
+     * 执行差异计算并返回收集到的差异映射表。
+     *
+     * @returns the map of all detected differences / 所有检测到的差异映射表
+     */
     calculate() {
         this._calculate(this.preObj, this.nextObj);
         return this.diffs;
     }
+    /**
+     * Recursively compare `pre` and `next` at the current path depth.
+     * Dispatches to primitive, array, or object comparison as appropriate.
+     *
+     * 在当前路径深度递归比较 `pre` 和 `next`。
+     * 根据类型分发到原始值、数组或对象比较逻辑。
+     */
     _calculate(pre, next) {
         const isPreSimple = ObjectHelper_1.ObjectHelper.isSimpleDataType(pre);
         const isNextSimple = ObjectHelper_1.ObjectHelper.isSimpleDataType(next);
-        // 如果是基本数据类型
+        // 如果是基本数据类型 / Both values are primitive types
         if (isPreSimple && isNextSimple) {
-            // 如果数据不相同，则记录
+            // 如果数据不相同，则记录 / Record if the values differ
             if (pre !== next) {
                 const path = new PathBase_1.PathBase(this.objStack);
                 this.diffs.set(path, {
@@ -35,16 +59,16 @@ class ObjectDiffCalculation {
                     new: ObjectHelper_1.ObjectHelper.clone(next),
                 });
             }
-            // 直接返回
+            // 直接返回 / No further recursion needed
             return;
         }
-        // 获取新老对象是否为数组类型
+        // 获取新老对象是否为数组类型 / Determine whether either value is an array
         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为数组
+                // Pre为数组 Next为数组 / Both are arrays — compare deeply
                 const isSame = ObjectHelper_1.ObjectHelper.compareObjects(pre, next);
                 if (isSame === "different") {
                     this.diffs.set(path, {
@@ -55,7 +79,7 @@ class ObjectDiffCalculation {
                 }
             }
             else {
-                // Pre或Next为数组，另外一个为object类型
+                // Pre或Next为数组，另外一个为object类型 / One is an array, the other is an object — always a diff
                 // Pre为简单对象 & Next为数组
                 // Pre为数组 & Next为简单对象
                 this.diffs.set(path, {
@@ -66,20 +90,29 @@ class ObjectDiffCalculation {
             }
             return;
         }
-        // 新老对象都是Object类型，按照Object类型进行比对
+        // 新老对象都是Object类型，按照Object类型进行比对 / Both are plain objects — recurse by key
         this._calculateObject(pre, next);
     }
+    /**
+     * Compare two plain objects key by key.
+     * Records deletions (keys only in `pre`), additions (keys only in `next`),
+     * and recurses for keys present in both.
+     *
+     * 逐键比较两个普通对象。
+     * 记录删除项（仅存在于 `pre` 中的键）、新增项（仅存在于 `next` 中的键），
+     * 并对两者共有的键递归比较。
+     */
     _calculateObject(pre, next) {
         const preKeys = Object.keys(pre);
         const nextKeys = Object.keys(next);
         const sameItems = [];
-        // 寻找已经删除的
+        // 寻找已经删除的 / Find keys that were removed in next
         for (const key of preKeys) {
             if (nextKeys.includes(key)) {
                 sameItems.push(key);
             }
             else {
-                // 已经被删除的对象，储存下来
+                // 已经被删除的对象，储存下来 / Key no longer exists — record as deleted
                 this.objStack.push(key);
                 const path = new PathBase_1.PathBase(this.objStack);
                 this.diffs.set(path, {
@@ -91,10 +124,10 @@ class ObjectDiffCalculation {
                 this.objStack.pop();
             }
         }
-        // 寻找新加的元素
+        // 寻找新加的元素 / Find keys that were added in next
         for (const key of nextKeys) {
             if (!preKeys.includes(key)) {
-                // 老的对象中不存在，新加的状态储存下来
+                // 老的对象中不存在，新加的状态储存下来 / Key did not exist before — record as added
                 this.objStack.push(key);
                 const path = new PathBase_1.PathBase(this.objStack);
                 this.diffs.set(path, {
@@ -106,7 +139,7 @@ class ObjectDiffCalculation {
                 this.objStack.pop();
             }
         }
-        // 依次遍历所有相同的元素，判断其是否存在改变
+        // 依次遍历所有相同的元素，判断其是否存在改变 / Recurse into keys present in both objects
         for (const key of sameItems) {
             this.objStack.push(key);
             this._calculate(pre[key], next[key]);
@@ -114,29 +147,61 @@ class ObjectDiffCalculation {
         }
     }
 }
+/**
+ * Check whether `pre` and `next` are deeply equal.
+ * 检查 `pre` 与 `next` 是否深度相等。
+ */
 function __checkOldAndNewStatus(pre, next) {
     return ObjectHelper_1.ObjectHelper.compareObjects(pre, next) === "same";
 }
-/** Object Calculation Manager of Tianyu to provide data changes delta calculation and merge */
+/**
+ * Object diff calculation and merge manager.
+ * Provides two static operations:
+ *   1. calculateDiff — compute the field-level delta between two object snapshots.
+ *   2. mergeDiff     — apply one or more diff maps to an object to advance its state.
+ *
+ * 对象差异计算与合并管理器。
+ * 提供两个静态操作：
+ *   1. calculateDiff — 计算两个对象快照之间的字段级差异。
+ *   2. mergeDiff     — 将一个或多个差异映射表应用到对象以推进其状态。
+ */
 class ObjectCalculater {
     /**
-     * Compare two objects and get the delta changes between the two objects
+     * Compute the field-level differences between two object snapshots.
+     * The result is an ObjectDiffMap keyed by the path of each changed field.
+     *
+     * 计算两个对象快照之间的字段级差异。
+     * 结果是以每个变更字段路径为键的 ObjectDiffMap。
      *
-     * @param previous the previous object
-     * @param newest the newest object
-     * @returns return the defferents map
+     * @param previous the previous (old) state / 之前（旧）状态的对象
+     * @param newest the next (new) state / 之后（新）状态的对象
+     * @returns a map of all field differences / 所有字段差异的映射表
      */
     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
+     * Apply an ordered sequence of diff maps to a value, producing the final merged state.
+     * Each diff map is applied in array order (earlier diffs are applied first).
+     *
+     * In strict mode, every merge step is validated:
+     * - Root-level diffs must not coexist with other diffs in the same map.
+     * - The current state must match the `old` value recorded in the diff entry.
+     * - Added fields must not already exist; deleted fields must still exist.
+     *
+     * 将有序的差异映射表序列应用到值上，生成最终合并状态。
+     * 每个差异映射表按数组顺序依次应用（先应用靠前的）。
+     *
+     * 在严格模式下，每步合并都会进行校验：
+     * - 根级差异不能与同一映射表中的其他差异共存。
+     * - 当前状态必须与差异条目中记录的 `old` 值匹配。
+     * - 新增字段不能已经存在；删除字段必须仍然存在。
      *
-     * @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
+     * @param value the base value to apply diffs onto / 要应用差异的基础值
+     * @param diffs an ordered array of diff maps to apply / 要依次应用的差异映射表数组
+     * @param strict when true, validates pre/post state on every change; defaults to false / 为 true 时对每次变更校验前后状态，默认为 false
+     * @returns the resulting value after all diffs have been applied / 应用所有差异后的最终值
      */
     static mergeDiff(value, diffs, strict) {
         const resultObj = { root: ObjectHelper_1.ObjectHelper.clone(value) };
@@ -156,39 +221,39 @@ class ObjectCalculater {
                             ? /* istanbul ignore next */ "add"
                             : "modify");
                 }
-                // 直接设置新值
+                // 直接设置新值 / Replace the entire root with the new value
                 resultObj.root = ObjectHelper_1.ObjectHelper.clone(rootPathDiff.new);
                 // 原始值为简单数据类型 或 数组类型 需要根目录修改
+                // Primitive or array root — must use a root-level diff entry
             }
             else if (ObjectHelper_1.ObjectHelper.isSimpleDataType(resultObj.root) || Array.isArray(resultObj.root)) {
                 throw new Errors_1.ObjectDiffApplyInvalidStatusException(resultObj.root);
             }
             else {
-                // 没有根目录修改
-                // 并且对象不是简单类型
-                // 按照复杂值递归进行更改
-                // 依次遍历所有的路径
+                // 没有根目录修改，按照复杂值递归进行更改
+                // No root-level change — apply each path entry individually
+                // 依次遍历所有的路径 / Iterate over every diff entry in this map
                 for (const [path, info] of diff) {
-                    // 此处不应该进入条件
+                    // 此处不应该进入条件 / Should not happen in normal usage
                     /* istanbul ignore if */
                     if (!!!path || !!!info) {
                         continue;
                     }
-                    // 获取路径并预处理
+                    // 获取路径并预处理 / Extract the path segments and isolate the terminal key
                     const pathDir = path.getDirs();
                     const endDir = pathDir.pop();
-                    // 此处不应该进入条件
+                    // 此处不应该进入条件 / Should not happen in normal usage
                     /* istanbul ignore if */
                     if (!!!endDir) {
                         continue;
                     }
                     const mergeType = info.added ? "add" : info.deleted ? "del" : "modify";
-                    // 依次查询元素路径
-                    // 检查父元素是否不存在（error）
+                    // 依次查询元素路径，检查父元素是否不存在
+                    // Traverse parent path segments, creating missing ones in non-strict mode
                     let obj = resultObj.root;
                     for (const key of pathDir) {
                         if (!!!obj[key]) {
-                            // 如果父对象不存在 在严格模式下抛出异常
+                            // 如果父对象不存在 在严格模式下抛出异常 / Missing parent — throw in strict mode
                             if (strict) {
                                 throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
                             }
@@ -196,39 +261,39 @@ class ObjectCalculater {
                                 obj[key] = {};
                             }
                         }
-                        // 目标点向下移动
+                        // 目标点向下移动 / Advance to the next level
                         obj = obj[key];
                     }
-                    // 再次检查对象状态 （理论上不应该进入此判断）
+                    // 再次检查对象状态（理论上不应该进入此判断）/ Sanity check — should not reach here
                     /* istanbul ignore if */
                     if (!!!obj) {
                         throw new Errors_1.ObjectDiffMergeFailedException(info.path);
                     }
                     if (info.added) {
-                        // 新增一个元素
-                        // 严格模式下 不允许新增对象存在
+                        // 新增一个元素 / Apply an addition
+                        // 严格模式下 不允许新增对象存在 / In strict mode, the key must not already exist
                         if (strict && obj[endDir]) {
                             throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
                         }
-                        // 执行拷贝
+                        // 执行拷贝 / Set the new value
                         obj[endDir] = ObjectHelper_1.ObjectHelper.clone(info.new);
                     }
                     else if (info.deleted) {
-                        // 删除一个元素
-                        // 严格模式下 不允许删除对象不存在
+                        // 删除一个元素 / Apply a deletion
+                        // 严格模式下 不允许删除对象不存在 / In strict mode, the key must still exist
                         if (strict && !!!obj[endDir]) {
                             throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
                         }
-                        // 执行删除（如果对象存在）
+                        // 执行删除（如果对象存在）/ Delete the property if it exists
                         !!obj[endDir] && delete obj[endDir];
                     }
                     else {
-                        // 修改一个元素
-                        // 严格模式下 不允许修改对象不存在
+                        // 修改一个元素 / Apply a modification
+                        // 严格模式下 不允许修改对象不存在 / In strict mode, the key must exist and match the recorded old value
                         if (strict && (!!!obj[endDir] || __checkOldAndNewStatus(info.old, obj[endDir]))) {
                             throw new Errors_1.ObjectMergeStatusCheckFailedException(info.path, mergeType);
                         }
-                        // 执行修改
+                        // 执行修改 / Overwrite with the new value
                         obj[endDir] = ObjectHelper_1.ObjectHelper.clone(info.new);
                     }
                 }

package/dist/lib/core/object/DataView.js

@@ -2,13 +2,22 @@
 /** @format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataView = void 0;
-/** DataView Object Type */
+/**
+ * DataView utility class for creating a globalThis.DataView from typed array buffers.
+ * 用于从类型化数组缓冲区创建 globalThis.DataView 的工具类。
+ */
 class DataView {
     /**
-     * Create a new node:DataView from given data buffer
+     * Create a globalThis.DataView wrapping the given buffer.
+     * Supports ArrayBuffer, Int8Array, Uint8Array, and Uint8ClampedArray as input.
+     * Throws an Error for unsupported input types.
      *
-     * @param data source data buffer
-     * @returns return node:DataView type equals to given data buffer
+     * 创建一个包装给定缓冲区的 globalThis.DataView。
+     * 支持 ArrayBuffer、Int8Array、Uint8Array 和 Uint8ClampedArray 作为输入。
+     * 不支持的输入类型将抛出 Error。
+     *
+     * @param data the source data buffer / 源数据缓冲区
+     * @returns a DataView over the given buffer / 对给定缓冲区的 DataView 视图
      */
     static parse(data) {
         if (data instanceof Int8Array || data instanceof Uint8Array || data instanceof Uint8ClampedArray) {

package/dist/lib/core/object/Integer.js

@@ -6,15 +6,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Integer = void 0;
 const crypto_1 = __importDefault(require("crypto"));
-/** Integer Object Type */
+/**
+ * Integer utility class providing random number generation,
+ * byte conversion, and safe bitwise operations.
+ *
+ * 整数工具类，提供随机数生成、字节转换及安全位运算操作。
+ */
 class Integer {
     /**
-     * Get a random integer between min value and max value.
-     * min value should greater than 0, max value should less than 2^48-1 (281474976710655)
+     * Generate a cryptographically random integer in the range [min, max).
+     * min is clamped to 0; max defaults to 2^48-1 (281474976710655).
      *
-     * @param min the min value (0 will be applied when not given)
-     * @param max the max value (281474976710655 will be applied when not given)
-     * @returns return the random value
+     * 在 [min, max) 范围内生成密码学安全的随机整数。
+     * min 最小为 0；max 默认为 2^48-1（281474976710655）。
+     *
+     * @param min lower bound (inclusive), defaults to 0 / 下界（含），默认为 0
+     * @param max upper bound (exclusive), defaults to 281474976710655 / 上界（不含），默认为 281474976710655
+     * @returns the random integer / 随机整数
      */
     static random(min, max) {
         const minNum = Math.max(min ?? 0, 0);
@@ -22,10 +30,11 @@ class Integer {
         return crypto_1.default.randomInt(Math.min(minNum, maxNum), Math.max(minNum, maxNum));
     }
     /**
-     * convert source number to be a 8-byte array
+     * Convert a number to an 8-byte (big-endian) number array.
+     * 将数值转换为 8 字节（大端序）数字数组。
      *
-     * @param srcValue source value
-     * @returns return a 8-byte array
+     * @param srcValue the source number / 源数值
+     * @returns an 8-element array of byte values / 包含 8 个字节值的数组
      */
     static toBytes(srcValue) {
         const bytes = [];
@@ -37,47 +46,57 @@ class Integer {
         return bytes;
     }
     /**
-     * number left shift
-     * times will be calculated to get the end 6-bit at the beginning to avoid over-flow
+     * Left-shift `value` by `times` bits.
+     * Only the lowest 6 bits of `times` are used to prevent overflow.
+     *
+     * 将 `value` 左移 `times` 位。
+     * 仅使用 `times` 的低 6 位以防止溢出。
      *
-     * @param value source value
-     * @param times left shift steps
-     * @returns return result value
+     * @param value source value / 源数值
+     * @param times number of bits to shift / 移位位数
+     * @returns shifted result / 移位结果
      */
     static left(value, times) {
         // eslint-disable-next-line no-bitwise
         return value << (times & 0x3f);
     }
     /**
-     * number right shift
-     * times will be calculated to get the end 6-bit at the beginning to avoid over-flow
+     * Signed right-shift `value` by `times` bits.
+     * Only the lowest 6 bits of `times` are used to prevent overflow.
      *
-     * @param value source value
-     * @param times right shift steps
-     * @returns return result value
+     * 对 `value` 进行有符号右移 `times` 位。
+     * 仅使用 `times` 的低 6 位以防止溢出。
+     *
+     * @param value source value / 源数值
+     * @param times number of bits to shift / 移位位数
+     * @returns shifted result / 移位结果
      */
     static right(value, times) {
         // eslint-disable-next-line no-bitwise
         return value >> (times & 0x3f);
     }
     /**
-     * number unsigned right shift
-     * times will be calculated to get the end 6-bit at the beginning to avoid over-flow
+     * Unsigned right-shift `value` by `times` bits.
+     * Only the lowest 6 bits of `times` are used to prevent overflow.
+     *
+     * 对 `value` 进行无符号右移 `times` 位。
+     * 仅使用 `times` 的低 6 位以防止溢出。
      *
-     * @param value source value
-     * @param times right shift steps
-     * @returns return result value
+     * @param value source value / 源数值
+     * @param times number of bits to shift / 移位位数
+     * @returns shifted result / 移位结果
      */
     static rightUnsigned(value, times) {
         // eslint-disable-next-line no-bitwise
         return value >>> (times & 0x3f);
     }
     /**
-     * or
+     * Bitwise OR of value1 and one or more additional values.
+     * 对 value1 与一个或多个附加值进行按位或运算。
      *
-     * @param value1 the first value
-     * @param values the following values array
-     * @returns return calculated value
+     * @param value1 the first operand / 第一个操作数
+     * @param values additional operands / 附加操作数
+     * @returns the bitwise OR result / 按位或结果
      */
     static or(value1, ...values) {
         let value = value1;
@@ -88,11 +107,12 @@ class Integer {
         return value;
     }
     /**
-     * and
+     * Bitwise AND of value1 and one or more additional values.
+     * 对 value1 与一个或多个附加值进行按位与运算。
      *
-     * @param value1 the first value
-     * @param values the following values array
-     * @returns return calculated value
+     * @param value1 the first operand / 第一个操作数
+     * @param values additional operands / 附加操作数
+     * @returns the bitwise AND result / 按位与结果
      */
     static and(value1, ...values) {
         let value = value1;
@@ -103,11 +123,12 @@ class Integer {
         return value;
     }
     /**
-     * xor
+     * Bitwise XOR of value1 and value2.
+     * 对 value1 和 value2 进行按位异或运算。
      *
-     * @param value1 the first value
-     * @param value2 the second value
-     * @returns return calculated value
+     * @param value1 the first operand / 第一个操作数
+     * @param value2 the second operand / 第二个操作数
+     * @returns the XOR result / 异或结果
      */
     static xor(value1, value2) {
         // eslint-disable-next-line no-bitwise

package/dist/lib/core/object/Json.js

@@ -2,26 +2,38 @@
 /** @format */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Json = void 0;
-/** Json Lib */
+/**
+ * JSON utility class providing safe and unsafe JSON parse helpers.
+ * JSON 工具类，提供安全与非安全的 JSON 解析帮助方法。
+ */
 class Json {
     /**
-     * @deprecated
+     * @deprecated Use parseSafe instead.
      *
-     * convert a string to be a javascript object.
-     * This is an unsafe function to convert a string to be object. suggest to use parseSafe to convert string to object.
+     * Parse a JSON string into a JavaScript object.
+     * This is an unsafe operation — it throws a SyntaxError if the string is invalid.
+     * Prefer parseSafe for production use.
      *
-     * @param src source string
-     * @returns target js-object
+     * 将 JSON 字符串解析为 JavaScript 对象。
+     * 这是一个不安全的操作——若字符串无效则抛出 SyntaxError。
+     * 生产环境建议使用 parseSafe。
+     *
+     * @param src the JSON source string / JSON 源字符串
+     * @returns the parsed JavaScript object / 解析后的 JavaScript 对象
      */
     static parse(src) {
         return JSON.parse(src);
     }
     /**
-     * convert a string to be a javascript object safty
+     * Parse a JSON string into a JavaScript object safely.
+     * Returns the specified fallback value (default: null) if parsing fails.
+     *
+     * 安全地将 JSON 字符串解析为 JavaScript 对象。
+     * 解析失败时返回指定的回退值（默认为 null）。
      *
-     * @param src source string
-     * @param failed value returned when converted failed, default is null
-     * @returns target js-object
+     * @param src the JSON source string / JSON 源字符串
+     * @param failed the value to return on parse failure, defaults to null / 解析失败时的返回值，默认为 null
+     * @returns the parsed object, or the fallback value on failure / 解析后的对象，失败时返回回退值
      */
     static parseSafe(src, failed = null) {
         try {

package/dist/lib/core/object/ObjectHelper.js

@@ -3,13 +3,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ObjectHelper = void 0;
 const Errors_1 = require("../Errors");
-/** Object Helper of Tianyu to provide data type checking, objects comparing, validation, data clone and other functions */
+/**
+ * Object utility class providing data type checking, deep cloning,
+ * serialization validation, and multi-object comparison.
+ *
+ * 对象工具类，提供数据类型检测、深度克隆、序列化校验和多对象比较功能。
+ */
 class ObjectHelper {
     /**
-     * check whether the specified value does extend from nodejs native type
+     * Check whether the given value is a JavaScript primitive type
+     * (boolean, string, number, symbol, null, or undefined).
      *
-     * @param {any} value supported value type of tianyu store
-     * @returns {boolean} return true if the value is based on type number, string, boolean, function, otherwise false
+     * 检查给定值是否为 JavaScript 原始类型
+     * （boolean、string、number、symbol、null 或 undefined）。
+     *
+     * @param value the value to inspect / 要检查的值
+     * @returns true if the value is a primitive type, false for objects and arrays
+     *          原始类型返回 true，对象和数组返回 false
      */
     static isSimpleDataType(value) {
         if (!!!value) {
@@ -19,10 +29,16 @@ class ObjectHelper {
         return typeofValue === "boolean" || typeofValue === "string" || typeofValue === "number" || typeofValue === "symbol";
     }
     /**
-     * get a deep copy from source
+     * Create a deep copy of the given value.
+     * Arrays and plain objects are recursively cloned.
+     * Throws ObjectCloneFunctionNotSupportException if the source contains a function.
+     *
+     * 创建给定值的深度副本。
+     * 数组和普通对象将递归克隆。
+     * 若源对象包含函数值，则抛出 ObjectCloneFunctionNotSupportException。
      *
-     * @param {any} sources the specified source value
-     * @returns {any} return a new value that is independent from sources
+     * @param source the value to clone / 要克隆的值
+     * @returns a new deep-copied value independent from the source / 与源对象独立的深度副本
      */
     static clone(source) {
         return ObjectHelper._clone(source);
@@ -71,10 +87,14 @@ class ObjectHelper {
         return result;
     }
     /**
-     * Check the object whether can be stringified
+     * Verify that the given value can be safely passed through JSON.stringify.
+     * Returns false for function types or objects containing function-valued properties.
      *
-     * @param obj be checked object
-     * @returns return true is valid, otherwise false
+     * 验证给定值是否可安全通过 JSON.stringify 序列化。
+     * 函数类型或包含函数属性的对象返回 false。
+     *
+     * @param obj the value to validate / 要校验的值
+     * @returns true if the value is JSON-serializable / 可 JSON 序列化时返回 true
      */
     static validateSerializable(obj) {
         // if type is function, is not invaliable to be string
@@ -113,11 +133,15 @@ class ObjectHelper {
         }
     }
     /**
-     * Compare two or more objects are the same or different
+     * Compare two or more values for deep equality.
+     * If fewer than two arguments are provided, "same" is returned.
+     *
+     * 对两个或多个值进行深度相等性比较。
+     * 若传入参数少于两个，则返回 "same"。
      *
-     * @param objs the objects which need to be compared
-     * @returns same - if all the objects are same, different - if at least one object is not same to other objects
-     * @description if there are only one parameter or no parameter is provided, same result will be returned
+     * @param objs the values to compare / 要比较的值
+     * @returns "same" if all values are deeply equal, "different" otherwise
+     *          所有值深度相等时返回 "same"，否则返回 "different"
      */
     static compareObjects(...objs) {
         // if objs less than 2, is not comparable