@codady/utils 0.0.11 → 0.0.13

package/CHANGELOG.md

@@ -2,7 +2,45 @@
 
 All changes to Utils including new features, updates, and removals are documented here.
 
-## [v0.0.11] - 2025-12-21
+
+## [v0.0.13] - 2025-12-25
+
+### Distribution Files
+* **JS**: https://unpkg.com/@codady/utils@0.0.13/dist/js/utils.js
+* **Zip**:https://unpkg.com/@codady/utils@0.0.13/dist.zip
+
+### Changes
+
+#### Fixed
+* Modify the `shallowCopy` function to add support for data types such as Date, Regex, Error, Buffer, ArrayBuffer, WeakSet, and WeakMap.修改`shallowCopy`函数，增加对Date、Regex、Error、Buffer、ArrayBuffer、WeakSet、WeakMap数据类型的支持。
+
+#### Added
+* Added the following functions: `copyObjectWithSymbol`.新增`copyObjectWithSymbol`函数。
+
+#### Removed
+* Null
+
+
+## [v0.0.12] - 2025-12-25
+
+### Distribution Files
+* **JS**: https://unpkg.com/@codady/utils@0.0.12/dist/js/utils.js
+* **Zip**:https://unpkg.com/@codady/utils@0.0.12/dist.zip
+
+### Changes
+
+#### Fixed
+* Improved the `deepMerge` function to support deep merging of Arrays, Objects, Sets, and Maps.强化了`deepMerge`函数，支持深度合并Array、Object、Set和Map。
+
+#### Added
+* New parameters added to the deepMerge function: `deepClone`, `onBeforeMerge`, and `onAfterMerge`.`deepMerge`函数的参数新增deepClone、onBeforeMerge、onAfterMerge参数。
+* Added the following functions: `shallowCopy`.新增`shallowCopy`函数。
+
+#### Removed
+* Removed the following functions: `deepEqual`, `deepMergeArrays`, `deepMergeObjects`, `deepMergeSets`, and `deepMergeMaps`.删除`deepEqual`、`deepMergeArrays`、`deepMergeObjects`、`deepMergeSets`、和`deepMegeMaps`函数。
+
+
+## [v0.0.11] - 2025-12-24
 
 ### Distribution Files
 * **JS**: https://unpkg.com/@codady/utils@0.0.11/dist/js/utils.js
@@ -14,7 +52,7 @@ All changes to Utils including new features, updates, and removals are documente
 * Null
 
 #### Added
-* 新增`deepEqual`、`deepMerge`、`deepMergeArrays`、`deepMergeObjects`、`deepMergeSets`、和`deepMegeMaps`函数。
+* Added the following functions: `deepEqual`, `deepMerge`, `deepMergeArrays`, `deepMergeObjects`, `deepMergeSets`, and `deepMergeMaps`.新增`deepEqual`、`deepMerge`、`deepMergeArrays`、`deepMergeObjects`、`deepMergeSets`、和`deepMegeMaps`函数。
 
 #### Removed
 * Null

package/dist/utils.cjs.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-24 17:50:8
+ * @since Last modified: 2025-12-25 14:33:12
  * @name Utils for web front-end.
