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

package/dist/cjs/socket/httpServer.js

@@ -4,6 +4,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpServer = void 0;
+/**
+ * @module socket/httpServer
+ * @description HTTP/HTTPS server. Provides RESTful API services based on the Koa framework,
+ * routing HTTP requests to corresponding controller methods.
+ *
+ * Request routing rules:
+ * - URL path maps to controller path, e.g., /controller/user/add → controller.user.add
+ * - GET request parameters from query, POST request parameters from body
+ * - Paths starting with 'controller' are used directly, otherwise 'controller' prefix is added automatically
+ * - URIs in filterRequest return specified data directly without going through controllers
+ *
+ * Middleware loading order:
+ * 1. Error handler (errorHandler)
+ * 2. Pre-middleware (preMiddleware)
+ * 3. CORS cross-origin middleware
+ * 4. koa-body request body parsing middleware
+ * 5. Core routing dispatch middleware (_dispatch)
+ * 6. Post-middleware (postMiddleware)
+ */
 const debug_1 = __importDefault(require("debug"));
 const assert_1 = __importDefault(require("assert"));
 const type_check_js_1 = require("../utils/type_check.js");
@@ -18,15 +37,37 @@ const index_js_2 = require("../ps/index.js");
 const index_js_3 = require("../controller/index.js");
 const index_js_4 = require("../config/index.js");
 const index_js_5 = require("../utils/port/index.js");
+const utils_js_1 = require("./utils.js");
 const debugLog = (0, debug_1.default)('ee-core:socket:httpServer');
