@codady/utils 0.0.15 → 0.0.17

package/src/deepMerge.ts

@@ -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.
@@ -59,20 +59,48 @@ 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;
+        targetType: string;
+        sourceType: string;
+    }) => any;
+
+    /**
+     * Callback function executed before merging each data structure
+     * 在每个数据结构合并前执行的回调函数
+     */
+    onBeforeMerge?: (params: {
+        target: any;
+        source: any;
+        parent?: any;
+        targetType: string;
+        sourceType: string;
+    }) => void;
+
+    /**
+     * Callback function executed after merging each data structure
+     * 在每个数据结构合并后执行的回调函数
+     */
+    onAfterMerge?: (params: {
+        result: any;
+        target: any;
+        source: any;
+        parent?: any;
+        targetType: string;
+        sourceType: string;
+        mergeType?: '' | 'Object' | 'Array' | 'Map' | 'Set';
+    }) => void;
+
+    /**
+     * 深度合并时的临时保存的父对象
+     */
+    parent?: any;
 }
 export type EnableObject = {
     enable: boolean;
@@ -122,31 +150,51 @@ 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,
+                mergeType: 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, 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属性的对象进行特殊处理
@@ -174,7 +222,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 +232,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) {
@@ -198,8 +245,8 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                         }
                     } else {
                         //类型相同
-                        if (resp.type) {
-                            if (resp.type === 'Object') {
+                        if (resp.mergeType) {
+                            if (resp.mergeType === 'Object') {
                                 //如果遇上对象则深度复制
                                 (result as any)[k] = resp.result;
                             }
@@ -221,13 +268,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 +287,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 +302,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 +320,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) {
@@ -283,19 +328,18 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                         result.set(key, _source);
                     } 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: 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 +351,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 +363,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;