@codady/utils 0.0.8 → 0.0.10

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/22 20:20:47
+ * 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/22 20:20:47
+ * 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;

package/src/getUniqueId.js

@@ -0,0 +1,39 @@
+/**
+* @since Last modified: 2025/12/22 14:29:27
+ * Generates a unique identifier string
+ *
+ * The ID format is: `[prefix_]timestamp_randomBase36_extraRandom`
+ * Example outputs:
+ * - "1734597601234_abc123def4567"
+ * - "snax_1734597601235_ghi789jkl0123_8899"
+ *
+ * Features:
+ * 1. Millisecond timestamp ensures uniqueness across time
+ * 2. Base-36 random string (9 chars = ~3.5e13 possibilities)
+ * 3. Additional 4-digit random number for extra entropy
+ * 4. Optional prefix for categorization
+ *
+ * @param options.prefix - Optional prefix string for the ID (e.g., 'snax', 'user', 'doc')
+ * @param options.suffix - Optional suffix string for the ID (e.g., 'snax', 'user', 'doc')
+ * @param options.base10 - Optional 4-digit random number
+ * @param options.base36 - Optional 9-digit random charactor
+ * @returns A unique identifier string
+ */
+export const getUniqueId = (options = {}) => {
+    const prefix = options.prefix, suffix = options.suffix, base10 = options.base10, base36 = options.base36;
+    // Current timestamp in milliseconds (since Unix epoch)
+    // This provides the primary uniqueness guarantee
+    const timestamp = Date.now(), 
+    // Generate a base-36 random string (0-9, a-z)
+    // Math.random() returns a number in [0, 1), converting to base-36 gives a compact representation
+    // substring(2, 11) extracts 9 characters starting from index 2
+    //0.259854635->0.9crs03e8v2
+    base36Random = base36 ? '-' + Math.random().toString(36).substring(2, 11) : '', 
+    // Additional 4-digit random number for extra randomness
+    // This helps avoid collisions in high-frequency generation scenarios
+    base10Random = base10 ? '-' + Math.floor(Math.random() * 10000).toString().padStart(4, '0') : '', prefixString = prefix ? prefix + '-' : '', suffixString = suffix ? '-' + suffix : '';
+    // Construct the final ID string
+    // Format: [prefix_]timestamp_randomBase36_extraRandom
+    return `${prefixString}${timestamp}${base36Random}${base10Random}${suffixString}`;
+};
+export default getUniqueId;

package/src/getUniqueId.ts

@@ -0,0 +1,47 @@
+/**
+* @since Last modified: 2025/12/22 14:29:27
+ * Generates a unique identifier string
+ * 
+ * The ID format is: `[prefix_]timestamp_randomBase36_extraRandom`
+ * Example outputs:
+ * - "1734597601234_abc123def4567"
+ * - "snax_1734597601235_ghi789jkl0123_8899"
+ * 
+ * Features:
+ * 1. Millisecond timestamp ensures uniqueness across time
+ * 2. Base-36 random string (9 chars = ~3.5e13 possibilities)
+ * 3. Additional 4-digit random number for extra entropy
+ * 4. Optional prefix for categorization
+ * 
+ * @param options.prefix - Optional prefix string for the ID (e.g., 'snax', 'user', 'doc')
+ * @param options.suffix - Optional suffix string for the ID (e.g., 'snax', 'user', 'doc')
+ * @param options.base10 - Optional 4-digit random number
+ * @param options.base36 - Optional 9-digit random charactor
+ * @returns A unique identifier string
+ */
+export const getUniqueId = (options: { prefix?: string, suffix?: string, base10?: boolean,base36?: boolean } = {}): string => {
+    const prefix = options.prefix,
+        suffix = options.suffix,
+        base10 = options.base10,
+        base36 = options.base36;
+    // Current timestamp in milliseconds (since Unix epoch)
+    // This provides the primary uniqueness guarantee
+    const timestamp = Date.now(),
+
+        // Generate a base-36 random string (0-9, a-z)
+        // Math.random() returns a number in [0, 1), converting to base-36 gives a compact representation
+        // substring(2, 11) extracts 9 characters starting from index 2
+        //0.259854635->0.9crs03e8v2
+        base36Random = base36?'-' +Math.random().toString(36).substring(2, 11):'',
+        // Additional 4-digit random number for extra randomness
+        // This helps avoid collisions in high-frequency generation scenarios
+        base10Random = base10 ? '-' + Math.floor(Math.random() * 10000).toString().padStart(4, '0') : '',
+        prefixString = prefix ? prefix + '-' : '',
+        suffixString = suffix ? '-' + suffix : '';
+
+    // Construct the final ID string
+    // Format: [prefix_]timestamp_randomBase36_extraRandom
+    return `${prefixString}${timestamp}${base36Random}${base10Random}${suffixString}`;
+};
+
+export default getUniqueId;

package/src/mapMutableMethods.js

@@ -0,0 +1,5 @@
+/**
+ * Available Map mutation methods
+ */
+export const mapMutableMethods = ['set', 'delete', 'clear'];
+export default mapMutableMethods;

package/src/mapMutableMethods.ts

@@ -0,0 +1,15 @@
+/**
+ * @since Last modified: 2025/12/22 17:16:39
+ * 
+ */
+/**
+ * Available mutation methods for Map objects
+ */
+export type MapMutationNames = 'set' | 'delete' | 'clear';
+
+/**
+ * Available Map mutation methods
+ */
+export const mapMutableMethods: MapMutationNames[] = ['set', 'delete', 'clear'];
+
+export default mapMutableMethods;

package/src/mutableMethods.js

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

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

@@ -0,0 +1,5 @@
+/**
+ * Available Set mutation methods
+ */
+export const setMutableMethods = ['add', 'delete', 'clear'];
+export default setMutableMethods;

package/src/setMutableMethods.js

@@ -0,0 +1,5 @@
+/**
+ * Available Set mutation methods
+ */
+export const setMutableMethods = ['add', 'delete', 'clear'];
+export default setMutableMethods;

package/src/setMutableMethods.ts

@@ -0,0 +1,14 @@
+/**
+ * @since Last modified: 2025/12/22 17:15:21
+ * 
+ */
+/**
+ * Available mutation methods for Set objects
+ */
+export type SetMutationNames = 'add' | 'delete' | 'clear';
+/**
+ * Available Set mutation methods
+ */
+export const setMutableMethods: SetMutationNames[] = ['add', 'delete', 'clear'];
+
+export default setMutableMethods;