@codady/utils 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All changes to Utils including new features, updates, and removals are documented here.
 
+
+## [v0.0.7] - 2025-12-19
+
+### Distribution Files
+- **JS**: https://unpkg.com/@codady/utils@0.0.7/dist/js/utils.js
+- **Zip**: https://unpkg.com/@codady/utils@0.0.7/dist.zip
+
+### Changes
+
+#### Fixed
+- Some problems.
+
+#### Added
+- The `mutateArray` function has been renamed to `wrapArrayMethods`.`mutateArray`函数改名为`wrapArrayMethods`。
+
+
+#### Removed
+- Null
+
 ## [v0.0.6] - 2025-12-19
 
 ### Distribution Files

package/dist/utils.cjs.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-19 9:4:44
+ * @since Last modified: 2025-12-19 10:14:9
  * @name Utils for web front-end.
- * @version 0.0.6
+ * @version 0.0.7
  * @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}
@@ -107,7 +107,7 @@ const mutableMethods = [
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
 
-const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
+const wrapArrayMethods = ({ target, 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.");
@@ -116,62 +116,64 @@ const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, on
     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 methods = {};
+    for (let method of allowList) {
+        methods[method] = function (...args) {
+            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,
+                ...props
+            };
+            // Construct and trigger the patch callback
+            onAfterMutate?.(patch);
+            return value;
+        };
+    }
+    return methods;
 };
 
 const requireTypes = (data, require, cb) => {
@@ -209,7 +211,7 @@ const utils = {
     //parseStr,
     deepClone,
     deepCloneToJSON,
-    mutateArray,
+    wrapArrayMethods,
     mutableMethods
 };
 

package/dist/utils.cjs.min.js

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

package/dist/utils.esm.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-19 9:4:44
+ * @since Last modified: 2025-12-19 10:14:9
  * @name Utils for web front-end.
- * @version 0.0.6
+ * @version 0.0.7
  * @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}
@@ -105,7 +105,7 @@ const mutableMethods = [
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
 
-const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
+const wrapArrayMethods = ({ target, 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.");
@@ -114,62 +114,64 @@ const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, on
     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 methods = {};
+    for (let method of allowList) {
+        methods[method] = function (...args) {
+            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,
+                ...props
+            };
+            // Construct and trigger the patch callback
+            onAfterMutate?.(patch);
+            return value;
+        };
+    }
+    return methods;
 };
 
 const requireTypes = (data, require, cb) => {
@@ -207,7 +209,7 @@ const utils = {
     //parseStr,
     deepClone,
     deepCloneToJSON,
-    mutateArray,
+    wrapArrayMethods,
     mutableMethods
 };
 

package/dist/utils.esm.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-19 9:4:44
+ * @since Last modified: 2025-12-19 10:14:9
  * @name Utils for web front-end.
- * @version 0.0.6
+ * @version 0.0.7
  * @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"],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};
+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 s={};for(let n of o)s[n]=function(...o){const s={},p=e.length;switch(n){case"push":case"unshift":s.addedItems=[...o];break;case"pop":s.poppedValue=e[p-1];break;case"shift":s.shiftedValue=e[0];break;case"splice":const[t,r]=o,a=t<0?Math.max(p+t,0):Math.min(t,p),n=void 0===r?p-a:r;s.deletedItems=e.slice(a,a+n);break;case"sort":case"reverse":s.oldSnapshot=[...e];break;case"fill":case"copyWithin":const l=o[1]||0,i=void 0===o[2]?p:o[2];s.oldItems=e.slice(l,i),s.start=l,s.end=i}t?.(s);const l=Array.prototype[n].apply(e,o),i={value:l,key:n,args:o,context:s,target:e,...a};return r?.(i),l};return s},requireTypes=(e,t,r)=>{let o=Array.isArray(t)?t:[t],a=getDataType(e),s=a.toLowerCase(),n=o.map(e=>e.toLowerCase()),p=s.includes("html")?"element":s;if(r)try{if(!n.includes(p))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${p}`)}catch(e){r(e,a)}else if(!n.includes(p))throw new TypeError(`Expected data type(s): [${n.join(", ")}], but got: ${p}`);return a},utils={getDataType:getDataType,requireTypes:requireTypes,deepClone:deepClone,deepCloneToJSON:deepCloneToJSON,wrapArrayMethods:wrapArrayMethods,mutableMethods:mutableMethods};export{utils as default};

package/dist/utils.umd.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-19 9:4:44
+ * @since Last modified: 2025-12-19 10:14:9
  * @name Utils for web front-end.
- * @version 0.0.6
+ * @version 0.0.7
  * @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}
@@ -111,7 +111,7 @@
         'sort', 'reverse', 'copyWithin', 'fill'
     ];
 
-    const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
+    const wrapArrayMethods = ({ target, 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.");
@@ -120,62 +120,64 @@
         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 methods = {};
+        for (let method of allowList) {
+            methods[method] = function (...args) {
+                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,
+                    ...props
+                };
+                // Construct and trigger the patch callback
+                onAfterMutate?.(patch);
+                return value;
+            };
+        }
+        return methods;
     };
 
     const requireTypes = (data, require, cb) => {
@@ -213,7 +215,7 @@
         //parseStr,
         deepClone,
         deepCloneToJSON,
-        mutateArray,
+        wrapArrayMethods,
         mutableMethods
     };
 

package/dist/utils.umd.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-19 9:4:44
+ * @since Last modified: 2025-12-19 10:14:9
  * @name Utils for web front-end.
- * @version 0.0.6
+ * @version 0.0.7
  * @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},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}});
+!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,wrapArrayMethods:({target:t,onBeforeMutate:r=()=>{},onAfterMutate:o=()=>{},allowList:s,props:n={}})=>{if(!Array.isArray(t))throw new TypeError("The 'target' parameter must be an array.");s&&!s?.length||(s=e);const a={};for(let e of s)a[e]=function(...s){const a={},i=t.length;switch(e){case"push":case"unshift":a.addedItems=[...s];break;case"pop":a.poppedValue=t[i-1];break;case"shift":a.shiftedValue=t[0];break;case"splice":const[e,r]=s,o=e<0?Math.max(i+e,0):Math.min(e,i),n=void 0===r?i-o:r;a.deletedItems=t.slice(o,o+n);break;case"sort":case"reverse":a.oldSnapshot=[...t];break;case"fill":case"copyWithin":const c=s[1]||0,l=void 0===s[2]?i:s[2];a.oldItems=t.slice(c,l),a.start=c,a.end=l}r?.(a);const c=Array.prototype[e].apply(t,s),l={value:c,key:e,args:s,context:a,target:t,...n};return o?.(l),c};return a},mutableMethods:e}});

package/package.json

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

@@ -1,13 +1,13 @@
 /**
- * @since Last modified: 2025/12/19 08:59:38
+ * @since Last modified: 2025/12/19 10:06:07
  * 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 mutableMethods = ('push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'sort' | 'reverse' | 'copyWithin' | 'fill')[];
-const mutableMethods: mutableMethods = [
+export type ArrayMutationNames = ('push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'sort' | 'reverse' | 'copyWithin' | 'fill')[];
+const mutableMethods: ArrayMutationNames = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];

package/src/wrapArrayMethods.js

@@ -0,0 +1,90 @@
+/**
+ * @since Last modified: 2025/12/19 10:14:03
+ * 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 - Array element type
+ * @param {MutationOptions<T>} options - Configuration object containing the target array and callbacks.
+ * @returns {ArrayMutationMethods<T>} - An object containing all mutable array methods bound to the target.
+ *
+ * @example
+ * // 获取方法对象后调用
+ * const arr = [1, 2, 3];
+ * const methods = mutateArray({
+ *   target: arr,
+ *   onAfterMutate: (patch) => { console.log(patch); }
+ * });
+ * methods.push(4); // arr is now [1, 2, 3, 4]
+ */
+'use strict';
+import mutableMethods from "./mutableMethods";
+const wrapArrayMethods = ({ target, 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;
+    }
+    const methods = {};
+    for (let method of allowList) {
+        methods[method] = function (...args) {
+            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,
+                ...props
+            };
+            // Construct and trigger the patch callback
+            onAfterMutate?.(patch);
+            return value;
+        };
+    }
+    return methods;
+};
+export default wrapArrayMethods;

package/src/wrapArrayMethods.ts

@@ -0,0 +1,164 @@
+/**
+ * @since Last modified: 2025/12/19 10:14:03
+ * 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 - Array element type
+ * @param {MutationOptions<T>} options - Configuration object containing the target array and callbacks.
+ * @returns {ArrayMutationMethods<T>} - An object containing all mutable array methods bound to the target.
+ * 
+ * @example
+ * // 获取方法对象后调用
+ * const arr = [1, 2, 3];
+ * const methods = mutateArray({
+ *   target: arr,
+ *   onAfterMutate: (patch) => { console.log(patch); }
+ * });
+ * methods.push(4); // arr is now [1, 2, 3, 4]
+ */
+'use strict';
+
+import mutableMethods, { ArrayMutationNames } from "./mutableMethods";
+
+
+/**
+ * Defines the structure of the captured state before mutation.
+ */
+export interface MutationContextt {
+    addedItems?: any[];      // Items added to the array
+    poppedValue?: any;       // Value popped from the array
+    shiftedValue?: any;      // Value shifted from the array
+    deletedItems?: any[];    // Items removed from the array
+    oldSnapshot?: any[];     // Snapshot of the array before methods like 'sort' or 'reverse'
+    oldItems?: any[];        // Items overwritten (for methods like 'fill' or 'copyWithin')
+    start?: number;          // Starting index for mutations like 'fill' or 'splice'
+    end?: number;            // Ending index for mutations like 'fill' or 'splice'
+}
+
+/**
+ * The data object passed to the callback after mutation.
+ */
+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: MutationContextt;  // The state before mutation
+    target: T[];             // Reference to the mutated array
+    [key: string]: any;      // Additional properties from props
+}
+/**
+ * The return type of wrapArrayMethods - an object containing all mutable array methods
+ */
+export interface ArrayMutationMethods<T = any> {
+    push: (...args: any[]) => number;
+    pop: () => T | undefined;
+    shift: () => T | undefined;
+    unshift: (...args: T[]) => number;
+    splice: (start: number, deleteCount?: number, ...items: T[]) => T[];
+    sort: (compareFn?: (a: T, b: T) => number) => T[];
+    reverse: () => T[];
+    fill: (value: T, start?: number, end?: number) => T[];
+    copyWithin: (target: number, start: number, end?: number) => T[];
+}
+/**
+ * Configuration options for the wrapArrayMethods function.
+ */
+export interface MutationOptions<T = any> {
+    target: T[];      // The array to mutate
+    onBeforeMutate?: (context: MutationContextt) => void;  // Callback triggered before the mutation
+    onAfterMutate?: (patch: MutationPatch) => void;  // Callback triggered after the mutation
+    allowList?: ArrayMutationNames;  // Optional list of allowed mutation methods
+    props?: Record<string, any>;  // Additional properties to attach to the patch
+}
+
+
+const wrapArrayMethods = <T = any>({
+    target,
+    onBeforeMutate = () => { },
+    onAfterMutate = () => { },
+    allowList,
+    props = {},
+}: MutationOptions<T>): ArrayMutationMethods<T> => {
+
+    // 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;
+    }
+
+    const methods: Partial<ArrayMutationMethods<T>> = {};
+
+    for (let method of allowList) {
+        
+        methods[method as keyof ArrayMutationMethods<T>]  = function (...args: any) {
+
+            const context: MutationContextt = {},
+                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 as any)[method].apply(target, args),
+                patch: MutationPatch<T> = {
+                    value,
+                    key: method,
+                    args,
+                    context,
+                    target,
+                    ...props
+                };
+
+            // Construct and trigger the patch callback
+            onAfterMutate?.(patch);
+            return value;
+        }
+    }
+
+    return methods as ArrayMutationMethods<T>;
+}
+
+export default wrapArrayMethods;

package/src/mutateArray.js

@@ -1,100 +0,0 @@
-/**
- * @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 {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
- * const arr = [1, 2, 3];
- * mutateArray({
- *   target: arr,
- *   method: 'push',
- *   args: [4],
- *   onPatch: (patch) => { console.log(patch); }
- * });
- * // arr is now [1, 2, 3, 4]
- *
- * @example
- * const arr = [1, 2, 3];
- * mutateArray({
- *   target: arr,
- *   method: 'splice',
- *   args: [1, 1, 4],
- *   onPatch: (patch) => { console.log(patch); }
- * });
- * // arr is now [1, 4, 3]
- * // The patch callback logs the mutation details including deleted items and added items.
- */
-'use strict';
-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 = 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;
-};
-export default mutateArray;

package/src/mutateArray.ts

@@ -1,162 +0,0 @@
-/**
- * @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 {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
- * const arr = [1, 2, 3];
- * mutateArray({
- *   target: arr,
- *   method: 'push',
- *   args: [4],
- *   onPatch: (patch) => { console.log(patch); }
- * });
- * // arr is now [1, 2, 3, 4]
- * 
- * @example
- * const arr = [1, 2, 3];
- * mutateArray({
- *   target: arr,
- *   method: 'splice',
- *   args: [1, 1, 4],
- *   onPatch: (patch) => { console.log(patch); }
- * });
- * // arr is now [1, 4, 3]
- * // The patch callback logs the mutation details including deleted items and added items.
- */
-'use strict';
-
-import mutableMethods from "./mutableMethods";
-
-
-/**
- * Defines the structure of the captured state before mutation.
- */
-export interface MutationContextt {
-    addedItems?: any[];      // Items added to the array
-    poppedValue?: any;       // Value popped from the array
-    shiftedValue?: any;      // Value shifted from the array
-    deletedItems?: any[];    // Items removed from the array
-    oldSnapshot?: any[];     // Snapshot of the array before methods like 'sort' or 'reverse'
-    oldItems?: any[];        // Items overwritten (for methods like 'fill' or 'copyWithin')
-    start?: number;          // Starting index for mutations like 'fill' or 'splice'
-    end?: number;            // Ending index for mutations like 'fill' or 'splice'
-}
-
-/**
- * The data object passed to the callback after mutation.
- */
-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: 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 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: 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 = ({
-    target,
-    method,
-    args = [],
-    onBeforeMutate = () => { },
-    onAfterMutate = () => { },
-    allowList,
-    props = {},
-}: MutationOptions): any => {
-
-    // 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: MutationContextt = {},
-        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 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?.(patch);
-
-    return value;
-}
-
-export default mutateArray;