@codady/utils 0.0.9 → 0.0.10

package/dist/utils.esm.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-19 15:23:38
+ * @since Last modified: 2025-12-22 20:26:42
  * @name Utils for web front-end.
- * @version 0.0.9
+ * @version 0.0.10
  * @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}
@@ -39,37 +39,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 === 'Date') {
-        return new Date(data.getTime());
+    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 === '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) => {
@@ -100,7 +163,7 @@ const deepCloneToJSON = (data) => {
     }
 };
 
-const mutableMethods = [
+const arrayMutableMethods = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
@@ -112,7 +175,7 @@ const wrapArrayMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate =
     }
     //使用默认
     if (!allowList || allowList?.length) {
-        allowList = mutableMethods;
+        allowList = arrayMutableMethods;
     }
     const methods = {};
     for (let method of allowList) {
@@ -128,10 +191,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, 
@@ -201,20 +264,160 @@ 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 utils = {
@@ -226,7 +429,11 @@ const utils = {
     deepClone,
     deepCloneToJSON,
     wrapArrayMethods,
-    mutableMethods,
+    arrayMutableMethods,
+    setMutableMethods,
+    mapMutableMethods,
+    wrapSetMethods,
+    wrapMapMethods,
     getUniqueId
 };
 

package/dist/utils.esm.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-19 15:23:38
+ * @since Last modified: 2025-12-22 20:26:42
  * @name Utils for web front-end.
- * @version 0.0.9
+ * @version 0.0.10
  * @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
  */
-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=>{const t=getDataType(e);if("Object"===t){const t={},r=Object.getOwnPropertySymbols(e);for(const r in e)t[r]=deepClone(e[r]);if(r.length>0)for(const o of r)t[o]=deepClone(e[o]);return t}if("Array"===t)return e.map(e=>deepClone(e));if("Date"===t)return new Date(e.getTime());if("RegExp"===t){const t=e;return new RegExp(t.source,t.flags)}return e},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},mutableMethods=["push","pop","shift","unshift","splice","sort","reverse","copyWithin","fill"],wrapArrayMethods=({target:e,onBeforeMutate:t=()=>{},onAfterMutate:r=()=>{},allowList:o,props:a={}})=>{if(!Array.isArray(e))throw new TypeError("The 'target' parameter must be an array.");o&&!o?.length||(o=mutableMethods);const n={};for(let s of o)n[s]=function(...o){const n={},p=e.length;switch(s){case"push":case"unshift":n.addedItems=[...o];break;case"pop":n.poppedValue=e[p-1];break;case"shift":n.shiftedValue=e[0];break;case"splice":const[t,r]=o,a=t<0?Math.max(p+t,0):Math.min(t,p),s=void 0===r?p-a:r;n.deletedItems=e.slice(a,a+s);break;case"sort":case"reverse":n.oldSnapshot=[...e];break;case"fill":case"copyWithin":const i=o[1]||0,l=void 0===o[2]?p:o[2];n.oldItems=e.slice(i,l),n.start=i,n.end=l}t?.(n);const i=Array.prototype[s].apply(e,o),l={value:i,key:s,args:o,context:n,target:e,...a};return r?.(l),i};return n},requireTypes=(e,t,r)=>{let o=Array.isArray(t)?t:[t],a=getDataType(e),n=a.toLowerCase(),s=o.map(e=>e.toLowerCase()),p=n.includes("html")?"element":n;if(r)try{if(!s.includes(p))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${p}`)}catch(e){r(e,a)}else if(!s.includes(p))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${p}`);return a},getUniqueId=(e,t=!0)=>`${e?e+"_":""}${Date.now()}_${Math.random().toString(36).substring(2,11)}${t?"_"+Math.floor(1e4*Math.random()).toString().padStart(4,"0"):""}`,utils={getDataType:getDataType,requireTypes:requireTypes,deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,wrapArrayMethods:wrapArrayMethods,mutableMethods:mutableMethods,getUniqueId:getUniqueId};export{utils as default};
+const getDataType=e=>{let t,o=Object.prototype.toString.call(e).slice(8,-1);return t="Function"===o&&/^\s*class\s+/.test(e.toString())?"Class":"Object"===o&&Object.getPrototypeOf(e)!==Object.prototype?"Instance":o,t},deepClone=(e,t={})=>{const o=getDataType(e),r=Object.assign({cloneSet:!0,cloneMap:!0,cloneObject:!0,cloneArray:!0,cloneDate:!0,cloneRegex:!0},t);if(r.interceptor&&"function"==typeof r.interceptor){let t=r.interceptor(e,o);if(t)return r.onAfterClone?.({output:t,input:e,type:o,cloned:t!==e}),t}r.onBeforeClone?.(e,o);let a,s=!0;if("Object"===o&&r.cloneObject){const t={},o=Object.getOwnPropertySymbols(e);for(const o in e)t[o]=deepClone(e[o],r);if(o.length>0)for(const a of o)t[a]=deepClone(e[a],r);a=t}else if("Array"===o&&r.cloneArray)a=e.map(e=>deepClone(e,r));else if("Map"===o&&r.cloneMap){const t=new Map;for(const[o,a]of e)t.set(deepClone(o,r),deepClone(a,r));a=t}else if("Set"===o&&r.cloneSet){const t=new Set;for(const o of e)t.add(deepClone(o,r));a=t}else if("Date"===o&&r.cloneDate)a=new Date(e.getTime());else if("RegExp"===o&&r.cloneRegex){const t=e;a=new RegExp(t.source,t.flags)}else a=e,s=!1;return r.onAfterClone?.({output:a,input:e,type:o,cloned:s}),a},deepCloneToJSON=e=>{const t=getDataType(e);if("Object"===t){const t={};for(const o in e)t[o]=deepCloneToJSON(e[o]);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},arrayMutableMethods=["push","pop","shift","unshift","splice","sort","reverse","copyWithin","fill"],wrapArrayMethods=({target:e,onBeforeMutate:t=()=>{},onAfterMutate:o=()=>{},allowList:r,props:a={}})=>{if(!Array.isArray(e))throw new TypeError("The 'target' parameter must be an array.");r&&!r?.length||(r=arrayMutableMethods);const s={};for(let n of r)s[n]=function(...r){const s={},l=e.length;switch(n){case"push":case"unshift":s.addedItems=[...r];break;case"pop":s.poppedItem=e[l-1];break;case"shift":s.shiftedItem=e[0];break;case"splice":const[t,o]=r,a=t<0?Math.max(l+t,0):Math.min(t,l),n=void 0===o?l-a:o;s.deletedItems=e.slice(a,a+n);break;case"sort":case"reverse":s.oldSnapshot=[...e];break;case"fill":case"copyWithin":const c=r[1]||0,p=void 0===r[2]?l:r[2];s.oldItems=e.slice(c,p),s.start=c,s.end=p}t?.(s);const c=Array.prototype[n].apply(e,r),p={value:c,key:n,args:r,context:s,target:e,...a};return o?.(p),c};return s},requireTypes=(e,t,o)=>{let r=Array.isArray(t)?t:[t],a=getDataType(e),s=a.toLowerCase(),n=r.map(e=>e.toLowerCase()),l=s.includes("html")?"element":s;if(o)try{if(!n.includes(l))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${l}`)}catch(e){o(e,a)}else if(!n.includes(l))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${l}`);return a},getUniqueId=(e={})=>{const t=e.prefix,o=e.suffix,r=e.base10,a=e.base36;return`${t?t+"-":""}${Date.now()}${a?"-"+Math.random().toString(36).substring(2,11):""}${r?"-"+Math.floor(1e4*Math.random()).toString().padStart(4,"0"):""}${o?"-"+o:""}`},setMutableMethods=["add","delete","clear"],mapMutableMethods=["set","delete","clear"],wrapSetMethods=({target:e,onBeforeMutate:t=()=>{},onAfterMutate:o=()=>{},allowList:r=setMutableMethods,props:a={}})=>{if(!(e instanceof Set))throw new TypeError("The 'target' parameter must be a Set.");const s={},createWrappedMethod=r=>function(...s){const n={};switch(r){case"add":{const[t]=s;n.addedItem=t,n.existed=e.has(t);break}case"delete":{const[t]=s;n.existed=e.has(t),n.deletedItem=n.existed?t:void 0;break}case"clear":n.clearedItems=Array.from(e),n.previousSize=e.size}t(n);const l=e[r].apply(e,s),c={method:r,result:l,args:s,context:n,target:e,...a};return o(c),l};for(const e of r)setMutableMethods.includes(e)&&(s[e]=createWrappedMethod(e));return Object.defineProperty(s,"target",{get:()=>e,enumerable:!1,configurable:!1}),s},wrapMapMethods=({target:e,onBeforeMutate:t=()=>{},onAfterMutate:o=()=>{},allowList:r=mapMutableMethods,props:a={}})=>{if(!(e instanceof Map))throw new TypeError("The 'target' parameter must be a Map.");const s={},createWrappedMethod=r=>function(...s){const n={};switch(r){case"set":{const[t,o]=s;n.key=t,n.newValue=o,n.existed=e.has(t),n.oldValue=n.existed?e.get(t):void 0;break}case"delete":{const[t]=s;n.key=t,n.existed=e.has(t),n.value=n.existed?e.get(t):void 0;break}case"clear":n.clearedItems=Array.from(e.entries()),n.previousSize=e.size}t(n);const l=e[r].apply(e,s),c={method:r,result:l,args:s,context:n,target:e,...a};return o(c),l};for(const e of r)mapMutableMethods.includes(e)&&(s[e]=createWrappedMethod(e));return Object.defineProperty(s,"target",{get:()=>e,enumerable:!1,configurable:!1}),s},utils={getDataType:getDataType,requireTypes:requireTypes,deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,wrapArrayMethods:wrapArrayMethods,arrayMutableMethods:arrayMutableMethods,setMutableMethods:setMutableMethods,mapMutableMethods:mapMutableMethods,wrapSetMethods:wrapSetMethods,wrapMapMethods:wrapMapMethods,getUniqueId:getUniqueId};export{utils as default};