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

package/dist/esm/core/utils/timing.d.ts

@@ -1,17 +1,64 @@
+/**
+ * @module core/utils/timing
+ * @description Timing utility. Used to record the loading duration of each framework stage for
+ * performance analysis and debugging. Used in ConfigLoader and ControllerLoader to record
+ * timing for stages like "Load Config", "Load Controller", etc.
+ */
 import type { TimingItem } from '../../types/index.js';
 declare const MAP: unique symbol;
 declare const LIST: unique symbol;
+/**
+ * Timing — Timer
+ *
+ * Usage:
+ * ```ts
+ * const timing = new Timing();
+ * timing.start('Load Controller');
+ * // ... perform loading
+ * timing.end('Load Controller');
+ * const items = timing.toJSON(); // Get all timing records
+ * ```
+ *
+ * Supports nested timing. Repeatedly calling start with the same name will automatically end the previous one first.
+ */
 export declare class Timing {
     private _enable;
+    /** Mapping of timing item names to timing items, for quick lookup and end() */
     private [MAP];
+    /** Chronologically ordered list of timing items */
     private [LIST];
     constructor();
+    /**
+     * Initialize: record process start time and script start execution time
+     */
     init(): void;
+    /**
+     * Start timing
+     *
+     * @param name - Timing item name
+     * @param start - Custom start timestamp (milliseconds); uses current time if not provided
+     * @returns Timing item object; if an item with the same name already exists, the previous one is ended first
+     */
     start(name: string, start?: number): TimingItem | undefined;
+    /**
+     * End timing
+     *
+     * @param name - Timing item name (must be started first)
+     * @returns Timing item object (including duration)
+     * @throws Throws an error when the timing item does not exist
+     */
     end(name: string): TimingItem | undefined;
+    /** Enable timing */
     enable(): void;
+    /** Disable timing */
     disable(): void;
+    /** Clear all timing records */
     clear(): void;
+    /**
+     * Export as JSON-formatted timing records
+     *
+     * @returns Chronologically ordered list of timing items
+     */
     toJSON(): TimingItem[];
 }
 export {};

