@codady/utils 0.0.15 → 0.0.17

package/dist/utils.umd.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-26 11:26:20
+ * @since Last modified: 2025-12-26 16:3:51
  * @name Utils for web front-end.
- * @version 0.0.15
+ * @version 0.0.17
  * @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}
@@ -65,16 +65,10 @@
         }, 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);
+            let result = opts.interceptor({ input: data, type: dataType, parent: opts.parent });
             if ((result ?? false)) {
                 // Call onAfterClone if set
-                opts.onAfterClone?.({
-                    output: result,
-                    input: data,
-                    type: dataType,
-                    cloned: result !== data,
-                    parent: opts.parent
-                });
+                
                 return result;
             }
             // If interceptor returns null/undefined, continue with normal cloning process
@@ -536,31 +530,49 @@
         }, opts), 
         // Main helper function for recursive merging
         // 递归合并的主辅助函数
-        deepMergeHelper = (target, source, options) => {
-            let targetType = getDataType(target), sourceType = getDataType(source), flag = true, type, result;
+        smartMerger = (target, source, options) => {
+            let targetType = getDataType(target), sourceType = getDataType(source), flag = true, mergeType, result;
+            // Check interceptor - if it returns a value (not null/undefined), use it directly
+            if (options.interceptor && typeof options.interceptor === 'function') {
+                let interceptorResult = options.interceptor({ target, source, targetType, sourceType, parent: options.parent });
+                if ((interceptorResult ?? false)) {
+                    //如果不是返回{target,source}，那么直接返回interceptorResult
+                    if (interceptorResult?.target === null || interceptorResult?.source === null) {
+                        return interceptorResult;
+                    }
+                    else {
+                        //interceptorResult={target,source}
+                        target = interceptorResult.target;
+                        source = interceptorResult.source;
+                    }
+                }
+                // If interceptor returns null/undefined, continue with normal cloning process
+            }
+            options?.onBeforeMerge?.({ target, source, targetType, sourceType, parent: options.parent });
             // Determine the type and perform appropriate merging
             // 确定类型并执行相应的合并
             if (targetType === 'Object' && sourceType === 'Object') {
                 result = deepMergeObjects(target, source, options);
-                type = 'Object';
+                mergeType = 'Object';
             }
             else if (targetType === 'Array' && sourceType === 'Array') {
                 result = deepMergeArrays(target, source, options);
-                type = 'Array';
+                mergeType = 'Array';
             }
             else if (targetType === 'Set' && sourceType === 'Set') {
                 result = deepMergeSets(target, source, options);
-                type = 'Set';
+                mergeType = 'Set';
             }
             else if (targetType === 'Map' && sourceType === 'Map') {
                 result = deepMergeMaps(target, source, options);
-                type = 'Map';
+                mergeType = 'Map';
             }
             else {
                 flag = false;
                 result = target;
             }
-            return { result, flag, type };
+            options?.onAfterMerge?.({ result, target, source, targetType, sourceType, mergeType, parent: opts.parent });
+            return { result, flag, mergeType };
         }, 
         // Special handling for objects with enable property
         // 对具有enable属性的对象进行特殊处理
@@ -588,7 +600,6 @@
             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
@@ -596,7 +607,7 @@
             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);
+                    let resp = smartMerger(result[k], source[k], { ...opts, parent: result });
                     //resp={result,flag,type}
                     //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                     if (!resp.flag) {
@@ -611,8 +622,8 @@
                     }
                     else {
                         //类型相同
-                        if (resp.type) {
-                            if (resp.type === 'Object') {
+                        if (resp.mergeType) {
+                            if (resp.mergeType === 'Object') {
                                 //如果遇上对象则深度复制
                                 result[k] = resp.result;
                             }
@@ -636,13 +647,11 @@
                         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
@@ -655,7 +664,7 @@
                     // 如果不允许添加超过长度
                     if (!opts.inheritMissing && i >= result.length)
                         break;
-                    let resp = deepMergeHelper(result[i], source[i], opts);
+                    let resp = smartMerger(result[i], source[i], { ...opts, parent: result });
                     //resp={result,flag,type}
                     //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                     if (!resp.flag) {
@@ -672,13 +681,11 @@
                 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
@@ -687,7 +694,7 @@
             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);
+                    const _target = result.get(key), _source = value, resp = smartMerger(_target, _source, opts);
                     //resp={result,flag,type}
                     //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                     if (!resp.flag) {
@@ -696,20 +703,18 @@
                     }
                     else {
                         // If both target and source are objects, merge them recursively
-                        resp.type === 'Object' && result.set(key, resp.result);
+                        resp.mergeType === '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
@@ -717,7 +722,7 @@
             // 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);
+                const _result = [...result], _source = [...source], resp = smartMerger(_result, _source, opts);
                 result.clear();
                 for (let item of resp.result)
                     result.add(item);
@@ -733,10 +738,9 @@
                 for (let item of source)
                     result.add(item);
             }
-            options?.onAfterMerge?.(result, target, source);
             return result;
         };
-        return deepMergeHelper(target, source, options).result;
+        return smartMerger(target, source, options).result;
     };
 
     const utils = {

package/dist/utils.umd.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-26 11:26:20
+ * @since Last modified: 2025-12-26 16:3:51
  * @name Utils for web front-end.
- * @version 0.0.15
+ * @version 0.0.17
  * @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}
