koa-ts-core 0.2.0 → 0.2.2

package/dist/init/register_controller.d.ts

@@ -1,9 +1,11 @@
 import type { AuthRouterCallback } from '../types/route';
 /**
  * 约定式控制器注册路由
- * @param controllerModulePath 控制器模块路径
- * @param validateModulePath 验证模块路径
- * @param authCallback 鉴权回调
+ * - 扫描 controller 目录下的所有控制器文件
+ * - 读取其中由装饰器收集的 routesMap
+ * - 为每个控制器注册路由（挂载鉴权与参数校验）
+ *
+ * @param authCheckCallback 鉴权回调（配合 @AuthRouter 使用）
  */
 declare const registerControllers: (authCheckCallback?: AuthRouterCallback) => void;
 export default registerControllers;

package/dist/init/register_env.d.ts

@@ -1,5 +1,14 @@
 /**
- * 初始化dotenv
+ * 初始化 dotenv
+ *
+ * 搜索 env 目录优先级：
+ * 1. process.env.ENV_DIR（可为绝对或相对路径）
+ * 2. <src>/env
+ * 3. <projectRoot>/env（即 src 的上一级）
+ *
+ * 加载顺序：
+ * 1. .common.env
+ * 2. .development.env / .test.env / .production.env （按 NODE_ENV）
  */
 declare const initializeDotenv: () => void;
 export default initializeDotenv;

package/dist/init/register_route.d.ts

@@ -1,8 +1,8 @@
 import { AuthRouterHandler, FilePathMeta, RouteConfig } from '../types/route';
 /**
  * 注册路由
- * @param validateModulePath 参数验证器路径
- * @param filePath 控制器文件路径
+ * @param validateModulePath validate 根目录路径
+ * @param filePath 控制器文件路径元信息
  * @param routesMap 路由映射
  * @param authCheckResult 鉴权结果处理函数
  */

package/dist/init/render_doc.d.ts

@@ -1,2 +1,8 @@
+/**
+ * 生成文档 HTML
+ * - 遍历 doc 目录下所有文档类文件
+ * - 收集类级别元数据（configs/desc/name/apiPrePath/pathPrefix）
+ * - 按 pathPrefix 分组后传入 Pug 模板渲染
+ */
 declare const generateDocHtml: () => Promise<string>;
 export default generateDocHtml;

package/dist/types/route.d.ts

@@ -1,6 +1,6 @@
 import type { Context, Middleware } from "koa";
 import type { Dirent } from "fs";
-export type HttpMethod = "get" | "post" | "put" | "delete" | "patch" | "options";
+export type HttpMethod = "get" | "post" | "put" | "delete" | "patch" | "options" | "head";
 /** 文件路径元数据 */
 export interface FilePathMeta {
     path: string;
@@ -16,7 +16,6 @@ export type WalkSyncHandler = (filePath: FilePathMeta, dirent: Dirent) => void;
 export interface RouteConfig {
     path: string;
     method: HttpMethod;
-    /** 控制器函数（使用 Koa 标准 Middleware 类型） */
     handler: Middleware;
     functionName: string;
     authRequired: boolean;

package/dist/utils/funtions.d.ts

@@ -0,0 +1 @@
+export declare const generateUuid: () => `${string}-${string}-${string}-${string}-${string}`;

package/dist/utils/path.d.ts

@@ -1,12 +1,10 @@
-import { FilePathMeta, WalkSyncHandler } from '../types/route';
+import type { FilePathMeta, WalkSyncHandler } from '../types/route';
 /**
- * 获取入口模块路径
- * @returns 模块路径对象
+ * 获取 src 根目录
  */
 export declare const getEntryPath: () => string;
 /**
- * 获取 src 模块的路径
- * @returns 模块路径对象
+ * 获取 src 下各模块目录
  */
 export declare const getSrcModulePaths: () => {
     controllerModule: string;
@@ -16,20 +14,18 @@ export declare const getSrcModulePaths: () => {
 };
 /**
  * 获取指定路径的默认导出
- * @param {string} filePath - 文件路径
- * @returns {T | undefined} - 文件的默认导出或 undefined
  */
 export declare const getDefaultExportFromFile: <T = any>(filePath: string) => T | undefined;
 /**
- * 递归同步遍历指定目录下的所有文件
- * @param {string} currentDirPath - 当前目录路径
- * @param {WalkSyncHandler} callback - 处理每个文件的回调函数
+ * 递归遍历指定目录下的所有文件
  */
 export declare function walkDirectorySync(currentDirPath: string, callback: WalkSyncHandler): void;
 /**
- * 根据文件路径和关键字部分生成路径的模块选项
- * @param {FilePathMeta} filePath - 文件路径元数据
- * @returns {Object} 包含控制器前缀、模块名和文件名的对象
+ * 统一处理不同平台的文件路径格式，将路径转换为 '/test/file' 格式
+ */
+export declare const formatPathByPlatform: (filePath: string) => string;
+/**
+ * 根据文件路径和关键字部分生成 controller 对应的路由前缀信息
  */
 export declare const generateOptionsByKeyPart: (filePath: FilePathMeta, keyPart: string) => {
     pathPrefix: string;
@@ -37,21 +33,7 @@ export declare const generateOptionsByKeyPart: (filePath: FilePathMeta, keyPart:
     name: string;
 };
 /**
- * 统一处理不同平台的文件路径格式，将路径转换为 '/test/file' 格式
- * @param {string} filePath - 原始文件路径
- * @returns {string} 转换后的文件路径
- */
-export declare const formatPathByPlatform: (filePath: string) => string;
-/**
- * 确保文件存在，如果不存在则创建目录和文件
- * @param {string} filePath - 要检查的文件路径
- * @param {string} content - 文件内容，如果不指定，则为空文件
- * @returns {boolean} 文件是否存在
- */
-export declare function ensureFileExists(filePath: string, content?: string): boolean;
-/**
- * 检查文件夹是否存在
- * @param targetPath - 目标路径
- * @returns
+ * 把类似 "api/v1" 转成 "/api/v1"
  */
+export declare const normalizeRoutePath: (p: string) => string;
 export declare function folderExists(targetPath: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "koa-ts-core",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "koa-ts-core",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",
@@ -33,8 +33,7 @@
     "portfinder": "^1.0.38",
     "pug": "^3.0.3",
     "rollup-plugin-copy-and-reference-dts": "0.0.2",
-    "rollup-plugin-pug": "^1.1.1",
-    "uuid": "^13.0.0"
+    "rollup-plugin-pug": "^1.1.1"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^29.0.0",