@codady/utils 0.0.5 → 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:39:9
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.4
+ * @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,19 +102,19 @@ const deepCloneToJSON = (data) => {
     }
 };
 
-const mutateMethods = [
+const mutableMethods = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
 
-const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList }) => {
+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 = mutateMethods;
+        allowList = mutableMethods;
     }
     if (!allowList?.includes(method)) {
         throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
@@ -158,18 +158,20 @@ 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;
 };
 
 const requireTypes = (data, require, cb) => {
@@ -208,7 +210,7 @@ const utils = {
     deepClone,
     deepCloneToJSON,
     mutateArray,
-    mutateMethods
+    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:39:9
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.4
+ * @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,19 +100,19 @@ const deepCloneToJSON = (data) => {
     }
 };
 
-const mutateMethods = [
+const mutableMethods = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
 
-const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList }) => {
+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 = mutateMethods;
+        allowList = mutableMethods;
     }
     if (!allowList?.includes(method)) {
         throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
@@ -156,18 +156,20 @@ 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;
 };
 
 const requireTypes = (data, require, cb) => {
@@ -206,7 +208,7 @@ const utils = {
     deepClone,
     deepCloneToJSON,
     mutateArray,
-    mutateMethods
+    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:39:9
+ * @since Last modified: 2025-12-19 9:4:44
  * @name Utils for web front-end.
- * @version 0.0.4
+ * @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,19 +106,19 @@
         }
     };
 
-    const mutateMethods = [
+    const mutableMethods = [
         'push', 'pop', 'shift', 'unshift', 'splice',
         'sort', 'reverse', 'copyWithin', 'fill'
     ];
 
-    const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList }) => {
+    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 = mutateMethods;
+            allowList = mutableMethods;
         }
         if (!allowList?.includes(method)) {
             throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
@@ -162,18 +162,20 @@
                 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;
     };
 
     const requireTypes = (data, require, cb) => {
@@ -212,7 +214,7 @@
         deepClone,
         deepCloneToJSON,
         mutateArray,
-        mutateMethods
+        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.5",
+  "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/{mutateMethods.js → mutableMethods.js}

@@ -1,5 +1,5 @@
-const mutateMethods = [
+const mutableMethods = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
-export default mutateMethods;
+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 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
@@ -30,15 +30,15 @@
  * // The patch callback logs the mutation details including deleted items and added items.
  */
 'use strict';
-import mutateMethods from "./mutateMethods";
-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 = mutateMethods;
+        allowList = mutableMethods;
     }
     if (!allowList?.includes(method)) {
         throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
@@ -82,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;