@codady/utils 0.0.4 → 0.0.5

package/dist/utils.cjs.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-18 21:39:9
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.4
  * @author AXUI development team <3217728223@qq.com>
  * @description This is a set of general-purpose JavaScript utility functions developed by the AXUI team. All functions are pure and do not involve CSS or other third-party libraries. They are suitable for any web front-end environment.
  * @see {@link https://www.axui.cn|Official website}
@@ -102,6 +102,76 @@ const deepCloneToJSON = (data) => {
     }
 };
 
+const mutateMethods = [
+    'push', 'pop', 'shift', 'unshift', 'splice',
+    'sort', 'reverse', 'copyWithin', 'fill'
+];
+
+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 = mutateMethods;
+    }
+    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;
+};
+
 const requireTypes = (data, require, cb) => {
     // Normalize the input types (convert to array if it's a single type)
     let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -136,7 +206,9 @@ const utils = {
     //renderTpl,
     //parseStr,
     deepClone,
-    deepCloneToJSON
+    deepCloneToJSON,
+    mutateArray,
+    mutateMethods
 };
 
 module.exports = utils;

package/dist/utils.esm.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-18 21:39:9
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.4
  * @author AXUI development team <3217728223@qq.com>
  * @description This is a set of general-purpose JavaScript utility functions developed by the AXUI team. All functions are pure and do not involve CSS or other third-party libraries. They are suitable for any web front-end environment.
  * @see {@link https://www.axui.cn|Official website}
@@ -100,6 +100,76 @@ const deepCloneToJSON = (data) => {
     }
 };
 
+const mutateMethods = [
+    'push', 'pop', 'shift', 'unshift', 'splice',
+    'sort', 'reverse', 'copyWithin', 'fill'
+];
+
+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 = mutateMethods;
+    }
+    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;
+};
+
 const requireTypes = (data, require, cb) => {
     // Normalize the input types (convert to array if it's a single type)
     let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -134,7 +204,9 @@ const utils = {
     //renderTpl,
     //parseStr,
     deepClone,
-    deepCloneToJSON
+    deepCloneToJSON,
+    mutateArray,
+    mutateMethods
 };
 
 export { utils as default };

package/dist/utils.umd.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-18 21:8:4
+ * @since Last modified: 2025-12-18 21:39:9
  * @name Utils for web front-end.
- * @version 0.0.2
+ * @version 0.0.4
  * @author AXUI development team <3217728223@qq.com>
  * @description This is a set of general-purpose JavaScript utility functions developed by the AXUI team. All functions are pure and do not involve CSS or other third-party libraries. They are suitable for any web front-end environment.
  * @see {@link https://www.axui.cn|Official website}
@@ -106,6 +106,76 @@
         }
     };
 
+    const mutateMethods = [
+        'push', 'pop', 'shift', 'unshift', 'splice',
+        'sort', 'reverse', 'copyWithin', 'fill'
+    ];
+
+    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 = mutateMethods;
+        }
+        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;
+    };
+
     const requireTypes = (data, require, cb) => {
         // Normalize the input types (convert to array if it's a single type)
         let requiredTypes = Array.isArray(require) ? require : [require], dataType = getDataType(data), typeLower = dataType.toLowerCase(), 
@@ -140,7 +210,9 @@
         //renderTpl,
         //parseStr,
         deepClone,
-        deepCloneToJSON
+        deepCloneToJSON,
+        mutateArray,
+        mutateMethods
     };
 
     return utils;

package/package.json

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

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/18 20:54:23
+ * @since Last modified: 2025/12/18 21:20:26
  * 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.
@@ -30,6 +30,7 @@
  * // 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 }) => {
     // Validation: Ensure target is an array and method is allowed
     if (!Array.isArray(target)) {
@@ -37,10 +38,7 @@ const mutateArray = ({ target, method, args = [], onBeforeMutate = () => { }, on
     }
     //使用默认
     if (!allowList || allowList?.length) {
-        allowList = [
-            'push', 'pop', 'shift', 'unshift', 'splice',
-            'sort', 'reverse', 'copyWithin', 'fill'
-        ];
+        allowList = mutateMethods;
     }
     if (!allowList?.includes(method)) {
         throw new Error(`Method "${method}" is not in the allowList or is not a mutation method.`);

package/src/mutateMethods.js

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