@codady/utils 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All changes to Utils including new features, updates, and removals are documented here.
 
+## [v0.0.6] - 2025-12-19
+
+### Distribution Files
+- **JS**: https://unpkg.com/@codady/utils@0.0.6/dist/js/utils.js
+- **Zip**: https://unpkg.com/@codady/utils@0.0.6/dist.zip
+
+### Changes
+
+#### Fixed
+- Some problems.
+
+#### Added
+- The `mutateMethods` variable has been renamed to `mutableMethods`.`mutateMethods`变量改名为`mutableMethods`。
+- Added `props` parameter to `mutateArray`.mutateArray新增参数props。
+- The `method` parameter in `onAfterMutate` callback of `mutateArray` has been renamed to `key`, and `result` renamed to `value`.mutateArray的onAfterMutate的参数method改名为key，result改名为value。
+
+
+#### Removed
+- Null
+
+
 ## [v0.0.3] - 2025-12-18
 
 ### Distribution Files

package/dist/utils.cjs.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.6
  * @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}
@@ -102,6 +102,78 @@ const deepCloneToJSON = (data) => {
     }
 };
 
+const mutableMethods = [
+    'push', 'pop', 'shift', 'unshift', 'splice',
+    'sort', 'reverse', 'copyWithin', 'fill'
+];
+
+const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
+    // Validation: Ensure target is an array and method is allowed
+    if (!Array.isArray(target)) {
+        throw new TypeError("The 'target' parameter must be an array.");
+    }
+    //使用默认
+    if (!allowList || allowList?.length) {
+        allowList = mutableMethods;
+    }
+    if (!allowList?.includes(method)) {
+        throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
+    }
+    const context = {}, len = target.length;
+    // Capture "Pre-mutation" context for Undo/Redo/Tracking purposes
+    switch (method) {
+        // 'push' and 'unshift' are add operations, in undo/redo, 
+        // we can determine the original data structure from result.length and args.length
+        // but methods that involve deletion need to record the deleted items to ensure the patch can restore the data structure during undo
+        case 'push':
+        case 'unshift':
+            context.addedItems = [...args];
+            break;
+        case 'pop':
+            context.poppedValue = target[len - 1];
+            break;
+        case 'shift':
+            context.shiftedValue = target[0];
+            break;
+        case 'splice':
+            const [s, d] = args, 
+            // Calculate actual start index (handling negative values)
+            start = s < 0 ? Math.max(len + s, 0) : Math.min(s, len), 
+            // Handle deleteCount defaults
+            deleteCount = d === undefined ? len - start : d;
+            context.deletedItems = target.slice(start, start + deleteCount);
+            break;
+        case 'sort':
+        case 'reverse':
+            // These methods reorder the whole array; requires a full shallow copy
+            context.oldSnapshot = [...target];
+            break;
+        case 'fill':
+        case 'copyWithin':
+            const startIdx = args[1] || 0, endIdx = args[2] === undefined ? len : args[2];
+            // Overwritten values
+            context.oldItems = target.slice(startIdx, endIdx);
+            context.start = startIdx;
+            context.end = endIdx;
+            break;
+    }
+    // Execute the "onBeforeMutate" callback before mutation
+    onBeforeMutate?.(context);
+    // Execute the native array mutation
+    const value = Array.prototype[method].apply(target, args), patch = {
+        value,
+        key: method,
+        args,
+        context,
+        target,
+        timestamp: Date.now(),
+        ...props
+    };
+    // Construct and trigger the patch callback
+    onAfterMutate?.(patch);
+    return value;
+};
+
 const requireTypes = (data, require, cb) => {
     // Normalize the input types (convert to array if it's a single type)
     let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -136,7 +208,9 @@ const utils = {
     //renderTpl,
     //parseStr,
     deepClone,
-    deepCloneToJSON
+    deepCloneToJSON,
+    mutateArray,
+    mutableMethods
 };
 
 module.exports = utils;

package/dist/utils.cjs.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.6
  * @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
  */
-"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=>{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},requireTypes=(e,t,r)=>{let o=Array.isArray(t)?t:[t],n=getDataType(e),s=n.toLowerCase(),p=o.map(e=>e.toLowerCase()),l=s.includes("html")?"element":s;if(r)try{if(!p.includes(l))throw new TypeError(`Expected data type(s): [${p.join(", ")}], but got: ${l}`)}catch(e){r(e,n)}else if(!p.includes(l))throw new TypeError(`Expected data type(s): [${p.join(", ")}], but got: ${l}`);return n},utils={getDataType:getDataType,requireTypes:requireTypes,deepClone:deepClone,deepCloneToJSON:deepCloneToJSON};module.exports=utils;
+"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=>{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"],mutateArray=({target:e,method:t,args:r=[],onBeforeMutate:o=()=>{},onAfterMutate:a=()=>{},allowList:s,props:n={}})=>{if(!Array.isArray(e))throw new TypeError("The 'target' parameter must be an array.");if(s&&!s?.length||(s=mutableMethods),!s?.includes(t))throw new Error(`Method "${t}" is not in the allowList or is not a mutation method.`);const i={},l=e.length;switch(t){case"push":case"unshift":i.addedItems=[...r];break;case"pop":i.poppedValue=e[l-1];break;case"shift":i.shiftedValue=e[0];break;case"splice":const[t,o]=r,a=t<0?Math.max(l+t,0):Math.min(t,l),s=void 0===o?l-a:o;i.deletedItems=e.slice(a,a+s);break;case"sort":case"reverse":i.oldSnapshot=[...e];break;case"fill":case"copyWithin":const n=r[1]||0,p=void 0===r[2]?l:r[2];i.oldItems=e.slice(n,p),i.start=n,i.end=p}o?.(i);const p=Array.prototype[t].apply(e,r),c={value:p,key:t,args:r,context:i,target:e,timestamp:Date.now(),...n};return a?.(c),p},requireTypes=(e,t,r)=>{let o=Array.isArray(t)?t:[t],a=getDataType(e),s=a.toLowerCase(),n=o.map(e=>e.toLowerCase()),i=s.includes("html")?"element":s;if(r)try{if(!n.includes(i))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${i}`)}catch(e){r(e,a)}else if(!n.includes(i))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${i}`);return a},utils={getDataType:getDataType,requireTypes:requireTypes,deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,mutateArray:mutateArray,mutableMethods:mutableMethods};module.exports=utils;

