koatty 4.3.3 → 5.0.0

package/dist/index.js

@@ -11,6 +11,7 @@ var koatty_logger = require('koatty_logger');
 var koatty_loader = require('koatty_loader');
 var koatty_trace = require('koatty_trace');
 var path = require('path');
+var fs = require('fs');
 
 function _interopNamespace(e) {
   if (e && e.__esModule) return e;
@@ -31,10 +32,11 @@ function _interopNamespace(e) {
 }
 
 var path__namespace = /*#__PURE__*/_interopNamespace(path);
+var fs__namespace = /*#__PURE__*/_interopNamespace(fs);
 
 /*!
 * @Author: richen
-* @Date: 2026-09-28 01:54:35
+* @Date: 2026-09-30 05:09:10
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
@@ -51,7 +53,7 @@ var require_package = __commonJS({
   "package.json"(exports$1, module) {
     module.exports = {
       name: "koatty",
-      version: "4.3.3",
+      version: "5.0.0",
       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",
@@ -62,7 +64,8 @@ var require_package = __commonJS({
         clean: "rimraf dist temp docs/api",
         lint: "eslint --ext .ts,.js ./src",
         test: "pnpm run lint && jest --passWithNoTests",
-        "test:cov": "jest --collectCoverage --detectOpenHandles"
+        "test:cov": "jest --collectCoverage --detectOpenHandles",
+        "test:example": "jest --config examples/mcp-order-service/jest.config.js --coverage=false"
       },
       main: "./dist/index.js",
       exports: {
@@ -159,7 +162,13 @@ var require_package = __commonJS({
         koatty_trace: "workspace:*",
         "ts-morph": "^27.0.2"
       },
-      types: "./dist/index.d.ts"
+      types: "./dist/index.d.ts",
+      files: [
+        "dist",
+        "README.md",
+        "CHANGELOG.md",
+        "LICENSE"
+      ]
     };
   }
 });
@@ -206,7 +215,7 @@ function checkRuntime() {
 __name(checkRuntime, "checkRuntime");
 var checkUTRuntime = /* @__PURE__ */ __name(() => {
   let isUTRuntime = false;
-  const argv = JSON.stringify(process.argv[1]);
+  const argv = String(process.argv[1] ?? "");
   if (argv.indexOf("jest") > -1) {
     isUTRuntime = true;
   }
@@ -224,11 +233,264 @@ var LOGO = `
 -------------------------------------------
 https://github.com/koatty
 `;
+
+// src/config/config.ts
+var config_default = {
+  /*app config*/
+  logsLevel: "debug"
+};
+
+// src/config/middleware.ts
+var middleware_default = {
+  // List of loaded middleware(except for the middleware loaded by default), 
+  // executed in the order of elements
+  list: [],
+  // middleware configuration
+  config: {
+    // ============================================
+    // Trace Middleware - 请求链路追踪中间件
+    // ============================================
+    // Koatty-Trace 用于追踪请求链路、记录日志、收集指标
+    // 它会自动作为第一个中间件加载，无需添加到 list 中
+    trace: {
+      // response timeout in milliseconds
+      timeout: 1e4,
+      // request id header name
+      requestIdHeaderName: "X-Request-Id",
+      // request id name
+      requestIdName: "requestId",
+      // id generator function
+      // idFactory: Function,
+      // encoding
+      encoding: "utf-8",
+      // Whether to enable trace (default: false)
+      enableTrace: false,
+      // asynchooks enabled
+      asyncHooks: false,
+      /**
+      * Metrics configuration
+      */
+      metricsConf: {
+        /**
+        * Metrics reporter function
+        */
+        // reporter: (metrics: {
+        //   duration: number,
+        //   status: number,
+        //   path: string,
+        //   attributes: Record<string, any>,
+        // }) => void,
+        /**
+        * Default attributes for metrics
+        */
+        defaultAttributes: {},
+        /**
+        * Prometheus metrics endpoint (production only)
+        */
+        metricsEndpoint: "/metrics",
+        /**
+        * Metrics report interval in milliseconds (default: 5000)
+        */
+        reportInterval: 5e3,
+        /**
+        * Prometheus metrics port (default: 9464)
+        */
+        metricsPort: 9464
+      },
+      /**
+      * OpenTelemetry configuration
+      */
+      opentelemetryConf: {
+        /**
+        * OTLP endpoint URL
+        */
+        endpoint: "http://localhost:4318/v1/traces",
+        /**
+        * Whether to enable topology analysis (default: same as enableTrace)
+        * 
+        */
+        enableTopology: false,
+        /**
+        * OTLP headers
+        */
+        headers: {},
+        /**
+        * Resource attributes
+        */
+        resourceAttributes: {},
+        /**
+        * Instrumentations to enable
+        */
+        instrumentations: [],
+        /**
+        * Exporter timeout in milliseconds
+        */
+        timeout: 1e4,
+        /**
+        * Maximum lifetime for a span in milliseconds
+        */
+        spanTimeout: 3e4,
+        /**
+        * Maximum number of active spans in memory (default: 1000)
+        */
+        maxActiveSpans: 1e3,
+        /**
+        * Request attributes to be added to the span
+        */
+        // spanAttributes: (ctx: KoattyContext) => Record<string, any>,
+        /**
+        * Sampling rate (0.0 - 1.0)
+        */
+        samplingRate: 1,
+        /**
+        * Maximum number of spans in batch queue
+        */
+        batchMaxQueueSize: 2048,
+        /**
+        * Maximum number of spans to export in one batch
+        */
+        batchMaxExportSize: 512,
+        /**
+        * Delay between batch exports in milliseconds
+        */
+        batchDelayMillis: 5e3,
+        /**
+        * Timeout for batch export in milliseconds
+        */
+        batchExportTimeout: 3e4
+      },
+      /**
+      * Retry configuration
+      */
+      retryConf: {
+        /**
+        * Whether to enable retry mechanism (default: false)
+        */
+        enabled: false,
+        /**
+        * Max retry count when error occurs (default: 3)
+        */
+        count: 3,
+        /**
+        * Retry interval in milliseconds (default: 1000)
+        */
+        interval: 1e3
+      }
+    }
+  }
+};
+
+// src/config/plugin.ts
+var plugin_default = {
+  // ============================================================
+  // User plugin loading list (executed in order)
+  // Note: Core components (@Component) are loaded automatically
+  // ============================================================
+  list: [],
+  // ============================================================
+  // Component/Plugin configuration
+  // ============================================================
+  config: {
+    // --- Core components (@Component) ---
+    // Framework built-in components, usually do not need to modify
+    // Can be disabled by setting enabled: false
+    RouterComponent: {
+      enabled: true
+    },
+    ServeComponent: {
+      enabled: true
+    }
+  }
+};
+
+// src/config/router.ts
+var router_default = {
+  /**
+   * prefix of the router
+   */
+  // prefix: string,
+  /**
+  * Methods which should be supported by the router.
+  */
+  // methods?: string[];
+  // routerPath?: string;
+  /**
+  * Whether or not routing should be case-sensitive.
+  */
+  // sensitive?: boolean;
+  /**
+  * Whether or not routes should matched strictly.
+  *
+  * If strict matching is enabled, the trailing slash is taken into
+  * account when matching routes.
+  */
+  // strict?: boolean;
+  /**
+  * payload options
+  *
+  */
+  payload: {
+    extTypes: {
+      json: [
+        "application/json"
+      ],
+      form: [
+        "application/x-www-form-urlencoded"
+      ],
+      text: [
+        "text/plain"
+      ],
+      multipart: [
+        "multipart/form-data"
+      ],
+      xml: [
+        "text/xml"
+      ],
+      grpc: [
+        "application/grpc"
+      ],
+      graphql: [
+        "application/graphql+json"
+      ],
+      websocket: [
+        "application/websocket"
+      ]
+    },
+    // body-size limit intentionally unset (ADR-102): the security profile
+    // decides (1mb in production, 20mb in development) unless the project
+    // config/router.ts sets payload.limit explicitly
+    encoding: "utf-8",
+    multiples: true
+  }
+};
+
+// src/config/server.ts
+var server_default = {
+  hostname: process.env.IP || "127.0.0.1",
+  // server port: single value (e.g. 3000) or array (e.g. [3000, 3001])
+  // For multi-protocol: if port is array, each port maps to corresponding protocol
+  // If port is single value, first protocol uses it, others auto-increment (3000, 3001, 3002...)
+  port: process.env.PORT || process.env.APP_PORT || 3e3,
+  // Server protocol: 'http' | 'https' | 'http2' | 'grpc' | 'ws' | 'wss' | 'graphql'
+  // For multi-protocol: use array like ["http", "grpc"] and configure ext below
+  protocol: "http",
+  trace: false,
+  ssl: {
+    mode: "auto",
+    key: "",
+    cert: "",
+    ca: ""
+    // ca file path
+  }
+};
+
+// src/core/Loader.ts
 var Loader = class _Loader {
   static {
     __name(this, "Loader");
   }
   app;
+  static loggingApps = /* @__PURE__ */ new Set();
   /**
   * Creates an instance of Loader.
   * @param {KoattyApplication} app
@@ -267,6 +529,11 @@ var Loader = class _Loader {
         app.version = app.version || pkg2.version;
       }
     }
+    koatty_lib.Helper.define(app, "paths", {
+      rootPath,
+      appPath,
+      koattyPath
+    });
     process.env.ROOT_PATH = rootPath;
     process.env.APP_PATH = appPath;
     process.env.KOATTY_PATH = koattyPath;
@@ -331,16 +598,31 @@ var Loader = class _Loader {
     const componentMetas = _Loader.GetComponentMeta(app, target);
     const configurationMetas = _Loader.GetConfigurationMeta(app, target);
     const exSet = /* @__PURE__ */ new Set();
-    koatty_loader.Load(componentMetas, "", (fileName, xpath, xTarget) => {
+    const manifestFile = path__namespace.join(app.rootPath, ".koatty", "manifest.json");
+    koatty_loader.Load(componentMetas, app.rootPath, (fileName, xpath, xTarget) => {
       checkClass(fileName, xpath, xTarget, exSet);
+      const exports$1 = typeof xTarget === "function" ? [
+        xTarget
+      ] : Object.values(xTarget ?? {});
+      for (const component of exports$1) {
+        if (koatty_lib.Helper.isClass(component)) app.container.saveClass(koatty_container.IOC.getType(component), component, koatty_container.IOC.getIdentifier(component));
+      }
     }, [
       "**/**.js",
       "**/**.ts",
       "!**/**.d.ts"
     ], [
       ...configurationMetas,
-      `${target.name || ".no"}.ts`
-    ]);
+      `${target.name || ".no"}.ts`,
+      `${target.name || ".no"}.js`
+    ], {
+      manifestFile: app.env === "production" && fs__namespace.existsSync(manifestFile) ? manifestFile : void 0
+    });
+    for (const item of koatty_container.IOC.listClass("COMPONENT")) {
+      const id = koatty_container.IOC.getIdentifier(item.target);
+      const options = koatty_container.IOC.getPropertyData("COMPONENT_OPTIONS", item.target, id);
+      if (options?.scope === "core") app.container.saveClass("COMPONENT", item.target, id);
+    }
     exSet.clear();
   }
   /**
@@ -355,6 +637,7 @@ var Loader = class _Loader {
     const data = app.getMetaData("_configs") || [];
     const configs = data[0] || {};
     if (configs.config) {
+      _Loader.loggingApps.add(app);
       const opt = configs.config;
       let logLevel = "debug", logFilePath = "", sensFields = [];
       if (app.env === "production") {
@@ -389,7 +672,8 @@ var Loader = class _Loader {
       }
       app.once(koatty_core.AppEvent.appStop, async () => {
         await koatty_logger.DefaultLogger.flushBatch();
-        await koatty_logger.DefaultLogger.destroy();
+        _Loader.loggingApps.delete(app);
+        if (_Loader.loggingApps.size === 0) koatty_logger.DefaultLogger.enableBatch(false);
       });
     }
   }
@@ -410,8 +694,8 @@ var Loader = class _Loader {
   */
   static async LoadAllComponents(app, target) {
     try {
-      if (koatty_lib.Helper.isFunction(koatty_container.IOC.preloadMetadata)) {
-        koatty_container.IOC.preloadMetadata();
+      if (koatty_lib.Helper.isFunction(app.container.preloadMetadata)) {
+        app.container.preloadMetadata();
       }
     } catch (error) {
       koatty_logger.DefaultLogger.Error("[Loader] preloadMetadata failed:", error);
@@ -467,12 +751,15 @@ var Loader = class _Loader {
           await koatty_core.asyncEvent(app, event);
           break;
         case koatty_core.AppEvent.loadServe:
+          await app.container?.ready?.();
           koatty_logger.DefaultLogger.Log("Koatty", "", "Emit loadServe ...");
           await koatty_core.asyncEvent(app, event);
           break;
         case koatty_core.AppEvent.appReady:
           koatty_logger.DefaultLogger.Log("Koatty", "", "Emit appReady ...");
           await koatty_core.asyncEvent(app, event);
+          await app.container?.ready?.();
+          app.container?.seal?.();
           break;
         default:
           await koatty_core.asyncEvent(app, event);
@@ -490,18 +777,23 @@ var Loader = class _Loader {
   * @param {string[]} [loadPath] - Optional array of paths to load application configs from
   */
   LoadConfigs(loadPath) {
-    const frameConfig = {};
-    koatty_loader.Load([
-      "./config"
-    ], this.app.koattyPath, function(name, path2, exp) {
-      frameConfig[name] = exp;
-    });
+    const frameConfig = koatty_lib.Helper.clone({
+      config: config_default,
+      middleware: middleware_default,
+      plugin: plugin_default,
+      router: router_default,
+      server: server_default
+    }, true);
     if (koatty_lib.Helper.isArray(loadPath)) {
       loadPath = loadPath.length > 0 ? loadPath : [
         "./config"
       ];
     }
-    let appConfig = koatty_config.LoadConfigs(loadPath, this.app.appPath);
+    const manifest = path__namespace.join(this.app.rootPath, ".koatty/manifest.json");
+    let appConfig = koatty_config.LoadConfigs(loadPath, this.app.appPath, void 0, void 0, void 0, this.app.env === "production" && fs__namespace.existsSync(manifest) ? {
+      manifestFile: manifest,
+      baseDir: this.app.rootPath
+    } : void 0);
     appConfig = koatty_lib.Helper.extend(frameConfig, appConfig, true);
     this.app.setMetaData("_configs", appConfig);
   }
@@ -533,16 +825,16 @@ var Loader = class _Loader {
     } catch (error) {
       koatty_logger.DefaultLogger.Warn(`Trace middleware failed to load: ${error.message}`);
     }
-    const appMiddleware = koatty_container.IOC.listClass("MIDDLEWARE") ?? [];
+    const appMiddleware = this.app.container.listClass("MIDDLEWARE") ?? [];
     appMiddleware.forEach((item) => {
       item.id = (item.id ?? "").replace("MIDDLEWARE:", "");
       if (item.id && koatty_lib.Helper.isClass(item.target)) {
-        koatty_container.IOC.reg(item.id, item.target, {
+        this.app.container.reg(item.id, item.target, {
           scope: "Prototype",
           type: "MIDDLEWARE",
           args: []
         });
-        const ctl = koatty_container.IOC.getInsByClass(item.target);
+        const ctl = this.app.container.getInsByClass(item.target);
         if (!koatty_core.implementsMiddlewareInterface(ctl)) {
           throw Error(`The middleware ${item.id} must implements interface 'IMiddleware'.`);
         }
@@ -555,7 +847,7 @@ var Loader = class _Loader {
     });
     const middlewareConfig = middlewareConf.config || {};
     for (const key of Array.from(appMList)) {
-      const handle = koatty_container.IOC.get(key, "MIDDLEWARE");
+      const handle = this.app.container.get(key, "MIDDLEWARE");
       if (!handle) {
         throw Error(`Middleware ${key} load error.`);
       }
@@ -568,7 +860,7 @@ var Loader = class _Loader {
       let decoratorOptions = {};
       if (middlewareClass) {
         try {
-          decoratorOptions = koatty_container.IOC.getPropertyData(koatty_core.MIDDLEWARE_OPTIONS, middlewareClass, key) || {};
+          decoratorOptions = this.app.container.getPropertyData(koatty_core.MIDDLEWARE_OPTIONS, middlewareClass, key) || {};
         } catch {
           decoratorOptions = {};
         }
@@ -608,21 +900,17 @@ var Loader = class _Loader {
   * @throws {Error} If a controller does not implement the IController interface.
   */
   async LoadControllers() {
-    const controllerList = koatty_container.IOC.listClass("CONTROLLER");
+    const controllerList = this.app.container.listClass("CONTROLLER");
     const controllers = [];
     controllerList.forEach((item) => {
       item.id = (item.id ?? "").replace("CONTROLLER:", "");
       if (item.id && koatty_lib.Helper.isClass(item.target)) {
         koatty_logger.DefaultLogger.Debug(`Load controller: ${item.id}`);
-        koatty_container.IOC.reg(item.id, item.target, {
+        this.app.container.reg(item.id, item.target, {
           scope: "Prototype",
           type: "CONTROLLER",
           args: []
         });
-        const ctl = koatty_container.IOC.getInsByClass(item.target);
-        if (!koatty_core.implementsControllerInterface(ctl)) {
-          throw Error(`The controller ${item.id} must implements interface 'IController'.`);
-        }
         controllers.push(item.id);
       }
     });
@@ -639,17 +927,20 @@ var Loader = class _Loader {
   * @throws {Error} When service does not implement IService interface
   */
   async LoadServices() {
-    const serviceList = koatty_container.IOC.listClass("SERVICE");
+    const serviceList = this.app.container.listClass("SERVICE");
     for (const item of serviceList) {
       item.id = (item.id ?? "").replace("SERVICE:", "");
       if (item.id && koatty_lib.Helper.isClass(item.target)) {
         koatty_logger.DefaultLogger.Debug(`Load service: ${item.id}`);
-        koatty_container.IOC.reg(item.id, item.target, {
+        const options = this.app.container.getPropertyData("SERVICE_OPTIONS", item.target, item.id) ?? {};
+        this.app.container.reg(item.id, item.target, {
           scope: "Singleton",
+          ...options,
           type: "SERVICE",
-          args: []
+          args: options.args ?? []
         });
-        const ctl = koatty_container.IOC.getInsByClass(item.target);
+        if (options.scope === "Request") continue;
+        const ctl = this.app.container.getInsByClass(item.target);
         if (!koatty_core.implementsServiceInterface(ctl)) {
           throw Error(`The service ${item.id} must implements interface 'IService'.`);
         }
@@ -668,17 +959,17 @@ var Loader = class _Loader {
   * @throws {Error} When plugin loading fails
   */
   async LoadComponents(componentManager) {
-    const componentList = koatty_container.IOC.listClass("COMPONENT");
+    const componentList = this.app.container.listClass("COMPONENT");
     componentList.forEach((item) => {
       item.id = (item.id ?? "").replace("COMPONENT:", "");
       if (koatty_lib.Helper.isClass(item.target)) {
-        koatty_container.IOC.reg(item.id, item.target, {
+        this.app.container.reg(item.id, item.target, {
           scope: "Singleton",
           type: "COMPONENT",
           args: []
         });
         if (item.id && item.id.endsWith("Aspect")) {
-          const ctl = koatty_container.IOC.getInsByClass(item.target);
+          const ctl = this.app.container.getInsByClass(item.target);
           if (!koatty_core.implementsAspectInterface(ctl)) {
             throw Error(`The aspect ${item.id} must implements interface 'IAspect'.`);
           }
@@ -698,7 +989,7 @@ var Loader = class _Loader {
       }
       const pluginConfList = pluginsConf.list ?? [];
       for (const key of pluginConfList) {
-        const handle = koatty_container.IOC.get(key, "COMPONENT");
+        const handle = this.app.container.get(key, "COMPONENT");
         if (!handle) {
           throw Error(`Plugin ${key} load error.`);
         }
@@ -747,7 +1038,8 @@ var bootstrapApplication = /* @__PURE__ */ __name(async function(target, bootFun
     koatty_logger.DefaultLogger.Log("Koatty", "", "Execute bootFunc ...");
     await bootFunc(app);
   }
-  koatty_container.IOC.setApp(app);
+  if (!app.container || app.container === koatty_container.IOC) app.container = new koatty_container.Container();
+  app.container.setApp(app);
   koatty_logger.DefaultLogger.Log("Koatty", "", "ComponentScan ...");
   Loader.CheckAllComponents(app, target);
   await Loader.LoadAllComponents(app, target);
@@ -789,7 +1081,6 @@ var listenCallback = /* @__PURE__ */ __name((app) => {
   koatty_logger.DefaultLogger.Log("Koatty", "", `App Environment: ${app.env}`);
   if (app.appDebug) koatty_logger.DefaultLogger.Warn(`Running in debug mode.`);
   koatty_logger.DefaultLogger.Log("Koatty", "", "====================================");
-  koatty_core.asyncEvent(app, koatty_core.AppEvent.appStart);
 }, "listenCallback");
 function Bootstrap(bootFunc) {
   return koatty_container.IOC.createDecorator((target, _context) => {
@@ -797,6 +1088,7 @@ function Bootstrap(bootFunc) {
       throw new Error(`class does not inherit from Koatty`);
     }
     koatty_container.IOC.saveClass("COMPONENT", target, "KOATTY_APP");
+    if (checkUTRuntime()) return;
     ExecBootStrap(bootFunc)(target).catch((err) => {
       koatty_logger.DefaultLogger.Fatal(err);
       process.exitCode = 1;
@@ -844,10 +1136,6 @@ Object.defineProperty(exports, "Log", {
   enumerable: true,
   get: function () { return koatty_logger.Log; }
 });
-Object.defineProperty(exports, "LogLevelType", {
-  enumerable: true,
-  get: function () { return koatty_logger.LogLevelType; }
-});
 Object.defineProperty(exports, "Logger", {
   enumerable: true,
   get: function () { return koatty_logger.DefaultLogger; }