package/dist/esm/core/utils/timing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../../../src/core/utils/timing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,QAAA,MAAM,GAAG,eAAuB,CAAC;AACjC,QAAA,MAAM,IAAI,eAAwB,CAAC;AAEnC,qBAAa,MAAM;IACjB,OAAO,CAAC,OAAO,CAAQ;IACvB,OAAO,CAAC,CAAC,GAAG,CAAC,CAA0B;IACvC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAe;;IAQ7B,IAAI,IAAI,IAAI;IAaZ,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAkB3D,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAYzC,MAAM,IAAI,IAAI;IAId,OAAO,IAAI,IAAI;IAIf,KAAK,IAAI,IAAI;IAKb,MAAM,IAAI,UAAU,EAAE;CAGvB"}
+{"version":3,"file":"timing.d.ts","sourceRoot":"","sources":["../../../../src/core/utils/timing.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEvD,QAAA,MAAM,GAAG,eAAuB,CAAC;AACjC,QAAA,MAAM,IAAI,eAAwB,CAAC;AAEnC;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,OAAO,CAAQ;IACvB,+EAA+E;IAC/E,OAAO,CAAC,CAAC,GAAG,CAAC,CAA0B;IACvC,mDAAmD;IACnD,OAAO,CAAC,CAAC,IAAI,CAAC,CAAe;;IAQ7B;;OAEG;IACH,IAAI,IAAI,IAAI;IAaZ;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAmB3D;;;;;;OAMG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAYzC,oBAAoB;IACpB,MAAM,IAAI,IAAI;IAId,qBAAqB;IACrB,OAAO,IAAI,IAAI;IAIf,+BAA+B;IAC/B,KAAK,IAAI,IAAI;IAKb;;;;OAIG;IACH,MAAM,IAAI,UAAU,EAAE;CAGvB"}

package/dist/esm/core/utils/timing.js

@@ -3,6 +3,20 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Timing = void 0;
 const MAP = Symbol('Timing#map');
 const LIST = Symbol('Timing#list');
+/**
+ * Timing — Timer
+ *
+ * Usage:
+ * ```ts
+ * const timing = new Timing();
+ * timing.start('Load Controller');
+ * // ... perform loading
+ * timing.end('Load Controller');
+ * const items = timing.toJSON(); // Get all timing records
+ * ```
+ *
+ * Supports nested timing. Repeatedly calling start with the same name will automatically end the previous one first.
+ */
 class Timing {
     constructor() {
         this._enable = true;
@@ -10,20 +24,31 @@ class Timing {
         this[LIST] = [];
         this.init();
     }
+    /**
+     * Initialize: record process start time and script start execution time
+     */
     init() {
-        // process start time
+        // Record Node.js process start time (current time - process uptime)
         this.start('Process Start', Date.now() - Math.floor(process.uptime() * 1000));
         this.end('Process Start');
+        // If scriptStartTime exists (provided by some runtimes), record script start time
         const proc = process;
         if (typeof proc.scriptStartTime === 'number') {
-            // js script start execute time
             this.start('Script Start', proc.scriptStartTime);
             this.end('Script Start');
         }
     }
+    /**
+     * Start timing
+     *
+     * @param name - Timing item name
+     * @param start - Custom start timestamp (milliseconds); uses current time if not provided
+     * @returns Timing item object; if an item with the same name already exists, the previous one is ended first
+     */
     start(name, start) {
         if (!name || !this._enable)
             return undefined;
+        // If a timing item with the same name already exists, end the previous one first
         if (this[MAP].has(name))
             this.end(name);
         const item = {
@@ -38,6 +63,13 @@ class Timing {
         this[LIST].push(item);
         return item;
     }
+    /**
+     * End timing
+     *
+     * @param name - Timing item name (must be started first)
+     * @returns Timing item object (including duration)
+     * @throws Throws an error when the timing item does not exist
+     */
     end(name) {
         if (!name || !this._enable)
             return undefined;
@@ -49,16 +81,24 @@ class Timing {
         item.duration = item.end - item.start;
         return item;
     }
+    /** Enable timing */
     enable() {
         this._enable = true;
     }
+    /** Disable timing */
     disable() {
         this._enable = false;
     }
+    /** Clear all timing records */
     clear() {
         this[MAP].clear();
         this[LIST] = [];
     }
+    /**
+     * Export as JSON-formatted timing records
+     *
+     * @returns Chronologically ordered list of timing items
+     */
     toJSON() {
         return this[LIST];
     }

package/dist/esm/core/utils/timing.js.map

@@ -1 +1 @@
-{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../../../src/core/utils/timing.ts"],"names":[],"mappings":";;;AAEA,MAAM,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;AACjC,MAAM,IAAI,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AAEnC,MAAa,MAAM;IAKjB;QAJQ,YAAO,GAAG,IAAI,CAAC;QAKrB,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAChB,IAAI,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAED,IAAI;QACF,qBAAqB;QACrB,IAAI,CAAC,KAAK,CAAC,eAAe,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC;QAC9E,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;QAE1B,MAAM,IAAI,GAAG,OAAkD,CAAC;QAChE,IAAI,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,EAAE,CAAC;YAC7C,+BAA+B;YAC/B,IAAI,CAAC,KAAK,CAAC,cAAc,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC;YACjD,IAAI,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAY,EAAE,KAAc;QAChC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAE7C,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAExC,MAAM,IAAI,GAAe;YACvB,IAAI;YACJ,KAAK,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,EAAE;YAC1B,GAAG,EAAE,SAAS;YACd,QAAQ,EAAE,SAAS;YACnB,GAAG,EAAE,OAAO,CAAC,GAAG;YAChB,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM;SACzB,CAAC;QACF,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAC7C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,UAAU,CAAC,CAAC;QAC9D,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QAClC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM;QACJ,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,OAAO;QACL,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC;QAClB,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IAClB,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;CACF;AAtED,wBAsEC"}
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../../../../src/core/utils/timing.ts"],"names":[],"mappings":"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"}

package/dist/esm/cross/cross.d.ts

@@ -1,25 +1,104 @@
+/**
+ * @module cross/cross
+ * @description Cross-process communication manager. Responsible for creating, managing, and terminating
+ * external child processes (e.g., Go/Python backends), and dynamically allocating ports for them.
+ *
+ * Core concepts:
+ * - children: Process mapping keyed by pid, storing CrossProcess instances
+ * - childrenMap: Mapping keyed by name, for quick process lookup by name
+ * - Event listening: Automatically cleans up from mappings when child processes exit/error
+ *
+ * Usage:
+ * ```ts
+ * const proc = await cross.run('goServer');
+ * const url = cross.getUrl('goServer');
+ * cross.killByName('goServer');
+ * ```
+ */
 import EventEmitter from 'events';
 import { CrossProcess } from './crossProcess.js';
+import type { CrossHost } from './crossProcess.js';
+/** Additional options when running a child process */
 export interface CrossRunOptions {
     [key: string]: unknown;
+    /** Override startup arguments */
     args?: string[];
+    /** Specify port number */
     port?: number;
 }
-export declare class Cross {
+/**
+ * Cross - cross-process communication manager
+ *
+ * Implements the CrossHost interface, providing event notification capability for child processes.
+ * Manages processes via children and childrenMap dual indexes, supporting operations by pid or name.
+ */
+export declare class Cross implements CrossHost {
+    /** Event emitter for receiving child process exit/error events */
     emitter: EventEmitter | undefined;
+    /** pid index: { pid: { name, entity } } */
     private children;
+    /** name index: { name: pid } */
     private childrenMap;
     constructor();
+    /**
+     * Create and start all cross-process services with enable=true in config
+     *
+     * Iterates over config.cross configuration, calling run() for each service with enable=true.
+     */
     create(): Promise<void>;
+    /**
+     * Run the specified cross-process service
+     *
+     * Flow:
+     * 1. Get service configuration from config, merge with runtime options
+     * 2. Parse port parameter, dynamically acquire available port if specified
+     * 3. Create CrossProcess child process
+     * 4. Register in children and childrenMap indexes
+     *
+     * @param service - Service name (corresponding to key name in config.cross)
+     * @param opt - Runtime options, can override configuration parameters
+     * @returns CrossProcess instance
+     * @throws Throws error when service configuration does not exist
+     */
     run(service: string, opt?: CrossRunOptions): Promise<CrossProcess>;
+    /** Terminate all child processes */
     killAll(): void;
+    /** Terminate child process by pid */
     kill(pid: string | number): void;
+    /** Terminate child process by name */
     killByName(name: string): void;
-    getUrl(name: string): string;
+    /**
+     * Get the URL of the specified service
+     *
+     * @param name - Service name
+     * @returns Service URL, or undefined if process does not exist
+     */
+    getUrl(name: string): string | undefined;
+    /**
+     * Get process instance by name
+     *
+     * @param name - Service name
+     * @returns CrossProcess instance
+     * @throws Throws error when process does not exist
+     */
     getProcByName(name: string): CrossProcess;
+    /**
+     * Get process instance by pid
+     *
+     * @param pid - Process ID
+     * @returns CrossProcess instance
+     * @throws Throws error when process does not exist
+     */
     getProc(pid: string | number): CrossProcess;
+    /** Get list of all child process pids */
     getPids(): string[];
+    /**
+     * Initialize event listeners
+     *
+     * Listens for child process exit and error events, automatically cleaning up terminated processes from indexes.
+     */
     _initEventEmitter(): void;
 }
+/** Cross manager singleton */
 export declare const cross: Cross;
 //# sourceMappingURL=cross.d.ts.map

package/dist/esm/cross/cross.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cross.d.ts","sourceRoot":"","sources":["../../../src/cross/cross.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,QAAQ,CAAC;AAGlC,OAAO,EAAE,YAAY,EAAqB,MAAM,mBAAmB,CAAC;AAMpE,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,KAAK;IAChB,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAIlC,OAAO,CAAC,QAAQ,CAAyD;IAIzE,OAAO,CAAC,WAAW,CAAyB;;IAStC,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAcvB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,eAAoB,GAAG,OAAO,CAAC,YAAY,CAAC;IAsC5E,OAAO,IAAI,IAAI;IAMf,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOhC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQ5B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAYzC,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY;IAU3C,OAAO,IAAI,MAAM,EAAE;IAKnB,iBAAiB,IAAI,IAAI;CAiB1B;AAED,eAAO,MAAM,KAAK,OAAc,CAAC"}
+{"version":3,"file":"cross.d.ts","sourceRoot":"","sources":["../../../src/cross/cross.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,YAAY,MAAM,QAAQ,CAAC;AAGlC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAMnD,sDAAsD;AACtD,MAAM,WAAW,eAAe;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,0BAA0B;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,qBAAa,KAAM,YAAW,SAAS;IACrC,kEAAkE;IAClE,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAElC,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAyD;IAEzE,gCAAgC;IAChC,OAAO,CAAC,WAAW,CAAyB;;IAS5C;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAW7B;;;;;;;;;;;;;OAaG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,GAAE,eAAoB,GAAG,OAAO,CAAC,YAAY,CAAC;IAuC5E,oCAAoC;IACpC,OAAO,IAAI,IAAI;IAMf,qCAAqC;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOhC,sCAAsC;IACtC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAO9B;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAQxC;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY;IAUzC;;;;;;OAMG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,YAAY;IAS3C,yCAAyC;IACzC,OAAO,IAAI,MAAM,EAAE;IAKnB;;;;OAIG;IACH,iBAAiB,IAAI,IAAI;CAiB1B;AAED,8BAA8B;AAC9B,eAAO,MAAM,KAAK,OAAc,CAAC"}

package/dist/esm/cross/cross.js

@@ -4,6 +4,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cross = exports.Cross = void 0;
+/**
+ * @module cross/cross
+ * @description Cross-process communication manager. Responsible for creating, managing, and terminating
+ * external child processes (e.g., Go/Python backends), and dynamically allocating ports for them.
+ *
+ * Core concepts:
+ * - children: Process mapping keyed by pid, storing CrossProcess instances
+ * - childrenMap: Mapping keyed by name, for quick process lookup by name
+ * - Event listening: Automatically cleans up from mappings when child processes exit/error
+ *
+ * Usage:
+ * ```ts
+ * const proc = await cross.run('goServer');
+ * const url = cross.getUrl('goServer');
+ * cross.killByName('goServer');
+ * ```
+ */
 const events_1 = __importDefault(require("events"));
 const index_js_1 = require("../config/index.js");
 const helper_js_1 = require("../utils/helper.js");
@@ -11,6 +28,12 @@ const crossProcess_js_1 = require("./crossProcess.js");
 const channel_js_1 = require("../const/channel.js");
 const extend_js_1 = require("../utils/extend.js");
 const index_js_2 = require("../utils/port/index.js");
+/**
+ * Cross - cross-process communication manager
+ *
+ * Implements the CrossHost interface, providing event notification capability for child processes.
+ * Manages processes via children and childrenMap dual indexes, supporting operations by pid or name.
+ */
 class Cross {
     constructor() {
         this.emitter = undefined;
@@ -18,18 +41,34 @@ class Cross {
         this.childrenMap = {};
         this._initEventEmitter();
     }
+    /**
+     * Create and start all cross-process services with enable=true in config
+     *
+     * Iterates over config.cross configuration, calling run() for each service with enable=true.
+     */
     async create() {
-        // boot services
         const crossCfg = (0, index_js_1.getConfig)().cross;
-        //await sleep(5 * 1000);
         for (const key of Object.keys(crossCfg)) {
             const val = crossCfg[key];
             if (val && val.enable === true) {
-                this.run(key);
+                await this.run(key);
             }
         }
     }
-    // run
+    /**
+     * Run the specified cross-process service
+     *
+     * Flow:
+     * 1. Get service configuration from config, merge with runtime options
+     * 2. Parse port parameter, dynamically acquire available port if specified
+     * 3. Create CrossProcess child process
+     * 4. Register in children and childrenMap indexes
+     *
+     * @param service - Service name (corresponding to key name in config.cross)
+     * @param opt - Runtime options, can override configuration parameters
+     * @returns CrossProcess instance
+     * @throws Throws error when service configuration does not exist
+     */
     async run(service, opt = {}) {
         const crossConf = (0, index_js_1.getConfig)().cross;
         const defaultOpt = crossConf[service] || {};
@@ -37,22 +76,23 @@ class Cross {
         if (Object.keys(targetConf).length === 0) {
             throw new Error(`[ee-core] [cross] The service [${service}] config does not exit`);
         }
-        // format params
+        // Parse and allocate port
         const tmpArgs = targetConf.args || [];
         let confPort = parseInt(String((0, helper_js_1.getValueFromArgv)(tmpArgs, 'port') || '0'), 10);
-        // 某些程序给它传入不存在的参数时会报错
+        // Some programs error when passed non-existent arguments, in which case use the port field from config
         if (isNaN(confPort) && (targetConf.port || 0) > 0) {
             confPort = targetConf.port || 0;
         }
         if (confPort > 0) {
-            // 动态生成port，传入的端口必须为int
+            // Dynamically acquire available port
             confPort = await (0, index_js_2.getPort)({ port: confPort });
-            // 替换port
+            // Replace port number in arguments
             targetConf.args = (0, helper_js_1.replaceArgsValue)(tmpArgs, 'port', String(confPort));
         }
-        // 创建进程
+        // Create child process
         const subProcess = new crossProcess_js_1.CrossProcess(this, { targetConf, port: confPort });
         let uniqueName = targetConf.name;
+        // Append pid suffix for duplicate service names to avoid conflicts
         if (Object.prototype.hasOwnProperty.call(this.childrenMap, uniqueName)) {
             uniqueName = uniqueName + '-' + String(subProcess.pid);
         }
@@ -64,31 +104,49 @@ class Cross {
         };
         return subProcess;
     }
+    /** Terminate all child processes */
     killAll() {
         Object.keys(this.children).forEach((pid) => {
             this.kill(pid);
         });
     }
+    /** Terminate child process by pid */
     kill(pid) {
         const entity = this.getProc(pid);
         if (entity) {
             entity.kill();
         }
     }
+    /** Terminate child process by name */
     killByName(name) {
         const entity = this.getProcByName(name);
         if (entity) {
             entity.kill();
         }
     }
+    /**
+     * Get the URL of the specified service
+     *
+     * @param name - Service name
+     * @returns Service URL, or undefined if process does not exist
+     */
     getUrl(name) {
-        const entity = this.getProcByName(name);
-        const url = entity.getUrl();
-        return url;
+        const pid = this.childrenMap[name];
+        if (!pid)
+            return undefined;
+        const child = this.children[String(pid)];
+        if (!child)
+            return undefined;
+        return child.entity.getUrl();
     }
-    // 获取 proc
+    /**
+     * Get process instance by name
+     *
+     * @param name - Service name
+     * @returns CrossProcess instance
+     * @throws Throws error when process does not exist
+     */
     getProcByName(name) {
-        // [todo] 如果有名字一样的服务，需要加 pid
         const pid = this.childrenMap[name];
         if (!pid) {
             throw new Error(`[ee-core] [cross] The process named [${name}] does not exit`);
@@ -96,7 +154,13 @@ class Cross {
         const entity = this.getProc(pid);
         return entity;
     }
-    // 获取 proc
+    /**
+     * Get process instance by pid
+     *
+     * @param pid - Process ID
+     * @returns CrossProcess instance
+     * @throws Throws error when process does not exist
+     */
     getProc(pid) {
         const child = this.children[String(pid)];
         if (!child) {
@@ -104,11 +168,16 @@ class Cross {
         }
         return child.entity;
     }
-    // 获取pids
+    /** Get list of all child process pids */
     getPids() {
         const pids = Object.keys(this.children);
         return pids;
     }
+    /**
+     * Initialize event listeners
+     *
+     * Listens for child process exit and error events, automatically cleaning up terminated processes from indexes.
+     */
     _initEventEmitter() {
         this.emitter = new events_1.default();
         this.emitter.on(channel_js_1.Events.childProcessExit, (data) => {
@@ -128,5 +197,6 @@ class Cross {
     }
 }
 exports.Cross = Cross;
+/** Cross manager singleton */
 exports.cross = new Cross();
 //# sourceMappingURL=cross.js.map

package/dist/esm/cross/cross.js.map

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

package/dist/esm/cross/crossProcess.d.ts

@@ -1,46 +1,117 @@
+/**
+ * @module cross/crossProcess
+ * @description Cross-process child process management. Encapsulates the logic of using cross-spawn
+ * to create external processes, handling process path resolution, platform differences,
+ * lifecycle monitoring, and graceful exit.
+ *
+ * Supported external program types:
+ * - Go compiled binaries
+ * - Python scripts
+ * - Other executable programs
+ *
+ * Process path resolution rules:
+ * - Config has cmd → use cmd as executable file path
+ * - Config has no cmd → use extraResourcesDir/{name} as path
+ * - Windows platform automatically adds .exe extension
+ * - Dev environment relative to project root, production relative to extraResources directory
+ */
 import EventEmitter from 'events';
 import crossSpawn from 'cross-spawn';
-export interface CrossTargetConfig {
-    name: string;
-    args?: string[];
-    cmd?: string;
-    directory?: string;
-    windowsExtname?: boolean;
-    stdio?: ('pipe' | 'ignore' | 'inherit' | 'ipc')[];
-    appExit?: boolean;
-    port?: number;
-    enable?: boolean;
-}
+import type { CrossTargetConfig } from '../types/index.js';
+export type { CrossTargetConfig };
+/** Options when creating a CrossProcess */
 export interface CrossProcessOptions {
+    /** Target service configuration */
     targetConf: CrossTargetConfig;
+    /** Allocated port number */
     port: number;
 }
+/**
+ * CrossProcess - child process instance
+ *
+ * Encapsulates the complete lifecycle of an external process:
+ * Create → Run → Listen for events → Terminate
+ *
+ * Notifies the Cross manager of child process events (exit/error) via the host's emitter.
+ */
 export declare class CrossProcess {
+    /** Event emitter */
     emitter: EventEmitter;
+    /** Host (Cross manager), used to notify process events */
     host: CrossHost;
+    /** Child process object returned by cross-spawn */
     child: ReturnType<typeof crossSpawn> | undefined;
+    /** Child process PID */
     pid: number;
+    /** Allocated port number */
     port: number;
+    /** Unique service name (may be rewritten by Cross manager to avoid conflicts) */
     name: string;
+    /** Service configuration */
     config: CrossTargetConfig;
     constructor(host: CrossHost, opt?: CrossProcessOptions);
     /**
-     * 初始化子进程
+     * Initialize child process
+     *
+     * Execution flow:
+     * 1. Save configuration and port
+     * 2. Resolve executable file path (handle cmd/directory configuration and platform differences)
+     * 3. Set standard output mode (inherit in dev environment, ignore in production)
+     * 4. Start child process using cross-spawn
+     * 5. Listen for exit and error events
      */
     _init(options?: CrossProcessOptions): void;
     /**
-     * kill
+     * Terminate child process
+     *
+     * First sends SIGINT signal for graceful exit, then sends SIGKILL for forced termination if it fails.
+     * If the process still hasn't exited after timeout, triggers _exitElectron as a safety net.
+     *
+     * @param timeout - Timeout for waiting exit (milliseconds)
      */
     kill(timeout?: number): void;
+    /**
+     * Get the service URL of the child process
+     *
+     * Parses hostname and ssl flag from startup arguments, constructs HTTP/HTTPS URL.
+     * Outputs warning when port is 0 (service may not have bound port correctly).
+     *
+     * @returns Service URL, e.g., http://127.0.0.1:7070
+     */
     getUrl(): string;
+    /**
+     * Get key-value object of startup arguments
+     *
+     * @returns Parsed arguments object
+     */
     getArgsObj(): Record<string, unknown>;
+    /**
+     * Set port number
+     *
+     * @param port - Port number (strings will be converted to numbers)
+     */
     setPort(port: string | number): void;
+    /**
+     * Generate unique ID
+     *
+     * @returns Unique identifier in the format 'node:{pid}:{randomString}'
+     */
     _generateId(): string;
     /**
-     * exit electron
+     * Trigger Electron main process exit when child process exits
+     *
+     * Only effective when appExit=true is configured, ensuring the main process also exits when the child process crashes.
+     *
+     * @param timeout - Delayed exit time (milliseconds), waiting for resource release
      */
     _exitElectron(timeout?: number): void;
 }
+/**
+ * CrossHost interface
+ *
+ * CrossProcess communicates with the host (Cross manager) through this interface,
+ * sending child process exit and error events.
+ */
 export interface CrossHost {
     emitter: EventEmitter | undefined;
 }

package/dist/esm/cross/crossProcess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crossProcess.d.ts","sourceRoot":"","sources":["../../../src/cross/crossProcess.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,QAAQ,CAAC;AAElC,OAAO,UAAU,MAAM,aAAa,CAAC;AAUrC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,CAAC,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,KAAK,CAAC,EAAE,CAAC;IAClD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE,iBAAiB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,YAAY;IACvB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,SAAS,CAAC;IACjD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,iBAAiB,CAAC;gBAEd,IAAI,EAAE,SAAS,EAAE,GAAG,GAAE,mBAA2D;IAW7F;;OAEG;IACH,KAAK,CAAC,OAAO,GAAE,mBAA2D,GAAG,IAAI;IAqFjF;;OAEG;IACH,IAAI,CAAC,OAAO,SAAO,GAAG,IAAI;IAc1B,MAAM,IAAI,MAAM;IAahB,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKrC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIpC,WAAW,IAAI,MAAM;IAKrB;;OAEG;IACH,aAAa,CAAC,OAAO,SAAO,GAAG,IAAI;CAQpC;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;CACnC"}
+{"version":3,"file":"crossProcess.d.ts","sourceRoot":"","sources":["../../../src/cross/crossProcess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,YAAY,MAAM,QAAQ,CAAC;AAElC,OAAO,UAAU,MAAM,aAAa,CAAC;AASrC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,YAAY,EAAE,iBAAiB,EAAE,CAAC;AAElC,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,UAAU,EAAE,iBAAiB,CAAC;IAC9B,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,oBAAoB;IACpB,OAAO,EAAE,YAAY,CAAC;IACtB,0DAA0D;IAC1D,IAAI,EAAE,SAAS,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,GAAG,SAAS,CAAC;IACjD,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,MAAM,EAAE,iBAAiB,CAAC;gBAEd,IAAI,EAAE,SAAS,EAAE,GAAG,GAAE,mBAA2D;IAW7F;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,GAAE,mBAA2D,GAAG,IAAI;IAuFjF;;;;;;;OAOG;IACH,IAAI,CAAC,OAAO,SAAO,GAAG,IAAI;IAkB1B;;;;;;;OAOG;IACH,MAAM,IAAI,MAAM;IAgBhB;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKrC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIpC;;;;OAIG;IACH,WAAW,IAAI,MAAM;IAKrB;;;;;;OAMG;IACH,aAAa,CAAC,OAAO,SAAO,GAAG,IAAI;CAOpC;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;CACnC"}