package/dist/utils.esm.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.6
  * @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}
@@ -100,6 +100,78 @@ const deepCloneToJSON = (data) => {
     }
 };
 
+const mutableMethods = [
+    'push', 'pop', 'shift', 'unshift', 'splice',
+    'sort', 'reverse', 'copyWithin', 'fill'
+];
+
+const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
+    // Validation: Ensure target is an array and method is allowed
+    if (!Array.isArray(target)) {
+        throw new TypeError("The 'target' parameter must be an array.");
+    }
+    //使用默认
+    if (!allowList || allowList?.length) {
+        allowList = mutableMethods;
+    }
+    if (!allowList?.includes(method)) {
+        throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
+    }
+    const context = {}, len = target.length;
+    // Capture "Pre-mutation" context for Undo/Redo/Tracking purposes
+    switch (method) {
+        // 'push' and 'unshift' are add operations, in undo/redo, 
+        // we can determine the original data structure from result.length and args.length
+        // but methods that involve deletion need to record the deleted items to ensure the patch can restore the data structure during undo
+        case 'push':
+        case 'unshift':
+            context.addedItems = [...args];
+            break;
+        case 'pop':
+            context.poppedValue = target[len - 1];
+            break;
+        case 'shift':
+            context.shiftedValue = target[0];
+            break;
+        case 'splice':
+            const [s, d] = args, 
+            // Calculate actual start index (handling negative values)
+            start = s < 0 ? Math.max(len + s, 0) : Math.min(s, len), 
+            // Handle deleteCount defaults
+            deleteCount = d === undefined ? len - start : d;
+            context.deletedItems = target.slice(start, start + deleteCount);
+            break;
+        case 'sort':
+        case 'reverse':
+            // These methods reorder the whole array; requires a full shallow copy
+            context.oldSnapshot = [...target];
+            break;
+        case 'fill':
+        case 'copyWithin':
+            const startIdx = args[1] || 0, endIdx = args[2] === undefined ? len : args[2];
+            // Overwritten values
+            context.oldItems = target.slice(startIdx, endIdx);
+            context.start = startIdx;
+            context.end = endIdx;
+            break;
+    }
+    // Execute the "onBeforeMutate" callback before mutation
+    onBeforeMutate?.(context);
+    // Execute the native array mutation
+    const value = Array.prototype[method].apply(target, args), patch = {
+        value,
+        key: method,
+        args,
+        context,
+        target,
+        timestamp: Date.now(),
+        ...props
+    };
+    // Construct and trigger the patch callback
+    onAfterMutate?.(patch);
+    return value;
+};
+
 const requireTypes = (data, require, cb) => {
     // Normalize the input types (convert to array if it's a single type)
     let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -134,7 +206,9 @@ const utils = {
     //renderTpl,
     //parseStr,
     deepClone,
-    deepCloneToJSON
+    deepCloneToJSON,
+    mutateArray,
+    mutableMethods
 };
 
 export { utils as default };

package/dist/utils.esm.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.6
  * @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},requireTypes=(e,t,r)=>{let o=Array.isArray(t)?t:[t],n=getDataType(e),p=n.toLowerCase(),s=o.map(e=>e.toLowerCase()),l=p.includes("html")?"element":p;if(r)try{if(!s.includes(l))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${l}`)}catch(e){r(e,n)}else if(!s.includes(l))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${l}`);return n},utils={getDataType:getDataType,requireTypes:requireTypes,deepClone:deepClone,deepCloneToJSON:deepCloneToJSON};export{utils as default};
