@codady/utils 0.0.14 → 0.0.16

package/src/deepMerge.ts

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/25 12:10:30
+ * @since Last modified: 2025/12/26 15:40:50
  * @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.
@@ -59,20 +59,42 @@ export interface DeepMergeOptions {
     // 启用克隆时传递给deepClone函数的选项
     deepClone?: Record<string, any>;
 
-    // Callback function executed before merging each data structure
-    // 在每个数据结构合并前执行的回调函数
-    onBeforeMerge?: (
-        target: Object | Array<any> | Map<any, any> | Set<any>,
-        source: Object | Array<any> | Map<any, any> | Set<any> | any
-    ) => void;
-
-    // Callback function executed after merging each data structure
-    // 在每个数据结构合并后执行的回调函数
-    onAfterMerge?: (
-        result: Object | Array<any> | Map<any, any> | Set<any>,
-        originalTarget: Object | Array<any> | Map<any, any> | Set<any>,
-        source: Object | Array<any> | Map<any, any> | Set<any> | any
-    ) => void;
+    /**
+     * Interceptor function. If returns a non-null value, use it as the merging result.
+     * 拦截器函数。如果返回非null值，则将其用作合并结果。
+     */
+    interceptor?: (params: {
+        target: any;
+        source: any;
+        parent?: any;
+    }) => any;
+
+    /**
+     * Callback function executed before merging each data structure
+     * 在每个数据结构合并前执行的回调函数
+     */
+    onBeforeMerge?: (params: {
+        target: any;
+        source: any;
+        parent?: any;
+    }) => void;
+
+    /**
+     * Callback function executed after merging each data structure
+     * 在每个数据结构合并后执行的回调函数
+     */
+    onAfterMerge?: (params: {
+        result: any;
+        target: any;
+        source: any;
+        parent?: any;
+        type?: '' | 'Object' | 'Array' | 'Map' | 'Set';
+    }) => void;
+
+    /**
+     * 深度合并时的临时保存的父对象
+     */
+    parent?: any;
 }
 export type EnableObject = {
     enable: boolean;
@@ -122,12 +144,31 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
     }, opts),
         // Main helper function for recursive merging
         // 递归合并的主辅助函数
-        deepMergeHelper = (target: any, source: any, options: DeepMergeOptions): any => {
+        smartMerger = (target: any, source: any, options: DeepMergeOptions): any => {
             let targetType = getDataType(target),
                 sourceType = getDataType(source),
                 flag = true,
-                type,
+                type: any,
                 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, 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, parent: options.parent });
+
             // Determine the type and perform appropriate merging
             // 确定类型并执行相应的合并
             if (targetType === 'Object' && sourceType === 'Object') {
@@ -146,6 +187,7 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                 flag = false;
                 result = target;
             }
+            options?.onAfterMerge?.({ result, target, source, type, parent: opts.parent });
             return { result, flag, type };
         },
         // Special handling for objects with enable property
@@ -174,7 +216,6 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
             if (targetType !== 'Object' || sourceType !== 'Object') {
                 return target;
             }
-            opts?.onBeforeMerge?.(target, source);
 
             const options = Object.assign({ inheritMissing: true, targetClone: false, useEnable: true }, opts);
             let result: any = {};
@@ -185,7 +226,7 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
             for (let k in source) {
                 if (source.hasOwnProperty(k) && result.hasOwnProperty(k)) {
 
-                    let resp = deepMergeHelper((result as any)[k], source[k], opts);
+                    let resp = smartMerger((result as any)[k], source[k], { ...opts, parent: result });
                     //resp={result,flag,type}
                     //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                     if (!resp.flag) {
@@ -221,13 +262,12 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                     for (let k of symbols) (result as any)[k] = source[k];
                 }
             }
-            options?.onAfterMerge?.(result, target, source);
             return result;
         },
         deepMergeArrays = (target: any[], source: any[], options: DeepMergeOptions = {}): any[] => {
             // 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),
 
@@ -241,7 +281,7 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                     // If not allowed to add beyond length
                     // 如果不允许添加超过长度
                     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) {
@@ -256,13 +296,12 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                 result.length = 0;
                 result.push(...source);
             }
-            options?.onAfterMerge?.(result, target, source);
             return result;
         },
         deepMergeMaps = (target: Map<any, any>, source: Map<any, any>, options: DeepMergeOptions = {}): Map<any, any> => {
             // 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),
 
@@ -275,7 +314,7 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                 if (result.has(key)) {
                     const _target = result.get(key),
                         _source = value,
-                        resp = deepMergeHelper(_target, _source, opts);
+                        resp = smartMerger(_target, _source, opts);
                     //resp={result,flag,type}
                     //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
                     if (!resp.flag) {
@@ -289,13 +328,12 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                     // 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: Set<any>, source: Set<any>, options: DeepMergeOptions = {}): Set<any> => {
             // 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),
 
@@ -307,11 +345,10 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                 // Replace mode: recursively merge items in the Sets
                 const _result = [...result],
                     _source = [...source],
-                    resp = deepMergeHelper(_result, _source, opts);
+                    resp = smartMerger(_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);
@@ -320,9 +357,11 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                 result.clear();
                 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;