@codady/utils 0.0.11 → 0.0.12

package/modules.js

@@ -1,5 +1,5 @@
 /**
- * Last modified: 2025/12/24 17:05:40
+ * Last modified: 2025/12/25 12:08:43
  */
 'use strict';
 import deepClone from './src/deepClone';
@@ -13,12 +13,8 @@ import setMutableMethods from './src/setMutableMethods';
 import mapMutableMethods from './src/mapMutableMethods';
 import wrapSetMethods from './src/wrapSetMethods';
 import wrapMapMethods from './src/wrapMapMethods';
-import { deepEqual } from 'assert';
 import deepMerge from './src/deepMerge';
-import deepMergeArrays from './src/deepMergeArrays';
-import deepMergeMaps from './src/deepMergeMaps';
-import deepMergeObjects from './src/deepMergeObjects';
-import deepMergeSets from './src/deepMergeSets';
+import shallowCopy from './src/shallowCopy';
 const utils = {
     //executeStr,
     getDataType,
@@ -34,11 +30,7 @@ const utils = {
     wrapSetMethods,
     wrapMapMethods,
     getUniqueId,
-    deepEqual,
     deepMerge,
-    deepMergeArrays,
-    deepMergeMaps,
-    deepMergeObjects,
-    deepMergeSets,
+    shallowCopy,
 };
 export default utils;

package/modules.ts

@@ -1,5 +1,5 @@
 /**
- * Last modified: 2025/12/24 17:05:40
+ * Last modified: 2025/12/25 12:08:43
  */
 'use strict'
 import deepClone from './src/deepClone';
@@ -16,12 +16,13 @@ import setMutableMethods from './src/setMutableMethods';
 import mapMutableMethods from './src/mapMutableMethods';
 import wrapSetMethods from './src/wrapSetMethods';
 import wrapMapMethods from './src/wrapMapMethods';
-import { deepEqual } from 'assert';
 import deepMerge from './src/deepMerge';
 import deepMergeArrays from './src/deepMergeArrays';
 import deepMergeMaps from './src/deepMergeMaps';
 import deepMergeObjects from './src/deepMergeObjects';
 import deepMergeSets from './src/deepMergeSets';
+import deepEqual from './src/deepEqual';
+import shallowCopy from './src/shallowCopy';
 
 
 
@@ -40,12 +41,9 @@ const utils = {
   wrapSetMethods,
   wrapMapMethods,
   getUniqueId,
-  deepEqual,
   deepMerge,
-  deepMergeArrays,
-  deepMergeMaps,
-  deepMergeObjects,
-  deepMergeSets,
+  shallowCopy,
+ 
 };
 
 export default utils;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codady/utils",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "author": "AXUI Development Team",
   "license": "MIT",
   "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.",

package/src/deepEqual.js

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/24 17:11:15
+ * @since Last modified: 2025/12/24 22:03:47
  * @function deepEqual
  * @description Compares two values for deep equality. This function checks whether the values are deeply equal, meaning that if the values are objects or arrays, their properties or items are recursively compared. If they are primitive types, a direct comparison is performed.
  * It supports comparison for arrays, objects, and primitive types (like numbers, strings, booleans, etc.). The comparison is done by value, not by reference.

package/src/deepEqual.ts

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/24 17:11:15
+ * @since Last modified: 2025/12/24 22:03:47
  * @function deepEqual
  * @description Compares two values for deep equality. This function checks whether the values are deeply equal, meaning that if the values are objects or arrays, their properties or items are recursively compared. If they are primitive types, a direct comparison is performed.
  * It supports comparison for arrays, objects, and primitive types (like numbers, strings, booleans, etc.). The comparison is done by value, not by reference.

package/src/deepMerge.js

@@ -1,34 +1,274 @@
 /**
- * @since Last modified: 2025/12/24 17:21:45
+ * @since Last modified: 2025/12/25 12:10:30
  * @function deepMerge
  * @description Deeply merges two data structures (Object, Array, Map, or Set) based on their types.
  * This function recursively merges the properties or items of the target and source, depending on their types.
  * If the types of target and source do not match, the target will be returned unchanged.
+ * 深度合并两个数据结构（对象、数组、Map或Set），根据类型递归合并属性和项。
+ * 如果目标和源的类型不匹配，则目标保持不变。
  * @param target The target data structure to merge into (can be Object, Array, Map, or Set).
+ * 要合并到的目标数据结构（可以是对象、数组、Map或Set）。
  * @param source The source data structure to merge from (can be Object, Array, Map, or Set).
+ * 要合并的源数据结构（可以是对象、数组、Map或Set）。
  * @param opts Configuration options for merging. The default options include:
- *  - `itemMode`: Specifies the merging mode (`'merge'`, `'replace'`, or `'concat'`).
- *  - `propAppend`: Whether to append properties from the source if they do not exist in the target.
+ * 合并的配置选项，默认值包括：
+ *  - `dataMode`: Specifies the merging mode (`'clear'`, `'replace'`, or `'concat'`).
+ *     指定合并模式（'clear'、'replace' 或 'concat'）。
+ *  - `inheritMissing`: Whether to append properties from the source if they do not exist in the target.
+ *     如果源中的属性在目标中不存在，是否追加这些属性。
  *  - `targetClone`: Whether to clone the target before merging (if true, the target is not modified).
+ *     是否在合并前克隆目标对象（如果为true，则目标对象不会被修改）。
  *  - `useEnable`: Some special handling for specific objects that have `enable` properties.
+ *     对具有enable属性的特定对象进行特殊处理。
  *  - `useSymbol`: Whether to merge symbol properties.
+ *     是否合并symbol属性。
  * @returns The deeply merged target data structure.
+ * 深度合并后的目标数据结构。
  * @example
  * let x = { a: 'man', b: 0, c: [] };
  * let y = { a: 'woman', b: 2, d: 'new' };
- * const merged = deepMerge(x, y, { itemMode: 'merge', propAppend: true });
+ * const merged = deepMerge(x, y, { dataMode: 'clear', inheritMissing: true });
  * // Returns { a: 'woman', b: 2, c: [], d: 'new' }
+ * // 返回 { a: 'woman', b: 2, c: [], d: 'new' }
  */
 'use strict';
-import deepMergeHelper from './deepMergeHelper';
+import getDataType from './getDataType';
+import shallowCopy from './shallowCopy';
 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);