+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"],mutateArray=({target:e,method:t,args:r=[],onBeforeMutate:o=()=>{},onAfterMutate:a=()=>{},allowList:s,props:n={}})=>{if(!Array.isArray(e))throw new TypeError("The 'target' parameter must be an array.");if(s&&!s?.length||(s=mutableMethods),!s?.includes(t))throw new Error(`Method "${t}" is not in the allowList or is not a mutation method.`);const i={},l=e.length;switch(t){case"push":case"unshift":i.addedItems=[...r];break;case"pop":i.poppedValue=e[l-1];break;case"shift":i.shiftedValue=e[0];break;case"splice":const[t,o]=r,a=t<0?Math.max(l+t,0):Math.min(t,l),s=void 0===o?l-a:o;i.deletedItems=e.slice(a,a+s);break;case"sort":case"reverse":i.oldSnapshot=[...e];break;case"fill":case"copyWithin":const n=r[1]||0,p=void 0===r[2]?l:r[2];i.oldItems=e.slice(n,p),i.start=n,i.end=p}o?.(i);const p=Array.prototype[t].apply(e,r),c={value:p,key:t,args:r,context:i,target:e,timestamp:Date.now(),...n};return a?.(c),p},requireTypes=(e,t,r)=>{let o=Array.isArray(t)?t:[t],a=getDataType(e),s=a.toLowerCase(),n=o.map(e=>e.toLowerCase()),i=s.includes("html")?"element":s;if(r)try{if(!n.includes(i))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${i}`)}catch(e){r(e,a)}else if(!n.includes(i))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${i}`);return a},utils={getDataType:getDataType,requireTypes:requireTypes,deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,mutateArray:mutateArray,mutableMethods:mutableMethods};export{utils as default};

package/dist/utils.umd.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.6
  * @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}
@@ -106,6 +106,78 @@
         }
     };
 
