koatty 4.1.6 → 4.1.8

package/dist/index.mjs

@@ -1,501 +1,796 @@
+import { LoadConfigs } from 'koatty_config';
+export { Config } from 'koatty_config';
+import { IOC, TAGGED_CLS } from 'koatty_container';
+export * from 'koatty_container';
+import { AppEvent, AppEventArr, asyncEvent, ComponentManager, implementsMiddlewareInterface, MIDDLEWARE_OPTIONS, protocolMiddleware, implementsControllerInterface, implementsServiceInterface, implementsAspectInterface, Koatty } from 'koatty_core';
+export * from 'koatty_core';
+export * from 'koatty_exception';
+import { Helper } from 'koatty_lib';
+export { Helper } from 'koatty_lib';
+export * from 'koatty_router';
+export * from 'koatty_serve';
+import { DefaultLogger } from 'koatty_logger';
+export { Log, LogLevelType, DefaultLogger as Logger } from 'koatty_logger';
+import { Load } from 'koatty_loader';
+import { Trace } from 'koatty_trace';
+import * as path from 'path';
+
 /*!
 * @Author: richen
-* @Date: 2026-02-04 10:57:35
+* @Date: 2026-02-10 09:13:30
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
 */
-import { LoadConfigs as t } from "koatty_config";
-
-export { Config } from "koatty_config";
-
-import { IOC as e, TAGGED_CLS as o } from "koatty_container";
-
-export * from "koatty_container";
-
-import { AppEvent as a, AppEventArr as s, asyncEvent as n, ComponentManager as i, implementsMiddlewareInterface as r, MIDDLEWARE_OPTIONS as l, protocolMiddleware as c, implementsControllerInterface as d, implementsServiceInterface as f, implementsAspectInterface as p, Koatty as g } from "koatty_core";
-
-export * from "koatty_core";
-
-export * from "koatty_exception";
-
-import { Helper as m } from "koatty_lib";
-
-export { Helper } from "koatty_lib";
-
-export * from "koatty_router";
-
-export * from "koatty_serve";
-
-import { DefaultLogger as u } from "koatty_logger";
-
-export { Log, DefaultLogger as Logger } from "koatty_logger";
-
-import { Load as h } from "koatty_loader";
-
-import { Trace as y } from "koatty_trace";
-
-import * as L from "path";
-
-/*
- * @Description: framework helper
- * @Usage:
- * @Author: richen
- * @Date: 2023-12-09 21:56:32
- * @LastEditTime: 2025-01-14 16:14:10
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */ const v = require("../../package.json");
-
-const {engines: w, version: C} = v;
-
-const E = C;
-
-const b = w.node.slice(1) || "12.0.0";
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __commonJS = (cb, mod) => function __require2() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
 