+/**
+ * HttpServer - HTTP server
+ *
+ * Created using factory pattern (static create()), because initialization requires async port acquisition.
+ * When enable=false in config, the service will not start after creation.
+ */
 class HttpServer {
     constructor() {
         const config = (0, index_js_4.getConfig)();
         this.config = config.httpServer;
         this.channelSeparator = config.mainServer.channelSeparator || '/';
         this.httpApp = undefined;
-        this.init();
     }
+    /**
+     * Factory method: create and initialize HttpServer
+     *
+     * @returns Fully initialized HttpServer instance
+     */
+    static async create() {
+        const instance = new HttpServer();
+        await instance.init();
+        return instance;
+    }
+    /**
+     * Initialize HTTP server
+     *
+     * Acquires an available port then creates a Koa application and starts listening.
+     * The port number is written to process.env.EE_HTTP_PORT for other modules to access.
+     */
     async init() {
         if (this.config.enable === false) {
             return;
@@ -39,12 +80,17 @@ class HttpServer {
         this.config.port = port;
         this._create();
     }
+    /**
+     * Create Koa application and start HTTP/HTTPS service
+     *
+     * Loads middleware in order, handles HTTPS configuration, and starts listening.
+     */
     async _create() {
         const config = this.config;
         const koaConfig = config.koaConfig || {};
         const preMiddleware = koaConfig.preMiddleware || [];
         const postMiddleware = koaConfig.postMiddleware || [];
-        const errorHandler = koaConfig.errorHandler;
+        const errorHandler = koaConfig.errorHandler || null;
         const isHttps = config.https.enable === true;
         const sslOptions = {};
         if (isHttps) {
@@ -60,15 +106,15 @@ class HttpServer {
         const url = config.protocol + config.host + ':' + config.port;
         const corsOptions = config.cors;
         const koaApp = new koa_1.default();
-        // 设置错误处理器，便于统一错误代码处理
+        // Set up error handler for unified error code handling
         this._setupErrorHandler(koaApp, errorHandler);
-        // 加载前置中间件
+        // Load pre-middleware
         this._loadMiddlewares(koaApp, preMiddleware, 'pre');
-        // 核心中间件
+        // Core middleware
         koaApp.use((0, koa2_cors_1.default)(corsOptions));
         koaApp.use((0, koa_body_1.default)(config.body));
         koaApp.use(this._dispatch.bind(this));
-        // 加载后置中间件
+        // Load post-middleware
         this._loadMiddlewares(koaApp, postMiddleware, 'post');
         let msg = '[socket/http] server is: ' + url;
         const listenOpt = { host: config.host, port: config.port };
@@ -91,44 +137,48 @@ class HttpServer {
         }
         this.httpApp = koaApp;
     }
+    /**
+     * Core routing dispatch middleware
+     *
+     * Maps HTTP request paths to controller methods:
+     * 1. Remove leading '/' from path
+     * 2. Check if path is in filter list (e.g., favicon.ico)
+     * 3. Ensure path starts with 'controller'
+     * 4. Find and call controller method via resolveControllerFn
+     * 5. GET requests pass query params, POST requests pass body params
+     *
+     * Error handling: When controller method throws an exception, returns 500 + { error: 'Internal Server Error' }
+     */
     async _dispatch(ctx, next) {
         const controller = (0, index_js_3.getController)();
         const { filterRequest } = (0, index_js_4.getConfig)().httpServer;
         let uriPath = ctx.request.path;
         const method = ctx.request.method;
         let params = ctx.request.query;
+        // Deep copy query object to avoid Express/Koa proxy object issues
         params = (0, type_check_js_1.isObject)(params) ? JSON.parse(JSON.stringify(params)) : {};
         const body = ctx.request.body;
         ctx.response.status = 200;
         try {
-            // 找函数
-            // 去除开头的 '/'
+            // Remove leading '/'
             if (uriPath.indexOf('/') === 0) {
                 uriPath = uriPath.substring(1);
             }
-            // 过滤
+            // Filter requests that don't need routing
             if (filterRequest.uris.includes(uriPath)) {
                 ctx.response.body = filterRequest.returnData;
                 await next();
                 return;
             }
+            // Automatically add 'controller' prefix
             if (uriPath.slice(0, 10) !== 'controller') {
                 uriPath = 'controller/' + uriPath;
             }
             const cmd = uriPath.split('/').join(this.channelSeparator);
             debugLog('[request] uri %s', cmd);
+            // GET uses query, POST uses body
             const args = method === 'POST' ? body : params;
-            let fn = null;
-            if ((0, type_check_js_1.isString)(cmd)) {
-                const actions = cmd.split(this.channelSeparator);
-                let obj = { controller };
-                actions.forEach((key) => {
-                    obj = obj[key];
-                    if (!obj)
-                        throw new Error(`class or function '${key}' not exists`);
-                });
-                fn = obj;
-            }
+            const fn = (0, utils_js_1.resolveControllerFn)(controller, cmd, this.channelSeparator);
             if (!fn)
                 throw new Error('function not exists');
             const result = await fn.call(controller, args, ctx);
@@ -136,31 +186,47 @@ class HttpServer {
         }
         catch (err) {
             index_js_1.coreLogger.error('[httpServer] throw error:', err);
+            ctx.response.status = 500;
+            ctx.response.body = { error: 'Internal Server Error' };
+            // Attach original error to ctx for downstream error-reporting middleware
+            ctx.__ee_error = err;
         }
         await next();
     }
+    /**
+     * Get Koa application instance
+     *
+     * @returns Koa instance, or undefined if HTTP service is not enabled
+     */
     getHttpApp() {
         return this.httpApp;
     }
-    // 设置错误处理函数
+    /**
+     * Set up Koa error handler
+     *
+     * @param app - Koa application instance
+     * @param errorHandler - Error handler function that receives an Error parameter
+     */
     _setupErrorHandler(app, errorHandler) {
         if ((0, type_check_js_1.isFunction)(errorHandler)) {
             app.on('error', errorHandler);
         }
     }
     /**
-     * 加载前置、后置中间件
-     * @param {*} app koaApp示例
-     * @param {*} middlewares 中间件数组
-     * @param {*} type 类型，pre/post
+     * Load pre/post middleware
+     *
+     * Middleware can be factory functions (called to return Koa middleware) or direct middleware functions.
+     * Invalid middleware will be skipped with a warning.
+     *
+     * @param app - Koa application instance
+     * @param middlewares - Middleware array
+     * @param type - Type identifier (pre/post), used for warning messages
      */
     _loadMiddlewares(app, middlewares = [], type = 'pre') {
         if ((0, type_check_js_1.isArray)(middlewares)) {
             middlewares.forEach((middleware) => {
                 if ((0, type_check_js_1.isFunction)(middleware)) {
-                    // middleware是一个方法
-                    // 返回值是中间件(ctx, next) => {}的异步函数
-                    // 便于使用async/await进行同步编程
+                    // middleware is a factory function, called to return (ctx, next) => {} style middleware
                     app.use(middleware());
                 }
                 else {

package/dist/cjs/socket/httpServer.js.map

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

package/dist/cjs/socket/index.d.ts

@@ -1,3 +1,15 @@
+/**
+ * @module socket
+ * @description Communication service module entry point. Provides creation and management of three communication modes:
+ *
+ * - SocketServer: SocketIO server for third-party software communication via WebSocket
+ * - HttpServer: HTTP/HTTPS server for RESTful API calls
+ * - IpcServer: Electron IPC server for renderer process communication via ipcRenderer
+ *
+ * Usage:
+ * - loadSocket(): Called during framework startup to create and initialize all communication services
+ * - getSocketServer() / getHttpServer() / getIpcServer(): Get service instances
+ */
 export { SocketServer } from './socketServer.js';
 export { HttpServer } from './httpServer.js';
 export { IpcServer } from './ipcServer.js';
@@ -8,11 +20,41 @@ import { SocketServer } from './socketServer.js';
 import { HttpServer } from './httpServer.js';
 import { IpcServer } from './ipcServer.js';
 export { Koa, IoServer, IoClient };
-export declare function createSocketServer(): SocketServer;
+/**
+ * Create SocketIO server
+ *
+ * @returns SocketServer instance
+ */
+export declare function createSocketServer(): Promise<SocketServer>;
+/**
+ * Get SocketIO server instance
+ */
 export declare function getSocketServer(): SocketServer | null;
-export declare function createHttpServer(): HttpServer;
+/**
+ * Create HTTP server
+ *
+ * @returns HttpServer instance
+ */
+export declare function createHttpServer(): Promise<HttpServer>;
+/**
+ * Get HTTP server instance
+ */
 export declare function getHttpServer(): HttpServer | null;
+/**
+ * Create IPC server
+ *
+ * @returns IpcServer instance
+ */
 export declare function createIpcServer(): IpcServer;
+/**
+ * Get IPC server instance
+ */
 export declare function getIpcServer(): IpcServer | null;
-export declare function loadSocket(): void;
+/**
+ * Load and initialize all communication services
+ *
+ * Created in order: SocketIO → HTTP → IPC
+ * Called by Application.run() during the framework startup flow.
+ */
+export declare function loadSocket(): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/socket/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,QAAQ,MAAM,kBAAkB,CAAC;AACxC,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAanC,wBAAgB,kBAAkB,IAAI,YAAY,CAGjD;AAGD,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAGD,wBAAgB,gBAAgB,IAAI,UAAU,CAG7C;AAGD,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAGD,wBAAgB,eAAe,IAAI,SAAS,CAG3C;AAGD,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAE/C;AAGD,wBAAgB,UAAU,IAAI,IAAI,CAIjC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,QAAQ,MAAM,kBAAkB,CAAC;AACxC,OAAO,GAAG,MAAM,KAAK,CAAC;AACtB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAanC;;;;GAIG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,YAAY,CAAC,CAGhE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,YAAY,GAAG,IAAI,CAErD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,UAAU,CAAC,CAG5D;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,SAAS,CAG3C;AAED;;GAEG;AACH,wBAAgB,YAAY,IAAI,SAAS,GAAG,IAAI,CAE/C;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAIhD"}

package/dist/cjs/socket/index.js

@@ -11,6 +11,18 @@ exports.getHttpServer = getHttpServer;
 exports.createIpcServer = createIpcServer;
 exports.getIpcServer = getIpcServer;
 exports.loadSocket = loadSocket;
+/**
+ * @module socket
+ * @description Communication service module entry point. Provides creation and management of three communication modes:
+ *
+ * - SocketServer: SocketIO server for third-party software communication via WebSocket
+ * - HttpServer: HTTP/HTTPS server for RESTful API calls
+ * - IpcServer: Electron IPC server for renderer process communication via ipcRenderer
+ *
+ * Usage:
+ * - loadSocket(): Called during framework startup to create and initialize all communication services
+ * - getSocketServer() / getHttpServer() / getIpcServer(): Get service instances
+ */
 var socketServer_js_1 = require("./socketServer.js");
 Object.defineProperty(exports, "SocketServer", { enumerable: true, get: function () { return socketServer_js_1.SocketServer; } });
 var httpServer_js_1 = require("./httpServer.js");
@@ -26,42 +38,66 @@ exports.Koa = koa_1.default;
 const socketServer_js_2 = require("./socketServer.js");
 const httpServer_js_2 = require("./httpServer.js");
 const ipcServer_js_2 = require("./ipcServer.js");
+/** Service instance storage */
 const Instance = {
     socketServer: null,
     httpServer: null,
     ipcServer: null,
 };
-// create SocketServer
-function createSocketServer() {
-    Instance.socketServer = new socketServer_js_2.SocketServer();
+/**
+ * Create SocketIO server
+ *
+ * @returns SocketServer instance
+ */
+async function createSocketServer() {
+    Instance.socketServer = await socketServer_js_2.SocketServer.create();
     return Instance.socketServer;
 }
-// socketServer
+/**
+ * Get SocketIO server instance
+ */
 function getSocketServer() {
     return Instance.socketServer;
 }
-// create Http Server
-function createHttpServer() {
-    Instance.httpServer = new httpServer_js_2.HttpServer();
+/**
+ * Create HTTP server
+ *
+ * @returns HttpServer instance
+ */
+async function createHttpServer() {
+    Instance.httpServer = await httpServer_js_2.HttpServer.create();
     return Instance.httpServer;
 }
-// httpServer
+/**
+ * Get HTTP server instance
+ */
 function getHttpServer() {
     return Instance.httpServer;
 }
-// create IPC Server
+/**
+ * Create IPC server
+ *
+ * @returns IpcServer instance
+ */
 function createIpcServer() {
     Instance.ipcServer = new ipcServer_js_2.IpcServer();
     return Instance.ipcServer;
 }
-// ipcServer
+/**
+ * Get IPC server instance
+ */
 function getIpcServer() {
     return Instance.ipcServer;
 }
-// load socket server
-function loadSocket() {
-    createSocketServer();
-    createHttpServer();
+/**
+ * Load and initialize all communication services
+ *
+ * Created in order: SocketIO → HTTP → IPC
+ * Called by Application.run() during the framework startup flow.
+ */
+async function loadSocket() {
+    await createSocketServer();
+    await createHttpServer();
     createIpcServer();
 }
 //# sourceMappingURL=index.js.map

package/dist/cjs/socket/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":";;;;;;AAwBA,gDAGC;AAGD,0CAEC;AAGD,4CAGC;AAGD,sCAEC;AAGD,0CAGC;AAGD,oCAEC;AAGD,gCAIC;AA7DD,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AACrB,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAElB,yCAA+C;AAOjC,yFAPK,kBAAQ,OAOL;AANtB,wEAAwC;AAMhB,mBANjB,0BAAQ,CAMiB;AALhC,8CAAsB;AAKb,cALF,aAAG,CAKE;AAJZ,uDAAiD;AACjD,mDAA6C;AAC7C,iDAA2C;AAI3C,MAAM,QAAQ,GAIV;IACF,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;IAChB,SAAS,EAAE,IAAI;CAChB,CAAC;AAEF,sBAAsB;AACtB,SAAgB,kBAAkB;IAChC,QAAQ,CAAC,YAAY,GAAG,IAAI,8BAAY,EAAE,CAAC;IAC3C,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC;AAED,eAAe;AACf,SAAgB,eAAe;IAC7B,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC;AAED,qBAAqB;AACrB,SAAgB,gBAAgB;IAC9B,QAAQ,CAAC,UAAU,GAAG,IAAI,0BAAU,EAAE,CAAC;IACvC,OAAO,QAAQ,CAAC,UAAU,CAAC;AAC7B,CAAC;AAED,aAAa;AACb,SAAgB,aAAa;IAC3B,OAAO,QAAQ,CAAC,UAAU,CAAC;AAC7B,CAAC;AAED,oBAAoB;AACpB,SAAgB,eAAe;IAC7B,QAAQ,CAAC,SAAS,GAAG,IAAI,wBAAS,EAAE,CAAC;IACrC,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC;AAED,YAAY;AACZ,SAAgB,YAAY;IAC1B,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC;AAED,qBAAqB;AACrB,SAAgB,UAAU;IACxB,kBAAkB,EAAE,CAAC;IACrB,gBAAgB,EAAE,CAAC;IACnB,eAAe,EAAE,CAAC;AACpB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/socket/index.ts"],"names":[],"mappings":";;;;;;AAyCA,gDAGC;AAKD,0CAEC;AAOD,4CAGC;AAKD,sCAEC;AAOD,0CAGC;AAKD,oCAEC;AAQD,gCAIC;AAjGD;;;;;;;;;;;GAWG;AACH,qDAAiD;AAAxC,+GAAA,YAAY,OAAA;AACrB,iDAA6C;AAApC,2GAAA,UAAU,OAAA;AACnB,+CAA2C;AAAlC,yGAAA,SAAS,OAAA;AAElB,yCAA+C;AAOjC,yFAPK,kBAAQ,OAOL;AANtB,wEAAwC;AAMhB,mBANjB,0BAAQ,CAMiB;AALhC,8CAAsB;AAKb,cALF,aAAG,CAKE;AAJZ,uDAAiD;AACjD,mDAA6C;AAC7C,iDAA2C;AAI3C,+BAA+B;AAC/B,MAAM,QAAQ,GAIV;IACF,YAAY,EAAE,IAAI;IAClB,UAAU,EAAE,IAAI;IAChB,SAAS,EAAE,IAAI;CAChB,CAAC;AAEF;;;;GAIG;AACI,KAAK,UAAU,kBAAkB;IACtC,QAAQ,CAAC,YAAY,GAAG,MAAM,8BAAY,CAAC,MAAM,EAAE,CAAC;IACpD,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAgB,eAAe;IAC7B,OAAO,QAAQ,CAAC,YAAY,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,gBAAgB;IACpC,QAAQ,CAAC,UAAU,GAAG,MAAM,0BAAU,CAAC,MAAM,EAAE,CAAC;IAChD,OAAO,QAAQ,CAAC,UAAU,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAgB,aAAa;IAC3B,OAAO,QAAQ,CAAC,UAAU,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe;IAC7B,QAAQ,CAAC,SAAS,GAAG,IAAI,wBAAS,EAAE,CAAC;IACrC,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,SAAgB,YAAY;IAC1B,OAAO,QAAQ,CAAC,SAAS,CAAC;AAC5B,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,UAAU;IAC9B,MAAM,kBAAkB,EAAE,CAAC;IAC3B,MAAM,gBAAgB,EAAE,CAAC;IACzB,eAAe,EAAE,CAAC;AACpB,CAAC"}

package/dist/cjs/socket/ipcServer.d.ts

@@ -1,10 +1,40 @@
+/**
+ * IpcServer - IPC server
+ *
+ * Traverses the controller object tree and registers ipcMain channel handlers for each exported method.
+ * Uses recursive loop() to traverse nested controller directory structures.
+ */
 export declare class IpcServer {
+    /** Channel separator, default '/' */
     channelSeparator: string;
+    /** Controller directory name (used to generate property path prefix) */
     directory: string;
     constructor();
+    /**
+     * Initialize: traverse controller tree and register all IPC channels
+     */
     init(): void;
+    /**
+     * Recursively traverse the controller object tree
+     *
+     * Distinguished by EXPORTS symbol marker:
+     * - Objects with EXPORTS marker → leaf nodes (controller method collections), call register()
+     * - Objects without marker → intermediate nodes (directory/namespace), continue recursion
+     *
+     * @param obj - Current object being traversed
+     * @param pathname - Current property path
+     */
     loop(obj: Record<string, unknown>, pathname: string): void;
+    /**
+     * Register controller methods as IPC channel handlers
+     *
+     * Registers two handlers for each method:
+     * 1. ipcMain.on (synchronous model): Sets event.returnValue, supports async methods
+     * 2. ipcMain.handle (asynchronous model): Returns Promise, recommended
+     *
+     * @param exportObj - Controller method collection object
+     * @param propertyChain - Property path (e.g., 'controller.user')
+     */
     register(exportObj: Record<string, unknown>, propertyChain: string): void;
-    findFn(controller: Record<string, unknown>, c: string): ((...args: unknown[]) => unknown) | null;
 }
 //# sourceMappingURL=ipcServer.d.ts.map

package/dist/cjs/socket/ipcServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ipcServer.d.ts","sourceRoot":"","sources":["../../../src/socket/ipcServer.ts"],"names":[],"mappings":"AAUA,qBAAa,SAAS;IACpB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;;IAQlB,IAAI,IAAI,IAAI;IAKZ,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAiB1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;IAqCzE,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,IAAI;CAsBjG"}
+{"version":3,"file":"ipcServer.d.ts","sourceRoot":"","sources":["../../../src/socket/ipcServer.ts"],"names":[],"mappings":"AA4BA;;;;;GAKG;AACH,qBAAa,SAAS;IACpB,qCAAqC;IACrC,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;;IAQlB;;OAEG;IACH,IAAI,IAAI,IAAI;IAKZ;;;;;;;;;OASG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAgB1D;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI;CAiC1E"}

package/dist/cjs/socket/ipcServer.js

@@ -4,104 +4,121 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IpcServer = void 0;
+/**
+ * @module socket/ipcServer
+ * @description Electron IPC server. Registers controller methods as IPC channel handlers,
+ * enabling renderer processes to call main process controller methods via ipcRenderer.
+ *
+ * Supports two communication models:
+ * - send/on model (synchronous): Renderer uses ipcRenderer.sendSync(),
+ *   main process returns results via event.returnValue.
+ *   Supports both sync and async controller methods (Electron's sendSync enters a nested
+ *   message loop that processes microtasks, so event.returnValue set after await is received).
+ *
+ * - invoke/handle model (asynchronous): Renderer uses ipcRenderer.invoke(),
+ *   main process returns a Promise via ipcMain.handle().
+ *   ✅ Recommended model, supports both synchronous and asynchronous controller methods.
+ *
+ * Channel naming rule: Replace '.' in controller path with channelSeparator (default '/')
+ * Example: controller.user.add → controller/user/add
+ */
 const debug_1 = __importDefault(require("debug"));
-const type_check_js_1 = require("../utils/type_check.js");
 const electron_1 = require("electron");
 const index_js_1 = require("../log/index.js");
 const index_js_2 = require("../controller/index.js");
 const file_loader_js_1 = require("../core/loader/file_loader.js");
 const index_js_3 = require("../config/index.js");
+const utils_js_1 = require("./utils.js");
 const debugLog = (0, debug_1.default)('ee-core:socket:ipcServer');
+/**
+ * IpcServer - IPC server
+ *
+ * Traverses the controller object tree and registers ipcMain channel handlers for each exported method.
+ * Uses recursive loop() to traverse nested controller directory structures.
+ */
 class IpcServer {
     constructor() {
         this.channelSeparator = (0, index_js_3.getConfig)().mainServer.channelSeparator || '/';
         this.directory = 'controller';
         this.init();
     }
+    /**
+     * Initialize: traverse controller tree and register all IPC channels
+     */
     init() {
         const controller = (0, index_js_2.getController)();
         this.loop(controller, this.directory);
     }
+    /**
+     * Recursively traverse the controller object tree
+     *
+     * Distinguished by EXPORTS symbol marker:
+     * - Objects with EXPORTS marker → leaf nodes (controller method collections), call register()
+     * - Objects without marker → intermediate nodes (directory/namespace), continue recursion
+     *
+     * @param obj - Current object being traversed
+     * @param pathname - Current property path
+     */
     loop(obj, pathname) {
         const keys = Object.keys(obj);
-        // debugLog("[loop] keys: %j", keys);
         for (const key of keys) {
             if (key === 'constructor')
                 continue;
             const subObj = obj[key];
             const propertyChain = pathname + '.' + key;
+            // EXPORTS symbol marker indicates this is a controller method collection (leaf node)
             if (subObj && subObj[file_loader_js_1.EXPORTS] === true) {
                 this.register(subObj, propertyChain);
             }
             else if (typeof subObj === 'object') {
-                // 如果子对象依然是对象，则递归调用继续判断
                 this.loop(subObj, propertyChain);
             }
         }
     }
+    /**
+     * Register controller methods as IPC channel handlers
+     *
+     * Registers two handlers for each method:
+     * 1. ipcMain.on (synchronous model): Sets event.returnValue, supports async methods
+     * 2. ipcMain.handle (asynchronous model): Returns Promise, recommended
+     *
+     * @param exportObj - Controller method collection object
+     * @param propertyChain - Property path (e.g., 'controller.user')
+     */
     register(exportObj, propertyChain) {
         const controller = (0, index_js_2.getController)();
         const keys = Object.keys(exportObj);
         for (const key of keys) {
-            // Supports two types of routing separators
-            // channel: controller.file.function | controller/file/function
             const tmpChannel = `${propertyChain}.${key}`;
             const channel = tmpChannel.split('.').join(this.channelSeparator);
             debugLog('[register] channel %s', channel);
-            // send/on model
+            // send/on model (synchronous)
+            // Electron's sendSync enters a nested message loop that processes microtasks,
+            // so event.returnValue set after await IS received by sendSync.
             electron_1.ipcMain.on(channel, async (event, params) => {
                 try {
-                    const fn = this.findFn(controller, channel);
+                    const fn = (0, utils_js_1.resolveControllerFn)(controller, channel, this.channelSeparator);
                     if (!fn)
                         return;
                     const result = await fn.call(controller, params, event);
                     event.returnValue = result;
-                    event.reply(channel, result);
                 }
                 catch (e) {
                     index_js_1.coreLogger.error('[socket/IpcServer] send/on throw error:', e);
+                    // Send error info back so renderer can distinguish errors from legitimate undefined
+                    event.returnValue = { __EE_ERROR__: true, message: e instanceof Error ? e.message : String(e) };
                 }
             });
-            // invoke/handle model
+            // invoke/handle model (asynchronous, recommended)
+            // Throw error so renderer's ipcRenderer.invoke() rejects, allowing try/catch on renderer side
             electron_1.ipcMain.handle(channel, async (event, params) => {
-                try {
-                    const fn = this.findFn(controller, channel);
-                    if (!fn)
-                        return undefined;
-                    return await fn.call(controller, params, event);
-                }
-                catch (e) {
-                    index_js_1.coreLogger.error('[socket/IpcServer] invoke/handle throw error:', e);
+                const fn = (0, utils_js_1.resolveControllerFn)(controller, channel, this.channelSeparator);
+                if (!fn)
                     return undefined;
-                }
+                return await fn.call(controller, params, event);
             });
         }
     }
-    findFn(controller, c) {
-        try {
-            // 找函数
-            const cmd = c;
-            let fn = null;
-            if ((0, type_check_js_1.isString)(cmd)) {
-                const actions = cmd.split(this.channelSeparator);
-                debugLog('[findFn] channel %o', actions);
-                let obj = { controller };
-                for (const key of actions) {
-                    obj = obj[key];
-                    if (!obj)
-                        throw new Error(`class or function '${key}' not exists`);
-                }
-                fn = obj;
-            }
-            if (!fn)
-                throw new Error('function not exists');
-            return fn;
-        }
-        catch (err) {
-            index_js_1.coreLogger.error('[socket/IpcServer] throw error:', err);
-            return null;
-        }
-    }
 }
 exports.IpcServer = IpcServer;
 //# sourceMappingURL=ipcServer.js.map