- * @version 0.0.11
+ * @version 0.0.13
  * @author AXUI development team <3217728223@qq.com>
  * @description This is a set of general-purpose JavaScript utility functions developed by the AXUI team. All functions are pure and do not involve CSS or other third-party libraries. They are suitable for any web front-end environment.
  * @see {@link https://www.axui.cn|Official website}
@@ -16,8 +16,6 @@
 
 'use strict';
 
-var assert = require('assert');
-
 const getDataType = (obj) => {
     let tmp = Object.prototype.toString.call(obj).slice(8, -1), result;
     if (tmp === 'Function' && /^\s*class\s+/.test(obj.toString())) {
@@ -424,31 +422,176 @@ const wrapMapMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate = ()
     return methods;
 };
 
-const deepMergeObjects = (target, source, opts = {}) => {
-    let targetType = getDataType(target), sourceType = getDataType(source);
-    //target不是对象或者source为空则直接返回
-    if (targetType !== 'Object' || sourceType !== 'Object') {
-        return target;
-    }
-    const options = Object.assign({ itemMode: 'merge', propAppend: true, targetClone: false, useEnable: true }, opts), 
-    //如果是复制方法，则先复制target
-    result = options.targetClone ? deepClone(target) : target;
-    for (let k in source) {
-        if (source.hasOwnProperty(k) && result.hasOwnProperty(k)) {
-            let resp = deepMergeHelper(result[k], source[k], opts);
-            //resp={result,flag,type}
-            //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
-            if (!resp.flag) {
-                //类型不同则直接覆盖
-                if (options.useEnable && result.hasOwnProperty(k) && result[k]?.hasOwnProperty('enable') && typeof source[k] === 'boolean') {
-                    //部分替换，仅针对result={enable:true/false,a:''}，source=false/true这种情况和相反的情况，因为这种情况再笨框架比较多见  
-                    if (result[k]?.hasOwnProperty('enable') && typeof source[k] === 'boolean') {
-                        //result={enable:true,a:'',b:''},source[k]=false=>result={enable:false,a:'',b:''}
-                        result[k].enable = source[k];
-                    }
-                    else if (source[k]?.hasOwnProperty('enable') && typeof result[k] === 'boolean') {
-                        //source={enable:true,a:'',b:''},(result as any)[k]=false=>result={enable:false,a:'',b:''}
-                        result = Object.assign({ enable: result[k] }, source[k]);
+const copyObjectWithSymbol = (data) => {
+    if (!data || typeof data !== 'object') {
+        return data;
+    }
+    // Ensure the object type includes string and symbol keys
+    const obj = data, symbolProperties = Object.getOwnPropertySymbols(obj).reduce((acc, sym) => {
+        acc[sym] = obj[sym];
+        return acc;
+    }, {});
+    // Shallow copy the object and include the Symbol properties
+    return { ...obj, ...symbolProperties };
+};
+
+const shallowCopy = (data, options = {}) => {
+    const dataType = getDataType(data);
+    // Check if data is a Set
+    if (dataType === 'Set') {
+        // Shallow copy Set
+        return new Set([...data]);
+    }
+    // Check if data is a Map
+    if (dataType === 'Map') {
+        // Shallow copy Map
+        return new Map([...data]);
+    }
+    // Check if data is an Array
+    if (Array.isArray(data)) {
+        // Shallow copy Array
+        return [...data];
+    }
+    // Check if data is a Plain Object (including Symbol keys)
+    if (dataType === 'object') {
+        // Ensure the object type includes string and symbol keys
+        // Shallow copy the object and include the Symbol properties
+        return copyObjectWithSymbol(data);
+    }
+    // Check if data is a Date
+    if (dataType === 'Date') {
+        return new Date(data.getTime());
+    }
+    // Check if data is a RegExp
+    if (dataType === 'RegExp') {
+        return new RegExp(data.source, data.flags);
+    }
+    // Check if data is a Buffer (for Node.js)
+    if (dataType === 'Buffer') {
+        return Buffer.from(data);
+    }
+    // Check if data is an ArrayBuffer or TypedArray
+    if (dataType === 'ArrayBuffer' || ArrayBuffer.isView(data)) {
+        return data.slice(0);
+    }
+    // Check if data is a WeakSet
+    if (dataType === 'WeakSet') {
+        return new WeakSet([...data]);
+    }
+    // Check if data is a WeakMap
+    if (dataType === 'WeakMap') {
+        return new WeakMap([...data]);
+    }
+    // Check if data is an Error
+    if (dataType === 'Error') {
+        return new Error(data.message);
+    }
+    // For other types (such as numbers, strings, booleans, etc.), return the original value
+    return data;
+};
+
+const deepMerge = (target, source, opts = {}) => {
+    // Set default options
+    // 设置默认选项
+    const options = Object.assign({
+        // Merging mode for array and set collections:
+        // 'clear' means clear first then append; 'concat' means append directly at the end;
+        // 'replace' means merge sequentially (deep merging)
+        // 对于array和set合集的合并方式：'clear'表示先清空再追加；'concat'表示直接在尾部追加；
+        // 'replace'表示按顺序进行合并（深度合并）
+        dataMode: 'clear',
+        // Whether to directly append properties/items from source that target doesn't have.
+        // true: append; false: discard
+        // source对象如果有target对象没有的item或prop属性，是否直接新追加。true则追加；false则丢弃
+        inheritMissing: true,
+        // Whether to clone the target object, generating a brand new object. Default false.
+        // 是否克隆target对象，生成全新对象，默认false。
+        targetClone: false,
+        // How to merge when target or source has enable property and boolean value into {enable:boolean}
+        // 当target或source有enable属性（prop）和boolean值时，如何合并为{enable:boolean}
+        useEnable: true,
+        // Whether to allow merging key=symbol key-value pairs when target is {} type.
+        // target是{}类型时，是否允许合并key=symbol的键值对。
+        useSymbol: true,
+        // Options passed to the deepClone function when targetClone is true
+        // 当targetClone为true时传递给deepClone函数的选项
+        deepClone: {},
+        // Callback function executed before merging each data structure
+        // 在每个数据结构合并前执行的回调函数
+        onBeforeMerge: undefined,
+        // Callback function executed after merging each data structure
+        // 在每个数据结构合并后执行的回调函数
+        onAfterMerge: undefined,
+    }, opts), 
+    // Main helper function for recursive merging
+    // 递归合并的主辅助函数
+    deepMergeHelper = (target, source, options) => {
+        let targetType = getDataType(target), sourceType = getDataType(source), flag = true, type, result;
+        // Determine the type and perform appropriate merging
+        // 确定类型并执行相应的合并
+        if (targetType === 'Object' && sourceType === 'Object') {
+            result = deepMergeObjects(target, source, options);
+            type = 'Object';
+        }
+        else if (targetType === 'Array' && sourceType === 'Array') {
+            result = deepMergeArrays(target, source, options);
+            type = 'Array';
+        }
+        else if (targetType === 'Set' && sourceType === 'Set') {
+            result = deepMergeSets(target, source, options);
+            type = 'Set';
+        }
+        else if (targetType === 'Map' && sourceType === 'Map') {
+            result = deepMergeMaps(target, source, options);
+            type = 'Map';
+        }
+        else {
+            flag = false;
+            result = target;
+        }
+        return { result, flag, type };
+    }, 
+    // Special handling for objects with enable property
+    // 对具有enable属性的对象进行特殊处理
+    mergeEnableObject = (target, source) => {
+        if (target?.hasOwnProperty('enable') && typeof source === 'boolean') {
+            //result={enable:true,a:'',b:''},source[k]=false=>result={enable:false,a:'',b:''}
+            //仅设置enable属性
+            target.enable = source;
+            //返回target原对象
+            return target;
+        }
+        else if (source?.hasOwnProperty('enable') && typeof target === 'boolean') {
+            //source={enable:true,a:'',b:''},(result as any)[k]=false=>result={enable:false,a:'',b:''}
+            //返回新值，新值包含enable属性
+            return Object.assign({ enable: target }, source);
+        }
+        return source;
+    }, 
+    // Deep merge for objects
+    // 对象的深度合并
+    deepMergeObjects = (target, source, opts = {}) => {
+        let targetType = getDataType(target), sourceType = getDataType(source);
+        // If target is not an object or source is empty, return target directly
+        // 如果target不是对象或者source为空则直接返回
+        if (targetType !== 'Object' || sourceType !== 'Object') {
+            return target;
+        }
+        opts?.onBeforeMerge?.(target, source);
+        const options = Object.assign({ inheritMissing: true, targetClone: false, useEnable: true }, opts);
+        let result = {};
+        // If cloning is enabled, clone the target first
+        // 如果是复制方法，则先复制target
+        result = options.targetClone ? shallowCopy(target) : target;
+        for (let k in source) {
+            if (source.hasOwnProperty(k) && result.hasOwnProperty(k)) {
+                let resp = deepMergeHelper(result[k], source[k], opts);
+                //resp={result,flag,type}
+                //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
+                if (!resp.flag) {
+                    //类型不同则直接覆盖
+                    if (options.useEnable) {
+                        result[k] = mergeEnableObject(result[k], source[k]);
                     }
                     else {
                         //完全替换
@@ -456,99 +599,89 @@ const deepMergeObjects = (target, source, opts = {}) => {
                     }
                 }
                 else {
-                    //完全替换
-                    result[k] = source[k];
+                    //类型相同
+                    if (resp.type) {
+                        if (resp.type === 'Object') {
+                            //如果遇上对象则深度复制
+                            result[k] = resp.result;
+                        }
+                    }
+                    else {
+                        //其他类型则直接覆盖
+                        result[k] = source[k];
+                    }
                 }
             }
-            else {
-                // If both target and source are objects, merge them recursively
-                if (resp.type === 'Object') {
-                    result[k] = resp.result;
-                }
+            else if (source.hasOwnProperty(k) && !result.hasOwnProperty(k) && options.inheritMissing) {
+                //如果source有属性，result没有该属性，但是options允许追加属性则直接赋值
+                result[k] = source[k];
             }
         }
-        else if (source.hasOwnProperty(k) && !result.hasOwnProperty(k) && options.propAppend) {
-            //如果source有属性，result没有该属性，但是options允许追加属性则直接赋值
-            result[k] = source[k];
-        }
-    }
-    //Symbol键直接追加，因为Symbol是唯一，结果同Object.assign
-    if (options.useSymbol) {
-        let symbols = Object.getOwnPropertySymbols(source);
-        if (symbols.length > 0) {
-            for (let k of symbols) {
-                result[k] = source[k];
+        //Symbol键直接追加，因为Symbol是唯一，结果同Object.assign
+        if (options.useSymbol) {
+            let symbols = Object.getOwnPropertySymbols(source);
+            if (symbols.length) {
+                for (let k of symbols)
+                    result[k] = source[k];
             }
         }
-    }
-    return result;
-};
-
-const deepMergeArrays = (target, source, options = { itemMode: 'merge', propAppend: true, targetClone: false, useEnable: true }) => {
-    // Ensure both target and source are arrays
-    if (!Array.isArray(target) || !Array.isArray(source))
-        return target;
-    // Merge options, with default values
-    const opts = Object.assign({ itemMode: 'merge', propAppend: true, targetClone: false }, options), 
-    // If cloning is enabled, create a deep copy of the target array
-    result = opts.targetClone ? [...target] : target;
-    // Handle different merge strategies based on itemMode
-    if (opts.itemMode === 'replace') {
-        // Replace mode: clear the target array and push all items from the source array
-        result.length = 0;
-        result.push(...source);
+        options?.onAfterMerge?.(result, target, source);
         return result;
-    }
-    else if (opts.itemMode === 'concat') {
-        // Concatenate mode: append all items from the source array to the target array
-        result.push(...source);
-        return result;
-    }
-    else {
-        // Default "merge" mode: recursively merge items in the arrays
-        for (let i = 0; i < source.length; i++) {
-            let resp = deepMergeHelper(result[i], source[i], opts);
-            //resp={result,flag,type}
-            //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
-            if (!resp.flag) {
-                result[i] = source[i];
+    }, deepMergeArrays = (target, source, options = {}) => {
+        // Ensure both target and source are arrays
+        if (!Array.isArray(target) || !Array.isArray(source))
+            return target;
+        options?.onBeforeMerge?.(target, source);
+        // Merge options, with default values
+        const opts = Object.assign({ dataMode: 'clear', inheritMissing: true, targetClone: false }, options), 
+        // If cloning is enabled, create a deep copy of the target array
+        result = opts.targetClone ? [...target] : target;
+        // Handle different merge strategies based on dataMode
+        if (opts.dataMode === 'replace') {
+            // "replace" mode: recursively merge items in the arrays
+            for (let i = 0; i < source.length; i++) {
+                // If not allowed to add beyond length
+                // 如果不允许添加超过长度
+                if (!opts.inheritMissing && i >= result.length)
+                    break;
+                let resp = deepMergeHelper(result[i], source[i], opts);
+                //resp={result,flag,type}
+                //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
+                if (!resp.flag) {
+                    result[i] = source[i];
+                }
             }
         }
+        else if (opts.dataMode === 'concat') {
+            // Concatenate mode: append all items from the source array to the target array
+            result.push(...source);
+        }
+        else {
+            //Default replace mode: clear the target array and push all items from the source array
+            result.length = 0;
+            result.push(...source);
+        }
+        options?.onAfterMerge?.(result, target, source);
         return result;
-    }
-};
-
-const deepMergeMaps = (target, source, options = { itemMode: 'merge', propAppend: true, targetClone: false, useEnable: true }) => {
-    // Ensure both target and source are Maps
-    if (!(target instanceof Map) || !(source instanceof Map))
-        return target;
-    // Merge options, with default values
-    const opts = Object.assign({ itemMode: 'merge', propAppend: true, targetClone: false, useEnable: true }, options), 
-    // If cloning is enabled, create a deep copy of the target Map
-    result = opts.targetClone ? new Map(target) : target;
-    // Handle different merge strategies based on itemMode
-    if (opts.itemMode === 'replace') {
-        // Replace mode: clear the target Map and add all entries from the source Map
-        result.clear();
-        source.forEach((value, key) => result.set(key, value));
-        return result;
-    }
-    else if (opts.itemMode === 'concat') {
-        // Concatenate mode: add all entries from the source Map to the target Map
-        source.forEach((value, key) => result.set(key, value));
-        return result;
-    }
-    else {
+    }, deepMergeMaps = (target, source, options = {}) => {
+        // Ensure both target and source are Maps
+        if (!(target instanceof Map) || !(source instanceof Map))
+            return target;
+        options?.onBeforeMerge?.(target, source);
+        // Merge options, with default values
+        const opts = Object.assign({ inheritMissing: true, targetClone: false, useEnable: true }, options), 
+        // If cloning is enabled, create a deep copy of the target Map
+        result = opts.targetClone ? new Map([...target]) : target;
         // Default "merge" mode: recursively merge entries in the Maps
-        source.forEach((value, key) => {
+        for (const [key, value] of source.entries())
             // Check if the key already exists in the target Map
             if (result.has(key)) {
-                const targetValue = result.get(key), sourceValue = value, resp = deepMergeHelper(targetValue, sourceValue, opts);
+                const _target = result.get(key), _source = value, resp = deepMergeHelper(_target, _source, opts);
                 //resp={result,flag,type}
                 //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                 if (!resp.flag) {
                     // For simple values, overwrite the target value with the source value
-                    result.set(key, sourceValue);
+                    result.set(key, _source);
                 }
                 else {
                     // If both target and source are objects, merge them recursively
@@ -557,116 +690,42 @@ const deepMergeMaps = (target, source, options = { itemMode: 'merge', propAppend
             }
             else {
                 // If the key doesn't exist in the target, add the entry from the source Map
-                result.set(key, value);
+                options.inheritMissing && result.set(key, value);
             }
-        });
+        options?.onAfterMerge?.(result, target, source);
         return result;
-    }
-};
-
-const deepEqual = (a, b) => {
-    // If both are equal by reference
-    if (a === b)
-        return true;
-    // If both are arrays, check equality recursively
-    if (Array.isArray(a) && Array.isArray(b)) {
-        if (a.length !== b.length)
-            return false;
-        for (let i = 0; i < a.length; i++) {
-            if (!deepEqual(a[i], b[i]))
-                return false;
+    }, deepMergeSets = (target, source, options = {}) => {
+        // Ensure both target and source are Sets
+        if (!(target instanceof Set) || !(source instanceof Set))
+            return target;
+        options?.onBeforeMerge?.(target, source);
+        // Merge options, with default values
+        const opts = Object.assign({ dataMode: 'clear', inheritMissing: true, targetClone: false, useEnable: true }, options), 
+        // If cloning is enabled, create a deep copy of the target Set
+        result = opts.targetClone ? new Set(...target) : target;
+        // Handle different merge strategies based on dataMode
+        if (opts.dataMode === 'replace') {
+            // Replace mode: recursively merge items in the Sets
+            const _result = [...result], _source = [...source], resp = deepMergeHelper(_result, _source, opts);
+            result.clear();
+            for (let item of resp.result)
+                result.add(item);
         }
-        return true;
-    }
-    // If both are objects, check equality recursively
-    if (typeof a === 'object' && typeof b === 'object') {
-        const keysA = Object.keys(a), keysB = Object.keys(b);
-        if (keysA.length !== keysB.length)
-            return false;
-        for (let key of keysA) {
-            if (!keysB.includes(key) || !deepEqual(a[key], b[key]))
-                return false;
+        else if (opts.dataMode === 'concat') {
+            // Concatenate mode: add all items from the source Set to the target Set
+            for (let item of source)
+                result.add(item);
         }
-        return true;
-    }
-    // For other types, direct comparison
-    return a === b;
-};
-
-const deepMergeSets = (target, source, options = { itemMode: 'merge', propAppend: true, targetClone: false, useEnable: true }) => {
-    // Ensure both target and source are Sets
-    if (!(target instanceof Set) || !(source instanceof Set))
-        return target;
-    // Merge options, with default values
-    const opts = Object.assign({ itemMode: 'merge', propAppend: true, targetClone: false, useEnable: true }, options), 
-    // If cloning is enabled, create a deep copy of the target Set
-    result = opts.targetClone ? new Set(target) : target;
-    // Handle different merge strategies based on itemMode
-    if (opts.itemMode === 'replace') {
-        // Replace mode: clear the target Set and add all items from the source Set
-        result.clear();
-        for (let item of source)
-            result.add(item);
-        return result;
-    }
-    else if (opts.itemMode === 'concat') {
-        // Concatenate mode: add all items from the source Set to the target Set
-        for (let item of source)
-            result.add(item);
-        return result;
-    }
-    else {
-        // Default "merge" mode: recursively merge items in the Sets
-        for (let item of source) {
-            // Check the type of the target and source items
-            let _target = [...result].find(val => deepEqual(val, item)), resp = deepMergeHelper(_target, item, opts);
-            //resp={result,flag}
-            //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
-            !resp.flag && result.add(item);
+        else {
+            //Default "clear" mode: clear the target Set and add all items from the source Set
+            result.clear();
+            for (let item of source)
+                result.add(item);
         }
+        options?.onAfterMerge?.(result, target, source);
         return result;
-    }
-};
-
-// deepMergeHelper.ts
-
-
-const deepMergeHelper = (target, source, options) => {
-    let targetType = getDataType(target), sourceType = getDataType(source), flag = true, type, result;
-    if (targetType === 'Object' && sourceType === 'Object') {
-        result = deepMergeObjects(target, source, options);
-        type = 'Object';
-    }
-    else if (targetType === 'Array' && sourceType === 'Array') {
-        result = deepMergeArrays(target, source, options);
-        type = 'Array';
-    }
-    else if (targetType === 'Set' && sourceType === 'Set') {
-        result = deepMergeSets(target, source, options);
-        type = 'Set';
-    }
-    else if (targetType === 'Map' && sourceType === 'Map') {
-        result = deepMergeMaps(target, source, options);
-        type = 'Map';
-    }
-    else {
-        flag = false;
-        result = target; // Default case, replace primitive values
-    }
-    return {
-        result, flag, type
     };
-};
-
-const deepMerge = (target, source, opts = {}) => {
-    // Get the data types of the target and source
-    let options = Object.assign({
-        itemMode: 'merge', // Default merge mode
-        propAppend: true, // Default to appending properties from source to target
-        targetClone: false, // Do not clone target by default
-        useEnable: true // Enable special handling for objects with an `enable` property
-    }, opts);
-    return deepMergeHelper(target, source, options);
+    return deepMergeHelper(target, source, options).result;
 };
 
 const utils = {
@@ -684,12 +743,9 @@ const utils = {
     wrapSetMethods,
     wrapMapMethods,
     getUniqueId,
-    deepEqual: assert.deepEqual,
     deepMerge,
-    deepMergeArrays,
-    deepMergeMaps,
-    deepMergeObjects,
-    deepMergeSets,
+    shallowCopy,
+    copyObjectWithSymbol,
 };
 
 module.exports = utils;