+    const mutableMethods = [
+        'push', 'pop', 'shift', 'unshift', 'splice',
+        'sort', 'reverse', 'copyWithin', 'fill'
+    ];
+
+    const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
+        // Validation: Ensure target is an array and method is allowed
+        if (!Array.isArray(target)) {
+            throw new TypeError("The 'target' parameter must be an array.");
+        }
+        //使用默认
+        if (!allowList || allowList?.length) {
+            allowList = mutableMethods;
+        }
+        if (!allowList?.includes(method)) {
+            throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
+        }
+        const context = {}, len = target.length;
+        // Capture "Pre-mutation" context for Undo/Redo/Tracking purposes
+        switch (method) {
+            // 'push' and 'unshift' are add operations, in undo/redo, 
+            // we can determine the original data structure from result.length and args.length
+            // but methods that involve deletion need to record the deleted items to ensure the patch can restore the data structure during undo
+            case 'push':
+            case 'unshift':
+                context.addedItems = [...args];
+                break;
+            case 'pop':
+                context.poppedValue = target[len - 1];
+                break;
+            case 'shift':
+                context.shiftedValue = target[0];
+                break;
+            case 'splice':
+                const [s, d] = args, 
+                // Calculate actual start index (handling negative values)
+                start = s < 0 ? Math.max(len + s, 0) : Math.min(s, len), 
+                // Handle deleteCount defaults
+                deleteCount = d === undefined ? len - start : d;
+                context.deletedItems = target.slice(start, start + deleteCount);
+                break;
+            case 'sort':
+            case 'reverse':
+                // These methods reorder the whole array; requires a full shallow copy
+                context.oldSnapshot = [...target];
+                break;
+            case 'fill':
+            case 'copyWithin':
+                const startIdx = args[1] || 0, endIdx = args[2] === undefined ? len : args[2];
+                // Overwritten values
+                context.oldItems = target.slice(startIdx, endIdx);
+                context.start = startIdx;
+                context.end = endIdx;
+                break;
+        }
+        // Execute the "onBeforeMutate" callback before mutation
+        onBeforeMutate?.(context);
+        // Execute the native array mutation
+        const value = Array.prototype[method].apply(target, args), patch = {
+            value,
+            key: method,
+            args,
+            context,
+            target,
+            timestamp: Date.now(),
+            ...props
+        };
+        // Construct and trigger the patch callback
+        onAfterMutate?.(patch);
+        return value;
+    };
+
     const requireTypes = (data, require, cb) => {
         // Normalize the input types (convert to array if it's a single type)
         let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -140,7 +212,9 @@
         //renderTpl,
         //parseStr,
         deepClone,
-        deepCloneToJSON
+        deepCloneToJSON,
+        mutateArray,
+        mutableMethods
     };
 
     return utils;