@@ -12,4 +12,4 @@
  * @copyright This software supports the MIT License, allowing free learning and commercial use, but please retain the terms 'ax,' 'axui,' 'AX,' and 'AXUI' within the software.
  * @license MIT license
  */
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).utils=t()}(this,function(){"use strict";const getDataType=e=>{let t,r=Object.prototype.toString.call(e).slice(8,-1);return t="Function"===r&&/^\s*class\s+/.test(e.toString())?"Class":"Object"===r&&Object.getPrototypeOf(e)!==Object.prototype?"Instance":r,t},deepClone=(e,t={})=>{const r=getDataType(e),n=Object.assign({cloneSet:!0,cloneMap:!0,cloneObject:!0,cloneArray:!0,cloneDate:!0,cloneRegex:!0},t);if(n.interceptor&&"function"==typeof n.interceptor){let t=n.interceptor(e,r);if(t)return n.onAfterClone?.({output:t,input:e,type:r,cloned:t!==e,parent:n.parent}),t}n.onBeforeClone?.({input:e,type:r,parent:n.parent});let o,a=!0;if("Object"===r&&n.cloneObject){const t={},r=Object.getOwnPropertySymbols(e);for(const r in e)t[r]=deepClone(e[r],n);if(r.length>0)for(const o of r)t[o]=deepClone(e[o],{...n,parent:e});o=t}else if("Array"===r&&n.cloneArray)o=e.map(t=>deepClone(t,{...n,parent:e}));else if("Map"===r&&n.cloneMap){const t=new Map;for(const[r,o]of e)t.set(deepClone(r,n),deepClone(o,{...n,parent:e}));o=t}else if("Set"===r&&n.cloneSet){const t=new Set;for(const r of e)t.add(deepClone(r,{...n,parent:e}));o=t}else if("Date"===r&&n.cloneDate)o=new Date(e.getTime());else if("RegExp"===r&&n.cloneRegex){const t=e;o=new RegExp(t.source,t.flags)}else o=e,a=!1;return n.onAfterClone?.({output:o,input:e,type:r,cloned:a,parent:n.parent}),o},deepCloneToJSON=e=>{const t=getDataType(e);if("Object"===t){const t={};for(const r in e)t[r]=deepCloneToJSON(e[r]);for(const e in t)void 0===t[e]&&Reflect.deleteProperty(t,e);return t}if("Array"===t){return e.map((e,t)=>deepCloneToJSON(e)).filter(e=>void 0!==e)}return["Number","String","Boolean","Null"].includes(t)?e:void 0},e=["push","pop","shift","unshift","splice","sort","reverse","copyWithin","fill"],t=["add","delete","clear"],r=["set","delete","clear"],copyObjectWithSymbol=e=>{if(!e||"object"!=typeof e)return e;const t=e,r=Object.getOwnPropertySymbols(t).reduce((e,r)=>(e[r]=t[r],e),{});return{...t,...r}},shallowCopy=(e,t={})=>{const r=getDataType(e);return"Set"===r?new Set([...e]):"Map"===r?new Map([...e]):Array.isArray(e)?[...e]:"object"===r?copyObjectWithSymbol(e):"Date"===r?new Date(e.getTime()):"RegExp"===r?new RegExp(e.source,e.flags):"Buffer"===r?Buffer.from(e):"ArrayBuffer"===r||ArrayBuffer.isView(e)?e.slice(0):"WeakSet"===r?new WeakSet([...e]):"WeakMap"===r?new WeakMap([...e]):"Error"===r?new Error(e.message):e};return{getDataType:getDataType,requireTypes:(e,t,r)=>{let n=Array.isArray(t)?t:[t],o=getDataType(e),a=o.toLowerCase(),s=n.map(e=>e.toLowerCase()),i=a.includes("html")?"element":a;if(r)try{if(!s.includes(i))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${i}`)}catch(e){r(e,o)}else if(!s.includes(i))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${i}`);return o},deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,wrapArrayMethods:({target:t,onBeforeMutate:r=()=>{},onAfterMutate:n=()=>{},allowList:o,props:a={}})=>{if(!Array.isArray(t))throw new TypeError("The 'target' parameter must be an array.");o&&!o?.length||(o=e);const s={};for(let e of o)s[e]=function(...o){const s={},i=t.length;switch(e){case"push":case"unshift":s.addedItems=[...o];break;case"pop":s.poppedItem=t[i-1];break;case"shift":s.shiftedItem=t[0];break;case"splice":const[e,r]=o,n=e<0?Math.max(i+e,0):Math.min(e,i),a=void 0===r?i-n:r;s.deletedItems=t.slice(n,n+a);break;case"sort":case"reverse":s.oldSnapshot=[...t];break;case"fill":case"copyWithin":const l=o[1]||0,c=void 0===o[2]?i:o[2];s.oldItems=t.slice(l,c),s.start=l,s.end=c}r?.(s);const l=Array.prototype[e].apply(t,o),c={value:l,key:e,args:o,context:s,target:t,...a};return n?.(c),l};return s},arrayMutableMethods:e,setMutableMethods:t,mapMutableMethods:r,wrapSetMethods:({target:e,onBeforeMutate:r=()=>{},onAfterMutate:n=()=>{},allowList:o=t,props:a={}})=>{if(!(e instanceof Set))throw new TypeError("The 'target' parameter must be a Set.");const s={},createWrappedMethod=t=>function(...o){const s={};switch(t){case"add":{const[t]=o;s.addedItem=t,s.existed=e.has(t);break}case"delete":{const[t]=o;s.existed=e.has(t),s.deletedItem=s.existed?t:void 0;break}case"clear":s.clearedItems=Array.from(e),s.previousSize=e.size}r(s);const i=e[t].apply(e,o),l={method:t,result:i,args:o,context:s,target:e,...a};return n(l),i};for(const e of o)t.includes(e)&&(s[e]=createWrappedMethod(e));return Object.defineProperty(s,"target",{get:()=>e,enumerable:!1,configurable:!1}),s},wrapMapMethods:({target:e,onBeforeMutate:t=()=>{},onAfterMutate:n=()=>{},allowList:o=r,props:a={}})=>{if(!(e instanceof Map))throw new TypeError("The 'target' parameter must be a Map.");const s={},createWrappedMethod=r=>function(...o){const s={};switch(r){case"set":{const[t,r]=o;s.key=t,s.newValue=r,s.existed=e.has(t),s.oldValue=s.existed?e.get(t):void 0;break}case"delete":{const[t]=o;s.key=t,s.existed=e.has(t),s.value=s.existed?e.get(t):void 0;break}case"clear":s.clearedItems=Array.from(e.entries()),s.previousSize=e.size}t(s);const i=e[r].apply(e,o),l={method:r,result:i,args:o,context:s,target:e,...a};return n(l),i};for(const e of o)r.includes(e)&&(s[e]=createWrappedMethod(e));return Object.defineProperty(s,"target",{get:()=>e,enumerable:!1,configurable:!1}),s},getUniqueId:(e={})=>{const t=e.prefix,r=e.suffix,n=e.base10,o=e.base36;return`${t?t+"-":""}${Date.now()}${o?"-"+Math.random().toString(36).substring(2,11):""}${n?"-"+Math.floor(1e4*Math.random()).toString().padStart(4,"0"):""}${r?"-"+r:""}`},deepMerge:(e,t,r={})=>{const n=Object.assign({dataMode:"clear",inheritMissing:!0,targetClone:!1,useEnable:!0,useSymbol:!0,deepClone:{},onBeforeMerge:void 0,onAfterMerge:void 0},r),deepMergeHelper=(e,t,r)=>{let n,o,a=getDataType(e),s=getDataType(t),i=!0;return"Object"===a&&"Object"===s?(o=deepMergeObjects(e,t,r),n="Object"):"Array"===a&&"Array"===s?(o=deepMergeArrays(e,t,r),n="Array"):"Set"===a&&"Set"===s?(o=deepMergeSets(e,t,r),n="Set"):"Map"===a&&"Map"===s?(o=deepMergeMaps(e,t,r),n="Map"):(i=!1,o=e),{result:o,flag:i,type:n}},mergeEnableObject=(e,t)=>e?.hasOwnProperty("enable")&&"boolean"==typeof t?(e.enable=t,e):t?.hasOwnProperty("enable")&&"boolean"==typeof e?Object.assign({enable:e},t):t,deepMergeObjects=(e,t,r={})=>{let n=getDataType(e),o=getDataType(t);if("Object"!==n||"Object"!==o)return e;r?.onBeforeMerge?.(e,t);const a=Object.assign({inheritMissing:!0,targetClone:!1,useEnable:!0},r);let s={};s=a.targetClone?shallowCopy(e):e;for(let e in t)if(t.hasOwnProperty(e)&&s.hasOwnProperty(e)){let n=deepMergeHelper(s[e],t[e],r);n.flag?n.type?"Object"===n.type&&(s[e]=n.result):s[e]=t[e]:a.useEnable?s[e]=mergeEnableObject(s[e],t[e]):s[e]=t[e]}else t.hasOwnProperty(e)&&!s.hasOwnProperty(e)&&a.inheritMissing&&(s[e]=t[e]);if(a.useSymbol){let e=Object.getOwnPropertySymbols(t);if(e.length)for(let r of e)s[r]=t[r]}return a?.onAfterMerge?.(s,e,t),s},deepMergeArrays=(e,t,r={})=>{if(!Array.isArray(e)||!Array.isArray(t))return e;r?.onBeforeMerge?.(e,t);const n=Object.assign({dataMode:"clear",inheritMissing:!0,targetClone:!1},r),o=n.targetClone?[...e]:e;if("replace"===n.dataMode)for(let e=0;e<t.length&&(n.inheritMissing||!(e>=o.length));e++){deepMergeHelper(o[e],t[e],n).flag||(o[e]=t[e])}else"concat"===n.dataMode||(o.length=0),o.push(...t);return r?.onAfterMerge?.(o,e,t),o},deepMergeMaps=(e,t,r={})=>{if(!(e instanceof Map&&t instanceof Map))return e;r?.onBeforeMerge?.(e,t);const n=Object.assign({inheritMissing:!0,targetClone:!1,useEnable:!0},r),o=n.targetClone?new Map([...e]):e;for(const[e,a]of t.entries())if(o.has(e)){const t=o.get(e),r=a,s=deepMergeHelper(t,r,n);s.flag?"Object"===s.type&&o.set(e,s.result):o.set(e,r)}else r.inheritMissing&&o.set(e,a);return r?.onAfterMerge?.(o,e,t),o},deepMergeSets=(e,t,r={})=>{if(!(e instanceof Set&&t instanceof Set))return e;r?.onBeforeMerge?.(e,t);const n=Object.assign({dataMode:"clear",inheritMissing:!0,targetClone:!1,useEnable:!0},r),o=n.targetClone?new Set(...e):e;if("replace"===n.dataMode){const e=[...o],r=[...t],a=deepMergeHelper(e,r,n);o.clear();for(let e of a.result)o.add(e)}else if("concat"===n.dataMode)for(let e of t)o.add(e);else{o.clear();for(let e of t)o.add(e)}return r?.onAfterMerge?.(o,e,t),o};return deepMergeHelper(e,t,n).result},shallowCopy:shallowCopy,copyObjectWithSymbol:copyObjectWithSymbol}});
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):(e="undefined"!=typeof globalThis?globalThis:e||self).utils=t()}(this,function(){"use strict";const getDataType=e=>{let t,r=Object.prototype.toString.call(e).slice(8,-1);return t="Function"===r&&/^\s*class\s+/.test(e.toString())?"Class":"Object"===r&&Object.getPrototypeOf(e)!==Object.prototype?"Instance":r,t},deepClone=(e,t={})=>{const r=getDataType(e),n=Object.assign({cloneSet:!0,cloneMap:!0,cloneObject:!0,cloneArray:!0,cloneDate:!0,cloneRegex:!0},t);if(n.interceptor&&"function"==typeof n.interceptor){let t=n.interceptor({input:e,type:r,parent:n.parent});if(t)return t}n.onBeforeClone?.({input:e,type:r,parent:n.parent});let o,a=!0;if("Object"===r&&n.cloneObject){const t={},r=Object.getOwnPropertySymbols(e);for(const r in e)t[r]=deepClone(e[r],n);if(r.length>0)for(const o of r)t[o]=deepClone(e[o],{...n,parent:e});o=t}else if("Array"===r&&n.cloneArray)o=e.map(t=>deepClone(t,{...n,parent:e}));else if("Map"===r&&n.cloneMap){const t=new Map;for(const[r,o]of e)t.set(deepClone(r,n),deepClone(o,{...n,parent:e}));o=t}else if("Set"===r&&n.cloneSet){const t=new Set;for(const r of e)t.add(deepClone(r,{...n,parent:e}));o=t}else if("Date"===r&&n.cloneDate)o=new Date(e.getTime());else if("RegExp"===r&&n.cloneRegex){const t=e;o=new RegExp(t.source,t.flags)}else o=e,a=!1;return n.onAfterClone?.({output:o,input:e,type:r,cloned:a,parent:n.parent}),o},deepCloneToJSON=e=>{const t=getDataType(e);if("Object"===t){const t={};for(const r in e)t[r]=deepCloneToJSON(e[r]);for(const e in t)void 0===t[e]&&Reflect.deleteProperty(t,e);return t}if("Array"===t){return e.map((e,t)=>deepCloneToJSON(e)).filter(e=>void 0!==e)}return["Number","String","Boolean","Null"].includes(t)?e:void 0},e=["push","pop","shift","unshift","splice","sort","reverse","copyWithin","fill"],t=["add","delete","clear"],r=["set","delete","clear"],copyObjectWithSymbol=e=>{if(!e||"object"!=typeof e)return e;const t=e,r=Object.getOwnPropertySymbols(t).reduce((e,r)=>(e[r]=t[r],e),{});return{...t,...r}},shallowCopy=(e,t={})=>{const r=getDataType(e);return"Set"===r?new Set([...e]):"Map"===r?new Map([...e]):Array.isArray(e)?[...e]:"object"===r?copyObjectWithSymbol(e):"Date"===r?new Date(e.getTime()):"RegExp"===r?new RegExp(e.source,e.flags):"Buffer"===r?Buffer.from(e):"ArrayBuffer"===r||ArrayBuffer.isView(e)?e.slice(0):"WeakSet"===r?new WeakSet([...e]):"WeakMap"===r?new WeakMap([...e]):"Error"===r?new Error(e.message):e};return{getDataType:getDataType,requireTypes:(e,t,r)=>{let n=Array.isArray(t)?t:[t],o=getDataType(e),a=o.toLowerCase(),s=n.map(e=>e.toLowerCase()),i=a.includes("html")?"element":a;if(r)try{if(!s.includes(i))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${i}`)}catch(e){r(e,o)}else if(!s.includes(i))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${i}`);return o},deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,wrapArrayMethods:({target:t,onBeforeMutate:r=()=>{},onAfterMutate:n=()=>{},allowList:o,props:a={}})=>{if(!Array.isArray(t))throw new TypeError("The 'target' parameter must be an array.");o&&!o?.length||(o=e);const s={};for(let e of o)s[e]=function(...o){const s={},i=t.length;switch(e){case"push":case"unshift":s.addedItems=[...o];break;case"pop":s.poppedItem=t[i-1];break;case"shift":s.shiftedItem=t[0];break;case"splice":const[e,r]=o,n=e<0?Math.max(i+e,0):Math.min(e,i),a=void 0===r?i-n:r;s.deletedItems=t.slice(n,n+a);break;case"sort":case"reverse":s.oldSnapshot=[...t];break;case"fill":case"copyWithin":const c=o[1]||0,l=void 0===o[2]?i:o[2];s.oldItems=t.slice(c,l),s.start=c,s.end=l}r?.(s);const c=Array.prototype[e].apply(t,o),l={value:c,key:e,args:o,context:s,target:t,...a};return n?.(l),c};return s},arrayMutableMethods:e,setMutableMethods:t,mapMutableMethods:r,wrapSetMethods:({target:e,onBeforeMutate:r=()=>{},onAfterMutate:n=()=>{},allowList:o=t,props:a={}})=>{if(!(e instanceof Set))throw new TypeError("The 'target' parameter must be a Set.");const s={},createWrappedMethod=t=>function(...o){const s={};switch(t){case"add":{const[t]=o;s.addedItem=t,s.existed=e.has(t);break}case"delete":{const[t]=o;s.existed=e.has(t),s.deletedItem=s.existed?t:void 0;break}case"clear":s.clearedItems=Array.from(e),s.previousSize=e.size}r(s);const i=e[t].apply(e,o),c={method:t,result:i,args:o,context:s,target:e,...a};return n(c),i};for(const e of o)t.includes(e)&&(s[e]=createWrappedMethod(e));return Object.defineProperty(s,"target",{get:()=>e,enumerable:!1,configurable:!1}),s},wrapMapMethods:({target:e,onBeforeMutate:t=()=>{},onAfterMutate:n=()=>{},allowList:o=r,props:a={}})=>{if(!(e instanceof Map))throw new TypeError("The 'target' parameter must be a Map.");const s={},createWrappedMethod=r=>function(...o){const s={};switch(r){case"set":{const[t,r]=o;s.key=t,s.newValue=r,s.existed=e.has(t),s.oldValue=s.existed?e.get(t):void 0;break}case"delete":{const[t]=o;s.key=t,s.existed=e.has(t),s.value=s.existed?e.get(t):void 0;break}case"clear":s.clearedItems=Array.from(e.entries()),s.previousSize=e.size}t(s);const i=e[r].apply(e,o),c={method:r,result:i,args:o,context:s,target:e,...a};return n(c),i};for(const e of o)r.includes(e)&&(s[e]=createWrappedMethod(e));return Object.defineProperty(s,"target",{get:()=>e,enumerable:!1,configurable:!1}),s},getUniqueId:(e={})=>{const t=e.prefix,r=e.suffix,n=e.base10,o=e.base36;return`${t?t+"-":""}${Date.now()}${o?"-"+Math.random().toString(36).substring(2,11):""}${n?"-"+Math.floor(1e4*Math.random()).toString().padStart(4,"0"):""}${r?"-"+r:""}`},deepMerge:(e,t,r={})=>{const n=Object.assign({dataMode:"clear",inheritMissing:!0,targetClone:!1,useEnable:!0,useSymbol:!0,deepClone:{},onBeforeMerge:void 0,onAfterMerge:void 0},r),smartMerger=(e,t,n)=>{let o,a,s=getDataType(e),i=getDataType(t),c=!0;if(n.interceptor&&"function"==typeof n.interceptor){let r=n.interceptor({target:e,source:t,targetType:s,sourceType:i,parent:n.parent});if(r){if(null===r?.target||null===r?.source)return r;e=r.target,t=r.source}}return n?.onBeforeMerge?.({target:e,source:t,targetType:s,sourceType:i,parent:n.parent}),"Object"===s&&"Object"===i?(a=deepMergeObjects(e,t,n),o="Object"):"Array"===s&&"Array"===i?(a=deepMergeArrays(e,t,n),o="Array"):"Set"===s&&"Set"===i?(a=deepMergeSets(e,t,n),o="Set"):"Map"===s&&"Map"===i?(a=deepMergeMaps(e,t,n),o="Map"):(c=!1,a=e),n?.onAfterMerge?.({result:a,target:e,source:t,targetType:s,sourceType:i,mergeType:o,parent:r.parent}),{result:a,flag:c,mergeType:o}},mergeEnableObject=(e,t)=>e?.hasOwnProperty("enable")&&"boolean"==typeof t?(e.enable=t,e):t?.hasOwnProperty("enable")&&"boolean"==typeof e?Object.assign({enable:e},t):t,deepMergeObjects=(e,t,r={})=>{let n=getDataType(e),o=getDataType(t);if("Object"!==n||"Object"!==o)return e;const a=Object.assign({inheritMissing:!0,targetClone:!1,useEnable:!0},r);let s={};s=a.targetClone?shallowCopy(e):e;for(let e in t)if(t.hasOwnProperty(e)&&s.hasOwnProperty(e)){let n=smartMerger(s[e],t[e],{...r,parent:s});n.flag?n.mergeType?"Object"===n.mergeType&&(s[e]=n.result):s[e]=t[e]:a.useEnable?s[e]=mergeEnableObject(s[e],t[e]):s[e]=t[e]}else t.hasOwnProperty(e)&&!s.hasOwnProperty(e)&&a.inheritMissing&&(s[e]=t[e]);if(a.useSymbol){let e=Object.getOwnPropertySymbols(t);if(e.length)for(let r of e)s[r]=t[r]}return s},deepMergeArrays=(e,t,r={})=>{if(!Array.isArray(e)||!Array.isArray(t))return e;const n=Object.assign({dataMode:"clear",inheritMissing:!0,targetClone:!1},r),o=n.targetClone?[...e]:e;if("replace"===n.dataMode)for(let e=0;e<t.length&&(n.inheritMissing||!(e>=o.length));e++){smartMerger(o[e],t[e],{...n,parent:o}).flag||(o[e]=t[e])}else"concat"===n.dataMode||(o.length=0),o.push(...t);return o},deepMergeMaps=(e,t,r={})=>{if(!(e instanceof Map&&t instanceof Map))return e;const n=Object.assign({inheritMissing:!0,targetClone:!1,useEnable:!0},r),o=n.targetClone?new Map([...e]):e;for(const[e,a]of t.entries())if(o.has(e)){const t=o.get(e),r=a,s=smartMerger(t,r,n);s.flag?"Object"===s.mergeType&&o.set(e,s.result):o.set(e,r)}else r.inheritMissing&&o.set(e,a);return o},deepMergeSets=(e,t,r={})=>{if(!(e instanceof Set&&t instanceof Set))return e;const n=Object.assign({dataMode:"clear",inheritMissing:!0,targetClone:!1,useEnable:!0},r),o=n.targetClone?new Set(...e):e;if("replace"===n.dataMode){const e=[...o],r=[...t],a=smartMerger(e,r,n);o.clear();for(let e of a.result)o.add(e)}else if("concat"===n.dataMode)for(let e of t)o.add(e);else{o.clear();for(let e of t)o.add(e)}return o};return smartMerger(e,t,n).result},shallowCopy:shallowCopy,copyObjectWithSymbol:copyObjectWithSymbol}});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codady/utils",
-  "version": "0.0.15",
+  "version": "0.0.17",
   "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/deepClone.js

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/26 11:26:10
+ * @since Last modified: 2025/12/26 15:13:54
  * Deep clone an array, object, or other cloneable data types.
  *
  * Features:
