@codady/utils 0.0.9 → 0.0.11

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;

package/src/wrapSetMethods.ts

@@ -0,0 +1,215 @@
+/**
+ * @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, { SetMutationNames } from "./setMutableMethods";
+
+/**
+ * Context captured before Set mutation for tracking purposes
+ */
+export interface SetMutationContext<T = any> {
+  /** For add method: the value being added */
+  addedItem?: T;
+  /** For add / delete method: whether the value already existed */
+  existed?: boolean;
+  /** For delete method: the value being deleted */
+  deletedItem?: T;
+  /** For clear method: snapshot of all values before clearing */
+  clearedItems?: T[];
+  /** For clear method: size of the Set before clearing */
+  previousSize?: number;
+}
+
+/**
+ * Data object passed to callback after Set mutation
+ */
+export interface SetMutationPatch<T = any> {
+  /** The mutation method called */
+  method: SetMutationNames;
+  /** The result returned by the mutation method */
+  result: any;
+  /** Arguments passed to the mutation method */
+  args: any[];
+  /** Context captured before mutation */
+  context: SetMutationContext<T>;
+  /** Reference to the mutated Set */
+  target: Set<T>;
+  /** Additional custom properties */
+  [key: string]: any;
+}
+
+/**
+ * Configuration options for wrapSet function
+ */
+export interface SetMutationOptions<T = any> {
+  /** The Set to wrap with mutation tracking */
+  target: Set<T>;
+  /** Callback triggered before mutation */
+  onBeforeMutate?: (context: SetMutationContext<T>) => void;
+  /** Callback triggered after mutation */
+  onAfterMutate?: (patch: SetMutationPatch<T>) => void;
+  /** Optional list of allowed mutation methods (default: all Set methods) */
+  allowList?: SetMutationNames[];
+  /** Additional properties to attach to the patch */
+  props?: Record<string, any>;
+}
+
+/**
+ * Wrapped mutation methods for Set
+ */
+export interface SetMutationMethods<T = any> {
+  /**
+   * Adds a value to the Set.
+   * @param value The value to add
+   * @returns The Set object
+   */
+  add: (value: T) => Set<T>;
+
+  /**
+   * Deletes a value from the Set.
+   * @param value The value to delete
+   * @returns true if the value existed and has been removed, false otherwise
+   */
+  delete: (value: T) => boolean;
+
+  /**
+   * Clears all values from the Set.
+   * @returns void
+   */
+  clear: () => void;
+
+  /**
+   * Gets the original Set instance for direct access
+   */
+  readonly target: Set<T>;
+}
+
+/**
+ * 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 = <T = any>({
+  target,
+  onBeforeMutate = () => { },
+  onAfterMutate = () => { },
+  allowList = setMutableMethods,
+  props = {},
+}: SetMutationOptions<T>): SetMutationMethods<T> => {
+
+  // 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: Partial<SetMutationMethods<T>> = {};
+
+  // Helper to create wrapped method
+  const createWrappedMethod = (method: SetMutationNames) => {
+    return function (...args: any[]) {
+      const context: SetMutationContext<T> = {};
+
+      // Capture pre-mutation context based on method
+      switch (method) {
+        case 'add': {
+          const [value] = args as [T];
+          context.addedItem = value;
+          //context.existed=true，说明值重复
+          context.existed = target.has(value);
+          break;
+        }
+
+        case 'delete': {
+          const [value] = args as [T];
+          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 as any)[method].apply(target, args);
+
+      // Construct patch object
+      const patch: SetMutationPatch<T> = {
+        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 as any)[method] = createWrappedMethod(method);
+    }
+  }
+
+  // Add target reference
+  Object.defineProperty(methods, 'target', {
+    get: () => target,
+    enumerable: false,
+    configurable: false
+  });
+
+  return methods as SetMutationMethods<T>;
+};
+
+export default wrapSetMethods;