@codady/utils 0.0.8 → 0.0.10

package/src/wrapArrayMethods.js

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/19 10:14:03
+ * @since Last modified: 2025/12/22 17:14:00
  * 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.
@@ -18,7 +18,7 @@
  * methods.push(4); // arr is now [1, 2, 3, 4]
  */
 'use strict';
-import mutableMethods from "./mutableMethods";
+import arrayMutableMethods from "./arrayMutableMethods";
 const wrapArrayMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList, props = {}, }) => {
     // Validation: Ensure target is an array and method is allowed
     if (!Array.isArray(target)) {
@@ -26,7 +26,7 @@ const wrapArrayMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate =
     }
     //使用默认
     if (!allowList || allowList?.length) {
-        allowList = mutableMethods;
+        allowList = arrayMutableMethods;
     }
     const methods = {};
     for (let method of allowList) {
@@ -42,10 +42,10 @@ const wrapArrayMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate =
                     context.addedItems = [...args];
                     break;
                 case 'pop':
-                    context.poppedValue = target[len - 1];
+                    context.poppedItem = target[len - 1];
                     break;
                 case 'shift':
-                    context.shiftedValue = target[0];
+                    context.shiftedItem = target[0];
                     break;
                 case 'splice':
                     const [s, d] = args, 

package/src/wrapArrayMethods.ts

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/19 10:14:03
+ * @since Last modified: 2025/12/22 17:14:00
  * 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.
@@ -19,7 +19,7 @@
  */
 'use strict';
 
-import mutableMethods, { ArrayMutationNames } from "./mutableMethods";
+import arrayMutableMethods, { ArrayMutationNames } from "./arrayMutableMethods";
 
 
 /**
@@ -27,8 +27,8 @@ import mutableMethods, { ArrayMutationNames } from "./mutableMethods";
  */
 export interface MutationContextt {
     addedItems?: any[];      // Items added to the array
-    poppedValue?: any;       // Value popped from the array
-    shiftedValue?: any;      // Value shifted from the array
+    poppedItem?: any;       // Value popped from the array
+    shiftedItem?: 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')
@@ -87,7 +87,7 @@ const wrapArrayMethods = <T = any>({
     }
     //使用默认
     if (!allowList || allowList?.length) {
-        allowList = mutableMethods;
+        allowList = arrayMutableMethods;
     }
 
     const methods: Partial<ArrayMutationMethods<T>> = {};
@@ -109,10 +109,10 @@ const wrapArrayMethods = <T = any>({
                     context.addedItems = [...args];
                     break;
                 case 'pop':
-                    context.poppedValue = target[len - 1];
+                    context.poppedItem = target[len - 1];
                     break;
                 case 'shift':
-                    context.shiftedValue = target[0];
+                    context.shiftedItem = target[0];
                     break;
                 case 'splice':
                     const [s, d] = args,

package/src/wrapMap - /345/211/257/346/234/254.js"

@@ -0,0 +1,119 @@
+/**
+ * @since Last modified: 2025/12/22 16:37:23
+ * Wraps Map objects with mutation tracking capabilities.
+ * Provides hooks for before/after mutation events and captures detailed context
+ * for undo/redo or change tracking purposes.
+ *
+ * @template K - Map key type
+ * @template V - Map value type
+ * @param {MapMutationOptions<K, V>} options - Configuration object containing target Map and callbacks
+ * @returns {MapMutationMethods<K, V>} - Object containing wrapped Map mutation methods
+ *
+ * @example
+ * // Basic usage with tracking
+ * const map = new Map([['key1', 'value1']]);
+ * const methods = wrapMap({
+ *   target: map,
+ *   onAfterMutate: (patch) => {
+ *     console.log(`Map ${patch.method} called`, patch.context);
+ *   }
+ * });
+ *
+ * methods.set('key2', 'value2'); // Tracked
+ * methods.delete('key1'); // Tracked
+ * methods.clear(); // Tracked
+ *
+ * @example
+ * // With undo/redo support
+ * const history: MapMutationPatch<any, any>[] = [];
+ * const map = new Map<string, number>();
+ *
+ * const methods = wrapMap({
+ *   target: map,
+ *   onBeforeMutate: (context) => {
+ *     console.log('Before mutation:', context);
+ *   },
+ *   onAfterMutate: (patch) => {
+ *     history.push(patch);
+ *     console.log('Mutation recorded:', patch.method, 'History size:', history.length);
+ *   }
+ * });
+ */
+'use strict';
+/**
+ * Available Map mutation methods
+ */
+export const mapMutableMethods = ['set', 'delete', 'clear'];
+/**
+ * Creates wrapped mutation methods for Map with tracking capabilities
+ *
+ * @param options Configuration options
+ * @returns Object containing wrapped Map mutation methods
+ * @throws TypeError if target is not a Map
+ */
+const wrapMap = ({ target, onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList = mapMutableMethods, props = {}, }) => {
+    // Validation: Ensure target is a Map
+    if (!(target instanceof Map)) {
+        throw new TypeError("The 'target' parameter must be a Map.");
+    }
+    // Create method wrappers
+    const methods = {};
+    // Helper to create wrapped method
+    const createWrappedMethod = (method) => {
+        return function (...args) {
+            const context = {};
+            // Capture pre-mutation context based on method
+            switch (method) {
+                case 'set': {
+                    const [key, newValue] = args;
+                    context.key = key;
+                    context.newValue = newValue;
+                    context.hadKey = target.has(key);
+                    context.oldValue = context.hadKey ? target.get(key) : undefined;
+                    break;
+                }
+                case 'delete': {
+                    const [key] = args;
+                    context.key = key;
+                    context.existed = target.has(key);
+                    break;
+                }
+                case 'clear': {
+                    context.clearedEntries = Array.from(target.entries());
+                    context.previousSize = target.size;
+                    break;
+                }
+            }
+            // Execute before mutation callback
+            onBeforeMutate(context);
+            // Execute the native Map method
+            const result = target[method].apply(target, args);
+            // Construct patch object
+            const patch = {
+                method,
+                result,
+                args,
+                context,
+                target,
+                ...props
+            };
+            // Execute after mutation callback
+            onAfterMutate(patch);
+            return result;
+        };
+    };
+    // Wrap allowed methods
+    for (const method of allowList) {
+        if (mapMutableMethods.includes(method)) {
+            methods[method] = createWrappedMethod(method);
+        }
+    }
+    // Add target reference
+    Object.defineProperty(methods, 'target', {
+        get: () => target,
+        enumerable: false,
+        configurable: false
+    });
+    return methods;
+};
+export default wrapMap;

package/src/wrapMapMethods.js

@@ -0,0 +1,118 @@
+/**
+ * @since Last modified: 2025/12/22 17:19:32
+ * Wraps Map objects with mutation tracking capabilities.
+ * Provides hooks for before/after mutation events and captures detailed context
+ * for undo/redo or change tracking purposes.
+ *
+ * @template K - Map key type
+ * @template V - Map value type
+ * @param {MapMutationOptions<K, V>} options - Configuration object containing target Map and callbacks
+ * @returns {MapMutationMethods<K, V>} - Object containing wrapped Map mutation methods
+ *
+ * @example
+ * // Basic usage with tracking
+ * const map = new Map([['key1', 'value1']]);
+ * const methods = wrapMap({
+ *   target: map,
+ *   onAfterMutate: (patch) => {
+ *     console.log(`Map ${patch.method} called`, patch.context);
+ *   }
+ * });
+ *
+ * methods.set('key2', 'value2'); // Tracked
+ * methods.delete('key1'); // Tracked
+ * methods.clear(); // Tracked
+ *
+ * @example
+ * // With undo/redo support
+ * const history: MapMutationPatch<any, any>[] = [];
+ * const map = new Map<string, number>();
+ *
+ * const methods = wrapMap({
+ *   target: map,
+ *   onBeforeMutate: (context) => {
+ *     console.log('Before mutation:', context);
+ *   },
+ *   onAfterMutate: (patch) => {
+ *     history.push(patch);
+ *     console.log('Mutation recorded:', patch.method, 'History size:', history.length);
+ *   }
+ * });
+ */
+'use strict';
+import mapMutableMethods from "./mapMutableMethods";
+/**
+ * Creates wrapped mutation methods for Map with tracking capabilities
+ *
+ * @param options Configuration options
+ * @returns Object containing wrapped Map mutation methods
+ * @throws TypeError if target is not a Map
+ */
+const wrapMapMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList = mapMutableMethods, props = {}, }) => {
+    // Validation: Ensure target is a Map
+    if (!(target instanceof Map)) {
+        throw new TypeError("The 'target' parameter must be a Map.");
+    }
+    // Create method wrappers
+    const methods = {};
+    // Helper to create wrapped method
+    const createWrappedMethod = (method) => {
+        return function (...args) {
+            const context = {};
+            // Capture pre-mutation context based on method
+            switch (method) {
+                case 'set': {
+                    const [key, newValue] = args;
+                    context.key = key;
+                    context.newValue = newValue;
+                    context.existed = target.has(key);
+                    context.oldValue = context.existed ? target.get(key) : undefined;
+                    break;
+                }
+                case 'delete': {
+                    const [key] = args;
+                    context.key = key;
+                    context.existed = target.has(key);
+                    context.value = context.existed ? target.get(key) : undefined;
+                    break;
+                }
+                case 'clear': {
+                    context.clearedItems = Array.from(target.entries());
+                    //用来做验证
+                    context.previousSize = target.size;
+                    break;
+                }
+            }
+            // Execute before mutation callback
+            onBeforeMutate(context);
+            // Execute the native Map method
+            const result = target[method].apply(target, args);
+            // Construct patch object
+            const patch = {
+                method,
+                result,
+                args,
+                context,
+                target,
+                ...props
+            };
+            // Execute after mutation callback
+            onAfterMutate(patch);
+            return result;
+        };
+    };
+    // Wrap allowed methods
+    for (const method of allowList) {
+        if (mapMutableMethods.includes(method)) {
+            methods[method] = createWrappedMethod(method);
+        }
+    }
+    // Add target reference
+    Object.defineProperty(methods, 'target', {
+        get: () => target,
+        enumerable: false,
+        configurable: false
+    });
+    return methods;
+};
+export default wrapMapMethods;

package/src/wrapMapMethods.ts

@@ -0,0 +1,226 @@
+/**
+ * @since Last modified: 2025/12/22 17:19:32
+ * Wraps Map objects with mutation tracking capabilities.
+ * Provides hooks for before/after mutation events and captures detailed context
+ * for undo/redo or change tracking purposes.
+ * 
+ * @template K - Map key type
+ * @template V - Map value type
+ * @param {MapMutationOptions<K, V>} options - Configuration object containing target Map and callbacks
+ * @returns {MapMutationMethods<K, V>} - Object containing wrapped Map mutation methods
+ * 
+ * @example
+ * // Basic usage with tracking
+ * const map = new Map([['key1', 'value1']]);
+ * const methods = wrapMap({
+ *   target: map,
+ *   onAfterMutate: (patch) => {
+ *     console.log(`Map ${patch.method} called`, patch.context);
+ *   }
+ * });
+ * 
+ * methods.set('key2', 'value2'); // Tracked
+ * methods.delete('key1'); // Tracked
+ * methods.clear(); // Tracked
+ * 
+ * @example
+ * // With undo/redo support
+ * const history: MapMutationPatch<any, any>[] = [];
+ * const map = new Map<string, number>();
+ * 
+ * const methods = wrapMap({
+ *   target: map,
+ *   onBeforeMutate: (context) => {
+ *     console.log('Before mutation:', context);
+ *   },
+ *   onAfterMutate: (patch) => {
+ *     history.push(patch);
+ *     console.log('Mutation recorded:', patch.method, 'History size:', history.length);
+ *   }
+ * });
+ */
+'use strict';
+
+import mapMutableMethods, { MapMutationNames } from "./mapMutableMethods";
+
+/**
+ * Context captured before Map mutation for tracking purposes
+ */
+export interface MapMutationContext<K = any, V = any> {
+  /** For set method: the key being set */
+  key?: K;
+  /** For delete method: the deleted value */
+  value?: V;
+  /** For set method: the new value being set */
+  newValue?: V;
+  /** For set method: the old value if key existed */
+  oldValue?: V;
+  /** For set / delete method: whether the key existed */
+  existed?: boolean;
+  /** For clear method: snapshot of all entries before clearing */
+  clearedItems?: [K, V][];
+  /** For clear method: size of the Map before clearing */
+  previousSize?: number;
+}
+
+/**
+ * Data object passed to callback after Map mutation
+ */
+export interface MapMutationPatch<K = any, V = any> {
+  /** The mutation method called */
+  method: MapMutationNames;
+  /** The result returned by the mutation method */
+  result: any;
+  /** Arguments passed to the mutation method */
+  args: any[];
+  /** Context captured before mutation */
+  context: MapMutationContext<K, V>;
+  /** Reference to the mutated Map */
+  target: Map<K, V>;
+  /** Additional custom properties */
+  [key: string]: any;
+}
+
+/**
+ * Configuration options for wrapMap function
+ */
+export interface MapMutationOptions<K = any, V = any> {
+  /** The Map to wrap with mutation tracking */
+  target: Map<K, V>;
+  /** Callback triggered before mutation */
+  onBeforeMutate?: (context: MapMutationContext<K, V>) => void;
+  /** Callback triggered after mutation */
+  onAfterMutate?: (patch: MapMutationPatch<K, V>) => void;
+  /** Optional list of allowed mutation methods (default: all Map methods) */
+  allowList?: MapMutationNames[];
+  /** Additional properties to attach to the patch */
+  props?: Record<string, any>;
+}
+
+/**
+ * Wrapped mutation methods for Map
+ */
+export interface MapMutationMethods<K = any, V = any> {
+  /**
+   * Sets the value for the key in the Map.
+   * @param key The key to set
+   * @param value The value to set
+   * @returns The Map object
+   */
+  set: (key: K, value: V) => Map<K, V>;
+
+  /**
+   * Deletes the key from the Map.
+   * @param key The key to delete
+   * @returns true if the key existed and has been removed, false otherwise
+   */
+  delete: (key: K) => boolean;
+
+  /**
+   * Clears all entries from the Map.
+   * @returns void
+   */
+  clear: () => void;
+
+  /**
+   * Gets the original Map instance for direct access
+   */
+  readonly target: Map<K, V>;
+}
+
+/**
+ * Creates wrapped mutation methods for Map with tracking capabilities
+ * 
+ * @param options Configuration options
+ * @returns Object containing wrapped Map mutation methods
+ * @throws TypeError if target is not a Map
+ */
+const wrapMapMethods = <K = any, V = any>({
+  target,
+  onBeforeMutate = () => { },
+  onAfterMutate = () => { },
+  allowList = mapMutableMethods,
+  props = {},
+}: MapMutationOptions<K, V>): MapMutationMethods<K, V> => {
+
+  // Validation: Ensure target is a Map
+  if (!(target instanceof Map)) {
+    throw new TypeError("The 'target' parameter must be a Map.");
+  }
+
+  // Create method wrappers
+  const methods: Partial<MapMutationMethods<K, V>> = {};
+
+  // Helper to create wrapped method
+  const createWrappedMethod = (method: MapMutationNames) => {
+    return function (...args: any[]) {
+      const context: MapMutationContext<K, V> = {};
+
+      // Capture pre-mutation context based on method
+      switch (method) {
+        case 'set': {
+          const [key, newValue] = args as [K, V];
+          context.key = key;
+          context.newValue = newValue;
+          context.existed = target.has(key);
+          context.oldValue = context.existed ? target.get(key) : undefined;
+          break;
+        }
+
+        case 'delete': {
+          const [key] = args as [K];
+          context.key = key;
+          context.existed = target.has(key);
+          context.value = context.existed ? target.get(key) : undefined;
+          break;
+        }
+
+        case 'clear': {
+          context.clearedItems = Array.from(target.entries());
+          //用来做验证
+          context.previousSize = target.size;
+          break;
+        }
+      }
+
+      // Execute before mutation callback
+      onBeforeMutate(context);
+
+      // Execute the native Map method
+      const result = (target as any)[method].apply(target, args);
+
+      // Construct patch object
+      const patch: MapMutationPatch<K, V> = {
+        method,
+        result,
+        args,
+        context,
+        target,
+        ...props
+      };
+
+      // Execute after mutation callback
+      onAfterMutate(patch);
+
+      return result;
+    };
+  };
+
+  // Wrap allowed methods
+  for (const method of allowList) {
+    if (mapMutableMethods.includes(method)) {
+      (methods as any)[method] = createWrappedMethod(method);
+    }
+  }
+
+  // Add target reference
+  Object.defineProperty(methods, 'target', {
+    get: () => target,
+    enumerable: false,
+    configurable: false
+  });
+
+  return methods as MapMutationMethods<K, V>;
+};
+
+export default wrapMapMethods;

package/src/wrapSetMethods.js

@@ -0,0 +1,112 @@
+/**
+ * @since Last modified: 2025/12/22 17:19:21
+ * Wraps Set objects with mutation tracking capabilities.
+ * Provides hooks for before/after mutation events and captures detailed context
+ * for undo/redo or change tracking purposes.
+ *
+ * @template T - Set element type
+ * @param {SetMutationOptions<T>} options - Configuration object containing target Set and callbacks
+ * @returns {SetMutationMethods<T>} - Object containing wrapped Set mutation methods
+ *
+ * @example
+ * // Basic usage with tracking
+ * const set = new Set([1, 2, 3]);
+ * const methods = wrapSet({
+ *   target: set,
+ *   onAfterMutate: (patch) => {
+ *     console.log(`Set ${patch.method} called`, patch.context);
+ *   }
+ * });
+ *
+ * methods.add(4); // Tracked
+ * methods.delete(2); // Tracked
+ * methods.clear(); // Tracked
+ *
+ * @example
+ * // With change detection for UI updates
+ * const set = new Set<string>();
+ * const methods = wrapSet({
+ *   target: set,
+ *   onAfterMutate: (patch) => {
+ *     // Trigger UI update when Set changes
+ *     if (patch.method === 'add' || patch.method === 'delete') {
+ *       updateUI(Array.from(patch.target));
+ *     }
+ *   }
+ * });
+ */
+'use strict';
+import setMutableMethods from "./setMutableMethods";
+/**
+ * Creates wrapped mutation methods for Set with tracking capabilities
+ *
+ * @param options Configuration options
+ * @returns Object containing wrapped Set mutation methods
+ * @throws TypeError if target is not a Set
+ */
+const wrapSetMethods = ({ target, onBeforeMutate = () => { }, onAfterMutate = () => { }, allowList = setMutableMethods, props = {}, }) => {
+    // Validation: Ensure target is a Set
+    if (!(target instanceof Set)) {
+        throw new TypeError("The 'target' parameter must be a Set.");
+    }
+    // Create method wrappers
+    const methods = {};
+    // Helper to create wrapped method
+    const createWrappedMethod = (method) => {
+        return function (...args) {
+            const context = {};
+            // Capture pre-mutation context based on method
+            switch (method) {
+                case 'add': {
+                    const [value] = args;
+                    context.addedItem = value;
+                    //context.existed=true，说明值重复
+                    context.existed = target.has(value);
+                    break;
+                }
+                case 'delete': {
+                    const [value] = args;
+                    context.existed = target.has(value);
+                    context.deletedItem = context.existed ? value : undefined;
+                    break;
+                }
+                case 'clear': {
+                    context.clearedItems = Array.from(target);
+                    //用来做验证
+                    context.previousSize = target.size;
+                    break;
+                }
+            }
+            // Execute before mutation callback
+            onBeforeMutate(context);
+            // Execute the native Set method
+            const result = target[method].apply(target, args);
+            // Construct patch object
+            const patch = {
+                method,
+                result,
+                args,
+                context,
+                target,
+                ...props
+            };
+            // Execute after mutation callback
+            onAfterMutate(patch);
+            return result;
+        };
+    };
+    // Wrap allowed methods
+    for (const method of allowList) {
+        if (setMutableMethods.includes(method)) {
+            methods[method] = createWrappedMethod(method);
+        }
+    }
+    // Add target reference
+    Object.defineProperty(methods, 'target', {
+        get: () => target,
+        enumerable: false,
+        configurable: false
+    });
+    return methods;
+};
+export default wrapSetMethods;