+    // 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 {
+                        //完全替换
+                        result[k] = source[k];
+                    }
+                }
+                else {
+                    //类型相同
+                    if (resp.type) {
+                        if (resp.type === 'Object') {
+                            //如果遇上对象则深度复制
+                            result[k] = resp.result;
+                        }
+                    }
+                    else {
+                        //其他类型则直接覆盖
+                        result[k] = source[k];
+                    }
+                }
+            }
+            else if (source.hasOwnProperty(k) && !result.hasOwnProperty(k) && options.inheritMissing) {
+                //如果source有属性，result没有该属性，但是options允许追加属性则直接赋值
+                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];
+            }
+        }
+        options?.onAfterMerge?.(result, target, source);
+        return result;
+    }, 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;
+    }, 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
+        for (const [key, value] of source.entries())
+            // Check if the key already exists in the target Map
+            if (result.has(key)) {
+                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, _source);
+                }
+                else {
+                    // If both target and source are objects, merge them recursively
+                    resp.type === 'Object' && result.set(key, resp.result);
+                }
+            }
+            else {
+                // If the key doesn't exist in the target, add the entry from the source Map
+                options.inheritMissing && result.set(key, value);
+            }
+        options?.onAfterMerge?.(result, target, source);
+        return result;
+    }, 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);
+        }
+        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);
+        }
+        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;
+    };
+    return deepMergeHelper(target, source, options).result;
 };
 export default deepMerge;