@codady/utils 0.0.9 → 0.0.11

package/modules.js

@@ -1,14 +1,24 @@
 /**
- * Last modified: 2025/12/19 15:23:21
+ * Last modified: 2025/12/24 17:05:40
  */
 'use strict';
 import deepClone from './src/deepClone';
 import deepCloneToJSON from './src/deepCloneToJSON';
 import getDataType from './src/getDataType';
 import wrapArrayMethods from './src/wrapArrayMethods';
-import mutableMethods from './src/mutableMethods';
 import requireTypes from './src/requireTypes';
 import getUniqueId from './src/getUniqueId';
+import arrayMutableMethods from './src/arrayMutableMethods';
+import setMutableMethods from './src/setMutableMethods';
+import mapMutableMethods from './src/mapMutableMethods';
+import wrapSetMethods from './src/wrapSetMethods';
+import wrapMapMethods from './src/wrapMapMethods';
+import { deepEqual } from 'assert';
+import deepMerge from './src/deepMerge';
+import deepMergeArrays from './src/deepMergeArrays';
+import deepMergeMaps from './src/deepMergeMaps';
+import deepMergeObjects from './src/deepMergeObjects';
+import deepMergeSets from './src/deepMergeSets';
 const utils = {
     //executeStr,
     getDataType,
@@ -18,7 +28,17 @@ const utils = {
     deepClone,
     deepCloneToJSON,
     wrapArrayMethods,
-    mutableMethods,
-    getUniqueId
+    arrayMutableMethods,
+    setMutableMethods,
+    mapMutableMethods,
+    wrapSetMethods,
+    wrapMapMethods,
+    getUniqueId,
+    deepEqual,
+    deepMerge,
+    deepMergeArrays,
+    deepMergeMaps,
+    deepMergeObjects,
+    deepMergeSets,
 };
 export default utils;

package/modules.ts

@@ -1,5 +1,5 @@
 /**
- * Last modified: 2025/12/19 15:23:21
+ * Last modified: 2025/12/24 17:05:40
  */
 'use strict'
 import deepClone from './src/deepClone';
@@ -7,11 +7,21 @@ import deepCloneToJSON from './src/deepCloneToJSON';
 import executeStr from './src/executeStr';
 import getDataType from './src/getDataType';
 import wrapArrayMethods from './src/wrapArrayMethods';
-import mutableMethods from './src/mutableMethods';
 import parseStr from './src/parseStr';
 import renderTpl from './src/renderTpl';
 import requireTypes from './src/requireTypes';
 import getUniqueId from './src/getUniqueId';
+import arrayMutableMethods from './src/arrayMutableMethods';
+import setMutableMethods from './src/setMutableMethods';
+import mapMutableMethods from './src/mapMutableMethods';
+import wrapSetMethods from './src/wrapSetMethods';
+import wrapMapMethods from './src/wrapMapMethods';
+import { deepEqual } from 'assert';
+import deepMerge from './src/deepMerge';
+import deepMergeArrays from './src/deepMergeArrays';
+import deepMergeMaps from './src/deepMergeMaps';
+import deepMergeObjects from './src/deepMergeObjects';
+import deepMergeSets from './src/deepMergeSets';
 
 
 
@@ -24,8 +34,18 @@ const utils = {
   deepClone,
   deepCloneToJSON,
   wrapArrayMethods,
-  mutableMethods,
-  getUniqueId
+  arrayMutableMethods,
+  setMutableMethods,
+  mapMutableMethods,
+  wrapSetMethods,
+  wrapMapMethods,
+  getUniqueId,
+  deepEqual,
+  deepMerge,
+  deepMergeArrays,
+  deepMergeMaps,
+  deepMergeObjects,
+  deepMergeSets,
 };
 
 export default utils;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codady/utils",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "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/arrayMutableMethods - /345/211/257/346/234/254.js"

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

package/src/arrayMutableMethods.js

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

package/src/{mutableMethods.ts → arrayMutableMethods.ts}

@@ -1,5 +1,5 @@
 /**
- * @since Last modified: 2025/12/19 10:06:07
+ * @since Last modified: 2025/12/22 17:20:46
  * 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,
@@ -7,9 +7,9 @@
  * 
  */
 export type ArrayMutationNames = ('push' | 'pop' | 'shift' | 'unshift' | 'splice' | 'sort' | 'reverse' | 'copyWithin' | 'fill')[];
-const mutableMethods: ArrayMutationNames = [
+const arrayMutableMethods: ArrayMutationNames = [
     'push', 'pop', 'shift', 'unshift', 'splice',
     'sort', 'reverse', 'copyWithin', 'fill'
 ];
 
-export default mutableMethods;
+export default arrayMutableMethods;

package/src/deepClone.js

@@ -1,53 +1,178 @@
 /**
- * @since Last modified: 2025/12/16 13:33:46
- * Deep clone an array or object.
- * Supports Symbol keys. These types are returned directly:
- * Number, String, Boolean, Symbol, HTML*Element, Function, Date, RegExp.
+ * @since Last modified: 2025/12/24 17:05:29
+ * Deep clone an array, object, or other cloneable data types.
  *
- * @template T
- * @param {T} data - Array or object to clone
- * @returns {T} - New object with different memory address
+ * Features:
+ * - Handles nested objects and arrays recursively
+ * - Preserves Symbol properties
+ * - Customizable cloning behavior via options
+ * - Interceptor for custom cloning logic
+ * - Lifecycle callbacks for monitoring
+ *
+ * Default cloning behavior:
+ * - Objects and arrays: Deep cloned (enabled by default)
+ * - Maps and Sets: Deep cloned (enabled by default)
+ * - Dates: Returned directly (disabled by default, set cloneDate: true to clone)
+ * - RegExp: Returned directly (disabled by default, set cloneRegex: true to clone)
+ * - DOM elements: Returned directly (disabled by default, set cloneElement: true to clone)
+ * - DocumentFragment: Returned directly (disabled by default, set cloneFragment: true to clone)
+ *
+ * Types always returned directly (no cloning):
+ * - Primitive types: Number, String, Boolean, BigInt, undefined, null
+ * - Functions and Classes
+ * - Symbol instances
+ * - Errors and Promises
+ * - ArrayBuffer, Blob, File
+ * - WeakMap and WeakSet
+ *
+ * @template T - Type of the data to clone
+ * @param {T} data - The data to deep clone
+ * @param {DeepCloneOptions} [options={}] - Configuration options for cloning behavior
+ * @returns {T} - A deep clone of the input data (new memory reference)
  *
  * @example
- * const obj = { a: '', b: 0, c: [] };
+ * // Basic usage - clones objects and arrays
+ * const obj = { a: '', b: 0, c: [], d: new Map([['key', 'value']]) };
  * const cloned = deepClone(obj);
+ * console.log(cloned !== obj); // true
+ * console.log(cloned.c !== obj.c); // true
+ *
+ * @example
+ * // With Symbol properties
+ * const sym = Symbol('id');
+ * const objWithSymbol = { [sym]: 'value', normal: 'property' };
+ * const clonedWithSymbol = deepClone(objWithSymbol);
+ *
+ * @example
+ * // Custom options - clone Dates and RegExp
+ * const data = { date: new Date(), regex: /test/gi };
+ * const cloned = deepClone(data, {
+ *   cloneDate: true,
+ *   cloneRegex: true
+ * });
+ *
+ * @example
+ * // Using interceptor for custom types
+ * class CustomClass {
+ *   constructor(public value: number) {}
+ * }
+ *
+ * const customData = new CustomClass(42);
+ * const cloned = deepClone(customData, {
+ *   interceptor: (data, type) => {
+ *     if (data instanceof CustomClass) {
+ *       return new CustomClass(data.value);
+ *     }
+ *     return null;
+ *   }
+ * });
  *
  * @example
- * const arr = [{}, {}, {}];
- * const cloned = deepClone(arr);
+ * // With lifecycle callbacks
+ * const trackedClone = deepClone(someData, {
+ *   onBeforeClone: (data, type) => {
+ *     console.log(`Starting to clone ${type}`);
+ *   },
+ *   onAfterClone: (result) => {
+ *     console.log(`Cloned ${result.type}, success: ${result.cloned}`);
+ *   }
+ * });
  */
 'use strict';
 import getDataType from './getDataType';
-const deepClone = (data) => {
-    const dataType = getDataType(data);
-    if (dataType === 'Object') {
-        const newObj = {};
-        const symbols = Object.getOwnPropertySymbols(data);
+//支持原始值的复制，包括Number、String、Boolean、Null
+//支持Date和Regex对象值复制（值转换）
+//支持{},[],Set和Map的遍历
+const deepClone = (data, options = {}) => {
+    const dataType = getDataType(data), 
+    // Default options
+    opts = Object.assign({
+        cloneSet: true,
+        cloneMap: true,
+        cloneObject: true,
+        cloneArray: true,
+        //可重新构建
+        cloneDate: true,
+        cloneRegex: true,
+        //节点默认不复制
+        //cloneElement: false,
+        //cloneFragment: false,
+    }, options);
+    // Check interceptor - if it returns a value (not null/undefined), use it directly
+    if (opts.interceptor && typeof opts.interceptor === 'function') {
+        let result = opts.interceptor(data, dataType);
+        if ((result ?? false)) {
+            // Call onAfterClone if set
+            opts.onAfterClone?.({
+                output: result,
+                input: data,
+                type: dataType,
+                cloned: result !== data,
+            });
+            return result;
+        }
+        // If interceptor returns null/undefined, continue with normal cloning process
+    }
+    // Callback before cloning
+    opts.onBeforeClone?.(data, dataType);
+    let newData, cloned = true;
+    if (dataType === 'Object' && opts.cloneObject) {
+        const newObj = {}, symbols = Object.getOwnPropertySymbols(data);
         // Clone regular properties
         for (const key in data) {
-            newObj[key] = deepClone(data[key]);
+            newObj[key] = deepClone(data[key], opts);
         }
         // Clone Symbol properties
         if (symbols.length > 0) {
             for (const symbol of symbols) {
-                newObj[symbol] = deepClone(data[symbol]);
+                newObj[symbol] = deepClone(data[symbol], opts);
             }
         }
-        return newObj;
+        newData = newObj;
     }
-    else if (dataType === 'Array') {
-        return data.map(item => deepClone(item));
+    else if (dataType === 'Array' && opts.cloneArray) {
+        newData = data.map(item => deepClone(item, opts));
+    }
+    else if (dataType === 'Map' && opts.cloneMap) {
+        const newMap = new Map();
+        for (const [key, value] of data) {
+            // Both Map keys and values need deep cloning
+            newMap.set(deepClone(key, opts), deepClone(value, opts));
+        }
+        newData = newMap;
+    }
+    else if (dataType === 'Set' && opts.cloneSet) {
+        const newSet = new Set();
+        for (const value of data) {
+            // Set values need deep cloning
+            newSet.add(deepClone(value, opts));
+        }
+        newData = newSet;
     }
-    else if (dataType === 'Date') {
-        return new Date(data.getTime());
+    else if (dataType === 'Date' && opts.cloneDate) {
+        newData = new Date(data.getTime());
     }
-    else if (dataType === 'RegExp') {
+    else if (dataType === 'RegExp' && opts.cloneRegex) {
         const regex = data;
-        return new RegExp(regex.source, regex.flags);
+        newData = new RegExp(regex.source, regex.flags);
+        // } else if ((dataType.includes('HTML') && opts.cloneElement) ||
+        //    (dataType === 'DocumentFragment' && opts.cloneFragment)
+        //) {
+        //Text,Comment,HTML*Element,DocumentFragment,Attr
+        //     newData = (data as any).cloneNode(true) as T;
     }
     else {
-        // Number, String, Boolean, Symbol,Text,Comment,Set,Map, HTML*Element, Function,Error,Promise,ArrayBuffer,Blob,File, return directly
-        return data;
+        // Number, String, Boolean, Symbol, Function,Error,Promise,ArrayBuffer,Blob,File, return directly
+        newData = data;
+        cloned = false;
     }
+    // Callback after cloning
+    opts.onAfterClone?.({
+        output: newData,
+        input: data,
+        type: dataType,
+        cloned,
+    });
+    return newData;
 };
 export default deepClone;

package/src/deepClone.ts

@@ -1,59 +1,218 @@
 /**
- * @since Last modified: 2025/12/16 13:33:46
- * Deep clone an array or object.
- * Supports Symbol keys. These types are returned directly: 
- * Number, String, Boolean, Symbol, HTML*Element, Function, Date, RegExp.
+ * @since Last modified: 2025/12/24 17:05:29
+ * Deep clone an array, object, or other cloneable data types.
  * 
- * @template T
- * @param {T} data - Array or object to clone
- * @returns {T} - New object with different memory address
+ * Features:
+ * - Handles nested objects and arrays recursively
+ * - Preserves Symbol properties
+ * - Customizable cloning behavior via options
+ * - Interceptor for custom cloning logic
+ * - Lifecycle callbacks for monitoring
+ * 
+ * Default cloning behavior:
+ * - Objects and arrays: Deep cloned (enabled by default)
+ * - Maps and Sets: Deep cloned (enabled by default)
+ * - Dates: Returned directly (disabled by default, set cloneDate: true to clone)
+ * - RegExp: Returned directly (disabled by default, set cloneRegex: true to clone)
+ * - DOM elements: Returned directly (disabled by default, set cloneElement: true to clone)
+ * - DocumentFragment: Returned directly (disabled by default, set cloneFragment: true to clone)
+ * 
+ * Types always returned directly (no cloning):
+ * - Primitive types: Number, String, Boolean, BigInt, undefined, null
+ * - Functions and Classes
+ * - Symbol instances
+ * - Errors and Promises
+ * - ArrayBuffer, Blob, File
+ * - WeakMap and WeakSet
+ * 
+ * @template T - Type of the data to clone
+ * @param {T} data - The data to deep clone
+ * @param {DeepCloneOptions} [options={}] - Configuration options for cloning behavior
+ * @returns {T} - A deep clone of the input data (new memory reference)
  * 
  * @example
- * const obj = { a: '', b: 0, c: [] };
+ * // Basic usage - clones objects and arrays
+ * const obj = { a: '', b: 0, c: [], d: new Map([['key', 'value']]) };
  * const cloned = deepClone(obj);
+ * console.log(cloned !== obj); // true
+ * console.log(cloned.c !== obj.c); // true
+ * 
+ * @example
+ * // With Symbol properties
+ * const sym = Symbol('id');
+ * const objWithSymbol = { [sym]: 'value', normal: 'property' };
+ * const clonedWithSymbol = deepClone(objWithSymbol);
+ * 
+ * @example
+ * // Custom options - clone Dates and RegExp
+ * const data = { date: new Date(), regex: /test/gi };
+ * const cloned = deepClone(data, { 
+ *   cloneDate: true, 
+ *   cloneRegex: true 
+ * });
+ * 
+ * @example
+ * // Using interceptor for custom types
+ * class CustomClass {
+ *   constructor(public value: number) {}
+ * }
  * 
- * @example  
- * const arr = [{}, {}, {}];
- * const cloned = deepClone(arr);
+ * const customData = new CustomClass(42);
+ * const cloned = deepClone(customData, {
+ *   interceptor: (data, type) => {
+ *     if (data instanceof CustomClass) {
+ *       return new CustomClass(data.value);
+ *     }
+ *     return null;
+ *   }
+ * });
+ * 
+ * @example
+ * // With lifecycle callbacks
+ * const trackedClone = deepClone(someData, {
+ *   onBeforeClone: (data, type) => {
+ *     console.log(`Starting to clone ${type}`);
+ *   },
+ *   onAfterClone: (result) => {
+ *     console.log(`Cloned ${result.type}, success: ${result.cloned}`);
+ *   }
+ * });
  */
 'use strict';
 import getDataType from './getDataType';
 
-const deepClone = <T>(data: T): T => {
-    const dataType = getDataType(data);
-    
-    if (dataType === 'Object') {
-        const newObj: Record<string | symbol, any> = {};
-        const symbols = Object.getOwnPropertySymbols(data);
-        
+export interface DeepCloneOptions {
+    cloneDate?: boolean;
+    cloneRegex?: boolean;
+    cloneSet?: boolean;
+    cloneMap?: boolean;
+    cloneObject?: boolean;
+    cloneArray?: boolean;
+    cloneElement?: boolean;
+    cloneFragment?: boolean;
+
+    /**
+     * Interceptor function. If returns a non-null value, use it as the cloning result.
+     */
+    interceptor?: <T>(data: T, dataType: string) => T | null | undefined;
+
+    /**
+     * Callback before cloning.
+     */
+    onBeforeClone?: (data: any, dataType: string) => void;
+
+    /**
+     * Callback after cloning.
+     * @param result Object containing cloning result.
+     */
+    onAfterClone?: (result: AfterCloneResult) => void;
+}
+export interface AfterCloneResult<T = any> {
+    // Cloned data
+    output: T;
+    // Original data
+    input: any;
+    // Data type
+    type: string;
+    // Whether cloning was performed
+    cloned: boolean;
+}
+//支持原始值的复制，包括Number、String、Boolean、Null
+//支持Date和Regex对象值复制（值转换）
+//支持{},[],Set和Map的遍历
+const deepClone = <T>(data: T, options: DeepCloneOptions = {}): T => {
+    const dataType = getDataType(data),
+        // Default options
+        opts = Object.assign({
+            cloneSet: true,
+            cloneMap: true,
+            cloneObject: true,
+            cloneArray: true,
+            //可重新构建
+            cloneDate: true,
+            cloneRegex: true,
+            //节点默认不复制
+            //cloneElement: false,
+            //cloneFragment: false,
+        }, options);
+
+    // Check interceptor - if it returns a value (not null/undefined), use it directly
+    if (opts.interceptor && typeof opts.interceptor === 'function') {
+        let result = opts.interceptor(data, dataType);
+        if ((result ?? false)) {
+            // Call onAfterClone if set
+            opts.onAfterClone?.({
+                output: result,
+                input: data,
+                type: dataType,
+                cloned: result !== data,
+            });
+            return result as T;
+        }
+        // If interceptor returns null/undefined, continue with normal cloning process
+    }
+
+    // Callback before cloning
+    opts.onBeforeClone?.(data, dataType);
+
+    let newData,
+        cloned = true;
+
+    if (dataType === 'Object' && opts.cloneObject) {
+        const newObj: Record<string | symbol, any> = {},
+            symbols = Object.getOwnPropertySymbols(data);
+
         // Clone regular properties
         for (const key in data) {
-            newObj[key] = deepClone((data as any)[key]);
+            newObj[key] = deepClone((data as any)[key],opts);
         }
-        
+
         // Clone Symbol properties
         if (symbols.length > 0) {
             for (const symbol of symbols) {
-                newObj[symbol] = deepClone((data as any)[symbol]);
+                newObj[symbol] = deepClone((data as any)[symbol],opts);
             }
         }
-        
-        return newObj as T;
-        
-    } else if (dataType === 'Array') {
-        return (data as any[]).map(item => deepClone(item)) as T;
-        
-    } else if (dataType === 'Date') {
-        return new Date((data as Date).getTime()) as T;
-        
-    } else if (dataType === 'RegExp') {
+        newData = newObj as T;
+    } else if (dataType === 'Array' && opts.cloneArray) {
+        newData = (data as any[]).map(item => deepClone(item,opts)) as T;
+    } else if (dataType === 'Map' && opts.cloneMap) {
+        const newMap = new Map();
+        for (const [key, value] of data as Map<any, any>) {
+            // Both Map keys and values need deep cloning
+            newMap.set(deepClone(key,opts), deepClone(value,opts));
+        }
+        newData = newMap as T;
+    } else if (dataType === 'Set' && opts.cloneSet) {
+        const newSet = new Set();
+        for (const value of data as Set<any>) {
+            // Set values need deep cloning
+            newSet.add(deepClone(value,opts));
+        }
+        newData = newSet as T;
+    } else if (dataType === 'Date' && opts.cloneDate) {
+        newData = new Date((data as Date).getTime()) as T;
+    } else if (dataType === 'RegExp' && opts.cloneRegex) {
         const regex = data as RegExp;
-        return new RegExp(regex.source, regex.flags) as T;
-        
+        newData = new RegExp(regex.source, regex.flags) as T;
+    // } else if ((dataType.includes('HTML') && opts.cloneElement) ||
+    //    (dataType === 'DocumentFragment' && opts.cloneFragment)
+    //) {
+        //Text,Comment,HTML*Element,DocumentFragment,Attr
+   //     newData = (data as any).cloneNode(true) as T;
     } else {
-        // Number, String, Boolean, Symbol,Text,Comment,Set,Map, HTML*Element, Function,Error,Promise,ArrayBuffer,Blob,File, return directly
-        return data;
+        // Number, String, Boolean, Symbol, Function,Error,Promise,ArrayBuffer,Blob,File, return directly
+        newData = data;
+        cloned = false;
     }
+    // Callback after cloning
+    opts.onAfterClone?.({
+        output: newData,
+        input: data,
+        type: dataType,
+        cloned,
+    });
+    return newData;
 };
 
 export default deepClone;

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

@@ -0,0 +1,47 @@
+/**
+ * @since Last modified: 2025/12/16 14:43:51
+ * Deep clone an array or object to a JSON-compatible structure.
+ * Converts non-serializable types like functions, symbols, Date, RegExp to plain values.
+ *
+ * @template T
+ * @param {T} data - Array or object to clone
+ * @returns {T} - New object with different memory address, in a JSON-compatible structure
+ *
+ * @example
+ * const obj = { a: '', b: 0, c: [] };
+ * const cloned = deepCloneToJSON(obj);
+ *
+ * @example
+ * const arr = [{}, {}, {}];
+ * const cloned = deepCloneToJSON(arr);
+ */
+'use strict';
+import getDataType from './getDataType';
+const deepCloneToJSON = (data) => {
+    const dataType = getDataType(data);
+    // Handle objects
+    if (dataType === 'Object') {
+        const newObj = {};
+        // Clone regular properties
+        for (const key in data) {
+            newObj[key] = deepCloneToJSON(data[key]);
+        }
+        for (const key in newObj) {
+            newObj[key] === undefined && Reflect.deleteProperty(newObj, key);
+        }
+        return newObj;
+        // Handle arrays
+    }
+    else if (dataType === 'Array') {
+        let tmp = data.map((item, index) => deepCloneToJSON(item)).filter(item => item !== undefined);
+        return tmp;
+        // Handle Date objects
+    }
+    else if (!['Number', 'String', 'Boolean', 'Null'].includes(dataType)) {
+        return undefined;
+    }
+    else {
+        return data;
+    }
+};
+export default deepCloneToJSON;