package/dist/utils.umd.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.6
  * @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=>{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};return{getDataType:getDataType,requireTypes:(e,t,r)=>{let o=Array.isArray(t)?t:[t],n=getDataType(e),i=n.toLowerCase(),s=o.map(e=>e.toLowerCase()),c=i.includes("html")?"element":i;if(r)try{if(!s.includes(c))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${c}`)}catch(e){r(e,n)}else if(!s.includes(c))throw new TypeError(`Expected data type(s): [${s.join(", ")}], but got: ${c}`);return n},deepClone:deepClone,deepCloneToJSON:deepCloneToJSON}});
+!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=>{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},e=["push","pop","shift","unshift","splice","sort","reverse","copyWithin","fill"];return{getDataType:getDataType,requireTypes:(e,t,r)=>{let o=Array.isArray(t)?t:[t],s=getDataType(e),n=s.toLowerCase(),a=o.map(e=>e.toLowerCase()),i=n.includes("html")?"element":n;if(r)try{if(!a.includes(i))throw new TypeError(`Expected data type(s): [${a.join(", ")}], but got: ${i}`)}catch(e){r(e,s)}else if(!a.includes(i))throw new TypeError(`Expected data type(s): [${a.join(", ")}], but got: ${i}`);return s},deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,mutateArray:({target:t,method:r,args:o=[],onBeforeMutate:s=()=>{},onAfterMutate:n=()=>{},allowList:a,props:i={}})=>{if(!Array.isArray(t))throw new TypeError("The 'target' parameter must be an array.");if(a&&!a?.length||(a=e),!a?.includes(r))throw new Error(`Method "${r}" is not in the allowList or is not a mutation method.`);const c={},l=t.length;switch(r){case"push":case"unshift":c.addedItems=[...o];break;case"pop":c.poppedValue=t[l-1];break;case"shift":c.shiftedValue=t[0];break;case"splice":const[e,r]=o,s=e<0?Math.max(l+e,0):Math.min(e,l),n=void 0===r?l-s:r;c.deletedItems=t.slice(s,s+n);break;case"sort":case"reverse":c.oldSnapshot=[...t];break;case"fill":case"copyWithin":const a=o[1]||0,i=void 0===o[2]?l:o[2];c.oldItems=t.slice(a,i),c.start=a,c.end=i}s?.(c);const p=Array.prototype[r].apply(t,o),u={value:p,key:r,args:o,context:c,target:t,timestamp:Date.now(),...i};return n?.(u),p},mutableMethods:e}});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codady/utils",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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/mutableMethods.js

@@ -0,0 +1,5 @@
+const mutableMethods = [
+    'push', 'pop', 'shift', 'unshift', 'splice',
+    'sort', 'reverse', 'copyWithin', 'fill'
+];
+export default mutableMethods;

package/src/{mutateMethods.ts → mutableMethods.ts}

@@ -1,15 +1,15 @@
 /**
- * @since Last modified: 2025/12/18 21:04:34
+ * @since Last modified: 2025/12/19 08:59:38
  * A list of supported array mutation methods.
  * These methods are commonly used to modify the contents of an array.
  * These methods can be tracked and handled in various use cases, such as undo/redo functionality,
  * or when applying certain transformations to arrays.
  * 
  */
-export type mutateMethods = ('push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'sort' | 'reverse' | 'copyWithin' | 'fill')[];
-const mutateMethods: mutateMethods = [
+export type mutableMethods = ('push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'sort' | 'reverse' | 'copyWithin' | 'fill')[];
+const mutableMethods: mutableMethods = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
 
-export default mutateMethods;
+export default mutableMethods;

package/src/mutateArray.js

@@ -1,11 +1,11 @@
 /**
- * @since Last modified: 2025/12/18 20:54:23
+ * @since Last modified: 2025/12/19 09:00:04
  * Mutates an array by applying one of the allowed mutation methods such as push, pop, shift, unshift, splice, etc.
  * Supports tracking of added, removed, and updated items for undo/redo or tracking purposes.
  * The mutation methods that can be tracked include push, pop, shift, unshift, splice, sort, reverse, fill, and copyWithin.
  *
  * @template T
- * @param {MutateOptions} options - Configuration object containing the target array, method to apply, arguments for the method, and an optional patch callback.
+ * @param {MutationOptions} options - Configuration object containing the target array, method to apply, arguments for the method, and an optional patch callback.
  * @returns {any} - The result of the array mutation.
  *
  * @example
@@ -30,17 +30,15 @@
  * // The patch callback logs the mutation details including deleted items and added items.
  */
 'use strict';
-const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList }) => {
+import mutableMethods from "./mutableMethods";
+const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
     // Validation: Ensure target is an array and method is allowed
     if (!Array.isArray(target)) {
         throw new TypeError("The 'target' parameter must be an array.");
     }
     //使用默认
     if (!allowList || allowList?.length) {
-        allowList = [
-            'push', 'pop', 'shift', 'unshift', 'splice',
-            'sort', 'reverse', 'copyWithin', 'fill'
-        ];
+        allowList = mutableMethods;
     }
     if (!allowList?.includes(method)) {
         throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
@@ -84,17 +82,19 @@ const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, on
             break;
     }
     // Execute the "onBeforeMutate" callback before mutation
-    onBeforeMutate && onBeforeMutate(context);
+    onBeforeMutate?.(context);
     // Execute the native array mutation
-    const result = Array.prototype[method].apply(target, args);
-    // Construct and trigger the patch callback
-    onAfterMutate && onAfterMutate({
-        method,
+    const value = Array.prototype[method].apply(target, args), patch = {
+        value,
+        key: method,
         args,
         context,
-        result,
-        timestamp: Date.now()
-    });
-    return result;
+        target,
+        timestamp: Date.now(),
+        ...props
+    };
+    // Construct and trigger the patch callback
+    onAfterMutate?.(patch);
+    return value;
 };
 export default mutateArray;

package/src/mutateArray.ts

@@ -1,11 +1,11 @@
 /**
- * @since Last modified: 2025/12/18 21:20:26
+ * @since Last modified: 2025/12/19 09:00:04
  * Mutates an array by applying one of the allowed mutation methods such as push, pop, shift, unshift, splice, etc.
  * Supports tracking of added, removed, and updated items for undo/redo or tracking purposes.
  * The mutation methods that can be tracked include push, pop, shift, unshift, splice, sort, reverse, fill, and copyWithin.
  * 
  * @template T
- * @param {MutateOptions} options - Configuration object containing the target array, method to apply, arguments for the method, and an optional patch callback.
+ * @param {MutationOptions} options - Configuration object containing the target array, method to apply, arguments for the method, and an optional patch callback.
  * @returns {any} - The result of the array mutation.
  * 
  * @example
@@ -31,13 +31,13 @@
  */
 'use strict';
 
-import mutateMethods from "./mutateMethods";
+import mutableMethods from "./mutableMethods";
 
 
 /**
  * Defines the structure of the captured state before mutation.
  */
-export interface MutateContext {
+export interface MutationContextt {
     addedItems?: any[];      // Items added to the array
     poppedValue?: any;       // Value popped from the array
     shiftedValue?: any;      // Value shifted from the array
@@ -51,24 +51,27 @@ export interface MutateContext {
 /**
  * The data object passed to the callback after mutation.
  */
-export interface MutatePatch {
-    method: string;    // The mutation method (e.g., 'push', 'pop', 'splice', etc.)
+export interface MutationPatch<T = any> {
+    key: string;    // The mutation method (e.g., 'push', 'pop', 'splice', etc.)
+    value: any;       // The result of the mutation (the modified array)
     args: any[];       // Arguments passed to the mutation method
-    context: MutateContext;  // The state before mutation
-    result: any;       // The result of the mutation (the modified array)
+    context: MutationContextt;  // The state before mutation
+    target: T[];             // Reference to the mutated array
     timestamp: number; // The timestamp of the mutation
+    [key: string]: any;      // Additional properties from props
 }
 
 /**
  * Configuration options for the mutateArray function.
  */
-export interface MutateOptions {
+export interface MutationOptions {
     target: any[];      // The array to mutate
     method: string;     // The mutation method to apply (e.g., 'push', 'splice', etc.)
     args?: any[];       // Optional arguments to pass to the mutation method
-    onBeforeMutate?: (context: MutateContext) => void;  // Callback triggered before the mutation
-    onAfterMutate?: (patch: MutatePatch) => void;  // Callback triggered after the mutation
+    onBeforeMutate?: (context: MutationContextt) => void;  // Callback triggered before the mutation
+    onAfterMutate?: (patch: MutationPatch) => void;  // Callback triggered after the mutation
     allowList?: string[];  // Optional list of allowed mutation methods
+    props?: Record<string, any>;  // Additional properties to attach to the patch
 }
 
 const mutateArray = ({
@@ -77,8 +80,9 @@ const mutateArray = ({
     args = [],
     onBeforeMutate = () => { },
     onAfterMutate = () => { },
-    allowList
-}: MutateOptions): any => {
+    allowList,
+    props = {},
+}: MutationOptions): any => {
 
     // Validation: Ensure target is an array and method is allowed
     if (!Array.isArray(target)) {
@@ -86,13 +90,13 @@ const mutateArray = ({
     }
     //使用默认
     if (!allowList || allowList?.length) {
-        allowList = mutateMethods;
+        allowList = mutableMethods;
     }
     if (!allowList?.includes(method)) {
         throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
     }
 
-    const context: MutateContext = {},
+    const context: MutationContextt = {},
         len = target.length;
 
     // Capture "Pre-mutation" context for Undo/Redo/Tracking purposes
@@ -135,21 +139,24 @@ const mutateArray = ({
     }
 
     // Execute the "onBeforeMutate" callback before mutation
-    onBeforeMutate && onBeforeMutate(context);
+    onBeforeMutate?.(context);
 
     // Execute the native array mutation
-    const result = (Array.prototype as any)[method].apply(target, args);
+    const value = (Array.prototype as any)[method].apply(target, args),
+        patch: MutationPatch = {
+            value,
+            key: method,
+            args,
+            context,
+            target,
+            timestamp: Date.now(),
+            ...props
+        };
 
     // Construct and trigger the patch callback
-    onAfterMutate && onAfterMutate({
-        method,
-        args,
-        context,
-        result,
-        timestamp: Date.now()
-    });
+    onAfterMutate?.(patch);
 
-    return result;
+    return value;
 }
 
 export default mutateArray;