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

package/dist/cjs/jobs/child/jobProcess.d.ts

@@ -1,34 +1,102 @@
 import { EventEmitter } from 'events';
 import { type ChildProcess, type ForkOptions } from 'child_process';
 import type { JobsConfig, MessageData } from '../../types/index.js';
+/** Options when creating a JobProcess */
 export interface JobProcessOptions {
+    /** Arguments object passed to the child process */
     processArgs?: Record<string, unknown>;
+    /** Fork options (cwd, env, stdio, etc.) */
     processOptions?: ForkOptions;
+    [key: string]: unknown;
 }
+/** Message format: Main process -> Child process */
 export interface JobMessage {
+    /** Message ID */
     mid: string;
+    /** Command (e.g. 'run') */
     cmd: string;
+    /** Task file path */
     jobPath?: string;
+    /** Task constructor arguments */
     jobParams?: unknown[];
+    /** Instance method name to call */
     jobFunc?: string;
+    /** Instance method arguments */
     jobFuncParams?: unknown[];
 }
+/** Message format: Child process -> Main process */
 export interface ProcessMessage extends MessageData {
+    /** Message receiver type */
     eventReceiver: string;
 }
+/**
+ * JobProcess - Child process manager
+ *
+ * Encapsulates the complete logic of forking a child process:
+ * 1. Determine app.js entry path (child process entry within node_modules/ee-core)
+ * 2. Configure working directory and environment variables
+ * 3. Fork the child process and register event listeners
+ * 4. Provide dispatch() and callFunc() for sending messages
+ * 5. Provide kill() for terminating the process
+ */
 export declare class JobProcess {
+    /** In-process event emitter (forkProcess-level messages) */
     emitter: EventEmitter;
+    /** Host event emitter (ChildJob/ChildPoolJob, childJob-level messages) */
     host: EventEmitter;
+    /** Arguments array passed to the child process */
     args: string[];
+    /** Whether the child process is in a sleeping state */
     sleeping: boolean;
+    /** Child process object returned by child_process.fork() */
     child: ChildProcess;
+    /** Child process PID */
     pid: number | undefined;
+    /** Task configuration */
     config: JobsConfig;
     constructor(host: EventEmitter, opt?: JobProcessOptions, config?: JobsConfig);
+    /**
+     * Initialize child process event listeners
+     *
+     * Listens for three types of events:
+     * - message: Process messages from the child process (exception display, business message forwarding)
+     * - exit: Child process exited, notify host to clean up
+     * - error: Child process error, notify host to clean up
+     */
     _init(): void;
+    /**
+     * Dispatch messages to different event emitters based on eventReceiver
+     *
+     * - forkProcess: send only to in-process emitter
+     * - childJob: send only to host emitter
+     * - all / others: send to both
+     */
     _eventEmit(m: ProcessMessage): void;
+    /**
+     * Send a dispatch message to the child process
+     *
+     * @param cmd - Command (e.g. 'run')
+     * @param jobPath - Task file path
+     * @param params - Task parameters
+     */
     dispatch(cmd: string, jobPath?: string, ...params: unknown[]): void;
+    /**
+     * Call a specified method on the task instance in the child process
+     *
+     * Resolves the task file path, then sends a run command with the specified function name.
+     *
+     * @param jobPath - Task file path (relative paths are resolved to absolute paths)
+     * @param funcName - Method name to call
+     * @param params - Method arguments
+     */
     callFunc(jobPath?: string, funcName?: string, ...params: unknown[]): void;
+    /**
+     * Terminate the child process
+     *
+     * First sends SIGINT for graceful exit, then sends SIGKILL to force termination after timeout.
+     *
+     * @param timeout - Timeout in milliseconds to wait for graceful exit
+     */
     kill(timeout?: number): void;
 }
 //# sourceMappingURL=jobProcess.d.ts.map

