koatty 3.13.2 → 4.0.0

package/dist/package.json

@@ -1,106 +1,107 @@
-{
-  "name": "koatty",
-  "version": "3.13.2",
-  "description": "Koa2 + Typescript = koatty. Use Typescript's decorator implement auto injection.",
-  "scripts": {
-    "build": "npm run build:js && npm run build:dts && npm run build:doc && npm run build:cp",
-    "build:cp": "node scripts/postBuild && npx copyfiles package.json LICENSE README.md dist/",
-    "build:js": "npx rollup --bundleConfigAsCjs -c .rollup.config.js",
-    "build:doc": "npx api-documenter markdown --input temp --output docs/api",
-    "build:dts": "npx tsc && npx api-extractor run --local --verbose",
-    "eslint": "eslint --ext .ts,.js ./",
-    "prepublishOnly": "npm test && npm run build && git push --follow-tags origin",
-    "prerelease": "npm test && npm run build",
-    "release": "standard-version",
-    "release:pre": "npm run release -- --prerelease",
-    "release:major": "npm run release -- --release-as major",
-    "release:minor": "npm run release -- --release-as minor",
-    "test": "npm run eslint && jest --passWithNoTests",
-    "test:cov": "jest --collectCoverage --detectOpenHandles",
-    "version": "conventional-changelog -p angular -i CHANGELOG.md -s"
-  },
-  "main": "./dist/index.js",
-  "exports": {
-    "require": "./dist/index.js",
-    "import": "./dist/index.mjs",
-    "types": "./dist/index.d.ts"
-  },
-  "directories": {
-    "doc": "docs"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/thinkkoa/koatty.git"
-  },
-  "engines": {
-    "node": ">12.0.0"
-  },
-  "author": {
-    "name": "richenlin",
-    "email": "richenlin@gmail.com"
-  },
-  "license": "BSD-3-Clause",
-  "bugs": {
-    "url": "https://github.com/thinkkoa/koatty/issues"
-  },
-  "homepage": "https://github.com/thinkkoa/koatty",
-  "maintainers": [
-    {
-      "name": "richenlin",
-      "email": "richenlin@gmail.com"
-    }
-  ],
-  "devDependencies": {
-    "@commitlint/cli": "^19.x.x",
-    "@commitlint/config-conventional": "^19.x.x",
-    "@grpc/grpc-js": "^1.12.2",
-    "@microsoft/api-documenter": "^7.x.x",
-    "@microsoft/api-extractor": "^7.x.x",
-    "@rollup/plugin-commonjs": "^28.x.x",
-    "@rollup/plugin-json": "^6.x.x",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-terser": "^0.x.x",
-    "@types/formidable": "^3.x.x",
-    "@types/jest": "^29.x.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",
-    "conventional-changelog-cli": "^5.x.x",
-    "eslint": "^8.x.x",
-    "eslint-plugin-jest": "^28.x.x",
-    "husky": "^4.x.x",
-    "jest": "^29.x.x",
-    "jest-html-reporters": "^3.x.x",
-    "koatty_validation": "~1.x.x",
-    "reflect-metadata": "^0.x.x",
-    "rollup": "^4.x.x",
-    "rollup-plugin-delete": "^2.x.x",
-    "rollup-plugin-typescript2": "^0.x.x",
-    "standard-version": "^9.x.x",
-    "supertest": "^7.x.x",
-    "ts-jest": "^29.x.x",
-    "ts-node": "^10.x.x",
-    "tslib": "^2.x.x",
-    "typescript": "^5.x.x"
-  },
-  "dependencies": {
-    "koa": "~2.16.1",
-    "koatty_config": "~1.2.0",
-    "koatty_container": "~1.12.0",
-    "koatty_core": "~1.16.2",
-    "koatty_exception": "~1.6.0",
-    "koatty_lib": "~1.4.2",
-    "koatty_loader": "~1.1.0",
-    "koatty_logger": "~2.2.0",
-    "koatty_router": "~1.15.0",
-    "koatty_serve": "~2.4.0",
-    "koatty_trace": "~1.15.2",
-    "ts-morph": "^25.0.1"
-  }
-}
+{
+  "name": "koatty",
+  "version": "4.0.0",
+  "description": "Koa + Typescript = koatty. Use Typescript's decorator implement auto injection.",
+  "scripts": {
+    "build": "npm run build:js && npm run build:dts && npm run build:doc && npm run build:cp && npm run build:fix",
+    "build:cp": "npx copyfiles package.json LICENSE README.md dist/ && node scripts/postBuild",
+    "build:fix": "node scripts/fixWorkspaceDeps",
+    "build:js": "npx rollup --bundleConfigAsCjs -c .rollup.config.js",
+    "build:doc": "npx api-documenter markdown --input temp --output docs/api",
+    "build:dts": "npx tsc --skipLibCheck && npx api-extractor run --local --verbose",
+    "eslint": "eslint --ext .ts,.js ./",
+    "prepublishOnly": "echo 'Skipping prepublishOnly in monorepo'",
+    "prerelease": "npm test && npm run build",
+    "release": "standard-version",
+    "release:pre": "npm run release -- --prerelease",
+    "release:major": "npm run release -- --release-as major",
+    "release:minor": "npm run release -- --release-as minor",
+    "test": "npm run eslint && jest --passWithNoTests",
+    "test:cov": "jest --collectCoverage --detectOpenHandles",
+    "version": "conventional-changelog -p angular -i CHANGELOG.md -s"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    "require": "./dist/index.js",
+    "import": "./dist/index.mjs",
+    "types": "./dist/index.d.ts"
+  },
+  "directories": {
+    "doc": "docs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/thinkkoa/koatty.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": {
+    "name": "richenlin",
+    "email": "richenlin@gmail.com"
+  },
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/thinkkoa/koatty/issues"
+  },
+  "homepage": "https://github.com/thinkkoa/koatty",
+  "maintainers": [
+    {
+      "name": "richenlin",
+      "email": "richenlin@gmail.com"
+    }
+  ],
+  "devDependencies": {
+    "@commitlint/cli": "^19.x.x",
+    "@commitlint/config-conventional": "^19.x.x",
+    "@grpc/grpc-js": "^1.12.2",
+    "@microsoft/api-documenter": "^7.x.x",
+    "@microsoft/api-extractor": "^7.x.x",
+    "@rollup/plugin-commonjs": "^28.x.x",
+    "@rollup/plugin-json": "^6.x.x",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-terser": "^0.x.x",
+    "@types/formidable": "^3.x.x",
+    "@types/jest": "^29.x.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",
+    "conventional-changelog-cli": "^5.x.x",
+    "eslint": "^8.x.x",
+    "eslint-plugin-jest": "^28.x.x",
+    "husky": "^4.x.x",
+    "jest": "^29.x.x",
+    "jest-html-reporters": "^3.x.x",
+    "koatty_validation": "~1.x.x",
+    "reflect-metadata": "^0.x.x",
+    "rollup": "^4.x.x",
+    "rollup-plugin-delete": "^2.x.x",
+    "rollup-plugin-typescript2": "^0.x.x",
+    "standard-version": "^9.x.x",
+    "supertest": "^7.x.x",
+    "ts-jest": "^29.x.x",
+    "ts-node": "^10.x.x",
+    "tslib": "^2.x.x",
+    "typescript": "^5.x.x"
+  },
+  "dependencies": {
+    "koa": "^3.0.3",
+    "koatty_config": "^1.2.2",
+    "koatty_container": "^1.17.0",
+    "koatty_core": "^2.0.8",
+    "koatty_exception": "^2.0.4",
+    "koatty_lib": "^1.4.3",
+    "koatty_loader": "^1.3.0",
+    "koatty_logger": "2.8.1",
+    "koatty_router": "^2.0.2",
+    "koatty_serve": "^3.0.0",
+    "koatty_trace": "^2.0.0",
+    "ts-morph": "^27.0.2"
+  }
+}

