ee-core 5.0.0-beta.2 → 5.0.0-beta.5

package/dist/esm/utils/extend.js

@@ -3,6 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.extend = extend;
 const hasOwn = Object.prototype.hasOwnProperty;
 const toStr = Object.prototype.toString;
+/**
+ * Determine if a value is a plain object
+ *
+ * A plain object is one created via {}, new Object(), or Object.create(null).
+ * Excludes built-in type instances (Date, RegExp, Buffer, etc.) and custom class instances.
+ *
+ * Judgment criteria:
+ * 1. toString returns '[object Object]'
+ * 2. No own constructor or constructor.prototype has isPrototypeOf
+ * 3. Last enumerable property is an own property (leveraging JS engine behavior of enumerating own properties first)
+ *
+ * @param obj - Value to check
+ * @returns true if the value is a plain object
+ */
 function isPlainObject(obj) {
     if (!obj || toStr.call(obj) !== '[object Object]') {
         return false;
@@ -12,46 +26,80 @@ function isPlainObject(obj) {
     const hasIsPrototypeOf = plainObj.constructor &&
         plainObj.constructor.prototype &&
         hasOwn.call(plainObj.constructor.prototype, 'isPrototypeOf');
-    // Not own constructor property must be Object
+    // If has constructor but it's not an own property, and no isPrototypeOf on the prototype chain,
+    // the constructor comes from prototype chain inheritance, not a plain object
     if (plainObj.constructor && !hasOwnConstructor && !hasIsPrototypeOf) {
         return false;
     }
-    // Own properties are enumerated firstly, so to speed up,
-    // if last one is own, then all properties are own.
+    // Leverage JS engine behavior of enumerating own properties before inherited ones:
+    // If the last enumerable property is own, then all enumerable properties are own
     let key;
     for (key in plainObj) {
-        // empty
+        // Iterate to the last item
     }
     return typeof key === 'undefined' || hasOwn.call(plainObj, key);
 }
+/**
+ * Merge object properties
+ *
+ * Merges properties from multiple source objects into the target object, supporting shallow and deep merge.
+ * This is the core implementation for framework configuration layer merging.
+ *
+ * Merge rules:
+ * - Shallow merge (deep=false): source properties directly overwrite target properties
+ * - Deep merge (deep=true): plain objects are recursively merged, non-plain-objects are directly overwritten
+ * - Skip __proto__ property, preventing prototype chain pollution
+ * - Skip undefined values, will not overwrite existing properties with undefined
+ * - Detect self-references (target === val), preventing infinite recursion
+ *
+ * @param deep - Whether to deep merge, can be a boolean or an object with a deep property
+ * @param target - Target object, merge result will be written to this object
+ * @param sources - One or more source objects, merged into target in order
+ * @returns Merged target object
+ *
+ * @example
+ * ```ts
+ * // Shallow merge
+ * extend(false, { a: 1 }, { a: 2, b: 3 }); // { a: 2, b: 3 }
+ *
+ * // Deep merge
+ * extend(true, { a: { x: 1 } }, { a: { y: 2 } }); // { a: { x: 1, y: 2 } }
+ *
+ * // Using options object
+ * extend({ deep: true }, { a: { x: 1 } }, { a: { y: 2 } }); // { a: { x: 1, y: 2 } }
+ * ```
+ */
 function extend(deep, target, ...sources) {
-    // Handle a deep copy situation
+    // Use Record<string, unknown> for internal mutations to avoid
+    // "generic type T can only be indexed for reading" error
+    const result = target;
     const isDeep = typeof deep === 'boolean' ? deep : deep?.deep ?? false;
     for (const source of sources) {
-        // Only deal with non-null/undefined values
+        // Skip null and undefined sources
         if (!source)
             continue;
-        // Extend the base object
-        for (const key of Object.keys(source)) {
+        const src = source;
+        for (const key of Object.keys(src)) {
+            // Prevent prototype chain pollution: __proto__ property is not merged
             if (key === '__proto__')
                 continue;
-            const val = source[key];
-            const src = target[key];
-            // Prevent never-ending loop
-            if (target === val)
+            const val = src[key];
+            const existing = result[key];
+            // Detect self-reference: skip when target and val are the same reference, preventing infinite recursion
+            if (result === val)
                 continue;
-            // Recurse if we're merging plain objects
+            // Deep merge: when value is a plain object, recursively merge instead of overwrite
             if (isDeep && val && isPlainObject(val)) {
-                const clone = src && isPlainObject(src) ? src : {};
-                target[key] = extend(true, clone, val);
+                // If target's corresponding property is also a plain object, recursively merge on the original object; otherwise create a new object
+                const clone = existing && isPlainObject(existing) ? existing : {};
+                result[key] = extend(true, clone, val);
             }
             else if (typeof val !== 'undefined') {
-                // Don't bring in undefined values
-                target[key] = val;
+                // Non-undefined values directly overwrite; undefined values do not overwrite existing properties
+                result[key] = val;
             }
         }
     }
-    // Return the modified object
-    return target;
+    return result;
 }
 //# sourceMappingURL=extend.js.map

package/dist/esm/utils/extend.js.map

@@ -1 +1 @@
-{"version":3,"file":"extend.js","sourceRoot":"","sources":["../../../src/utils/extend.ts"],"names":[],"mappings":";;AAgCA,wBAgCC;AA9DD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC;AAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;AAExC,SAAS,aAAa,CAAC,GAAY;IACjC,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,iBAAiB,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,GAA8B,CAAC;IAChD,MAAM,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAC/D,MAAM,gBAAgB,GACpB,QAAQ,CAAC,WAAW;QACnB,QAAQ,CAAC,WAAW,CAAC,SAAqC;QAC3D,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IAE/D,8CAA8C;IAC9C,IAAI,QAAQ,CAAC,WAAW,IAAI,CAAC,iBAAiB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yDAAyD;IACzD,mDAAmD;IACnD,IAAI,GAAuB,CAAC;IAC5B,KAAK,GAAG,IAAI,QAAQ,EAAE,CAAC;QACrB,QAAQ;IACV,CAAC;IAED,OAAO,OAAO,GAAG,KAAK,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAClE,CAAC;AAED,SAAgB,MAAM,CACpB,IAA6B,EAC7B,MAA+B,EAC/B,GAAG,OAA0D;IAE7D,+BAA+B;IAC/B,MAAM,MAAM,GAAG,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,KAAK,CAAC;IAEtE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,2CAA2C;QAC3C,IAAI,CAAC,MAAM;YAAE,SAAS;QAEtB,yBAAyB;QACzB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACtC,IAAI,GAAG,KAAK,WAAW;gBAAE,SAAS;YAClC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,4BAA4B;YAC5B,IAAI,MAAM,KAAK,GAAG;gBAAE,SAAS;YAC7B,yCAAyC;YACzC,IAAI,MAAM,IAAI,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxC,MAAM,KAAK,GAAG,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,KAAgC,EAAE,GAA8B,CAAC,CAAC;YAC/F,CAAC;iBAAM,IAAI,OAAO,GAAG,KAAK,WAAW,EAAE,CAAC;gBACtC,kCAAkC;gBAClC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IAED,6BAA6B;IAC7B,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"extend.js","sourceRoot":"","sources":["../../../src/utils/extend.ts"],"names":[],"mappings":";;AA0FA,wBAmCC;AA9GD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC;AAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC;AAExC;;;;;;;;;;;;;GAaG;AACH,SAAS,aAAa,CAAC,GAAY;IACjC,IAAI,CAAC,GAAG,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,iBAAiB,EAAE,CAAC;QAClD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,QAAQ,GAAG,GAA8B,CAAC;IAChD,MAAM,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;IAC/D,MAAM,gBAAgB,GACpB,QAAQ,CAAC,WAAW;QACnB,QAAQ,CAAC,WAAW,CAAC,SAAqC;QAC3D,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;IAE/D,gGAAgG;IAChG,6EAA6E;IAC7E,IAAI,QAAQ,CAAC,WAAW,IAAI,CAAC,iBAAiB,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACpE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mFAAmF;IACnF,iFAAiF;IACjF,IAAI,GAAuB,CAAC;IAC5B,KAAK,GAAG,IAAI,QAAQ,EAAE,CAAC;QACrB,2BAA2B;IAC7B,CAAC;IAED,OAAO,OAAO,GAAG,KAAK,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAgB,MAAM,CACpB,IAA6B,EAC7B,MAAS,EACT,GAAG,OAAuE;IAE1E,8DAA8D;IAC9D,yDAAyD;IACzD,MAAM,MAAM,GAAG,MAAiC,CAAC;IACjD,MAAM,MAAM,GAAG,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,KAAK,CAAC;IAEtE,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,kCAAkC;QAClC,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,GAAG,GAAG,MAAiC,CAAC;QAE9C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACnC,sEAAsE;YACtE,IAAI,GAAG,KAAK,WAAW;gBAAE,SAAS;YAClC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;YACrB,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC7B,wGAAwG;YACxG,IAAI,MAAM,KAAK,GAAG;gBAAE,SAAS;YAC7B,mFAAmF;YACnF,IAAI,MAAM,IAAI,GAAG,IAAI,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;gBACxC,qIAAqI;gBACrI,MAAM,KAAK,GAAG,QAAQ,IAAI,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBAClE,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,KAAgC,EAAE,GAA8B,CAAC,CAAC;YAC/F,CAAC;iBAAM,IAAI,OAAO,GAAG,KAAK,WAAW,EAAE,CAAC;gBACtC,iGAAiG;gBACjG,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;YACpB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAW,CAAC;AACrB,CAAC"}

package/dist/esm/utils/helper.d.ts

@@ -1,16 +1,169 @@
-export declare function fnDebounce(): (fn: (args?: unknown) => void, delayTime?: number, isImediate?: boolean, args?: unknown) => void;
+/**
+ * Create debounce function factory
+ *
+ * Returns a debounce wrapper that applies debounce control to the passed function.
+ *
+ * Debounce mechanism:
+ * - When delayTime is 0 or isImedite is true, the function executes immediately (no debounce)
+ * - Otherwise, sets a timer for delayed execution; if the same function is called again before
+ *   the timer fires, the previous timer is cancelled and reset, ensuring the function only
+ *   executes once after the last call's delayTime milliseconds
+ * - Uses Map with function reference as key to store timers, supporting debounce for multiple
+ *   different functions simultaneously
+ * - Timers are automatically cleaned from the Map after firing, preventing memory leaks
+ *
+ * @returns Debounce wrapper function
+ * @param fn - Target function to debounce
+ * @param delayTime - Delay time (ms), 0 or omitted executes immediately
+ * @param isImedite - Whether to execute immediately, true skips debounce and calls directly
+ * @param args - Arguments to pass to the target function
+ *
+ * @example
+ * ```ts
+ * const debounce = fnDebounce();
+ * // Debounced call: repeated calls within 300ms only execute the last one
+ * debounce(myFunction, 300, false, data);
+ * // Immediate execution: bypasses debounce
+ * debounce(myFunction, 0, true, data);
+ * ```
+ */
+export declare function fnDebounce(): (fn: (args?: unknown) => void, delayTime?: number, isImedite?: boolean, args?: unknown) => void;
+/**
+ * Generate a random string
+ *
+ * Generates an approximately 10-character alphanumeric string based on Math.random().
+ * Suitable for generating temporary identifiers, not for security scenarios.
+ *
+ * @returns Random string (e.g. 'x3k9m2a1b5')
+ */
 export declare function getRandomString(): string;
+/**
+ * Recursively create directory
+ *
+ * No error if directory already exists, equivalent to mkdir -p.
+ *
+ * @param filepath - Directory path to create
+ * @param opt - Optional parameters, mode specifies directory permissions
+ */
 export declare function mkdir(filepath: string, opt?: {
     mode?: number;
 }): void;
+/**
+ * Recursively modify file and directory permissions
+ *
+ * Traverses all files and subdirectories under the specified path, recursively modifying permissions.
+ * Modifies child file/directory permissions first, then the root directory's own permissions.
+ *
+ * @param filepath - Target directory path
+ * @param mode - Permission value (e.g. 0o755)
+ */
 export declare function chmodPath(filepath: string, mode: number): void;
+/**
+ * Compare two semantic version numbers
+ *
+ * Splits version numbers by '.' and compares each segment numerically.
+ * Pads shorter versions with 0s for alignment.
+ *
+ * @param v1 - First version number (e.g. '1.2.3')
+ * @param v2 - Second version number (e.g. '1.3.0')
+ * @returns 1 if v1 > v2, -1 if v1 < v2, 0 if equal
+ */
 export declare function compareVersion(v1: string, v2: string): number;
+/**
+ * Serialize object to JSON string
+ *
+ * Unlike JSON.stringify, can exclude specified fields to hide sensitive information.
+ *
+ * @param obj - Object to serialize
+ * @param ignore - List of property names to exclude
+ * @returns Filtered JSON string
+ */
 export declare function stringify(obj: Record<string, unknown>, ignore?: string[]): string;
+/**
+ * Check if value is valid
+ *
+ * Determines if the value is non-null, non-undefined, and non-empty string.
+ * Commonly used for configuration validation and parameter validity checks.
+ *
+ * @param value - Value to check
+ * @returns true if value is valid, false if value is null/undefined/empty string
+ */
 export declare function validValue(value: unknown): boolean;
+/**
+ * Check if configuration file exists
+ *
+ * Checks if the specified path exists as a file under the project root directory,
+ * used for pre-checking before configuration loading.
+ *
+ * @param prop - File path relative to project root
+ * @returns true if file exists
+ */
 export declare function checkConfig(prop: string): boolean;
+/**
+ * Async sleep
+ *
+ * Returns a Promise that resolves after the specified milliseconds.
+ * Releases the event loop during sleep, allowing other async tasks to execute.
+ *
+ * @param ms - Sleep time (ms)
+ * @returns Promise that resolves after ms milliseconds
+ */
 export declare function sleep(ms: number): Promise<void>;
+/**
+ * Synchronous blocking sleep (does not release event loop)
+ *
+ * Used in scenarios requiring synchronous waiting, blocks the current thread until
+ * the specified time is reached.
+ * Implementation strategy:
+ * 1. Prefer Atomics.wait: zero CPU usage, achieves true thread blocking via
+ *    SharedArrayBuffer; Atomics.wait automatically unblocks after timeout
+ * 2. Falls back to while loop busy wait: CPU spins but achieves the same blocking effect
+ *
+ * Suitable for: child process initialization waiting, Electron main process synchronous timing control
+ * Not suitable for: renderer process (will freeze UI)
+ *
+ * @param ms - Sleep time (ms), must be a non-negative finite number
+ * @throws TypeError - ms is not of type 'number'
+ * @throws RangeError - ms is not in the range [0, Infinity)
+ */
 export declare function systemSleep(ms: number): void;
+/**
+ * Replace a specified key's value in command line arguments
+ *
+ * Finds key=value format parameters in the argv array and replaces the value part.
+ * Commonly used to dynamically modify parameter values when starting child processes.
+ *
+ * @param argv - Command line argument array
+ * @param key - Parameter key name to replace
+ * @param value - New parameter value
+ * @returns Modified argv array
+ *
+ * @example
+ * ```ts
+ * replaceArgsValue(['--port=8080', '--env=dev'], 'port', '9090')
+ * // => ['--port=9090', '--env=dev']
+ * ```
+ */
 export declare function replaceArgsValue(argv: string[], key: string, value: string): string[];
+/**
+ * Get the value of a specified key from command line argument array
+ *
+ * First parses standard format parameters (--key value) via pargv,
+ * then falls back to scanning bare key-value pairs (key=value format, no -- prefix).
+ *
+ * @param argv - Command line argument array
+ * @param key - Key name to look up
+ * @returns Value corresponding to the key, or undefined if not found
+ */
 export declare function getValueFromArgv(argv: string[], key: string): unknown;
+/**
+ * Check if a file exists
+ *
+ * Determines if the path is a file via fs.statSync.
+ * Any error (file not found, insufficient permissions, etc.) returns false.
+ *
+ * @param filepath - File path
+ * @returns true if file exists, false if it doesn't exist or isn't a file
+ */
 export declare function fileIsExist(filepath: string): boolean;
 //# sourceMappingURL=helper.d.ts.map

package/dist/esm/utils/helper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../src/utils/helper.ts"],"names":[],"mappings":"AAMA,wBAAgB,UAAU,IAAI,CAC5B,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,EAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,OAAO,EACpB,IAAI,CAAC,EAAE,OAAO,KACX,IAAI,CAwBR;AAGD,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAGD,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAEzE;AAGD,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAa9D;AAGD,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAwB7D;AAGD,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,MAAM,CAQrF;AAGD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAElD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAcD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAY5C;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAYrF;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAmBrE;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAErD"}
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../../../src/utils/helper.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,IAAI,CAC5B,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,EAC5B,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,OAAO,EACnB,IAAI,CAAC,EAAE,OAAO,KACX,IAAI,CAyBR;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,IAAI,CAEzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAe9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAyB7D;AAED;;;;;;;;GAQG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAE,MAAM,EAAO,GAAG,MAAM,CAQrF;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAElD;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGjD;AAED;;;;;;;;GAQG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AA8BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAa5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAarF;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAerE;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAMrD"}

package/dist/esm/utils/helper.js

@@ -16,62 +16,131 @@ exports.systemSleep = systemSleep;
 exports.replaceArgsValue = replaceArgsValue;
 exports.getValueFromArgv = getValueFromArgv;
 exports.fileIsExist = fileIsExist;
+/**
+ * @module utils/helper
+ * @description Common utility function collection. Provides debounce, sleep, version comparison,
+ * file operations, command line argument processing and other common functionalities
+ * for framework modules and business code.
+ */
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const pargv_js_1 = require("./pargv.js");
 const _basePath = process.cwd();
+/**
+ * Create debounce function factory
+ *
+ * Returns a debounce wrapper that applies debounce control to the passed function.
+ *
+ * Debounce mechanism:
+ * - When delayTime is 0 or isImedite is true, the function executes immediately (no debounce)
+ * - Otherwise, sets a timer for delayed execution; if the same function is called again before
+ *   the timer fires, the previous timer is cancelled and reset, ensuring the function only
+ *   executes once after the last call's delayTime milliseconds
+ * - Uses Map with function reference as key to store timers, supporting debounce for multiple
+ *   different functions simultaneously
+ * - Timers are automatically cleaned from the Map after firing, preventing memory leaks
+ *
+ * @returns Debounce wrapper function
+ * @param fn - Target function to debounce
+ * @param delayTime - Delay time (ms), 0 or omitted executes immediately
+ * @param isImedite - Whether to execute immediately, true skips debounce and calls directly
+ * @param args - Arguments to pass to the target function
+ *
+ * @example
+ * ```ts
+ * const debounce = fnDebounce();
+ * // Debounced call: repeated calls within 300ms only execute the last one
+ * debounce(myFunction, 300, false, data);
+ * // Immediate execution: bypasses debounce
+ * debounce(myFunction, 0, true, data);
+ * ```
+ */
 function fnDebounce() {
-    const fnObject = {};
-    let timer;
-    return (fn, delayTime, isImediate, args) => {
+    const fnMap = new Map();
+    return (fn, delayTime, isImedite, args) => {
         const setTimer = () => {
-            timer = setTimeout(() => {
+            const timer = setTimeout(() => {
                 fn(args);
                 clearTimeout(timer);
-                delete fnObject[fn];
+                // Remove from Map after timer executes, releasing the reference
+                fnMap.delete(fn);
             }, delayTime);
-            fnObject[fn] = { delayTime: delayTime || 0, timer };
+            fnMap.set(fn, { delayTime: delayTime || 0, timer });
         };
-        if (!delayTime || isImediate)
+        // No delay or immediate execution requested, call function directly without debounce
+        if (!delayTime || isImedite)
             return fn(args);
-        if (fnObject[fn]) {
-            clearTimeout(timer);
-            setTimer();
-        }
-        else {
-            setTimer();
+        // Same function has a pending timer, cancel the old one and reset (core debounce logic)
+        const existing = fnMap.get(fn);
+        if (existing) {
+            clearTimeout(existing.timer);
         }
+        setTimer();
     };
 }
-// 随机10位字符串
+/**
+ * Generate a random string
+ *
+ * Generates an approximately 10-character alphanumeric string based on Math.random().
+ * Suitable for generating temporary identifiers, not for security scenarios.
+ *
+ * @returns Random string (e.g. 'x3k9m2a1b5')
+ */
 function getRandomString() {
     return Math.random().toString(36).substring(2);
 }
-// 创建文件夹
+/**
+ * Recursively create directory
+ *
+ * No error if directory already exists, equivalent to mkdir -p.
+ *
+ * @param filepath - Directory path to create
+ * @param opt - Optional parameters, mode specifies directory permissions
+ */
 function mkdir(filepath, opt = {}) {
     fs_1.default.mkdirSync(filepath, { recursive: true, ...opt });
 }
-// 修改文件权限
+/**
+ * Recursively modify file and directory permissions
+ *
+ * Traverses all files and subdirectories under the specified path, recursively modifying permissions.
+ * Modifies child file/directory permissions first, then the root directory's own permissions.
+ *
+ * @param filepath - Target directory path
+ * @param mode - Permission value (e.g. 0o755)
+ */
 function chmodPath(filepath, mode) {
     if (fs_1.default.existsSync(filepath)) {
         const files = fs_1.default.readdirSync(filepath);
         files.forEach((file) => {
             const curPath = path_1.default.join(filepath, file);
             if (fs_1.default.statSync(curPath).isDirectory()) {
+                // Recursively process subdirectories
                 chmodPath(curPath, mode);
             }
             else {
                 fs_1.default.chmodSync(curPath, mode);
             }
         });
+        // Finally modify the directory's own permissions
         fs_1.default.chmodSync(filepath, mode);
     }
 }
-// 版本号比较
+/**
+ * Compare two semantic version numbers
+ *
+ * Splits version numbers by '.' and compares each segment numerically.
+ * Pads shorter versions with 0s for alignment.
+ *
+ * @param v1 - First version number (e.g. '1.2.3')
+ * @param v2 - Second version number (e.g. '1.3.0')
+ * @returns 1 if v1 > v2, -1 if v1 < v2, 0 if equal
+ */
 function compareVersion(v1, v2) {
     const s1 = v1.split('.');
     const s2 = v2.split('.');
     const len = Math.max(s1.length, s2.length);
+    // Pad shorter version with zeros, e.g. '1.2' becomes '1.2.0'
     while (s1.length < len) {
         s1.push('0');
     }
@@ -90,7 +159,15 @@ function compareVersion(v1, v2) {
     }
     return 0;
 }
-// 序列化对象
+/**
+ * Serialize object to JSON string
+ *
+ * Unlike JSON.stringify, can exclude specified fields to hide sensitive information.
+ *
+ * @param obj - Object to serialize
+ * @param ignore - List of property names to exclude
+ * @returns Filtered JSON string
+ */
 function stringify(obj, ignore = []) {
     const result = {};
     Object.keys(obj).forEach((key) => {
@@ -100,27 +177,86 @@ function stringify(obj, ignore = []) {
     });
     return JSON.stringify(result);
 }
-// 是否有效值
+/**
+ * Check if value is valid
+ *
+ * Determines if the value is non-null, non-undefined, and non-empty string.
+ * Commonly used for configuration validation and parameter validity checks.
+ *
+ * @param value - Value to check
+ * @returns true if value is valid, false if value is null/undefined/empty string
+ */
 function validValue(value) {
     return value !== undefined && value !== null && value !== '';
 }
+/**
+ * Check if configuration file exists
+ *
+ * Checks if the specified path exists as a file under the project root directory,
+ * used for pre-checking before configuration loading.
+ *
+ * @param prop - File path relative to project root
+ * @returns true if file exists
+ */
 function checkConfig(prop) {
     const filepath = path_1.default.join(_basePath, prop);
     return fs_1.default.existsSync(filepath);
 }
+/**
+ * Async sleep
+ *
+ * Returns a Promise that resolves after the specified milliseconds.
+ * Releases the event loop during sleep, allowing other async tasks to execute.
+ *
+ * @param ms - Sleep time (ms)
+ * @returns Promise that resolves after ms milliseconds
+ */
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Naive synchronous sleep implementation (polling wait)
+ *
+ * Continuously checks time via a while loop, high CPU usage.
+ * Only used as a fallback when Atomics.wait is unavailable.
+ *
+ * @param ms - Sleep time (ms)
+ */
 const sleepNaive = (ms) => {
     const endTime = Date.now() + ms;
     while (endTime > Date.now()) {
-        /* sleeping */
+        /* sleeping - busy wait, CPU spinning */
     }
 };
+/**
+ * Atomic synchronous sleep implementation
+ *
+ * Uses Atomics.wait on a SharedArrayBuffer to block the current thread,
+ * a truly synchronous blocking approach that does not consume CPU.
+ * Requires Node.js environment with SharedArrayBuffer and Atomics support.
+ *
+ * @param ms - Sleep time (ms), Atomics.wait automatically unblocks after timeout
+ */
 const sleepAtomic = (ms) => {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 };
-// 同步阻塞休眠（不释放事件循环）
+/**
+ * Synchronous blocking sleep (does not release event loop)
+ *
+ * Used in scenarios requiring synchronous waiting, blocks the current thread until
+ * the specified time is reached.
+ * Implementation strategy:
+ * 1. Prefer Atomics.wait: zero CPU usage, achieves true thread blocking via
+ *    SharedArrayBuffer; Atomics.wait automatically unblocks after timeout
+ * 2. Falls back to while loop busy wait: CPU spins but achieves the same blocking effect
+ *
+ * Suitable for: child process initialization waiting, Electron main process synchronous timing control
+ * Not suitable for: renderer process (will freeze UI)
+ *
+ * @param ms - Sleep time (ms), must be a non-negative finite number
+ * @throws TypeError - ms is not of type 'number'
+ * @throws RangeError - ms is not in the range [0, Infinity)
+ */
 function systemSleep(ms) {
     if (typeof ms !== 'number') {
         throw new TypeError(`systemSleep: ms is not of type 'number'. Given: ${ms} of type '${typeof ms}'`);
@@ -128,6 +264,7 @@ function systemSleep(ms) {
     if (!(ms >= 0 && ms < Infinity)) {
         throw new RangeError(`systemSleep: ms must be in the range [0, Infinity). Given: ${ms}`);
     }
+    // Prefer Atomics approach for zero CPU usage; otherwise fall back to busy wait
     if (typeof SharedArrayBuffer !== 'undefined' && typeof Atomics !== 'undefined') {
         sleepAtomic(ms);
     }
@@ -135,6 +272,23 @@ function systemSleep(ms) {
         sleepNaive(ms);
     }
 }
+/**
+ * Replace a specified key's value in command line arguments
+ *
+ * Finds key=value format parameters in the argv array and replaces the value part.
+ * Commonly used to dynamically modify parameter values when starting child processes.
+ *
+ * @param argv - Command line argument array
+ * @param key - Parameter key name to replace
+ * @param value - New parameter value
+ * @returns Modified argv array
+ *
+ * @example
+ * ```ts
+ * replaceArgsValue(['--port=8080', '--env=dev'], 'port', '9090')
+ * // => ['--port=9090', '--env=dev']
+ * ```
+ */
 function replaceArgsValue(argv, key, value) {
     const searchKey = key + '=';
     for (let i = 0; i < argv.length; i++) {
@@ -143,32 +297,55 @@ function replaceArgsValue(argv, key, value) {
             continue;
         const pos = item.indexOf(searchKey);
         if (pos !== -1) {
+            // Keep the key= prefix, only replace the value after it
             argv[i] = item.substring(0, pos + searchKey.length) + value;
             break;
         }
     }
     return argv;
 }
+/**
+ * Get the value of a specified key from command line argument array
+ *
+ * First parses standard format parameters (--key value) via pargv,
+ * then falls back to scanning bare key-value pairs (key=value format, no -- prefix).
+ *
+ * @param argv - Command line argument array
+ * @param key - Key name to look up
+ * @returns Value corresponding to the key, or undefined if not found
+ */
 function getValueFromArgv(argv, key) {
     const argvObj = (0, pargv_js_1.parseArgv)(argv);
     if (Object.prototype.hasOwnProperty.call(argvObj, key)) {
         return argvObj[key];
     }
+    // Fallback strategy: scan bare key-value pairs without -- prefix
     const searchKey = key + '=';
-    let value;
-    for (let i = 0; i < argv.length; i++) {
-        const item = argv[i];
+    for (const item of argv) {
         if (!item)
             continue;
         const pos = item.indexOf(searchKey);
         if (pos !== -1) {
-            value = item.substring(pos + searchKey.length);
-            break;
+            return item.substring(pos + searchKey.length);
         }
     }
-    return value;
+    return undefined;
 }
+/**
+ * Check if a file exists
+ *
+ * Determines if the path is a file via fs.statSync.
+ * Any error (file not found, insufficient permissions, etc.) returns false.
+ *
+ * @param filepath - File path
+ * @returns true if file exists, false if it doesn't exist or isn't a file
+ */
 function fileIsExist(filepath) {
-    return fs_1.default.existsSync(filepath) && fs_1.default.statSync(filepath).isFile();
+    try {
+        return fs_1.default.statSync(filepath).isFile();
+    }
+    catch {
+        return false;
+    }
 }
 //# sourceMappingURL=helper.js.map