@codady/utils 0.0.8 → 0.0.10

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;