@@ -100,16 +100,16 @@ const deepClone = (data, options = {}) => {
     }, 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);
+        let result = opts.interceptor({ input: data, type: dataType, parent: opts.parent });
         if ((result ?? false)) {
             // Call onAfterClone if set
-            opts.onAfterClone?.({
-                output: result,
-                input: data,
-                type: dataType,
-                cloned: result !== data,
-                parent: opts.parent
-            });
+            /*   opts.onAfterClone?.({
+                  output: result,
+                  input: data,
+                  type: dataType,
+                  cloned: result !== data,
+                  parent: opts.parent
+              }); */
             return result;
         }
         // If interceptor returns null/undefined, continue with normal cloning process

package/src/deepClone.ts

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/26 11:26:10
+ * @since Last modified: 2025/12/26 15:13:54
  * Deep clone an array, object, or other cloneable data types.
  * 
  * Features:
@@ -94,7 +94,7 @@ export interface DeepCloneOptions {
     /**
      * Interceptor function. If returns a non-null value, use it as the cloning result.
      */
-    interceptor?: <T>(data: T, dataType: string) => T | null | undefined;
+    interceptor?: <T>(result: BeforeCloneResult) => T | null | undefined;
 
  /**
      * Callback before cloning.
@@ -147,16 +147,16 @@ const deepClone = <T>(data: T, options: DeepCloneOptions = {}): T => {
 
     // 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);
+        let result = opts.interceptor({input: data, type: dataType,parent: opts.parent});
         if ((result ?? false)) {
             // Call onAfterClone if set
-            opts.onAfterClone?.({
+          /*   opts.onAfterClone?.({
                 output: result,
                 input: data,
                 type: dataType,
                 cloned: result !== data,
                 parent: opts.parent
-            });
+            }); */
             return result as T;
         }
         // If interceptor returns null/undefined, continue with normal cloning process

