ee-core 4.1.5 → 5.0.0-beta.5

package/dist/cjs/utils/extend.js

@@ -0,0 +1,105 @@
+"use strict";
+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;
+    }
+    const plainObj = obj;
+    const hasOwnConstructor = hasOwn.call(plainObj, 'constructor');
+    const hasIsPrototypeOf = plainObj.constructor &&
+        plainObj.constructor.prototype &&
+        hasOwn.call(plainObj.constructor.prototype, 'isPrototypeOf');
+    // 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;
+    }
+    // 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) {
+        // 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) {
+    // 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) {
+        // Skip null and undefined sources
+        if (!source)
+            continue;
+        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 = 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;
+            // Deep merge: when value is a plain object, recursively merge instead of overwrite
+            if (isDeep && val && isPlainObject(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') {
+                // Non-undefined values directly overwrite; undefined values do not overwrite existing properties
+                result[key] = val;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=extend.js.map

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

@@ -0,0 +1 @@
+{"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/cjs/utils/helper.d.ts

@@ -0,0 +1,169 @@
+/**
+ * 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/cjs/utils/helper.d.ts.map

@@ -0,0 +1 @@
+{"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/cjs/utils/helper.js

@@ -0,0 +1,351 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fnDebounce = fnDebounce;
+exports.getRandomString = getRandomString;
+exports.mkdir = mkdir;
+exports.chmodPath = chmodPath;
+exports.compareVersion = compareVersion;
+exports.stringify = stringify;
+exports.validValue = validValue;
+exports.checkConfig = checkConfig;
+exports.sleep = sleep;
+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 fnMap = new Map();
+    return (fn, delayTime, isImedite, args) => {
+        const setTimer = () => {
+            const timer = setTimeout(() => {
+                fn(args);
+                clearTimeout(timer);
+                // Remove from Map after timer executes, releasing the reference
+                fnMap.delete(fn);
+            }, delayTime);
+            fnMap.set(fn, { delayTime: delayTime || 0, timer });
+        };
+        // No delay or immediate execution requested, call function directly without debounce
+        if (!delayTime || isImedite)
+            return fn(args);
+        // 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();
+    };
+}
+/**
+ * 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');
+    }
+    while (s2.length < len) {
+        s2.push('0');
+    }
+    for (let i = 0; i < len; i++) {
+        const num1 = parseInt(s1[i] || '0');
+        const num2 = parseInt(s2[i] || '0');
+        if (num1 > num2) {
+            return 1;
+        }
+        else if (num1 < num2) {
+            return -1;
+        }
+    }
+    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) => {
+        if (!ignore.includes(key)) {
+            result[key] = obj[key];
+        }
+    });
+    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 - 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}'`);
+    }
+    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);
+    }
+    else {
+        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++) {
+        const item = argv[i];
+        if (!item)
+            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 + '=';
+    for (const item of argv) {
+        if (!item)
+            continue;
+        const pos = item.indexOf(searchKey);
+        if (pos !== -1) {
+            return item.substring(pos + searchKey.length);
+        }
+    }
+    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) {
+    try {
+        return fs_1.default.statSync(filepath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=helper.js.map

package/dist/cjs/utils/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../../../src/utils/helper.ts"],"names":[],"mappings":"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"}