@codady/utils 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -2,11 +2,32 @@
 
 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.1/dist/js/utils.js
-- **Zip**: https://unpkg.com/@codady/utils@0.0.1/dist.zip
+- **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
 

package/dist/utils.cjs.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-16 14:44:11
+ * @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}

package/dist/utils.cjs.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-16 14:44:11
+ * @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}

package/dist/utils.esm.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-16 14:44:11
+ * @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}

package/dist/utils.esm.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-16 14:44:11
+ * @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}

package/dist/utils.umd.js

@@ -1,8 +1,8 @@
 
 /*!
- * @since Last modified: 2025-12-16 14:44:11
+ * @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}

package/dist/utils.umd.min.js

@@ -1,7 +1,7 @@
 /*!
- * @since Last modified: 2025-12-16 14:44:11
+ * @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}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codady/utils",
-  "version": "0.0.2",
+  "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/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;