-function P(t, e, o, a) {
-  if (m.isClass(o) && o.name != t) throw Error(`The file(${e}) name should be always the same as class name.`);
-  if (o["__esModule"]) if (o.name === void 0) {
-    const a = Object.keys(o);
-    if (a[0] != t && m.isClass(o[a[0]])) throw Error(`The file(${e}) name should be always the same as class name.`);
-  } else if (o.name != t) throw Error(`The file(${e}) name should be always the same as class name.`);
-  if (!a) return;
-  if (a.has(t)) throw new Error(`A same class already exists. at \`${e}\`.`);
-  a.add(t);
+// package.json
+var require_package = __commonJS({
+  "package.json"(exports$1, module) {
+    module.exports = {
+      name: "koatty",
+      version: "4.1.8",
+      description: "Koa + Typescript = koatty. Use Typescript's decorator implement auto injection.",
+      scripts: {
+        build: "pnpm run build:js && pnpm run build:dts && pnpm run build:doc && pnpm run build:cp",
+        "build:js": "tsup",
+        "build:dts": "bash scripts/build-dts.sh",
+        "build:doc": "api-documenter markdown --input temp --output docs/api",
+        "build:cp": "node scripts/copyFiles && node ../../scripts/postBuild.js",
+        clean: "rimraf dist temp docs/api",
+        lint: "eslint --ext .ts,.js ./src",
+        test: "pnpm run lint && jest --passWithNoTests",
+        "test:cov": "jest --collectCoverage --detectOpenHandles"
+      },
+      main: "./dist/index.js",
+      exports: {
+        ".": {
+          types: "./dist/index.d.ts",
+          import: "./dist/index.mjs",
+          require: "./dist/index.js"
+        }
+      },
+      keywords: [
+        "koatty",
+        "koa",
+        "typescript",
+        "framework",
+        "mvc",
+        "http",
+        "https",
+        "websocket",
+        "grpc",
+        "quic",
+        "http2",
+        "http3",
+        "di",
+        "aop",
+        "ioc",
+        "inversion of control",
+        "dependency injection",
+        "aspect-oriented programming",
+        "decorator",
+        "decorator pattern",
+        "decorator factory"
+      ],
+      directories: {
+        doc: "docs"
+      },
+      repository: {
+        type: "git",
+        url: "git+https://github.com/koatty/koatty.git"
+      },
+      engines: {
+        node: ">=18.0.0"
+      },
+      author: {
+        name: "richenlin",
+        email: "richenlin@gmail.com"
+      },
+      license: "BSD-3-Clause",
+      bugs: {
+        url: "https://github.com/koatty/koatty/issues"
+      },
+      homepage: "https://github.com/koatty/koatty",
+      maintainers: [
+        {
+          name: "richenlin",
+          email: "richenlin@gmail.com"
+        }
+      ],
+      devDependencies: {
+        "@grpc/grpc-js": "^1.12.2",
+        "@microsoft/api-documenter": "^7.26.x",
+        "@microsoft/api-extractor": "^7.52.x",
+        "@types/formidable": "^3.x.x",
+        "@types/jest": "^29.5.x",
+        "@types/koa": "^2.x.x",
+        "@types/koa-compose": "^3.x.x",
+        "@types/lodash": "^4.x.x",
+        "@types/node": "^22.x.x",
+        "@types/on-finished": "^2.x.x",
+        "@types/supertest": "^6.x.x",
+        "@types/ws": "^8.x.x",
+        "@typescript-eslint/eslint-plugin": "^8.x.x",
+        "@typescript-eslint/parser": "^8.x.x",
+        eslint: "^8.x.x",
+        "eslint-plugin-jest": "^28.x.x",
+        jest: "^29.x.x",
+        "jest-html-reporters": "^3.x.x",
+        koatty_validation: "workspace:*",
+        "reflect-metadata": "^0.2.2",
+        supertest: "^7.x.x",
+        "ts-jest": "^29.x.x",
+        tslib: "^2.x.x"
+      },
+      dependencies: {
+        koa: "^3.1.1",
+        koatty_config: "workspace:*",
+        koatty_container: "workspace:*",
+        koatty_core: "workspace:*",
+        koatty_exception: "workspace:*",
+        koatty_lib: "workspace:*",
+        koatty_loader: "workspace:*",
+        koatty_logger: "workspace:*",
+        koatty_router: "workspace:*",
+        koatty_serve: "workspace:*",
+        koatty_trace: "workspace:*",
+        "ts-morph": "^27.0.2"
+      },
+      types: "./dist/index.d.ts"
+    };
+  }
+});
+var pkg = require_package();
+var { engines, version } = pkg;
+var KOATTY_VERSION = version;
+var ENGINES_VERSION = engines.node.slice(1) || "12.0.0";
+function checkClass(fileName, xpath, target, exSet) {
+  if (Helper.isClass(target) && target.name != fileName) {
+    throw Error(`The file(${xpath}) name should be always the same as class name.`);
+  }
+  if (target["__esModule"]) {
+    if (target.name === void 0) {
+      const keys = Object.keys(target);
+      if (keys[0] != fileName && Helper.isClass(target[keys[0]])) {
+        throw Error(`The file(${xpath}) name should be always the same as class name.`);
+      }
+    } else if (target.name != fileName) {
+      throw Error(`The file(${xpath}) name should be always the same as class name.`);
+    }
+  }
+  if (!exSet) {
+    return;
+  }
+  if (exSet.has(fileName)) {
+    throw new Error(`A same class already exists. at \`${xpath}\`.`);
+  }
+  exSet.add(fileName);
   return;
 }
-
-function k() {
-  let t = b;
-  t = t.slice(0, t.lastIndexOf("."));
-  let e = process.version;
-  if (e[0] === "v") e = e.slice(1);
-  e = e.slice(0, e.lastIndexOf("."));
-  if (m.toNumber(t) > m.toNumber(e)) u.Fatal(`Koatty need node version > ${t}, current version is ${e}, please upgrade it.`);
+__name(checkClass, "checkClass");
+function checkRuntime() {
+  let nodeEngines = ENGINES_VERSION;
+  nodeEngines = nodeEngines.slice(0, nodeEngines.lastIndexOf("."));
+  let nodeVersion = process.version;
+  if (nodeVersion[0] === "v") {
+    nodeVersion = nodeVersion.slice(1);
+  }
+  nodeVersion = nodeVersion.slice(0, nodeVersion.lastIndexOf("."));
+  if (Helper.toNumber(nodeEngines) > Helper.toNumber(nodeVersion)) {
+    DefaultLogger.Fatal(`Koatty need node version > ${nodeEngines}, current version is ${nodeVersion}, please upgrade it.`);
+  }
 }
-
-const M = () => {
-  let t = !1;
-  const e = JSON.stringify(process.argv[1]);
-  if (e.indexOf("jest") > -1) t = !0;
-  return t;
-};
-
-/*
- * @Description: framework constants
- * @Usage:
- * @Author: richen
- * @Date: 2023-12-09 21:56:32
- * @LastEditTime: 2023-12-09 23:00:13
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */ const O = "COMPONENT_SCAN";
-
-const _ = "CONFIGURATION_SCAN";
-
-const T = `\n\n┬┌─┌─┐┌─┐┌┬┐┌┬┐┬ ┬\n├┴┐│ │├─┤ │  │ └┬┘\n┴ ┴└─┘┴ ┴ ┴  ┴  ┴ \n-------------------------------------------\nhttps://github.com/koatty\n`
-/*
- * @Description: framework loader
- * @Usage:
- * @Author: richen
- * @Date: 2023-12-09 22:55:49
- * @LastEditTime: 2025-03-13 16:44:39
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */;
-
-class Loader {
-  constructor(t) {
-    this.app = t;
+__name(checkRuntime, "checkRuntime");
+var checkUTRuntime = /* @__PURE__ */ __name(() => {
+  let isUTRuntime = false;
+  const argv = JSON.stringify(process.argv[1]);
+  if (argv.indexOf("jest") > -1) {
+    isUTRuntime = true;
+  }
+  return isUTRuntime;
+}, "checkUTRuntime");
+
+// src/core/Constants.ts
+var COMPONENT_SCAN = "COMPONENT_SCAN";
+var CONFIGURATION_SCAN = "CONFIGURATION_SCAN";
+var LOGO = `
+
+\u252C\u250C\u2500\u250C\u2500\u2510\u250C\u2500\u2510\u250C\u252C\u2510\u250C\u252C\u2510\u252C \u252C
+\u251C\u2534\u2510\u2502 \u2502\u251C\u2500\u2524 \u2502  \u2502 \u2514\u252C\u2518
+\u2534 \u2534\u2514\u2500\u2518\u2534 \u2534 \u2534  \u2534  \u2534 
+-------------------------------------------
+https://github.com/koatty
+`;
+var Loader = class _Loader {
+  static {
+    __name(this, "Loader");
   }
-  static initialize(t) {
-    if (t.env == "development") u.setLevel("debug"); else u.setLevel("info");
-    const e = t.rootPath || process.cwd();
-    const o = t.appPath || L.resolve(e, t.appDebug ? "src" : "dist");
-    const a = L.resolve(__dirname, "..");
-    m.define(t, "rootPath", e);
-    m.define(t, "appPath", o);
-    m.define(t, "koattyPath", a);
-    if (m.isEmpty(t.name)) {
-      const e = m.safeRequire(`${L.dirname(o)}/package.json`);
-      if (e.name) {
-        t.name = e.name;
-        t.version = t.version || e.version;
+  app;
+  /**
+  * Creates an instance of Loader.
+  * @param {KoattyApplication} app
+  * @memberof Loader
+  */
+  constructor(app) {
+    this.app = app;
+  }
+  /**
+  * Initialize application configuration and environment settings.
+  * Sets up logging levels, defines essential paths, and loads application metadata.
+  *
+  * @param {KoattyApplication} app - The Koatty application instance
+  * - Sets logging level based on environment
+  * - Defines root, app and framework paths on app object
+  * - Loads application name and version from package.json
+  * - Sets environment variables for paths
+  * - Maintains backward compatibility with legacy path variables
+  */
+  static initialize(app) {
+    if (app.env == "development") {
+      DefaultLogger.setLevel("debug");
+    } else {
+      DefaultLogger.setLevel("info");
+    }
+    const rootPath = app.rootPath || process.cwd();
+    const appPath = app.appPath || path.resolve(rootPath, app.appDebug ? "src" : "dist");
+    const koattyPath = path.resolve(__dirname, "..");
+    Helper.define(app, "rootPath", rootPath);
+    Helper.define(app, "appPath", appPath);
+    Helper.define(app, "koattyPath", koattyPath);
+    if (Helper.isEmpty(app.name)) {
+      const pkg2 = Helper.safeRequire(`${path.dirname(appPath)}/package.json`);
+      if (pkg2.name) {
+        app.name = pkg2.name;
+        app.version = app.version || pkg2.version;
       }
     }
-    process.env.ROOT_PATH = e;
-    process.env.APP_PATH = o;
-    process.env.KOATTY_PATH = a;
-    process.env.THINK_PATH = a;
-    m.define(t, "thinkPath", a);
+    process.env.ROOT_PATH = rootPath;
+    process.env.APP_PATH = appPath;
+    process.env.KOATTY_PATH = koattyPath;
+    process.env.THINK_PATH = koattyPath;
+    Helper.define(app, "thinkPath", koattyPath);
   }
-  static GetComponentMeta(t, a) {
-    let s = [];
-    const n = e.getClassMetadata(o, O, a);
-    if (n) if (m.isArray(n)) s = n; else s.push(n);
-    if (s.length < 1) s = [ t.appPath ];
-    return s;
+  /**
+  * Get component metadata from target class.
+  * 
+  * @param {KoattyApplication} app - The Koatty application instance
+  * @param {any} target - The target class to get metadata from
+  * @returns {any[]} Array of component metadata paths
+  * 
+  * @static
+  * @public
+  */
+  static GetComponentMeta(app, target) {
+    let componentMetas = [];
+    const componentMeta = IOC.getClassMetadata(TAGGED_CLS, COMPONENT_SCAN, target);
+    if (componentMeta) {
+      if (Helper.isArray(componentMeta)) {
+        componentMetas = componentMeta;
+      } else {
+        componentMetas.push(componentMeta);
+      }
+    }
+    if (componentMetas.length < 1) {
+      componentMetas = [
+        app.appPath
+      ];
+    }
+    return componentMetas;
   }
-  static GetConfigurationMeta(t, a) {
-    const s = e.getClassMetadata(o, _, a);
-    let n = [];
-    if (s) if (m.isArray(s)) n = s; else n.push(s);
-    return n;
+  /**
+  * Get configuration metadata from target class.
+  * 
+  * @param {KoattyApplication} app Application instance
+  * @param {any} target Target class
+  * @returns {any[]} Array of configuration metadata
+  */
+  static GetConfigurationMeta(app, target) {
+    const confMeta = IOC.getClassMetadata(TAGGED_CLS, CONFIGURATION_SCAN, target);
+    let configurationMetas = [];
+    if (confMeta) {
+      if (Helper.isArray(confMeta)) {
+        configurationMetas = confMeta;
+      } else {
+        configurationMetas.push(confMeta);
+      }
+    }
+    return configurationMetas;
   }
-  static CheckAllComponents(t, e) {
-    const o = Loader.GetComponentMeta(t, e);
-    const a = Loader.GetConfigurationMeta(t, e);
-    const s = new Set;
-    h(o, "", (t, e, o) => {
-      P(t, e, o, s);
-    }, [ "**/**.js", "**/**.ts", "!**/**.d.ts" ], [ ...a, `${e.name || ".no"}.ts` ]);
-    s.clear();
+  /**
+  * Check and load all components(excepted config/*、App.ts) in the application.
+  * 
+  * @param {KoattyApplication} app - The Koatty application instance
+  * @param {any} target - The target class or object to check components from
+  * @static
+  * @public
+  */
+  static CheckAllComponents(app, target) {
+    const componentMetas = _Loader.GetComponentMeta(app, target);
+    const configurationMetas = _Loader.GetConfigurationMeta(app, target);
+    const exSet = /* @__PURE__ */ new Set();
+    Load(componentMetas, "", (fileName, xpath, xTarget) => {
+      checkClass(fileName, xpath, xTarget, exSet);
+    }, [
+      "**/**.js",
+      "**/**.ts",
+      "!**/**.d.ts"
+    ], [
+      ...configurationMetas,
+      `${target.name || ".no"}.ts`
+    ]);
+    exSet.clear();
   }
-  static SetLogger(t) {
-    const e = t.getMetaData("_configs") || [];
-    const o = e[0] || {};
-    if (o.config) {
-      const e = o.config;
-      let s = "debug", n = "", i = [];
-      if (t.env === "production") s = "info";
-      if (e.logsLevel) s = e.logsLevel.toLowerCase();
-      if (e.logsPath) n = e.logsPath;
-      if (e.sensFields) i = e.sensFields;
-      if (!t.appDebug) {
-        u.enableBatch(!0);
-        u.setBatchConfig({
+  /**
+  * Set logger configuration for the Koatty application.
+  * 
+  * @param {KoattyApplication} app - The Koatty application instance
+  * @description Configures logging settings based on application environment and config options.
+  * Handles log level, log file path, and sensitive fields configuration.
+  * In production environment, default log level is 'info', otherwise 'debug'.
+  */
+  static SetLogger(app) {
+    const data = app.getMetaData("_configs") || [];
+    const configs = data[0] || {};
+    if (configs.config) {
+      const opt = configs.config;
+      let logLevel = "debug", logFilePath = "", sensFields = [];
+      if (app.env === "production") {
+        logLevel = "info";
+      }
+      if (opt.logsLevel) {
+        logLevel = opt.logsLevel.toLowerCase();
+      }
+      if (opt.logsPath) {
+        logFilePath = opt.logsPath;
+      }
+      if (opt.sensFields) {
+        sensFields = opt.sensFields;
+      }
+      if (!app.appDebug) {
+        DefaultLogger.enableBatch(true);
+        DefaultLogger.setBatchConfig({
           maxSize: 200,
           flushInterval: 500
         });
       }
-      if (s) u.setLevel(s);
-      if (n && !t.silent) {
-        m.define(t, "logsPath", n);
-        process.env.LOGS_PATH = n;
-        u.setLogFilePath(n);
+      if (logLevel) {
+        DefaultLogger.setLevel(logLevel);
       }
-      if (i) u.setSensFields(i);
-      t.once(a.appStop, async () => {
-        await u.flushBatch();
-        await u.destroy();
+      if (logFilePath && !app.silent) {
+        Helper.define(app, "logsPath", logFilePath);
+        process.env.LOGS_PATH = logFilePath;
+        DefaultLogger.setLogFilePath(logFilePath);
+      }
+      if (sensFields) {
+        DefaultLogger.setSensFields(sensFields);
+      }
+      app.once(AppEvent.appStop, async () => {
+        await DefaultLogger.flushBatch();
+        await DefaultLogger.destroy();
       });
     }
   }
-  static async LoadAllComponents(t, o) {
+  /**
+  * Load all components and initialize the application.
+  * 
+  * @param app - The KoattyApplication instance
+  * @param target - The target class or object containing configuration metadata
+  * 
+  * This method performs the following initialization steps:
+  * 1. Loads configurations
+  * 2. Creates server and router instances
+  * 3. Loads components, middlewares, services and controllers
+  * 4. Sets up routing
+  * 
+  * @static
+  * @async
+  */
+  static async LoadAllComponents(app, target) {
     try {
-      if (m.isFunction(e.preloadMetadata)) e.preloadMetadata();
+      if (Helper.isFunction(IOC.preloadMetadata)) {
+        IOC.preloadMetadata();
+      }
     } catch {
-      u.Warn("[Loader] preloadMetadata is optional, ignore if not available");
+      DefaultLogger.Warn("[Loader] preloadMetadata is optional, ignore if not available");
     }
-    const r = Loader.GetConfigurationMeta(t, o);
-    const l = new Loader(t);
-    for (const e of s) switch (e) {
-     case a.appBoot:
-      u.Log("Koatty", "", "Load Configurations ...");
-      l.LoadConfigs(r);
-      Loader.SetLogger(t);
-      await n(t, e);
-      break;
-
-     case a.loadConfigure:
-      u.Log("Koatty", "", "Emit loadConfigure ...");
-      await n(t, e);
-      break;
-
-     case a.loadComponent:
-      u.Log("Koatty", "", "Initializing Component Manager ...");
-      const s = new i(t);
-      m.define(t, "componentManager", s);
-      s.discoverComponents();
-      const c = s.getStats();
-      u.Log("Koatty", "", `Discovered ${c.coreComponents} core components, ${c.userComponents} user components`);
-      u.Log("Koatty", "", "Load Components ...");
-      await l.LoadComponents(s);
-      s.registerAppEvents(o);
-      s.registerCoreComponentHooks();
-      await n(t, e);
-      break;
-
-     case a.loadPlugin:
-      u.Log("Koatty", "", "Emit loadPlugin ...");
-      await n(t, e);
-      break;
-
-     case a.loadMiddleware:
-      u.Log("Koatty", "", "Load Middlewares ...");
-      await l.LoadMiddlewares();
-      await n(t, e);
-      break;
-
-     case a.loadService:
-      u.Log("Koatty", "", "Load Services ...");
-      await l.LoadServices();
-      await n(t, e);
-      break;
-
-     case a.loadController:
-      u.Log("Koatty", "", "Load Controllers ...");
-      await l.LoadControllers();
-      await n(t, e);
-      break;
-
-     case a.loadRouter:
-      u.Log("Koatty", "", "Initialize Router and Load Routes ...");
-      await n(t, e);
-      break;
-
-     case a.loadServe:
-      u.Log("Koatty", "", "Emit loadServe ...");
-      await n(t, e);
-      break;
-
-     case a.appReady:
-      u.Log("Koatty", "", "Emit appReady ...");
-      await n(t, e);
-      break;
-
-     default:
-      await n(t, e);
-      break;
+    const configurationMeta = _Loader.GetConfigurationMeta(app, target);
+    const loader = new _Loader(app);
+    for (const event of AppEventArr) {
+      switch (event) {
+        case AppEvent.appBoot:
+          DefaultLogger.Log("Koatty", "", "Load Configurations ...");
+          loader.LoadConfigs(configurationMeta);
+          _Loader.SetLogger(app);
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadConfigure:
+          DefaultLogger.Log("Koatty", "", "Emit loadConfigure ...");
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadComponent:
+          DefaultLogger.Log("Koatty", "", "Initializing Component Manager ...");
+          const componentManager = new ComponentManager(app);
+          Helper.define(app, "componentManager", componentManager);
+          componentManager.discoverComponents();
+          const stats = componentManager.getStats();
+          DefaultLogger.Log("Koatty", "", `Discovered ${stats.coreComponents} core components, ${stats.userComponents} user components`);
+          DefaultLogger.Log("Koatty", "", "Load Components ...");
+          await loader.LoadComponents(componentManager);
+          componentManager.registerAppEvents(target);
+          componentManager.registerCoreComponentHooks();
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadPlugin:
+          DefaultLogger.Log("Koatty", "", "Emit loadPlugin ...");
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadMiddleware:
+          DefaultLogger.Log("Koatty", "", "Load Middlewares ...");
+          await loader.LoadMiddlewares();
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadService:
+          DefaultLogger.Log("Koatty", "", "Load Services ...");
+          await loader.LoadServices();
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadController:
+          DefaultLogger.Log("Koatty", "", "Load Controllers ...");
+          await loader.LoadControllers();
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadRouter:
+          DefaultLogger.Log("Koatty", "", "Initialize Router and Load Routes ...");
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.loadServe:
+          DefaultLogger.Log("Koatty", "", "Emit loadServe ...");
+          await asyncEvent(app, event);
+          break;
+        case AppEvent.appReady:
+          DefaultLogger.Log("Koatty", "", "Emit appReady ...");
+          await asyncEvent(app, event);
+          break;
+        default:
+          await asyncEvent(app, event);
+          break;
+      }
     }
   }
-  LoadConfigs(e) {
-    const o = {};
-    h([ "./config" ], this.app.koattyPath, function(t, e, a) {
-      o[t] = a;
+  /**
+  * Load configuration files from specified paths.
+  * First loads framework configurations from './config' directory,
+  * then loads application configurations from custom paths.
+  * Finally merges both configurations with framework configs as lower priority.
+  * 
+  * @protected
+  * @param {string[]} [loadPath] - Optional array of paths to load application configs from
+  */
+  LoadConfigs(loadPath) {
+    const frameConfig = {};
+    Load([
+      "./config"
+    ], this.app.koattyPath, function(name, path2, exp) {
+      frameConfig[name] = exp;
     });
-    if (m.isArray(e)) e = e.length > 0 ? e : [ "./config" ];
-    let a = t(e, this.app.appPath);
-    a = m.extend(o, a, !0);
-    this.app.setMetaData("_configs", a);
+    if (Helper.isArray(loadPath)) {
+      loadPath = loadPath.length > 0 ? loadPath : [
+        "./config"
+      ];
+    }
+    let appConfig = LoadConfigs(loadPath, this.app.appPath);
+    appConfig = Helper.extend(frameConfig, appConfig, true);
+    this.app.setMetaData("_configs", appConfig);
   }
+  /**
+  * Load and register middleware components.
+  * Processes middleware configuration, registers middleware classes with IOC container,
+  * and mounts middleware to the application.
+  * Supports protocol-specific middleware mounting via @Middleware({ protocol }) option.
+  * 
+  * @protected
+  * @returns {Promise<void>}
+  * @throws {Error} When middleware doesn't implement IMiddleware interface
+  * @throws {Error} When middleware loading fails
+  */
   async LoadMiddlewares() {
-    var t, o, a, s;
-    let n = this.app.config(void 0, "middleware");
-    if (m.isEmpty(n)) n = {
-      config: {},
-      list: []
-    };
+    let middlewareConf = this.app.config(void 0, "middleware");
+    if (Helper.isEmpty(middlewareConf)) {
+      middlewareConf = {
+        config: {},
+        list: []
+      };
+    }
     try {
-      const e = (o = (t = n.config) === null || t === void 0 ? void 0 : t.trace) !== null && o !== void 0 ? o : {};
-      const a = y(e, this.app);
-      m.define(this.app, "tracer", a);
-      this.app.use(a);
-      u.Debug(`Trace middleware registered`);
-    } catch (t) {
-      u.Warn(`Trace middleware failed to load: ${t.message}`);
+      const traceOptions = middlewareConf.config?.trace ?? {};
+      const tracer = Trace(traceOptions, this.app);
+      Helper.define(this.app, "tracer", tracer);
+      this.app.use(tracer);
+      DefaultLogger.Debug(`Trace middleware registered`);
+    } catch (error) {
+      DefaultLogger.Warn(`Trace middleware failed to load: ${error.message}`);
     }
-    const i = (a = e.listClass("MIDDLEWARE")) !== null && a !== void 0 ? a : [];
-    i.forEach(t => {
-      var o;
-      t.id = ((o = t.id) !== null && o !== void 0 ? o : "").replace("MIDDLEWARE:", "");
-      if (t.id && m.isClass(t.target)) {
-        e.reg(t.id, t.target, {
+    const appMiddleware = IOC.listClass("MIDDLEWARE") ?? [];
+    appMiddleware.forEach((item) => {
+      item.id = (item.id ?? "").replace("MIDDLEWARE:", "");
+      if (item.id && Helper.isClass(item.target)) {
+        IOC.reg(item.id, item.target, {
           scope: "Prototype",
           type: "MIDDLEWARE",
           args: []
         });
-        const o = e.getInsByClass(t.target);
-        if (!r(o)) throw Error(`The middleware ${t.id} must implements interface 'IMiddleware'.`);
+        const ctl = IOC.getInsByClass(item.target);
+        if (!implementsMiddlewareInterface(ctl)) {
+          throw Error(`The middleware ${item.id} must implements interface 'IMiddleware'.`);
+        }
       }
     });
-    const d = n.list || [];
-    const f = new Set([]);
-    d.forEach(t => {
-      f.add(t);
+    const middlewareList = middlewareConf.list || [];
+    const appMList = /* @__PURE__ */ new Set([]);
+    middlewareList.forEach((item) => {
+      appMList.add(item);
     });
-    const p = n.config || {};
-    for (const t of Array.from(f)) {
-      const o = e.get(t, "MIDDLEWARE");
-      if (!o) throw Error(`Middleware ${t} load error.`);
-      if (!m.isFunction(o.run)) throw Error(`The middleware ${t} must implements interface 'IMiddleware'.`);
-      u.Debug(`Load middleware: ${t}`);
-      const a = p[t] || {};
-      const n = (s = i.find(e => e.id === t)) === null || s === void 0 ? void 0 : s.target;
-      let r = {};
-      if (n) try {
-        r = e.getPropertyData(l, n, t) || {};
-      } catch {
-        r = {};
+    const middlewareConfig = middlewareConf.config || {};
+    for (const key of Array.from(appMList)) {
+      const handle = IOC.get(key, "MIDDLEWARE");
+      if (!handle) {
+        throw Error(`Middleware ${key} load error.`);
+      }
+      if (!Helper.isFunction(handle.run)) {
+        throw Error(`The middleware ${key} must implements interface 'IMiddleware'.`);
+      }
+      DefaultLogger.Debug(`Load middleware: ${key}`);
+      const middlewareOpt = middlewareConfig[key] || {};
+      const middlewareClass = appMiddleware.find((m) => m.id === key)?.target;
+      let decoratorOptions = {};
+      if (middlewareClass) {
+        try {
+          decoratorOptions = IOC.getPropertyData(MIDDLEWARE_OPTIONS, middlewareClass, key) || {};
+        } catch {
+          decoratorOptions = {};
+        }
       }
-      const d = {
-        ...r,
-        ...a
+      const mergedOptions = {
+        ...decoratorOptions,
+        ...middlewareOpt
       };
-      if (d.enabled === !1) {
-        u.Warn(`The middleware ${t} has been loaded but is disabled.`);
+      if (mergedOptions.enabled === false) {
+        DefaultLogger.Warn(`The middleware ${key} has been loaded but is disabled.`);
         continue;
       }
-      const f = await o.run(d, this.app);
-      if (m.isFunction(f)) {
-        let e = f;
-        if (d.protocol) {
-          const o = m.isArray(d.protocol) ? d.protocol : [ d.protocol ];
-          u.Log("Koatty", "", `Middleware ${t} limited to protocols: ${o.join(", ")}`);
-          e = c(o, f);
+      const result = await handle.run(mergedOptions, this.app);
+      if (Helper.isFunction(result)) {
+        let middleware = result;
+        if (mergedOptions.protocol) {
+          const protocols = Helper.isArray(mergedOptions.protocol) ? mergedOptions.protocol : [
+            mergedOptions.protocol
+          ];
+          DefaultLogger.Log("Koatty", "", `Middleware ${key} limited to protocols: ${protocols.join(", ")}`);
+          middleware = protocolMiddleware(protocols, result);
+        }
+        if (middleware.length < 3) {
+          this.app.use(middleware);
+        } else {
+          this.app.useExp(middleware);
         }
-        if (e.length < 3) this.app.use(e); else this.app.useExp(e);
       }
     }
   }
+  /**
+  * Load and register controller classes from IOC container.
+  * Each controller must implement the IController interface.
+  * 
+  * @returns {Promise<string[]>} A promise that resolves to an array of controller IDs.
+  * @protected
+  * @throws {Error} If a controller does not implement the IController interface.
+  */
   async LoadControllers() {
-    const t = e.listClass("CONTROLLER");
-    const o = [];
-    t.forEach(t => {
-      var a;
-      t.id = ((a = t.id) !== null && a !== void 0 ? a : "").replace("CONTROLLER:", "");
-      if (t.id && m.isClass(t.target)) {
-        u.Debug(`Load controller: ${t.id}`);
-        e.reg(t.id, t.target, {
+    const controllerList = IOC.listClass("CONTROLLER");
+    const controllers = [];
+    controllerList.forEach((item) => {
+      item.id = (item.id ?? "").replace("CONTROLLER:", "");
+      if (item.id && Helper.isClass(item.target)) {
+        DefaultLogger.Debug(`Load controller: ${item.id}`);
+        IOC.reg(item.id, item.target, {
           scope: "Prototype",
           type: "CONTROLLER",
           args: []
         });
-        const a = e.getInsByClass(t.target);
-        if (!d(a)) throw Error(`The controller ${t.id} must implements interface 'IController'.`);
-        o.push(t.id);
+        const ctl = IOC.getInsByClass(item.target);
+        if (!implementsControllerInterface(ctl)) {
+          throw Error(`The controller ${item.id} must implements interface 'IController'.`);
+        }
+        controllers.push(item.id);
       }
     });
-    this.app.setMetaData("_controllers", o);
-    return o;
+    this.app.setMetaData("_controllers", controllers);
+    return controllers;
   }
+  /**
+  * Load and register service components into IOC container.
+  * Each service must implement the IService interface.
+  * Services are registered with singleton scope.
+  * 
+  * @protected
+  * @returns {Promise<void>}
+  * @throws {Error} When service does not implement IService interface
+  */
   async LoadServices() {
-    var t;
-    const o = e.listClass("SERVICE");
-    for (const a of o) {
-      a.id = ((t = a.id) !== null && t !== void 0 ? t : "").replace("SERVICE:", "");
-      if (a.id && m.isClass(a.target)) {
-        u.Debug(`Load service: ${a.id}`);
-        e.reg(a.id, a.target, {
+    const serviceList = IOC.listClass("SERVICE");
+    for (const item of serviceList) {
+      item.id = (item.id ?? "").replace("SERVICE:", "");
+      if (item.id && Helper.isClass(item.target)) {
+        DefaultLogger.Debug(`Load service: ${item.id}`);
+        IOC.reg(item.id, item.target, {
           scope: "Singleton",
           type: "SERVICE",
           args: []
         });
-        const t = e.getInsByClass(a.target);
-        if (!f(t)) throw Error(`The service ${a.id} must implements interface 'IService'.`);
+        const ctl = IOC.getInsByClass(item.target);
+        if (!implementsServiceInterface(ctl)) {
+          throw Error(`The service ${item.id} must implements interface 'IService'.`);
+        }
       }
     }
   }
-  async LoadComponents(t) {
-    var o, a;
-    const s = e.listClass("COMPONENT");
-    s.forEach(t => {
-      var o;
-      t.id = ((o = t.id) !== null && o !== void 0 ? o : "").replace("COMPONENT:", "");
-      if (m.isClass(t.target)) {
-        e.reg(t.id, t.target, {
+  /**
+  * Load and initialize components, plugins and aspects.
+  * Components with suffix 'Plugin' must implement IPlugin interface.
+  * Components with suffix 'Aspect' must implement IAspect interface.
+  * Plugins are loaded based on configuration and executed synchronously.
+  * 
+  * @protected
+  * @returns {Promise<void>}
+  * @throws {Error} When plugin/aspect doesn't implement required interface
+  * @throws {Error} When plugin loading fails
+  */
+  async LoadComponents(componentManager) {
+    const componentList = IOC.listClass("COMPONENT");
+    componentList.forEach((item) => {
+      item.id = (item.id ?? "").replace("COMPONENT:", "");
+      if (Helper.isClass(item.target)) {
+        IOC.reg(item.id, item.target, {
           scope: "Singleton",
           type: "COMPONENT",
           args: []
         });
-        if (t.id && t.id.endsWith("Aspect")) {
-          const o = e.getInsByClass(t.target);
-          if (!p(o)) throw Error(`The aspect ${t.id} must implements interface 'IAspect'.`);
+        if (item.id && item.id.endsWith("Aspect")) {
+          const ctl = IOC.getInsByClass(item.target);
+          if (!implementsAspectInterface(ctl)) {
+            throw Error(`The aspect ${item.id} must implements interface 'IAspect'.`);
+          }
         }
       }
     });
-    if (t) await t.loadUserComponents(); else {
-      u.Warn("Loading plugins in legacy mode");
-      let t = this.app.config(void 0, "plugin");
-      if (m.isEmpty(t)) t = {
-        config: {},
-        list: []
-      };
-      const s = (o = t.list) !== null && o !== void 0 ? o : [];
-      for (const o of s) {
-        const s = e.get(o, "COMPONENT");
-        if (!s) throw Error(`Plugin ${o} load error.`);
-        if (!m.isFunction(s.run)) throw Error(`Plugin ${o} must implements interface 'IPlugin'.`);
-        if (t.config[o] === !1) {
-          u.Warn(`Plugin ${o} already loaded but not effective.`);
+    if (componentManager) {
+      await componentManager.loadUserComponents();
+    } else {
+      DefaultLogger.Warn("Loading plugins in legacy mode");
+      let pluginsConf = this.app.config(void 0, "plugin");
+      if (Helper.isEmpty(pluginsConf)) {
+        pluginsConf = {
+          config: {},
+          list: []
+        };
+      }
+      const pluginConfList = pluginsConf.list ?? [];
+      for (const key of pluginConfList) {
+        const handle = IOC.get(key, "COMPONENT");
+        if (!handle) {
+          throw Error(`Plugin ${key} load error.`);
+        }
+        if (!Helper.isFunction(handle.run)) {
+          throw Error(`Plugin ${key} must implements interface 'IPlugin'.`);
+        }
+        if (pluginsConf.config[key] === false) {
+          DefaultLogger.Warn(`Plugin ${key} already loaded but not effective.`);
           continue;
         }
-        await s.run((a = t.config[o]) !== null && a !== void 0 ? a : {}, this.app);
+        await handle.run(pluginsConf.config[key] ?? {}, this.app);
       }
     }
   }
-}
-
-/*
- * @Description: framework bootstrap
- * @Usage:
- * @Author: richen
- * @Date: 2021-12-09 21:56:32
- * @LastEditTime: 2025-01-14 16:11:21
- * @License: BSD (3-Clause)
- * @Copyright (c): <richenlin(at)gmail.com>
- */ function A(t) {
-  return async e => {
-    if (!(e.prototype instanceof g)) throw new Error(`class ${e.name} does not inherit from Koatty`);
-    return await $(e, t, !0);
+};
+function ExecBootStrap(bootFunc) {
+  return async (target) => {
+    if (!(target.prototype instanceof Koatty)) {
+      throw new Error(`class ${target.name} does not inherit from Koatty`);
+    }
+    return await executeBootstrap(target, bootFunc, true);
   };
 }
-
-const $ = async function(t, o, a = !1) {
+__name(ExecBootStrap, "ExecBootStrap");
+var executeBootstrap = /* @__PURE__ */ __name(async function(target, bootFunc, isInitiative = false) {
   if (process.env.NODE_DEBUG) {
-    const t = process.env.NODE_DEBUG.split(",").filter(t => !t.includes("winston")).join(",");
-    process.env.NODE_DEBUG = t;
+    const debugModules = process.env.NODE_DEBUG.split(",").filter((m) => !m.includes("winston")).join(",");
+    process.env.NODE_DEBUG = debugModules;
+  }
+  checkRuntime();
+  const isUTRuntime = checkUTRuntime();
+  if (!isInitiative && isUTRuntime) {
+    return;
   }
-  k();
-  const s = M();
-  if (!a && s) return;
-  const n = Reflect.construct(t, []);
-  if (s) {
-    n.silent = !0;
-    u.enable(!1);
+  const app = Reflect.construct(target, []);
+  if (isUTRuntime) {
+    app.silent = true;
+    DefaultLogger.enable(false);
   }
   try {
-    if (!n.silent) console.log(T);
-    if (!(n instanceof g)) throw new Error(`class ${t.name} does not inherit from Koatty`);
-    Loader.initialize(n);
-    if (m.isFunction(o)) {
-      u.Log("Koatty", "", "Execute bootFunc ...");
-      await o(n);
+    if (!app.silent) console.log(LOGO);
+    if (!(app instanceof Koatty)) {
+      throw new Error(`class ${target.name} does not inherit from Koatty`);
     }
-    e.setApp(n);
-    u.Log("Koatty", "", "ComponentScan ...");
-    Loader.CheckAllComponents(n, t);
-    await Loader.LoadAllComponents(n, t);
-    if (!s) n.listen(K);
-    return n;
-  } catch (t) {
-    u.Fatal(t);
+    Loader.initialize(app);
+    if (Helper.isFunction(bootFunc)) {
+      DefaultLogger.Log("Koatty", "", "Execute bootFunc ...");
+      await bootFunc(app);
+    }
+    IOC.setApp(app);
+    DefaultLogger.Log("Koatty", "", "ComponentScan ...");
+    Loader.CheckAllComponents(app, target);
+    await Loader.LoadAllComponents(app, target);
+    if (!isUTRuntime) {
+      app.listen(listenCallback);
+    }
+    return app;
+  } catch (err) {
+    DefaultLogger.Fatal(err);
   }
-};
-
-const K = t => {
-  u.Log("Koatty", "", "====================================");
-  u.Log("Koatty", "", `Nodejs Version: ${process.version}`);
-  u.Log("Koatty", "", `Koatty Version: v${E}`);
-  u.Log("Koatty", "", `App Environment: ${t.env}`);
-  if (t.appDebug) u.Warn(`Running in debug mode.`);
-  u.Log("Koatty", "", "====================================");
-  n(t, a.appStart);
-};
-
-function D(t) {
-  return function(o) {
-    if (!(o.prototype instanceof g)) throw new Error(`class does not inherit from Koatty`);
-    e.saveClass("COMPONENT", o, "KOATTY_APP");
-    A(t)(o);
-    return o;
+}, "executeBootstrap");
+var listenCallback = /* @__PURE__ */ __name((app) => {
+  DefaultLogger.Log("Koatty", "", "====================================");
+  DefaultLogger.Log("Koatty", "", `Nodejs Version: ${process.version}`);
+  DefaultLogger.Log("Koatty", "", `Koatty Version: v${KOATTY_VERSION}`);
+  DefaultLogger.Log("Koatty", "", `App Environment: ${app.env}`);
+  if (app.appDebug) DefaultLogger.Warn(`Running in debug mode.`);
+  DefaultLogger.Log("Koatty", "", "====================================");
+  asyncEvent(app, AppEvent.appStart);
+}, "listenCallback");
+function Bootstrap(bootFunc) {
+  return function(target) {
+    if (!(target.prototype instanceof Koatty)) {
+      throw new Error(`class does not inherit from Koatty`);
+    }
+    IOC.saveClass("COMPONENT", target, "KOATTY_APP");
+    ExecBootStrap(bootFunc)(target);
+    return target;
   };
 }
-
-function N(t) {
-  return a => {
-    if (!(a.prototype instanceof g)) throw new Error(`class does not inherit from Koatty`);
-    t = t !== null && t !== void 0 ? t : "";
-    e.saveClassMetadata(o, O, t, a);
+__name(Bootstrap, "Bootstrap");
+function ComponentScan(scanPath) {
+  return (target) => {
+    if (!(target.prototype instanceof Koatty)) {
+      throw new Error(`class does not inherit from Koatty`);
+    }
+    scanPath = scanPath ?? "";
+    IOC.saveClassMetadata(TAGGED_CLS, COMPONENT_SCAN, scanPath, target);
   };
 }
-
-function S(t) {
-  return a => {
-    if (!(a.prototype instanceof g)) throw new Error(`class does not inherit from Koatty`);
-    t = t !== null && t !== void 0 ? t : "";
-    e.saveClassMetadata(o, _, t, a);
+__name(ComponentScan, "ComponentScan");
+function ConfigurationScan(scanPath) {
+  return (target) => {
+    if (!(target.prototype instanceof Koatty)) {
+      throw new Error(`class does not inherit from Koatty`);
+    }
+    scanPath = scanPath ?? "";
+    IOC.saveClassMetadata(TAGGED_CLS, CONFIGURATION_SCAN, scanPath, target);
   };
 }
-
-export { D as Bootstrap, N as ComponentScan, S as ConfigurationScan, A as ExecBootStrap };
+__name(ConfigurationScan, "ConfigurationScan");
+/**
+ * Decorator for Koatty framework
+ * @author richen
+ * @copyright Copyright (c) - <richenlin(at)gmail.com>
+ * @license BSD (3-Clause)
+ * @version 2026-02-03 10:00:00
+ */
+
+export { Bootstrap, ComponentScan, ConfigurationScan, ExecBootStrap };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map