@codady/utils 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 All changes to Utils including new features, updates, and removals are documented here.
 
+## [v0.0.3] - 2025-12-18
+
+### Distribution Files
+- **JS**: https://unpkg.com/@codady/utils@0.0.3/dist/js/utils.js
+- **Zip**: https://unpkg.com/@codady/utils@0.0.3/dist.zip
+
+### Changes
+
+#### Fixed
+- Some problems.
+
+#### Added
+- Added the `mutateMethods` variable and `mutateArray` function.新增了mutateMethods变量和mutateArray函数
+- Added the `deepCloneToJSON` function.新增了deepCloneToJSON函数
+
+
+#### Removed
+- Null
+
+
+
+## [v0.0.2] - 2025-12-16
+
+### Distribution Files
+- **JS**: https://unpkg.com/@codady/utils@0.0.2/dist/js/utils.js
+- **Zip**: https://unpkg.com/@codady/utils@0.0.2/dist.zip
+
+### Changes
+
+#### Fixed
+- Some problems.
+
+#### Added
+- Null
+
+#### Removed
+- Null
+
+
+
 ## [v0.0.1] - 2025-12-15
 
 ### Distribution Files

package/dist/utils.cjs.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-16 9:8:6
+ * @since Last modified: 2025-12-18 21:8:4
  * @name Utils for web front-end.
- * @version 0.0.1
+ * @version 0.0.2
  * @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}
@@ -74,6 +74,34 @@ const deepClone = (data) => {
     }
 };
 
+const deepCloneToJSON = (data) => {
+    const dataType = getDataType(data);
+    // Handle objects
+    if (dataType === 'Object') {
+        const newObj = {};
+        // Clone regular properties
+        for (const key in data) {
+            newObj[key] = deepCloneToJSON(data[key]);
+        }
+        for (const key in newObj) {
+            newObj[key] === undefined && Reflect.deleteProperty(newObj, key);
+        }
+        return newObj;
+        // Handle arrays
+    }
+    else if (dataType === 'Array') {
+        let tmp = data.map((item, index) => deepCloneToJSON(item)).filter(item => item !== undefined);
+        return tmp;
+        // Handle Date objects
+    }
+    else if (!['Number', 'String', 'Boolean', 'Null'].includes(dataType)) {
+        return undefined;
+    }
+    else {
+        return data;
+    }
+};
+
 const requireTypes = (data, require, cb) => {
     // Normalize the input types (convert to array if it's a single type)
     let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -108,6 +136,7 @@ const utils = {
     //renderTpl,
     //parseStr,
     deepClone,
+    deepCloneToJSON
 };
 
 module.exports = utils;

package/dist/utils.cjs.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-11-15 11:0:34
+ * @since Last modified: 2025-12-18 21:8:4
  * @name Utils for web front-end.
- * @version 1.0.0
+ * @version 0.0.2
  * @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},requireTypes=(e,t,r)=>{let s=getDataType(e).toLowerCase(),o="string"==typeof t?[t]:t;if(s.includes("html")&&(s="element"),o=o.map(e=>e.toLowerCase()),r)try{if(!o.includes(s))throw new Error(`Wrong data type,Require types: "${""+o}"!`)}catch(e){r(e)}else if(!o.includes(s))throw new Error(`Wrong data type,Require types: "${""+o}"!`)};exports.getDataType=getDataType,exports.requireTypes=requireTypes;
+"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;

package/dist/utils.esm.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-16 9:8:6
+ * @since Last modified: 2025-12-18 21:8:4
  * @name Utils for web front-end.
- * @version 0.0.1
+ * @version 0.0.2
  * @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}
@@ -72,6 +72,34 @@ const deepClone = (data) => {
     }
 };
 
+const deepCloneToJSON = (data) => {
+    const dataType = getDataType(data);
+    // Handle objects
+    if (dataType === 'Object') {
+        const newObj = {};
+        // Clone regular properties
+        for (const key in data) {
+            newObj[key] = deepCloneToJSON(data[key]);
+        }
+        for (const key in newObj) {
+            newObj[key] === undefined && Reflect.deleteProperty(newObj, key);
+        }
+        return newObj;
+        // Handle arrays
+    }
+    else if (dataType === 'Array') {
+        let tmp = data.map((item, index) => deepCloneToJSON(item)).filter(item => item !== undefined);
+        return tmp;
+        // Handle Date objects
+    }
+    else if (!['Number', 'String', 'Boolean', 'Null'].includes(dataType)) {
+        return undefined;
+    }
+    else {
+        return data;
+    }
+};
+
 const requireTypes = (data, require, cb) => {
     // Normalize the input types (convert to array if it's a single type)
     let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -106,6 +134,7 @@ const utils = {
     //renderTpl,
     //parseStr,
     deepClone,
+    deepCloneToJSON
 };
 
 export { utils as default };

package/dist/utils.esm.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-11-15 11:0:34
+ * @since Last modified: 2025-12-18 21:8:4
  * @name Utils for web front-end.
- * @version 1.0.0
+ * @version 0.0.2
  * @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},requireTypes=(e,t,r)=>{let o=getDataType(e).toLowerCase(),s="string"==typeof t?[t]:t;if(o.includes("html")&&(o="element"),s=s.map(e=>e.toLowerCase()),r)try{if(!s.includes(o))throw new Error(`Wrong data type,Require types: "${""+s}"!`)}catch(e){r(e)}else if(!s.includes(o))throw new Error(`Wrong data type,Require types: "${""+s}"!`)};export{getDataType,requireTypes};