package/src/deepMerge.js

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/25 12:10:30
+ * @since Last modified: 2025/12/26 16:03:37
  * @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.
@@ -69,31 +69,49 @@ const deepMerge = (target, source, opts = {}) => {
     }, opts), 
     // Main helper function for recursive merging
     // 递归合并的主辅助函数
-    deepMergeHelper = (target, source, options) => {
-        let targetType = getDataType(target), sourceType = getDataType(source), flag = true, type, result;
+    smartMerger = (target, source, options) => {
+        let targetType = getDataType(target), sourceType = getDataType(source), flag = true, mergeType, result;
+        // Check interceptor - if it returns a value (not null/undefined), use it directly
+        if (options.interceptor && typeof options.interceptor === 'function') {
+            let interceptorResult = options.interceptor({ target, source, targetType, sourceType, parent: options.parent });
+            if ((interceptorResult ?? false)) {
+                //如果不是返回{target,source}，那么直接返回interceptorResult
+                if (interceptorResult?.target === null || interceptorResult?.source === null) {
+                    return interceptorResult;
+                }
+                else {
+                    //interceptorResult={target,source}
+                    target = interceptorResult.target;
+                    source = interceptorResult.source;
+                }
+            }
+            // If interceptor returns null/undefined, continue with normal cloning process
+        }
+        options?.onBeforeMerge?.({ target, source, targetType, sourceType, parent: options.parent });
         // Determine the type and perform appropriate merging
         // 确定类型并执行相应的合并
         if (targetType === 'Object' && sourceType === 'Object') {
             result = deepMergeObjects(target, source, options);
-            type = 'Object';
+            mergeType = 'Object';
         }
         else if (targetType === 'Array' && sourceType === 'Array') {
             result = deepMergeArrays(target, source, options);
-            type = 'Array';
+            mergeType = 'Array';
         }
         else if (targetType === 'Set' && sourceType === 'Set') {
             result = deepMergeSets(target, source, options);
-            type = 'Set';
+            mergeType = 'Set';
         }
         else if (targetType === 'Map' && sourceType === 'Map') {
             result = deepMergeMaps(target, source, options);
-            type = 'Map';
+            mergeType = 'Map';
         }
         else {
             flag = false;
             result = target;
         }
-        return { result, flag, type };
+        options?.onAfterMerge?.({ result, target, source, targetType, sourceType, mergeType, parent: opts.parent });
+        return { result, flag, mergeType };
     }, 
     // Special handling for objects with enable property
     // 对具有enable属性的对象进行特殊处理
@@ -121,7 +139,6 @@ const deepMerge = (target, source, opts = {}) => {
         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
@@ -129,7 +146,7 @@ const deepMerge = (target, source, opts = {}) => {
         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);
+                let resp = smartMerger(result[k], source[k], { ...opts, parent: result });
                 //resp={result,flag,type}
                 //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                 if (!resp.flag) {
@@ -144,8 +161,8 @@ const deepMerge = (target, source, opts = {}) => {
                 }
                 else {
                     //类型相同
-                    if (resp.type) {
-                        if (resp.type === 'Object') {
+                    if (resp.mergeType) {
+                        if (resp.mergeType === 'Object') {
                             //如果遇上对象则深度复制
                             result[k] = resp.result;
                         }
@@ -169,13 +186,11 @@ const deepMerge = (target, source, opts = {}) => {
                     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
@@ -188,7 +203,7 @@ const deepMerge = (target, source, opts = {}) => {
                 // 如果不允许添加超过长度
                 if (!opts.inheritMissing && i >= result.length)
                     break;
-                let resp = deepMergeHelper(result[i], source[i], opts);
+                let resp = smartMerger(result[i], source[i], { ...opts, parent: result });
                 //resp={result,flag,type}
                 //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                 if (!resp.flag) {
@@ -205,13 +220,11 @@ const deepMerge = (target, source, opts = {}) => {
             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
@@ -220,7 +233,7 @@ const deepMerge = (target, source, opts = {}) => {
         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);
+                const _target = result.get(key), _source = value, resp = smartMerger(_target, _source, opts);
                 //resp={result,flag,type}
                 //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                 if (!resp.flag) {
@@ -229,20 +242,18 @@ const deepMerge = (target, source, opts = {}) => {
                 }
                 else {
                     // If both target and source are objects, merge them recursively
-                    resp.type === 'Object' && result.set(key, resp.result);
+                    resp.mergeType === '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
@@ -250,7 +261,7 @@ const deepMerge = (target, source, opts = {}) => {
         // 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);
+            const _result = [...result], _source = [...source], resp = smartMerger(_result, _source, opts);
             result.clear();
             for (let item of resp.result)
                 result.add(item);
@@ -266,9 +277,8 @@ const deepMerge = (target, source, opts = {}) => {
             for (let item of source)
                 result.add(item);
         }
-        options?.onAfterMerge?.(result, target, source);
         return result;
     };
-    return deepMergeHelper(target, source, options).result;
+    return smartMerger(target, source, options).result;
 };
 export default deepMerge;