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

package/dist/cjs/core/utils/index.js

@@ -1,4 +1,37 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -9,32 +42,49 @@ exports.callFn = callFn;
 exports.getResolvedFilename = getResolvedFilename;
 exports.isBytecodeClass = isBytecodeClass;
 exports.filePatterns = filePatterns;
+exports.loadFileAsync = loadFileAsync;
+/**
+ * @module core/utils
+ * @description Core utility functions. Provides file loading, function invocation, bytecode class detection,
+ * and other foundational capabilities. Serves as a low-level dependency for FileLoader and other modules.
+ */
 require("bytenode");
 const type_check_js_1 = require("../../utils/type_check.js");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const module_1 = require("module");
-const requireMod = (0, module_1.createRequire)(__filename);
+// __filename is available in CJS; in pure ESM without a bundler, use cwd as the base path for createRequire
+const requireMod = (0, module_1.createRequire)(typeof __filename !== 'undefined'
+    ? __filename
+    : path_1.default.join(process.cwd(), '__virtual__.js'));
 const Module = requireMod('module');
-// Module._extensions:
-// '.js': [Function (anonymous)],
-// '.json': [Function (anonymous)],
-// '.node': [Function: func],
-// '.jsc': [Function (anonymous)]
+// File extensions natively supported by Node.js (including .jsc registered by bytenode)
 const extensions = Module._extensions;
 exports.extensions = extensions;
