@codady/utils 0.0.9 → 0.0.11

package/CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All changes to Utils including new features, updates, and removals are documented here.
 
+## [v0.0.11] - 2025-12-21
+
+### Distribution Files
+* **JS**: https://unpkg.com/@codady/utils@0.0.11/dist/js/utils.js
+* **Zip**:https://unpkg.com/@codady/utils@0.0.11/dist.zip
+
+### Changes
+
+#### Fixed
+* Null
+
+#### Added
+* 新增`deepEqual`、`deepMerge`、`deepMergeArrays`、`deepMergeObjects`、`deepMergeSets`、和`deepMegeMaps`函数。
+
+#### Removed
+* Null
+
+
+## [v0.0.10] - 2025-12-21
+
+### Distribution Files
+* **JS**: https://unpkg.com/@codady/utils@0.0.10/dist/js/utils.js
+* **Zip**:https://unpkg.com/@codady/utils@0.0.10/dist.zip
+
+### Changes
+
+#### Fixed
+* Modified the `getUniqueId` parameter structure, changing the `extra` parameter to `base10`, and adding a `base36` parameter.修改了`getUniqueId`的参数结构，extra参数改为base10，新增base36参数。
+* Modified the `deepClone` function, adding an `options` parameter. By default, it does not copy reference types like `Date`, `Function`, `RegExp`, etc.修改了`deepClone`函数，增加options参数，默认不复制Date、Function、RegExp等引用类型数据。
+* Changed `mutableMethods` to `arrayMutableMethods`.将`mutableMethods`改为`arrayMutableMethods`。
+
+#### Added
+* Added `setMutableMethods` and `mapMutableMethods` variables.新增`setMutableMethods`和`mapMutableMethods`变量。
+* Added `wrapSetMethods` and `wrapMapMethods` functions.新增`wrapSetMethods`和`wrapMapMethods`函数。
+
+#### Removed
+* Null
+
 
 ## [v0.0.7] - 2025-12-19
 

package/dist/utils.cjs.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-19 15:23:38
+ * @since Last modified: 2025-12-24 17:50:8
  * @name Utils for web front-end.
- * @version 0.0.9
+ * @version 0.0.11
  * @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,6 +16,8 @@
 
 '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())) {
@@ -41,37 +43,100 @@ const getDataType = (obj) => {
     //document.createElementNS('http://www.w3.org/1998/Math/MathML', 'math'); -> MathMLElement
 };
 