+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};

package/dist/utils.umd.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-16 9:8:6
+ * @since Last modified: 2025-12-18 21:8:4
  * @name Utils for web front-end.
- * @version 0.0.1
+ * @version 0.0.2
  * @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}
@@ -78,6 +78,34 @@
         }
     };
 
+    const deepCloneToJSON = (data) => {
+        const dataType = getDataType(data);
+        // Handle objects
+        if (dataType === 'Object') {
+            const newObj = {};
+            // Clone regular properties
+            for (const key in data) {
+                newObj[key] = deepCloneToJSON(data[key]);
+            }
+            for (const key in newObj) {
+                newObj[key] === undefined && Reflect.deleteProperty(newObj, key);
+            }
+            return newObj;
+            // Handle arrays
+        }
+        else if (dataType === 'Array') {
+            let tmp = data.map((item, index) => deepCloneToJSON(item)).filter(item => item !== undefined);
+            return tmp;
+            // Handle Date objects
+        }
+        else if (!['Number', 'String', 'Boolean', 'Null'].includes(dataType)) {
+            return undefined;
+        }
+        else {
+            return data;
+        }
+    };
+
     const requireTypes = (data, require, cb) => {
         // Normalize the input types (convert to array if it's a single type)
         let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -112,6 +140,7 @@
         //renderTpl,
         //parseStr,
         deepClone,
+        deepCloneToJSON
     };
 
     return utils;

package/dist/utils.umd.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-11-15 11:0:34
+ * @since Last modified: 2025-12-18 21:8:4
  * @name Utils for web front-end.
- * @version 1.0.0
+ * @version 0.0.2
  * @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?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).utils={})}(this,function(e){"use strict";const getDataType=e=>{let t,o=Object.prototype.toString.call(e).slice(8,-1);return t="Function"===o&&/^\s*class\s+/.test(e.toString())?"Class":"Object"===o&&Object.getPrototypeOf(e)!==Object.prototype?"Instance":o,t};e.getDataType=getDataType,e.requireTypes=(e,t,o)=>{let n=getDataType(e).toLowerCase(),s="string"==typeof t?[t]:t;if(n.includes("html")&&(n="element"),s=s.map(e=>e.toLowerCase()),o)try{if(!s.includes(n))throw new Error(`Wrong data type,Require types: "${""+s}"!`)}catch(e){o(e)}else if(!s.includes(n))throw new Error(`Wrong data type,Require types: "${""+s}"!`)}});
+!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}});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codady/utils",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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/deepClone.js

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/16 09:02:07
+ * @since Last modified: 2025/12/16 13:33:46
  * Deep clone an array or object.
  * Supports Symbol keys. These types are returned directly:
  * Number, String, Boolean, Symbol, HTML*Element, Function, Date, RegExp.

package/src/deepClone.ts

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/16 09:02:07
+ * @since Last modified: 2025/12/16 13:33:46
  * Deep clone an array or object.
  * Supports Symbol keys. These types are returned directly: 
  * Number, String, Boolean, Symbol, HTML*Element, Function, Date, RegExp.

package/src/deepCloneToJSON.js

@@ -0,0 +1,47 @@
+/**
+ * @since Last modified: 2025/12/16 14:43:51
+ * Deep clone an array or object to a JSON-compatible structure.
+ * Converts non-serializable types like functions, symbols, Date, RegExp to plain values.
+ *
+ * @template T
+ * @param {T} data - Array or object to clone
+ * @returns {T} - New object with different memory address, in a JSON-compatible structure
+ *
+ * @example
+ * const obj = { a: '', b: 0, c: [] };
+ * const cloned = deepCloneToJSON(obj);
+ *
+ * @example
+ * const arr = [{}, {}, {}];
+ * const cloned = deepCloneToJSON(arr);
+ */
+'use strict';
+import getDataType from './getDataType';
+const deepCloneToJSON = (data) => {
+    const dataType = getDataType(data);
+    // Handle objects
+    if (dataType === 'Object') {
+        const newObj = {};
+        // Clone regular properties
+        for (const key in data) {
+            newObj[key] = deepCloneToJSON(data[key]);
+        }
+        for (const key in newObj) {
+            newObj[key] === undefined && Reflect.deleteProperty(newObj, key);
+        }
+        return newObj;
+        // Handle arrays
+    }
+    else if (dataType === 'Array') {
+        let tmp = data.map((item, index) => deepCloneToJSON(item)).filter(item => item !== undefined);
+        return tmp;
+        // Handle Date objects
+    }
+    else if (!['Number', 'String', 'Boolean', 'Null'].includes(dataType)) {
+        return undefined;
+    }
+    else {
+        return data;
+    }
+};
+export default deepCloneToJSON;