+/**
+ * Load a file synchronously
+ *
+ * Execution flow:
+ * 1. Non-JS files (extensions not in Module._extensions) -> return file content as Buffer
+ * 2. JS/CJS/JSC files -> load module using require()
+ * 3. ESM modules (with __esModule marker) -> extract default export
+ *
+ * @param filepath - Absolute file path
+ * @returns File content (Buffer) or module export value
+ * @throws Throws an error containing the file path when file loading fails
+ */
 function loadFile(filepath) {
     try {
-        // if not js module, just return content buffer
+        // Non-JS module, return file content directly
         const extname = path_1.default.extname(filepath);
         if (extname && !extensions[extname]) {
             return fs_1.default.readFileSync(filepath);
         }
-        // require js module
+        // Load JS module
         const obj = requireMod(filepath);
         if (!obj)
             return obj;
-        // it's es module
+        // ESM interop: extract default export
         if (obj.__esModule)
             return 'default' in obj ? obj.default : obj;
         return obj;
@@ -45,29 +95,87 @@ function loadFile(filepath) {
         throw error;
     }
 }
+/**
+ * Call a function with bound context
+ *
+ * @param fn - Function to call
+ * @param args - Function argument list
+ * @param ctx - Function execution context (this binding); if not provided, calls directly
+ * @returns Function return value; returns undefined if fn is not a function
+ */
 async function callFn(fn, args, ctx) {
     args = args || [];
     if (!(0, type_check_js_1.isFunction)(fn))
         return undefined;
     return ctx ? fn.call(ctx, ...args) : fn(...args);
 }
+/**
+ * Get the relative path name of a file
+ *
+ * Converts an absolute path to a relative path based on baseDir, using forward slashes as separators.
+ *
+ * @param filepath - Absolute file path
+ * @param baseDir - Base directory
+ * @returns Relative path (forward slash separated)
+ */
 function getResolvedFilename(filepath, baseDir) {
     const reg = /[/\\]/g;
     return filepath.replace(baseDir + path_1.default.sep, '').replace(reg, '/');
 }
 /**
- * 字节码类
+ * Determine if an export is a bytecode class
+ *
+ * Checks whether the toString() result contains '[class'.
+ * Classes from bytenode-compiled .jsc files appear as '[class XXX]' in Node.js.
+ *
+ * @param exports - Export value to check
+ * @returns Whether it is a bytecode class
  */
 function isBytecodeClass(exports) {
     if (!exports)
         return false;
-    // 标识
     return String(exports).indexOf('[class') !== -1;
 }
 /**
- * 文件类型
+ * Get supported file match patterns
+ *
+ * Used for filtering file types when globby scans directories.
+ *
+ * @returns File pattern list (.js and .jsc)
  */
 function filePatterns() {
     return ['**/*.js', '**/*.jsc'];
 }
+/**
+ * Load a file asynchronously (ESM support)
+ *
+ * Same functionality as loadFile, but uses dynamic import() to load modules,
+ * supporting ESM format files. Non-JS files are read using fs.promises.readFile.
+ *
+ * @param filepath - Absolute file path
+ * @returns File content (Buffer) or module export value
+ * @throws Throws an error containing the file path when file loading fails
+ */
+async function loadFileAsync(filepath) {
+    try {
+        const extname = path_1.default.extname(filepath);
+        // Non-JS/ESM files: return content as Buffer
+        if (extname && !extensions[extname] && extname !== '.mjs') {
+            return fs_1.default.promises.readFile(filepath);
+        }
+        // Dynamic import, supporting both ESM and CJS
+        const obj = await Promise.resolve(`${filepath}`).then(s => __importStar(require(s)));
+        if (!obj)
+            return obj;
+        // ESM interop: extract default export
+        if (obj.__esModule)
+            return 'default' in obj ? obj.default : obj;
+        return obj;
+    }
+    catch (err) {
+        const error = err;
+        error.message = `[ee-core] load file async: ${filepath}, error: ${error.message}`;
+        throw error;
+    }
+}
 //# sourceMappingURL=index.js.map

package/dist/cjs/core/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/utils/index.ts"],"names":[],"mappings":";;;;;;AAiBA,4BAmBC;AAED,wBAIC;AAED,kDAGC;AAKD,0CAIC;AAKD,oCAEC;AA/DD,oBAAkB;AAClB,6DAA0E;AAC1E,gDAAwB;AACxB,4CAAoB;AACpB,mCAAuC;AAEvC,MAAM,UAAU,GAAG,IAAA,sBAAa,EAAC,UAAU,CAAC,CAAC;AAC7C,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;AAEpC,sBAAsB;AACtB,iCAAiC;AACjC,mCAAmC;AACnC,6BAA6B;AAC7B,iCAAiC;AAEjC,MAAM,UAAU,GAA6B,MAAM,CAAC,WAAW,CAAC;AAkDvD,gCAAU;AAhDnB,SAAgB,QAAQ,CAAC,QAAgB;IACvC,IAAI,CAAC;QACH,+CAA+C;QAC/C,MAAM,OAAO,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,OAAO,YAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC;QAED,oBAAoB;QACpB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG;YAAE,OAAO,GAAG,CAAC;QACrB,iBAAiB;QACjB,IAAI,GAAG,CAAC,UAAU;YAAE,OAAO,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QAChE,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,GAAY,CAAC;QAC3B,KAAK,CAAC,OAAO,GAAG,wBAAwB,QAAQ,YAAY,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5E,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAEM,KAAK,UAAU,MAAM,CAAC,EAAmC,EAAE,IAAgB,EAAE,GAAa;IAC/F,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;IAClB,IAAI,CAAC,IAAA,0BAAe,EAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;AACnD,CAAC;AAED,SAAgB,mBAAmB,CAAC,QAAgB,EAAE,OAAe;IACnE,MAAM,GAAG,GAAG,QAAQ,CAAC;IACrB,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,GAAG,cAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACpE,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe,CAAC,OAAgB;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,KAAK;IACL,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/utils/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkCA,4BAmBC;AAUD,wBAIC;AAWD,kDAGC;AAWD,0CAGC;AASD,oCAEC;AAcD,sCAmBC;AA3ID;;;;GAIG;AACH,oBAAkB;AAClB,6DAA0E;AAC1E,gDAAwB;AACxB,4CAAoB;AACpB,mCAAuC;AAEvC,4GAA4G;AAC5G,MAAM,UAAU,GAAG,IAAA,sBAAa,EAC9B,OAAO,UAAU,KAAK,WAAW;IAC/B,CAAC,CAAC,UAAU;IACZ,CAAC,CAAC,cAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,gBAAgB,CAAC,CAC/C,CAAC;AACF,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;AAEpC,wFAAwF;AACxF,MAAM,UAAU,GAA6B,MAAM,CAAC,WAAW,CAAC;AAwFvD,gCAAU;AAtFnB;;;;;;;;;;;GAWG;AACH,SAAgB,QAAQ,CAAC,QAAgB;IACvC,IAAI,CAAC;QACH,8CAA8C;QAC9C,MAAM,OAAO,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACpC,OAAO,YAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC;QAED,iBAAiB;QACjB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;QACjC,IAAI,CAAC,GAAG;YAAE,OAAO,GAAG,CAAC;QACrB,sCAAsC;QACtC,IAAI,GAAG,CAAC,UAAU;YAAE,OAAO,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QAChE,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,GAAY,CAAC;QAC3B,KAAK,CAAC,OAAO,GAAG,wBAAwB,QAAQ,YAAY,KAAK,CAAC,OAAO,EAAE,CAAC;QAC5E,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,UAAU,MAAM,CAAC,EAAmC,EAAE,IAAgB,EAAE,GAAa;IAC/F,IAAI,GAAG,IAAI,IAAI,EAAE,CAAC;IAClB,IAAI,CAAC,IAAA,0BAAe,EAAC,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,mBAAmB,CAAC,QAAgB,EAAE,OAAe;IACnE,MAAM,GAAG,GAAG,QAAQ,CAAC;IACrB,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,GAAG,cAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;AACpE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAAC,OAAgB;IAC9C,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,YAAY;IAC1B,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC;AAID;;;;;;;;;GASG;AACI,KAAK,UAAU,aAAa,CAAC,QAAgB;IAClD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACvC,6CAA6C;QAC7C,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;YAC1D,OAAO,YAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACxC,CAAC;QAED,8CAA8C;QAC9C,MAAM,GAAG,GAAG,yBAAa,QAAQ,uCAAC,CAAC;QACnC,IAAI,CAAC,GAAG;YAAE,OAAO,GAAG,CAAC;QACrB,sCAAsC;QACtC,IAAI,GAAG,CAAC,UAAU;YAAE,OAAO,SAAS,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;QAChE,OAAO,GAAG,CAAC;IACb,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,KAAK,GAAG,GAAY,CAAC;QAC3B,KAAK,CAAC,OAAO,GAAG,8BAA8B,QAAQ,YAAY,KAAK,CAAC,OAAO,EAAE,CAAC;QAClF,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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/cjs/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"}