package/examples/README.md

@@ -0,0 +1,172 @@
+# Koatty Examples
+
+这个目录包含了Koatty框架的各种示例应用，帮助你快速上手和理解框架的使用方法。
+
+## 📚 示例列表
+
+### 🟢 basic-app - 基础应用示例
+
+完整的基础应用示例，展示Koatty框架的核心功能。
+
+**功能特性**:
+- ✅ HTTP路由和控制器
+- ✅ 中间件使用
+- ✅ 服务层和依赖注入
+- ✅ 数据验证（DTO）
+- ✅ 异常处理
+- ✅ AOP切面编程
+- ✅ 静态资源服务
+- ✅ 视图模板
+
+**查看详情**: [basic-app/README.md](./basic-app/README.md)
+
+---
+
+### 🔵 graphql-app - GraphQL应用示例 (规划中)
+
+展示如何使用Koatty构建GraphQL API。
+
+**功能特性**:
+- GraphQL Schema定义
+- Resolver实现
+- GraphiQL调试界面
+- DataLoader优化
+
+---
+
+### 🟣 grpc-app - gRPC应用示例 (规划中)
+
+展示如何使用Koatty构建gRPC服务。
+
+**功能特性**:
+- Protocol Buffers定义
+- gRPC服务实现
+- 双向流通信
+- 健康检查
+
+---
+
+### 🟡 microservices - 微服务示例 (规划中)
+
+展示如何使用Koatty构建微服务架构。
+
+**功能特性**:
+- 服务发现
+- 负载均衡
+- 熔断降级
+- 分布式追踪
+
+---
+
+## 🚀 快速开始
+
+### 1. 克隆仓库
+
+```bash
+git clone https://github.com/koatty/koatty-monorepo.git
+cd koatty-monorepo
+```
+
+### 2. 安装依赖
+
+```bash
+pnpm install
+```
+
+### 3. 运行示例
+
+```bash
+# 运行基础应用示例
+cd examples/basic-app
+pnpm dev
+```
+
+### 4. 使用VS Code调试
+
+按 `F5` 启动调试，选择对应的调试配置。
+
+---
+
+## 📋 通用要求
+
+所有示例都需要：
+
+- **Node.js**: >= 18.0.0
+- **pnpm**: >= 8.0.0
+
+---
+
+## 🏗️ 项目结构
+
+```
+examples/
+├── basic-app/              # 基础应用示例
+│   ├── src/               # 源代码
+│   ├── static/            # 静态资源
+│   ├── view/              # 视图模板
+│   ├── package.json       # 依赖配置
+│   ├── tsconfig.json      # TypeScript配置
+│   └── README.md          # 示例说明
+├── graphql-app/           # GraphQL示例 (规划中)
+├── grpc-app/              # gRPC示例 (规划中)
+├── microservices/         # 微服务示例 (规划中)
+└── README.md              # 本文件
+```
+
+---
+
+## 📝 贡献示例
+
+欢迎贡献新的示例！请遵循以下规范：
+
+### 示例结构
+
+```
+your-example/
+├── src/                   # 源代码
+├── package.json           # 必须使用workspace依赖
+├── tsconfig.json          # TypeScript配置
+└── README.md              # 详细说明
+```
+
+### package.json规范
+
+```json
+{
+  "name": "@koatty/example-your-name",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "koatty": "workspace:*"
+  }
+}
+```
+
+### README规范
+
+每个示例必须包含：
+1. 功能描述
+2. 项目结构
+3. 快速开始指南
+4. API示例
+5. 相关链接
+
+---
+
+## 🔗 相关链接
+
+- [Koatty主项目](https://github.com/koatty/koatty)
+- [Koatty文档](https://koatty.github.io/)
+- [API文档](https://koatty.github.io/api/)
+- [问题反馈](https://github.com/koatty/koatty/issues)
+
+---
+
+## 📄 许可证
+
+所有示例代码均采用 BSD-3-Clause 许可证。
+
+---
+
+**享受使用Koatty构建应用！** 🚀
+

package/examples/basic-app/README.md

@@ -0,0 +1,72 @@
+# Koatty Basic Application Example
+
+这是一个基本的 Koatty 应用示例,位于 `packages/koatty/examples/basic-app` 目录下。
+
+## 目录结构
+
+```
+packages/koatty/examples/basic-app/
+├── src/
+│   ├── App.ts              # 应用入口
+│   ├── bootstrap/          # 启动引导
+│   ├── controller/         # 控制器
+│   ├── service/            # 服务层
+│   ├── middleware/         # 中间件
+│   ├── dto/                # 数据传输对象
+│   ├── aspect/             # 切面
+│   ├── plugin/             # 插件
+│   └── config/             # 配置文件
+├── package.json
+└── tsconfig.json
+```
+
+## 安装依赖
+
+```bash
+cd packages/koatty/examples/basic-app
+pnpm install
+```
+
+## 运行
+
+### 开发模式
+
+```bash
+pnpm run dev
+```
+
+### VSCode 调试
+
+1. 在 VSCode 中打开项目根目录
+2. 按 F5 或点击调试面板中的 "Koatty Demo Program"
+3. 可以在 `packages/koatty/src` 目录下的源码中设置断点进行调试
+
+## 导入说明
+
+由于示例项目位于 `packages/koatty/examples/basic-app` 下,使用相对路径导入 Koatty 框架:
+
+```typescript
+// 导入 Koatty 核心功能
+import { Bootstrap } from "../../../src";
+import { Koatty } from "../../../../koatty-core/src";
+import { AppEvent, KoattyApplication } from "../../../../../koatty-core/src";
+```
+
+这样可以直接调试框架源码,无需编译。
+
+## 配置文件
+
+配置文件位于 `src/config/` 目录:
+
+- `config.ts` - 主配置文件
+- `router.ts` - 路由配置
+- `middleware.ts` - 中间件配置
+- `plugin.ts` - 插件配置
+- `db.ts` - 数据库配置
+
+## 项目特点
+
+- ✅ 支持 TypeScript 源码级调试
+- ✅ 使用相对路径直接引用框架源码
+- ✅ 完整的 MVC 架构示例
+- ✅ 包含控制器、服务、中间件、切面等示例代码

package/examples/basic-app/config/config.ts

@@ -0,0 +1,142 @@
+/*
+ * @Description: app config
+ * @Usage: 
+ * @Author: richen
+ * @Date: 2023-12-09 21:56:32
+ * @LastEditTime: 2025-10-25 10:15:00
+ * @License: BSD (3-Clause)
+ * @Copyright (c): <richenlin(at)gmail.com>
+ */
+export default {
+  /*app config*/
+  logsLevel: "debug", // Level log is printed to the console, "debug" | "info" | "warning" | "error"
+  // logsPath: "./logs", // Log file directory
+  // sensFields: ["password"] // Defined privacy fields will not be printed in logs.
+
+  server: { // server configuration
+    hostname: process.env.IP || '127.0.0.1', // server hostname
+    // 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 || 3000,
+    protocol: ["http"], // Server protocol 'http' | 'https' | 'http2' |  'http3' | 'grpc' | 'ws' | 'wss' | 'graphql'
+    trace: false, // Full stack debug & trace, default: false
+    ssl: {
+      mode: 'auto', // 'auto' | 'manual' | 'mutual_tls'
+      key: '',  // key file path
+      cert: '',  // crt file path
+      ca: ''  // ca file path
+    },
+    ext: {}
+  },
+  trace: { // trace configuration
+    // response timeout in milliseconds
+    timeout: 10000,
+    // request id header name
+    requestIdHeaderName: 'X-Request-Id',
+    // request id name
+    requestIdName: "requestId",
+    // encoding
+    encoding: 'utf-8',
+    // Whether to enable trace (default: false)
+    enableTrace: false,
+    // asynchooks enabled
+    asyncHooks: false,
+    /**
+     * Metrics configuration
+     */
+    metricsConf: {
+      /**
+       * Default attributes for metrics
+       */
+      defaultAttributes: {},
+      /**
+       * Prometheus metrics endpoint (production only)
+       */
+      metricsEndpoint: '/metrics',
+      /**
+       * Metrics report interval in milliseconds (default: 5000)
+       */
+      reportInterval: 5000,
+      /**
+       * 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: [] as any,
+      /**
+       * Exporter timeout in milliseconds
+       */
+      timeout: 10000,
+      /**
+       * Maximum lifetime for a span in milliseconds
+       */
+      spanTimeout: 30000,
+      /**
+       * Maximum number of active spans in memory (default: 1000)
+       */
+      maxActiveSpans: 1000,
+      /**
+       * Sampling rate (0.0 - 1.0)
+       */
+      samplingRate: 1.0,
+      /**
+       * 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: 5000,
+      /**
+       * Timeout for batch export in milliseconds
+       */
+      batchExportTimeout: 30000,
+    },
+    /**
+     * 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: 1000,
+    },
+  }
+};

package/examples/basic-app/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@koatty/example-basic-app",
+  "version": "1.0.0",
+  "description": "Koatty framework basic application example",
+  "private": true,
+  "main": "src/App.ts",
+  "keywords": [
+    "koatty",
+    "example",
+    "demo"
+  ],
+  "author": "richenlin",
+  "license": "BSD-3-Clause",
+  "devDependencies": {
+    "@types/node": "^24.9.1",
+    "ts-node": "^10.x.x",
+    "tsconfig-paths": "^4.x.x",
+    "typescript": "^5.x.x"
+  }
+}

package/examples/basic-app/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+# This file ensures pnpm treats this as a standalone workspace
+packages:
+  - '.'
+

package/examples/basic-app/test-simple.ts

@@ -0,0 +1,13 @@
+import { Bootstrap, Koatty } from "koatty";
+
+@Bootstrap(() => {
+  console.log("Bootstrap function called");
+})
+export class TestApp extends Koatty {
+  public init() {
+    console.log("Init method called");
+    this.appDebug = true;
+  }
+}
+
+console.log("File loaded");

package/examples/basic-app/view/index.html

@@ -0,0 +1,25 @@
+<!--
+ * @Description: 
+ * @Usage: 
+ * @Author: richen
+ * @Date: 2020-12-22 15:57:16
+ * @LastEditTime: 2022-03-15 14:23:33
+-->
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>
+    <%=title%>
+  </title>
+</head>
+
+<body>
+  <H1>
+    <%=content%>
+  </H1>
+</body>
+
+</html>