package/dist/cjs/jobs/child/jobProcess.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jobProcess.d.ts","sourceRoot":"","sources":["../../../../src/jobs/child/jobProcess.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAQ,KAAK,YAAY,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAQ7F,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAwB,MAAM,sBAAsB,CAAC;AAE1F,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,cAAc,CAAC,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,qBAAa,UAAU;IACrB,OAAO,EAAE,YAAY,CAAC;IACtB,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,MAAM,EAAE,UAAU,CAAC;gBAEP,IAAI,EAAE,YAAY,EAAE,GAAG,GAAE,iBAAsB,EAAE,MAAM,GAAE,UAAkC;IAsCvG,KAAK,IAAI,IAAI;IA8Bb,UAAU,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI;IAenC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAK,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAe/D,QAAQ,CAAC,OAAO,SAAK,EAAE,QAAQ,SAAK,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAejE,IAAI,CAAC,OAAO,SAAO,GAAG,IAAI;CAO3B"}
+{"version":3,"file":"jobProcess.d.ts","sourceRoot":"","sources":["../../../../src/jobs/child/jobProcess.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAQ,KAAK,YAAY,EAAqB,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAS7F,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAwB,MAAM,sBAAsB,CAAC;AAE1F,yCAAyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,2CAA2C;IAC3C,cAAc,CAAC,EAAE,WAAW,CAAC;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,GAAG,EAAE,MAAM,CAAC;IACZ,2BAA2B;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IACtB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gCAAgC;IAChC,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,4BAA4B;IAC5B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAU;IACrB,4DAA4D;IAC5D,OAAO,EAAE,YAAY,CAAC;IACtB,0EAA0E;IAC1E,IAAI,EAAE,YAAY,CAAC;IACnB,kDAAkD;IAClD,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,KAAK,EAAE,YAAY,CAAC;IACpB,wBAAwB;IACxB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,yBAAyB;IACzB,MAAM,EAAE,UAAU,CAAC;gBAEP,IAAI,EAAE,YAAY,EAAE,GAAG,GAAE,iBAAsB,EAAE,MAAM,GAAE,UAAkC;IA2CvG;;;;;;;OAOG;IACH,KAAK,IAAI,IAAI;IA6Cb;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,EAAE,cAAc,GAAG,IAAI;IAenC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,SAAK,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAY/D;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,SAAK,EAAE,QAAQ,SAAK,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI;IAcjE;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,SAAO,GAAG,IAAI;CAO3B"}

package/dist/cjs/jobs/child/jobProcess.js

@@ -4,31 +4,58 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JobProcess = void 0;
+/**
+ * @module jobs/child/jobProcess
+ * @description Child process manager. Encapsulates child_process.fork() creation and communication logic,
+ * providing the main process with the ability to create child processes, send messages, and terminate processes.
+ *
+ * Communication mechanism:
+ * - Main process sends JobMessage to child process via child.send()
+ * - Child process sends ProcessMessage to main process via process.send()
+ * - Messages are categorized by channel: showException (exception), sendToMain (business message)
+ * - Messages are dispatched by eventReceiver: childJob (global), forkProcess (per-process), all (both)
+ */
 const path_1 = __importDefault(require("path"));
 const events_1 = require("events");
 const child_process_1 = require("child_process");
 const serialize_javascript_1 = __importDefault(require("serialize-javascript"));
 const index_js_1 = require("../../log/index.js");
 const index_js_2 = require("../../ps/index.js");
+const index_js_3 = require("../../config/index.js");
 const channel_js_1 = require("../../const/channel.js");
 const helper_js_1 = require("../../utils/helper.js");
-const index_js_3 = require("../../loader/index.js");
+const index_js_4 = require("../../loader/index.js");
 const extend_js_1 = require("../../utils/extend.js");
+/**
+ * JobProcess - Child process manager
+ *
+ * Encapsulates the complete logic of forking a child process:
+ * 1. Determine app.js entry path (child process entry within node_modules/ee-core)
+ * 2. Configure working directory and environment variables
+ * 3. Fork the child process and register event listeners
+ * 4. Provide dispatch() and callFunc() for sending messages
+ * 5. Provide kill() for terminating the process
+ */
 class JobProcess {
     constructor(host, opt = {}, config = { messageLog: false }) {
         let cwd = (0, index_js_2.getBaseDir)();
+        // Locate app.js entry: child process startup file within the ee-core package
         const currentFilePath = typeof __filename !== 'undefined' ? __filename : '';
         const appPath = path_1.default.join(path_1.default.dirname(currentFilePath), 'app.js');
-        // todo fork的cwd目录为什么要在app.asar外 ？
+        // After packaging, cwd must be outside app.asar (child processes need access to node_modules)
         if ((0, index_js_2.isPackaged)()) {
             cwd = path_1.default.join((0, index_js_2.getBaseDir)(), '..');
         }
         const defaultOptions = {
-            processArgs: {},
+            processArgs: {
+                type: 'childJob',
+                // Pass main process config to child process so it doesn't need to load from filesystem
+                eeConfig: (0, index_js_3.getConfig)(),
+            },
             processOptions: {
                 cwd,
                 env: (0, index_js_2.allEnv)(),
-                stdio: 'ignore', // pipe
+                stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
             },
         };
         const options = (0, extend_js_1.extend)(true, defaultOptions, opt);
@@ -37,26 +64,48 @@ class JobProcess {
         this.args = [];
         this.sleeping = false;
         this.config = config;
-        // 传递给子进程的参数
+        // Serialize arguments and pass them to the child process
         this.args.push(JSON.stringify(options.processArgs));
         this.child = (0, child_process_1.fork)(appPath, this.args, options.processOptions ?? {});
         this.pid = this.child.pid;
         this._init();
     }
+    /**
+     * Initialize child process event listeners
+     *
+     * Listens for three types of events:
+     * - message: Process messages from the child process (exception display, business message forwarding)
+     * - exit: Child process exited, notify host to clean up
+     * - error: Child process error, notify host to clean up
+     */
     _init() {
         const { messageLog } = this.config;
         this.child.on('message', (m) => {
             if (messageLog) {
                 index_js_1.coreLogger.info(`[jobs/child] received a message from child-process, message: ${(0, serialize_javascript_1.default)(m)}`);
             }
+            // Exception message: log it
             if (m.channel === channel_js_1.Processes.showException) {
                 index_js_1.coreLogger.error(`${m.data}`);
             }
-            // 收到子进程消息，转发到 event
+            // Business message: dispatch based on eventReceiver
             if (m.channel === channel_js_1.Processes.sendToMain) {
                 this._eventEmit(m);
             }
         });
+        // Capture child process stdout/stderr for debugging
+        const stdout = this.child.stdout;
+        const stderr = this.child.stderr;
+        if (stdout) {
+            stdout.on('data', (data) => {
+                index_js_1.coreLogger.info(`[jobs/child] stdout: ${data.toString().trim()}`);
+            });
+        }
+        if (stderr) {
+            stderr.on('data', (data) => {
+                index_js_1.coreLogger.error(`[jobs/child] stderr: ${data.toString().trim()}`);
+            });
+        }
         this.child.on('exit', (code, signal) => {
             const data = { pid: this.pid };
             this.host.emit(channel_js_1.Events.childProcessExit, data);
@@ -68,6 +117,13 @@ class JobProcess {
             index_js_1.coreLogger.error(`[jobs/child] received a error from child-process, error: ${err}, pid:${this.pid}`);
         });
     }
+    /**
+     * Dispatch messages to different event emitters based on eventReceiver
+     *
+     * - forkProcess: send only to in-process emitter
+     * - childJob: send only to host emitter
+     * - all / others: send to both
+     */
     _eventEmit(m) {
         switch (m.eventReceiver) {
             case channel_js_1.Receiver.forkProcess:
@@ -82,8 +138,14 @@ class JobProcess {
                 break;
         }
     }
+    /**
+     * Send a dispatch message to the child process
+     *
+     * @param cmd - Command (e.g. 'run')
+     * @param jobPath - Task file path
+     * @param params - Task parameters
+     */
     dispatch(cmd, jobPath = '', ...params) {
-        // 消息对象
         const mid = (0, helper_js_1.getRandomString)();
         const msg = {
             mid,
@@ -91,13 +153,19 @@ class JobProcess {
             jobPath,
             jobParams: params,
         };
-        // todo 是否会发生监听未完成时，接收不到消息？
-        // 发消息到子进程
         this.child.send(msg);
     }
+    /**
+     * Call a specified method on the task instance in the child process
+     *
+     * Resolves the task file path, then sends a run command with the specified function name.
+     *
+     * @param jobPath - Task file path (relative paths are resolved to absolute paths)
+     * @param funcName - Method name to call
+     * @param params - Method arguments
+     */
     callFunc(jobPath = '', funcName = '', ...params) {
-        const fullPath = (0, index_js_3.getFullpath)(jobPath);
-        // 消息对象
+        const fullPath = (0, index_js_4.getFullpath)(jobPath);
         const mid = (0, helper_js_1.getRandomString)();
         const msg = {
             mid,
@@ -108,6 +176,13 @@ class JobProcess {
         };
         this.child.send(msg);
     }
+    /**
+     * Terminate the child process
+     *
+     * First sends SIGINT for graceful exit, then sends SIGKILL to force termination after timeout.
+     *
+     * @param timeout - Timeout in milliseconds to wait for graceful exit
+     */
     kill(timeout = 1000) {
         this.child.kill('SIGINT');
         setTimeout(() => {

package/dist/cjs/jobs/child/jobProcess.js.map

@@ -1 +1 @@
-{"version":3,"file":"jobProcess.js","sourceRoot":"","sources":["../../../../src/jobs/child/jobProcess.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jobProcess.js","sourceRoot":"","sources":["../../../../src/jobs/child/jobProcess.ts"],"names":[],"mappings":";;;;;;AAAA;;;;;;;;;;GAUG;AACH,gDAAwB;AACxB,mCAAsC;AACtC,iDAA6F;AAC7F,gFAA6C;AAC7C,iDAAgD;AAChD,gDAAmE;AACnE,oDAAkD;AAClD,uDAAqE;AACrE,qDAAwD;AACxD,oDAAoD;AACpD,qDAA+C;AAkC/C;;;;;;;;;GASG;AACH,MAAa,UAAU;IAgBrB,YAAY,IAAkB,EAAE,MAAyB,EAAE,EAAE,SAAqB,EAAE,UAAU,EAAE,KAAK,EAAE;QACrG,IAAI,GAAG,GAAG,IAAA,qBAAU,GAAE,CAAC;QACvB,6EAA6E;QAC7E,MAAM,eAAe,GAAG,OAAO,UAAU,KAAK,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,MAAM,OAAO,GAAG,cAAI,CAAC,IAAI,CAAC,cAAI,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAC;QACnE,8FAA8F;QAC9F,IAAI,IAAA,qBAAU,GAAE,EAAE,CAAC;YACjB,GAAG,GAAG,cAAI,CAAC,IAAI,CAAC,IAAA,qBAAU,GAAE,EAAE,IAAI,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,cAAc,GAAsB;YACxC,WAAW,EAAE;gBACX,IAAI,EAAE,UAAU;gBAChB,uFAAuF;gBACvF,QAAQ,EAAE,IAAA,oBAAS,GAAE;aACtB;YACD,cAAc,EAAE;gBACd,GAAG;gBACH,GAAG,EAAE,IAAA,iBAAM,GAAE;gBACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,CAAyB;aACjE;SACF,CAAC;QAEF,MAAM,OAAO,GAAG,IAAA,kBAAM,EACpB,IAAI,EACJ,cAAc,EACd,GAAG,CACiB,CAAC;QAEvB,IAAI,CAAC,OAAO,GAAG,IAAI,qBAAY,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACtB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAErB,yDAAyD;QACzD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;QAEpD,IAAI,CAAC,KAAK,GAAG,IAAA,oBAAI,EAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;QACpE,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC;QAC1B,IAAI,CAAC,KAAK,EAAE,CAAC;IACf,CAAC;IAED;;;;;;;OAOG;IACH,KAAK;QACH,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,CAAiB,EAAE,EAAE;YAC7C,IAAI,UAAU,EAAE,CAAC;gBACf,qBAAU,CAAC,IAAI,CAAC,gEAAgE,IAAA,8BAAS,EAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAClG,CAAC;YAED,4BAA4B;YAC5B,IAAI,CAAC,CAAC,OAAO,KAAK,sBAAS,CAAC,aAAa,EAAE,CAAC;gBAC1C,qBAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YAChC,CAAC;YAED,oDAAoD;YACpD,IAAI,CAAC,CAAC,OAAO,KAAK,sBAAS,CAAC,UAAU,EAAE,CAAC;gBACvC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACrB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,oDAAoD;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QACjC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;QACjC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;gBACjC,qBAAU,CAAC,IAAI,CAAC,wBAAwB,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACpE,CAAC,CAAC,CAAC;QACL,CAAC;QACD,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;gBACjC,qBAAU,CAAC,KAAK,CAAC,wBAAwB,IAAI,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACrE,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAmB,EAAE,MAAqB,EAAE,EAAE;YACnE,MAAM,IAAI,GAAyB,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;YACrD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAM,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;YAC9C,qBAAU,CAAC,IAAI,CAAC,yDAAyD,IAAI,YAAY,MAAM,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACtH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YACpC,MAAM,IAAI,GAAyB,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;YACrD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAM,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;YAC/C,qBAAU,CAAC,KAAK,CAAC,4DAA4D,GAAG,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QACvG,CAAC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,UAAU,CAAC,CAAiB;QAC1B,QAAQ,CAAC,CAAC,aAAa,EAAE,CAAC;YACxB,KAAK,qBAAQ,CAAC,WAAW;gBACvB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;gBACnC,MAAM;YACR,KAAK,qBAAQ,CAAC,QAAQ;gBACpB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;gBAChC,MAAM;YACR;gBACE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;gBAChC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;gBACnC,MAAM;QACV,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,GAAW,EAAE,OAAO,GAAG,EAAE,EAAE,GAAG,MAAiB;QACtD,MAAM,GAAG,GAAG,IAAA,2BAAe,GAAE,CAAC;QAC9B,MAAM,GAAG,GAAe;YACtB,GAAG;YACH,GAAG;YACH,OAAO;YACP,SAAS,EAAE,MAAM;SAClB,CAAC;QAEF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAmB,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,GAAG,EAAE,EAAE,QAAQ,GAAG,EAAE,EAAE,GAAG,MAAiB;QACxD,MAAM,QAAQ,GAAG,IAAA,sBAAW,EAAC,OAAO,CAAC,CAAC;QAEtC,MAAM,GAAG,GAAG,IAAA,2BAAe,GAAE,CAAC;QAC9B,MAAM,GAAG,GAAe;YACtB,GAAG;YACH,GAAG,EAAE,KAAK;YACV,OAAO,EAAE,QAAQ;YACjB,OAAO,EAAE,QAAQ;YACjB,aAAa,EAAE,MAAM;SACtB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAmB,CAAC,CAAC;IACvC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,OAAO,GAAG,IAAI;QACjB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC1B,UAAU,CAAC,GAAG,EAAE;YACd,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM;gBAAE,OAAO;YAC9B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC7B,CAAC,EAAE,OAAO,CAAC,CAAC;IACd,CAAC;CACF;AA9LD,gCA8LC"}

package/dist/cjs/jobs/child-pool/index.d.ts

@@ -1,30 +1,126 @@
+/**
+ * @module jobs/child-pool
+ * @description Child process pool manager. Maintains a set of child processes, distributes tasks
+ * through a load balancing algorithm, avoiding the overhead of frequent process creation and destruction.
+ *
+ * Core features:
+ * - Pool size: min=3, max=6, configurable
+ * - Load balancing: supports multiple algorithms (polling/weights/random, etc.), default is polling
+ * - Process binding: binds specific IDs to fixed processes via boundMap (e.g. session binding)
+ * - Auto cleanup: child processes are automatically removed from the pool on exit/error
+ *
+ * Usage:
+ * ```ts
+ * const pool = new ChildPoolJob();
+ * await pool.create(3); // Create 3 child processes
+ * await pool.run('service/job'); // Load balancer selects a process to execute
+ * ```
+ */
 import { EventEmitter } from 'events';
 import { LoadBalancer } from '../load-balancer/index.js';
 import { JobProcess } from '../child/jobProcess.js';
 import type { JobsConfig } from '../../types/index.js';
+/** Child process pool options */
 export interface ChildPoolOptions {
+    /** Weight values for each process (used by weighted load balancing algorithms) */
     weights?: number[];
 }
+/**
+ * ChildPoolJob - Child process pool
+ *
+ * Manages a set of child processes, distributes tasks through LoadBalancer.
+ * Inherits EventEmitter, listens for child process exit/error events for auto cleanup.
+ */
 export declare class ChildPoolJob extends EventEmitter {
+    /** Task configuration */
     config: JobsConfig;
+    /** Binding map: boundId -> pid (binds specific IDs to fixed processes) */
     boundMap: Map<string | number, number>;
+    /** Child process pool: pid -> JobProcess */
     children: Record<number, JobProcess>;
+    /** Minimum number of processes */
     min: number;
+    /** Maximum number of processes */
     max: number;
+    /** Load balancing strategy name */
     strategy: string;
+    /** Weight array for each process */
     weights: number[];
+    /** Load balancer instance */
     LB: LoadBalancer;
     constructor(opt?: ChildPoolOptions);
+    /**
+     * Initialize event listeners
+     *
+     * Automatically removes child processes from the pool and load balancer on exit or error.
+     */
     _initEvents(): void;
+    /**
+     * Remove a child process from the pool
+     *
+     * Removes from both children map and load balancer.
+     */
     _removeChild(pid: number): void;
+    /**
+     * Create a specified number of child processes
+     *
+     * New processes are added to the pool and load balancer.
+     * The count is limited by max; excess processes will not be created.
+     *
+     * @param number - Number of processes to create
+     * @returns List of all process PIDs after creation
+     * @throws Throws an error if the count is invalid or exceeds the maximum limit
+     */
     create(number?: number): Promise<string[]>;
+    /**
+     * Registration handling after child process creation
+     *
+     * Adds the process to the children map and load balancer.
+     */
     _childCreated(childProcess: JobProcess): void;
+    /**
+     * Execute a task file
+     *
+     * Selects a child process via the load balancer and sends a run command to execute the task.
+     *
+     * @param filepath - Task file path
+     * @param params - Task parameters
+     * @returns The child process instance executing the task
+     */
     run(filepath: string, params?: Record<string, unknown>): Promise<JobProcess>;
+    /**
+     * Asynchronously execute a task file (alias for run)
+     */
     runPromise(filepath: string, params?: Record<string, unknown>): Promise<JobProcess>;
+    /**
+     * Get a bound child process
+     *
+     * The same boundId is always assigned to the same child process, suitable for session binding scenarios.
+     * If the bound process no longer exists, a new process is reassigned.
+     *
+     * @param boundId - Binding identifier (e.g. user ID, session ID)
+     * @returns Child process instance
+     */
     getBoundChild(boundId: string | number): Promise<JobProcess>;
+    /** Get a child process by PID */
     getChildByPid(pid: number): JobProcess | null;
+    /**
+     * Get an available child process
+     *
+     * If the pool is empty, automatically creates one.
+     * Uses the load balancer to select a process.
+     *
+     * @returns Child process instance
+     * @throws Throws an error if retrieval fails
+     */
     getChild(): Promise<JobProcess>;
+    /** Get PID list of all child processes */
     getPids(): string[];
+    /**
+     * Kill all child processes
+     *
+     * @param type - Kill mode: 'parallel' kills all at once, 'sequence' kills one per second
+     */
     killAll(type?: 'sequence' | 'parallel'): void;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/jobs/child-pool/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/jobs/child-pool/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,UAAU,EAA0B,MAAM,wBAAwB,CAAC;AAI5E,OAAO,KAAK,EAAE,UAAU,EAAwB,MAAM,sBAAsB,CAAC;AAE7E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,qBAAa,YAAa,SAAQ,YAAY;IAC5C,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,EAAE,EAAE,YAAY,CAAC;gBAEL,GAAG,GAAE,gBAAqB;IAgCtC,WAAW,IAAI,IAAI;IAanB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAUzB,MAAM,CAAC,MAAM,SAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA2B3C,aAAa,CAAC,YAAY,EAAE,UAAU,GAAG,IAAI;IAevC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAShF,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAKvF,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAclE,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAIvC,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IAwBrC,OAAO,IAAI,MAAM,EAAE;IAInB,OAAO,CAAC,IAAI,GAAE,UAAU,GAAG,UAAuB,GAAG,IAAI;CAgB1D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/jobs/child-pool/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAEzD,OAAO,EAAE,UAAU,EAA0B,MAAM,wBAAwB,CAAC;AAI5E,OAAO,KAAK,EAAE,UAAU,EAAwB,MAAM,sBAAsB,CAAC;AAE7E,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,YAAY;IAC5C,yBAAyB;IACzB,MAAM,EAAE,UAAU,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6BAA6B;IAC7B,EAAE,EAAE,YAAY,CAAC;gBAEL,GAAG,GAAE,gBAAqB;IAiCtC;;;;OAIG;IACH,WAAW,IAAI,IAAI;IAanB;;;;OAIG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAU/B;;;;;;;;;OASG;IACG,MAAM,CAAC,MAAM,SAAI,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA2B3C;;;;OAIG;IACH,aAAa,CAAC,YAAY,EAAE,UAAU,GAAG,IAAI;IAc7C;;;;;;;;OAQG;IACG,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQtF;;OAEG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI7F;;;;;;;;OAQG;IACG,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAelE,iCAAiC;IACjC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAI7C;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC;IA0BrC,0CAA0C;IAC1C,OAAO,IAAI,MAAM,EAAE;IAInB;;;;OAIG;IACH,OAAO,CAAC,IAAI,GAAE,UAAU,GAAG,UAAuB,GAAG,IAAI;CAgB1D"}

package/dist/cjs/jobs/child-pool/index.js

@@ -1,6 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChildPoolJob = void 0;
+/**
+ * @module jobs/child-pool
+ * @description Child process pool manager. Maintains a set of child processes, distributes tasks
+ * through a load balancing algorithm, avoiding the overhead of frequent process creation and destruction.
+ *
+ * Core features:
+ * - Pool size: min=3, max=6, configurable
+ * - Load balancing: supports multiple algorithms (polling/weights/random, etc.), default is polling
+ * - Process binding: binds specific IDs to fixed processes via boundMap (e.g. session binding)
+ * - Auto cleanup: child processes are automatically removed from the pool on exit/error
+ *
+ * Usage:
+ * ```ts
+ * const pool = new ChildPoolJob();
+ * await pool.create(3); // Create 3 child processes
+ * await pool.run('service/job'); // Load balancer selects a process to execute
+ * ```
+ */
 const events_1 = require("events");
 const index_js_1 = require("../load-balancer/index.js");
 const index_js_2 = require("../../loader/index.js");
@@ -8,6 +26,12 @@ const jobProcess_js_1 = require("../child/jobProcess.js");
 const channel_js_1 = require("../../const/channel.js");
 const helper_js_1 = require("../../utils/helper.js");
 const index_js_3 = require("../../config/index.js");
+/**
+ * ChildPoolJob - Child process pool
+ *
+ * Manages a set of child processes, distributes tasks through LoadBalancer.
+ * Inherits EventEmitter, listens for child process exit/error events for auto cleanup.
+ */
 class ChildPoolJob extends events_1.EventEmitter {
     constructor(opt = {}) {
         super();
@@ -21,6 +45,7 @@ class ChildPoolJob extends events_1.EventEmitter {
         this.min = 3;
         this.max = 6;
         this.strategy = 'polling';
+        // Default weight is 1, can be customized via configuration
         this.weights = new Array(this.max).fill(0).map((_v, i) => {
             const w = options.weights[i];
             return (0, helper_js_1.validValue)(w) ? w : 1;
@@ -36,6 +61,11 @@ class ChildPoolJob extends events_1.EventEmitter {
         }
         this._initEvents();
     }
+    /**
+     * Initialize event listeners
+     *
+     * Automatically removes child processes from the pool and load balancer on exit or error.
+     */
     _initEvents() {
         this.on(channel_js_1.Events.childProcessExit, (data) => {
             if (data.pid !== undefined) {
@@ -48,6 +78,11 @@ class ChildPoolJob extends events_1.EventEmitter {
             }
         });
     }
+    /**
+     * Remove a child process from the pool
+     *
+     * Removes from both children map and load balancer.
+     */
     _removeChild(pid) {
         const length = Object.keys(this.children).length;
         const lbOpt = {
@@ -57,6 +92,16 @@ class ChildPoolJob extends events_1.EventEmitter {
         this.LB.del(lbOpt);
         delete this.children[pid];
     }
+    /**
+     * Create a specified number of child processes
+     *
+     * New processes are added to the pool and load balancer.
+     * The count is limited by max; excess processes will not be created.
+     *
+     * @param number - Number of processes to create
+     * @returns List of all process PIDs after creation
+     * @throws Throws an error if the count is invalid or exceeds the maximum limit
+     */
     async create(number = 3) {
         if (number < 0 || number > this.max) {
             throw new Error('[ee-core] [jobs/child-pool] The number is invalid !');
@@ -65,6 +110,7 @@ class ChildPoolJob extends events_1.EventEmitter {
         if (currentNumber > this.max) {
             throw new Error(`[ee-core] [jobs/child-pool] The number of current processes number: ${currentNumber} is greater than the maximum: ${this.max} !`);
         }
+        // Adjust creation count to not exceed maximum limit
         if (number + currentNumber > this.max) {
             number = this.max - currentNumber;
         }
@@ -79,7 +125,11 @@ class ChildPoolJob extends events_1.EventEmitter {
         }
         return Object.keys(this.children);
     }
-    // Post creation processing of child processes
+    /**
+     * Registration handling after child process creation
+     *
+     * Adds the process to the children map and load balancer.
+     */
     _childCreated(childProcess) {
         const pid = childProcess.pid;
         if (pid === undefined)
@@ -92,18 +142,36 @@ class ChildPoolJob extends events_1.EventEmitter {
         };
         this.LB.add(lbTask);
     }
-    // Execute a job file
+    /**
+     * Execute a task file
+     *
+     * Selects a child process via the load balancer and sends a run command to execute the task.
+     *
+     * @param filepath - Task file path
+     * @param params - Task parameters
+     * @returns The child process instance executing the task
+     */
     async run(filepath, params = {}) {
         const jobPath = (0, index_js_2.getFullpath)(filepath);
         const childProcess = await this.getChild();
         childProcess.dispatch('run', jobPath, params);
         return childProcess;
     }
-    // Asynchronous execution of a job file
+    /**
+     * Asynchronously execute a task file (alias for run)
+     */
     async runPromise(filepath, params = {}) {
         return this.run(filepath, params);
     }
-    // Get the bound process object
+    /**
+     * Get a bound child process
+     *
+     * The same boundId is always assigned to the same child process, suitable for session binding scenarios.
+     * If the bound process no longer exists, a new process is reassigned.
+     *
+     * @param boundId - Binding identifier (e.g. user ID, session ID)
+     * @returns Child process instance
+     */
     async getBoundChild(boundId) {
         let proc;
         const boundPid = this.boundMap.get(boundId);
@@ -112,17 +180,29 @@ class ChildPoolJob extends events_1.EventEmitter {
             if (proc)
                 return proc;
         }
+        // Bound process does not exist, retrieve and bind a new one
         proc = await this.getChild();
         this.boundMap.set(boundId, proc.pid ?? 0);
         return proc;
     }
+    /** Get a child process by PID */
     getChildByPid(pid) {
         return this.children[pid] || null;
     }
+    /**
+     * Get an available child process
+     *
+     * If the pool is empty, automatically creates one.
+     * Uses the load balancer to select a process.
+     *
+     * @returns Child process instance
+     * @throws Throws an error if retrieval fails
+     */
     async getChild() {
         let proc;
         const currentPids = Object.keys(this.children);
         if (currentPids.length === 0) {
+            // Pool is empty, auto-create
             const subIds = await this.create(1);
             const firstId = subIds[0];
             if (firstId) {
@@ -130,6 +210,7 @@ class ChildPoolJob extends events_1.EventEmitter {
             }
         }
         else {
+            // Select via load balancer
             const picked = this.LB.pickOne();
             if (picked && typeof picked.id === 'number') {
                 proc = this.children[picked.id];
@@ -140,9 +221,15 @@ class ChildPoolJob extends events_1.EventEmitter {
         }
         return proc;
     }
+    /** Get PID list of all child processes */
     getPids() {
         return Object.keys(this.children);
     }
+    /**
+     * Kill all child processes
+     *
+     * @param type - Kill mode: 'parallel' kills all at once, 'sequence' kills one per second
+     */
     killAll(type = 'parallel') {
         let i = 1;
         Object.keys(this.children).forEach(key => {