-const deepClone = (data) => {
-    const dataType = getDataType(data);
-    if (dataType === 'Object') {
-        const newObj = {};
-        const symbols = Object.getOwnPropertySymbols(data);
+//支持原始值的复制，包括Number、String、Boolean、Null
+//支持Date和Regex对象值复制（值转换）
+//支持{},[],Set和Map的遍历
+const deepClone = (data, options = {}) => {
+    const dataType = getDataType(data), 
+    // Default options
+    opts = Object.assign({
+        cloneSet: true,
+        cloneMap: true,
+        cloneObject: true,
+        cloneArray: true,
+        //可重新构建
+        cloneDate: true,
+        cloneRegex: true,
+        //节点默认不复制
+        //cloneElement: false,
+        //cloneFragment: false,
+    }, options);
+    // Check interceptor - if it returns a value (not null/undefined), use it directly
+    if (opts.interceptor && typeof opts.interceptor === 'function') {
+        let result = opts.interceptor(data, dataType);
+        if ((result ?? false)) {
+            // Call onAfterClone if set
+            opts.onAfterClone?.({
+                output: result,
+                input: data,
+                type: dataType,
+                cloned: result !== data,
+            });
+            return result;
+        }
+        // If interceptor returns null/undefined, continue with normal cloning process
+    }
+    // Callback before cloning
+    opts.onBeforeClone?.(data, dataType);
+    let newData, cloned = true;
+    if (dataType === 'Object' && opts.cloneObject) {
+        const newObj = {}, symbols = Object.getOwnPropertySymbols(data);
         // Clone regular properties
         for (const key in data) {
-            newObj[key] = deepClone(data[key]);
+            newObj[key] = deepClone(data[key], opts);
         }
         // Clone Symbol properties
         if (symbols.length > 0) {
             for (const symbol of symbols) {
-                newObj[symbol] = deepClone(data[symbol]);
+                newObj[symbol] = deepClone(data[symbol], opts);
             }
         }
-        return newObj;
+        newData = newObj;
     }
-    else if (dataType === 'Array') {
-        return data.map(item => deepClone(item));
+    else if (dataType === 'Array' && opts.cloneArray) {
+        newData = data.map(item => deepClone(item, opts));
+    }
+    else if (dataType === 'Map' && opts.cloneMap) {
+        const newMap = new Map();
+        for (const [key, value] of data) {
+            // Both Map keys and values need deep cloning
+            newMap.set(deepClone(key, opts), deepClone(value, opts));
+        }
+        newData = newMap;
     }
-    else if (dataType === 'Date') {
-        return new Date(data.getTime());
+    else if (dataType === 'Set' && opts.cloneSet) {
+        const newSet = new Set();
+        for (const value of data) {
+            // Set values need deep cloning
+            newSet.add(deepClone(value, opts));
+        }
+        newData = newSet;
     }
-    else if (dataType === 'RegExp') {
+    else if (dataType === 'Date' && opts.cloneDate) {
+        newData = new Date(data.getTime());
+    }
+    else if (dataType === 'RegExp' && opts.cloneRegex) {
         const regex = data;
-        return new RegExp(regex.source, regex.flags);
+        newData = new RegExp(regex.source, regex.flags);
+        // } else if ((dataType.includes('HTML') && opts.cloneElement) ||
+        //    (dataType === 'DocumentFragment' && opts.cloneFragment)
+        //) {
+        //Text,Comment,HTML*Element,DocumentFragment,Attr
+        //     newData = (data as any).cloneNode(true) as T;
     }
     else {
-        // Number, String, Boolean, Symbol,Text,Comment,Set,Map, HTML*Element, Function,Error,Promise,ArrayBuffer,Blob,File, return directly
-        return data;
+        // Number, String, Boolean, Symbol, Function,Error,Promise,ArrayBuffer,Blob,File, return directly
+        newData = data;
+        cloned = false;
     }
+    // Callback after cloning
+    opts.onAfterClone?.({
+        output: newData,
+        input: data,
+        type: dataType,
+        cloned,
+    });
+    return newData;
 };
 
 const deepCloneToJSON = (data) => {
@@ -102,7 +167,7 @@ const deepCloneToJSON = (data) => {
     }
 };
 
-const mutableMethods = [
+const arrayMutableMethods = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
@@ -114,7 +179,7 @@ const wrapArrayMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate =
     }
     //使用默认
     if (!allowList || allowList?.length) {
-        allowList = mutableMethods;
+        allowList = arrayMutableMethods;
     }
     const methods = {};
     for (let method of allowList) {
@@ -130,10 +195,10 @@ const wrapArrayMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate =
                     context.addedItems = [...args];
                     break;
                 case 'pop':
-                    context.poppedValue = target[len - 1];
+                    context.poppedItem = target[len - 1];
                     break;
                 case 'shift':
-                    context.shiftedValue = target[0];
+                    context.shiftedItem = target[0];
                     break;
                 case 'splice':
                     const [s, d] = args, 
@@ -203,20 +268,405 @@ const requireTypes = (data, require, cb) => {
     return dataType;
 };
 
-const getUniqueId = (prefix, extra = true) => {
+const getUniqueId = (options = {}) => {
+    const prefix = options.prefix, suffix = options.suffix, base10 = options.base10, base36 = options.base36;
     // Current timestamp in milliseconds (since Unix epoch)
     // This provides the primary uniqueness guarantee
     const timestamp = Date.now(), 
     // Generate a base-36 random string (0-9, a-z)
     // Math.random() returns a number in [0, 1), converting to base-36 gives a compact representation
     // substring(2, 11) extracts 9 characters starting from index 2
-    random = Math.random().toString(36).substring(2, 11), 
+    //0.259854635->0.9crs03e8v2
+    base36Random = base36 ? '-' + Math.random().toString(36).substring(2, 11) : '', 
     // Additional 4-digit random number for extra randomness
     // This helps avoid collisions in high-frequency generation scenarios
-    extraRandom = extra ? '_' + Math.floor(Math.random() * 10000).toString().padStart(4, '0') : '', prefixString = prefix ? prefix + '_' : '';
+    base10Random = base10 ? '-' + Math.floor(Math.random() * 10000).toString().padStart(4, '0') : '', prefixString = prefix ? prefix + '-' : '', suffixString = suffix ? '-' + suffix : '';
     // Construct the final ID string
     // Format: [prefix_]timestamp_randomBase36_extraRandom
-    return `${prefixString}${timestamp}_${random}${extraRandom}`;
+    return `${prefixString}${timestamp}${base36Random}${base10Random}${suffixString}`;
+};
+
+const setMutableMethods = ['add', 'delete', 'clear'];
+
+const mapMutableMethods = ['set', 'delete', 'clear'];
+
+const wrapSetMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList = setMutableMethods, props = {}, }) => {
+    // Validation: Ensure target is a Set
+    if (!(target instanceof Set)) {
+        throw new TypeError("The 'target' parameter must be a Set.");
+    }
+    // Create method wrappers
+    const methods = {};
+    // Helper to create wrapped method
+    const createWrappedMethod = (method) => {
+        return function (...args) {
+            const context = {};
+            // Capture pre-mutation context based on method
+            switch (method) {
+                case 'add': {
+                    const [value] = args;
+                    context.addedItem = value;
+                    //context.existed=true，说明值重复
+                    context.existed = target.has(value);
+                    break;
+                }
+                case 'delete': {
+                    const [value] = args;
+                    context.existed = target.has(value);
+                    context.deletedItem = context.existed ? value : undefined;
+                    break;
+                }
+                case 'clear': {
+                    context.clearedItems = Array.from(target);
+                    //用来做验证
+                    context.previousSize = target.size;
+                    break;
+                }
+            }
+            // Execute before mutation callback
+            onBeforeMutate(context);
+            // Execute the native Set method
+            const result = target[method].apply(target, args);
+            // Construct patch object
+            const patch = {
+                method,
+                result,
+                args,
+                context,
+                target,
+                ...props
+            };
+            // Execute after mutation callback
+            onAfterMutate(patch);
+            return result;
+        };
+    };
+    // Wrap allowed methods
+    for (const method of allowList) {
+        if (setMutableMethods.includes(method)) {
+            methods[method] = createWrappedMethod(method);
+        }
+    }
+    // Add target reference
+    Object.defineProperty(methods, 'target', {
+        get: () => target,
+        enumerable: false,
+        configurable: false
+    });
+    return methods;
+};
+
+const wrapMapMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList = mapMutableMethods, props = {}, }) => {
+    // Validation: Ensure target is a Map
+    if (!(target instanceof Map)) {
+        throw new TypeError("The 'target' parameter must be a Map.");
+    }
+    // Create method wrappers
+    const methods = {};
+    // Helper to create wrapped method
+    const createWrappedMethod = (method) => {
+        return function (...args) {
+            const context = {};
+            // Capture pre-mutation context based on method
+            switch (method) {
+                case 'set': {
+                    const [key, newValue] = args;
+                    context.key = key;
+                    context.newValue = newValue;
+                    context.existed = target.has(key);
+                    context.oldValue = context.existed ? target.get(key) : undefined;
+                    break;
+                }
+                case 'delete': {
+                    const [key] = args;
+                    context.key = key;
+                    context.existed = target.has(key);
+                    context.value = context.existed ? target.get(key) : undefined;
+                    break;
+                }
+                case 'clear': {
+                    context.clearedItems = Array.from(target.entries());
+                    //用来做验证
+                    context.previousSize = target.size;
+                    break;
+                }
+            }
+            // Execute before mutation callback
+            onBeforeMutate(context);
+            // Execute the native Map method
+            const result = target[method].apply(target, args);
+            // Construct patch object
+            const patch = {
+                method,
+                result,
+                args,
+                context,
+                target,
+                ...props
+            };
+            // Execute after mutation callback
+            onAfterMutate(patch);
+            return result;
+        };
+    };
+    // Wrap allowed methods
+    for (const method of allowList) {
+        if (mapMutableMethods.includes(method)) {
+            methods[method] = createWrappedMethod(method);
+        }
+    }
+    // Add target reference
+    Object.defineProperty(methods, 'target', {
+        get: () => target,
+        enumerable: false,
+        configurable: false
+    });
+    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]);
+                    }
+                    else {
+                        //完全替换
+                        result[k] = source[k];
+                    }
+                }
+                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.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];
+            }
+        }
+    }
+    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);
+        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];
+            }
+        }
+        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 {
+        // Default "merge" mode: recursively merge entries in the Maps
+        source.forEach((value, key) => {
+            // 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);
+                //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);
+                }
+                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
+                result.set(key, value);
+            }
+        });
+        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;
+        }
+        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;
+        }
+        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);
+        }
+        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);
 };
 
 const utils = {
@@ -228,8 +678,18 @@ const utils = {
     deepClone,
     deepCloneToJSON,
     wrapArrayMethods,
-    mutableMethods,
-    getUniqueId
+    arrayMutableMethods,
+    setMutableMethods,
+    mapMutableMethods,
+    wrapSetMethods,
+    wrapMapMethods,
+    getUniqueId,
+    deepEqual: assert.deepEqual,
+    deepMerge,
+    deepMergeArrays,
+    deepMergeMaps,
+    deepMergeObjects,
+    deepMergeSets,
 };
 
 module.exports = utils;