package/src/deepCloneToJSON.ts

@@ -0,0 +1,52 @@
+/**
+ * @since Last modified: 2025/12/16 14:43:51
+ * Deep clone an array or object to a JSON-compatible structure.
+ * Converts non-serializable types like functions, symbols, Date, RegExp to plain values.
+ * 
+ * @template T
+ * @param {T} data - Array or object to clone
+ * @returns {T} - New object with different memory address, in a JSON-compatible structure
+ * 
+ * @example
+ * const obj = { a: '', b: 0, c: [] };
+ * const cloned = deepCloneToJSON(obj);
+ * 
+ * @example  
+ * const arr = [{}, {}, {}];
+ * const cloned = deepCloneToJSON(arr);
+ */
+'use strict';
+import getDataType from './getDataType';
+
+const deepCloneToJSON = (data: Record<string, any>|Record<string, any>[]): any => {
+    const dataType = getDataType(data);
+
+    // Handle objects
+    if (dataType === 'Object') {
+        const newObj: Record<string, any> = {};
+
+        // Clone regular properties
+        for (const key in data) {
+            newObj[key] = deepCloneToJSON((data as any)[key]);
+        }
+        for(const key in newObj){
+            newObj[key] === undefined && Reflect.deleteProperty(newObj, key);
+        }
+
+        return newObj ;
+
+        // Handle arrays
+    } else if (dataType === 'Array') {
+        let tmp = (data as any[]).map((item, index) => deepCloneToJSON(item)).filter(item => item !== undefined);
+        return tmp;
+        // Handle Date objects
+    } else if (!['Number', 'String', 'Boolean', 'Null'].includes(dataType)) {
+        return undefined ;
+    } else {
+        return data;
+    }
+
+};
+
+export default deepCloneToJSON;
+

package/src/mutateArray.js

@@ -0,0 +1,100 @@
+/**
+ * @since Last modified: 2025/12/18 20:54:23
+ * 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.
+ * @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';
+const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList }) => {
+    // Validation: Ensure target is an array and method is allowed
+    if (!Array.isArray(target)) {
+        throw new TypeError("The 'target' parameter must be an array.");
+    }
+    //使用默认
+    if (!allowList || allowList?.length) {
+        allowList = [
+            'push', 'pop', 'shift', 'unshift', 'splice',
+            'sort', 'reverse', 'copyWithin', 'fill'
+        ];
+    }
+    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 && onBeforeMutate(context);
+    // Execute the native array mutation
+    const result = Array.prototype[method].apply(target, args);
+    // Construct and trigger the patch callback
+    onAfterMutate && onAfterMutate({
+        method,
+        args,
+        context,
+        result,
+        timestamp: Date.now()
+    });
+    return result;
+};
+export default mutateArray;

package/src/mutateArray.ts

@@ -0,0 +1,155 @@
+/**
+ * @since Last modified: 2025/12/18 21:04:39
+ * 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.
+ * @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 mutateMethods from "./mutateMethods";
+
+
+/**
+ * Defines the structure of the captured state before mutation.
+ */
+export interface MutateContext {
+    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 MutatePatch {
+    method: string;    // The mutation method (e.g., 'push', 'pop', 'splice', etc.)
+    args: any[];       // Arguments passed to the mutation method
+    context: MutateContext;  // The state before mutation
+    result: any;       // The result of the mutation (the modified array)
+    timestamp: number; // The timestamp of the mutation
+}
+
+/**
+ * Configuration options for the mutateArray function.
+ */
+export interface MutateOptions {
+    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
+    allowList?: string[];  // Optional list of allowed mutation methods
+}
+
+const mutateArray = ({
+    target,
+    method,
+    args = [],
+    onBeforeMutate = () => { },
+    onAfterMutate = () => { },
+    allowList
+}: MutateOptions): 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 = mutateMethods;
+    }
+    if (!allowList?.includes(method)) {
+        throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);
+    }
+
+    const context: MutateContext = {},
+        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 && onBeforeMutate(context);
+
+    // Execute the native array mutation
+    const result = (Array.prototype as any)[method].apply(target, args);
+
+    // Construct and trigger the patch callback
+    onAfterMutate && onAfterMutate({
+        method,
+        args,
+        context,
+        result,
+        timestamp: Date.now()
+    });
+
+    return result;
+}
+
+export default mutateArray;

package/src/mutateMethods.ts

@@ -0,0 +1,15 @@
+/**
+ * @since Last modified: 2025/12/18 21:04:34
+ * 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 = [
+    'push', 'pop', 'shift', 'unshift', 'splice',
+    'sort', 'reverse', 'copyWithin', 'fill'
+];
+
+export default mutateMethods;