@codady/utils 0.0.17 → 0.0.19

package/src/deepMerge.ts

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/26 16:03:37
+ * @since Last modified: 2025/12/27 14:35:01
  * @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.
@@ -42,6 +42,10 @@ export interface DeepMergeOptions {
     // Mode for handling array items
     // 处理数组成员的模式
     dataMode?: 'clear' | 'replace' | 'concat';
+    //如果source值=null，target如何处理，ignore表示不理会null保持target；preserve将覆盖target，delete将删除target（key）
+    nullBehavior?: 'ignore' | 'preserve' | 'delete';
+    //如果source值=undefined，target如何处理，ignore表示不理会undefined保持target；preserve将覆盖target，delete将删除target（key）
+    undefinedBehavior?: 'ignore' | 'preserve' | 'delete';
     // Whether to append properties (for objects)
     // 是否追加属性（针对对象）
     inheritMissing?: boolean;
@@ -136,6 +140,10 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
         // target是{}类型时，是否允许合并key=symbol的键值对。
         useSymbol: true,
 
+        nullBehavior:'preserve',
+        
+        undefinedBehavior:'preserve',
+
         // Options passed to the deepClone function when targetClone is true
         // 当targetClone为true时传递给deepClone函数的选项
         deepClone: {},
@@ -230,18 +238,38 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
             result = options.targetClone ? shallowCopy(target) : target;
 
             for (let k in source) {
+                const _result = (result as any)[k],
+                    _source = source[k];
                 if (source.hasOwnProperty(k) && result.hasOwnProperty(k)) {
 
-                    let resp = smartMerger((result as any)[k], source[k], { ...opts, parent: result });
+                    const resp = smartMerger(_result, _source, { ...opts, parent: result });
                     //resp={result,flag,type}
-                    //flag=true表示类型一致并完成了合并，false表示并没有合并需要直接赋值
+                    //flag=true表示类型一致（object/array/map/set）并完成了合并，false表示并没有合并需要直接赋值
                     if (!resp.flag) {
                         //类型不同则直接覆盖
-                        if (options.useEnable) {
-                            (result as any)[k] = mergeEnableObject((result as any)[k], source[k]);
+                        let tmp = options.useEnable ? mergeEnableObject(_result, _source) : _source;
+                        if (_result !== tmp && tmp === null) {
+                            if (options.nullBehavior === 'ignore') {
+                                //不处理
+                            } else if (options.nullBehavior === 'delete') {
+                                //删除属性
+                                Reflect.deleteProperty(result, k);
+                            } else {
+                                //替换
+                                (result as any)[k] = tmp;
+                            }
+                        } else if (_result !== tmp && tmp === undefined) {
+                            if (options.undefinedBehavior === 'ignore') {
+                                //不处理
+                            } else if (options.undefinedBehavior === 'delete') {
+                                //删除属性
+                                Reflect.deleteProperty(result, k);
+                            } else {
+                                //替换
+                                (result as any)[k] = _source;
+                            }
                         } else {
-                            //完全替换
-                            (result as any)[k] = source[k];
+                            (result as any)[k] = _source;
                         }
                     } else {
                         //类型相同
@@ -252,13 +280,13 @@ const deepMerge = (target: Object | Array<any> | Map<any, any> | Set<any>, sourc
                             }
                         } else {
                             //其他类型则直接覆盖
-                            (result as any)[k] = source[k];
+                            (result as any)[k] = _source;
                         }
                     }
 
                 } else if (source.hasOwnProperty(k) && !result.hasOwnProperty(k) && options.inheritMissing) {
                     //如果source有属性，result没有该属性，但是options允许追加属性则直接赋值
-                    (result as any)[k] = source[k];
+                    (result as any)[k] = _source;
                 }
             }
             //Symbol键直接追加，因为Symbol是唯一，结果同Object.assign

package/src/getEl.js

@@ -0,0 +1,38 @@
+/**
+ * @since Last modified: 2026/01/05 10:28:14
+ * @function getEl
+ * @description Get a DOM node (real or virtual). Supports obtaining nodes from various types (not just HTMLElement).
+ * @param {string|Node} obj - Can be a node selector (e.g., #id, .classname, NODENAME, [attribute]) or any node type (HTMLElement, Node, DocumentFragment, etc.).
+ * @param {Node|string} wrap - Parent node (or selector) from which to get the sub-node. Defaults to document.body.
+ * @returns {Node|null} Returns the matching node or null if not found.
+ * @example
+ * ax.getEl('#demo');
+ * <!-- returns a DOM node -->
+ */
+//简介：获得一个节点。支持获得一个真实节点或虚拟节点
+//参数obj：可以是#id、.className、NODENAME、[attribute]等节点选择器或节点
+//参数parent：父节点，从该节点获取子节点，默认document.body
+//返回：一个节点或null
+'use strict';
+import getDataType from './getDataType';
+const getEl = (obj, wrap = document.body) => {
+    let objType = getDataType(obj), parType = getDataType(wrap), parent = parType.includes('HTML') ? wrap : document.querySelector(wrap), 
+    //如果parent是template节点，需要通过node.content.querySelector取得子节点
+    root = parent && parent instanceof HTMLTemplateElement ? parent.content : parent, result = null;
+    if (obj) {
+        if (objType.includes('HTML')) {
+            result = obj;
+        }
+        else if (objType === 'String') {
+            try {
+                result = (root || document).querySelector(obj.trim());
+                //可能会报错，报错则返回null
+            }
+            catch {
+                result = null;
+            }
+        }
+    }
+    return result;
+};
+export default getEl;

package/src/getEl.ts

@@ -0,0 +1,41 @@
+/**
+ * @since Last modified: 2026/01/05 10:28:14
+ * @function getEl
+ * @description Get a DOM node (real or virtual). Supports obtaining nodes from various types (not just HTMLElement).
+ * @param {string|Node} obj - Can be a node selector (e.g., #id, .classname, NODENAME, [attribute]) or any node type (HTMLElement, Node, DocumentFragment, etc.).
+ * @param {Node|string} wrap - Parent node (or selector) from which to get the sub-node. Defaults to document.body.
+ * @returns {Node|null} Returns the matching node or null if not found.
+ * @example
+ * ax.getEl('#demo'); 
+ * <!-- returns a DOM node -->
+ */
+//简介：获得一个节点。支持获得一个真实节点或虚拟节点
+//参数obj：可以是#id、.className、NODENAME、[attribute]等节点选择器或节点
+//参数parent：父节点，从该节点获取子节点，默认document.body
+//返回：一个节点或null
+'use strict';
+import getDataType from './getDataType';
+
+
+const getEl = (obj: string | Node | null, wrap: Node | string | null = document.body): Node | null => {
+    let objType = getDataType(obj),
+        parType = getDataType(wrap),
+        parent = parType.includes('HTML') ? wrap : document.querySelector(wrap as string),
+        //如果parent是template节点，需要通过node.content.querySelector取得子节点
+        root = parent && parent instanceof HTMLTemplateElement ? parent.content : parent,
+        result: Node | null = null;
+    if (obj) {
+        if (objType.includes('HTML')) {
+            result = (obj as Node);
+        } else if (objType === 'String') {
+            try {
+                result = (((root as Node) || document) as any).querySelector((obj as string).trim());
+                //可能会报错，报错则返回null
+            } catch {
+                result = null;
+            }
+        }
+    }
+    return result;
+}
+export default getEl;

package/src/getEls.js

@@ -0,0 +1,48 @@
+/**
+ * @since Last modified: 2026/01/05 10:29:34
+ * @function getEls
+ * @description Get the node array.
+ * @param {*} data  - It can be a single node selector or a node array.
+ * @param {HTMLElement} parent  - Parent node, get sub-node from this node, default document.body
+ * @returns {array} Return a node array.
+ * @example
+ * ax.getEls('#demo');
+ * <!--return [node]-->
+ * ax.getEls('#demo1,#demo2,#demo3');
+ * <!--return [node1,node2,node3]-->
+ * ax.getEls(['#demo1','#demo2,'#demo3']);
+ * <!--return [node1,node2,node3]-->
+ */
+//简介：获得节点数组。
+//参数data：可以单个节点选择器，使用方法同getEl，也可以是以“,”分隔的多个选择器，也可以节点数组。
+//参数parent：父节点，从该节点获取子节点，默认document。
+//返回：一个节点数组。
+'use strict';
+import getDataType from './getDataType';
+import getEl from './getEl';
+import isEmpty from './isEmpty';
+const getEls = (data, parent = document.body) => {
+    let type = getDataType(data), parentEl = getEl(parent), root = parentEl && parentEl instanceof HTMLTemplateElement ? parentEl.content : (parentEl || document), result = [];
+    //data为空直接返回空数组
+    if (isEmpty(data)) {
+        return result;
+    }
+    if (type.includes('HTML')) {
+        //一个节点
+        result.push(data);
+    }
+    else if (type === 'String') {
+        data = data.trim();
+        //以英文逗号作为节点选择器分隔符
+        result = data.split(',').map((k) => {
+            return [...root.querySelectorAll(k)];
+        }).flat();
+    }
+    else if (type === 'Array') {
+        result = data.map((k) => {
+            return getEl(k, parentEl);
+        });
+    }
+    return result.filter(Boolean);
+};
+export default getEls;

package/src/getEls.ts

@@ -0,0 +1,48 @@
+/**
+ * @since Last modified: 2026/01/05 10:29:34
+ * @function getEls
+ * @description Get the node array.
+ * @param {*} data  - It can be a single node selector or a node array.
+ * @param {HTMLElement} parent  - Parent node, get sub-node from this node, default document.body
+ * @returns {array} Return a node array.
+ * @example
+ * ax.getEls('#demo');
+ * <!--return [node]-->
+ * ax.getEls('#demo1,#demo2,#demo3');
+ * <!--return [node1,node2,node3]-->
+ * ax.getEls(['#demo1','#demo2,'#demo3']);
+ * <!--return [node1,node2,node3]-->
+ */
+//简介：获得节点数组。
+//参数data：可以单个节点选择器，使用方法同getEl，也可以是以“,”分隔的多个选择器，也可以节点数组。
+//参数parent：父节点，从该节点获取子节点，默认document。
+//返回：一个节点数组。
+'use strict';
+import getDataType from './getDataType';
+import getEl from './getEl';
+import isEmpty from './isEmpty';
+
+const getEls = (data: Node | string |  null | (Node | string)[], parent: Node | string | null = document.body): (Node | string)[] => {
+    let type = getDataType(data),
+        parentEl = getEl(parent),
+        root = parentEl && parentEl instanceof HTMLTemplateElement ? parentEl.content : (parentEl || document),
+        result: any[] = [];
+        //data为空直接返回空数组
+    if (isEmpty(data)) { return result; }
+    if (type.includes('HTML')) {
+        //一个节点
+        result.push(data);
+    } else if (type === 'String') {
+        data = (data as string).trim();
+        //以英文逗号作为节点选择器分隔符
+        result = data.split(',').map((k: any) => {
+            return [...(root as any).querySelectorAll(k)];
+        }).flat();
+    } else if (type === 'Array') {
+        result = (data as (Node | string)[]).map((k: any) => {
+            return getEl(k, parentEl);
+        });
+    }
+    return result.filter(Boolean);
+}
+export default getEls;