vitarx-router 4.0.0-beta.2 → 4.0.0-beta.21

package/dist/file-router/index.d.ts

@@ -1,143 +1,277 @@
-import { type ResolvedConfig } from './config/index.js';
-import type { FileRouterOptions, ParsedPage } from './types.js';
-export * from './utils/logger.js';
-export * from './types.js';
 /**
- * 路由生成结果
+ * @fileoverview 文件路由管理器
+ *
+ * 封装文件路由的核心流程，可在不同构建工具中复用。
+ * 支持 Vite、Webpack、Rollup 等构建工具，或在 Node.js 脚本中直接使用。
  */
-export interface RoutesResult {
-    /** 生成的路由代码 */
-    code: string;
-    /** 页面列表 */
-    pages: ParsedPage[];
-    /** 路由树 */
-    routeTree: ParsedPage[];
-}
+import type { GeneratorResult } from '@babel/generator';
+import { ResolvedConfig } from './config/index.js';
+import { type GenerateResult } from './generator/index.js';
+import { type FilterOptions } from './parser/index.js';
+import type { FileRouterOptions, ScanNode } from './types/index.js';
+export { resolvePageConfigs } from './config/resolve.js';
+export * from './generator/index.js';
+export { mergePageOptions } from './macros/definePage.js';
+export type * from './types/index.js';
+export { findRoute } from './utils/findRoute.js';
+export * from './utils/logger.js';
 /**
- * 类型定义生成结果
+ * 文件监听器事件类型
+ *
+ * 对应 chokidar 文件监听器的事件类型
  */
-interface WriteDtsResult {
-    /** 类型定义内容 */
-    content: string;
-    /** 写入路径（绝对路径） */
-    path: string;
-}
+export type FileWatcherEvent = 'add' | 'addDir' | 'change' | 'unlink' | 'unlinkDir';
 /**
  * 文件路由管理器
- *
- * 封装文件路由的核心流程，提供统一的 API 供不同构建工具使用。
- *
- * @example
- * ```typescript
- * // 基本使用
- * const router = new FileRouter({
- *   pagesDir: 'src/pages',
- *   extensions: ['.tsx', '.ts']
- * })
- *
- * router.setRoot('/project/root')
- * router.scan()
- *
- * // 生成路由代码
- * const routes = await router.generateRoutes()
- *
- * // 生成类型定义
- * const dts = router.generateDts()
- * ```
- *
- * @example
- * ```typescript
- * // 在 Vite 插件中使用
- * const router = new FileRouter(options)
- *
- * return {
- *   configResolved(config) {
- *     router.setRoot(config.root)
- *     router.scan()
- *   },
- *   async load(id) {
- *     if (id === VIRTUAL_ID) {
- *       return (await router.generateRoutes()).code
- *     }
- *   }
- * }
- * ```
  */
 export declare class FileRouter {
+    #private;
+    /**
+     * 配置项
+     */
     readonly config: ResolvedConfig;
-    private _pages;
-    private _routeTree;
-    private _cachedRoutesPromise;
     /**
      * 创建文件路由管理器
      *
      * @param options - 配置选项
+     * @param [init = true] - 是否初始化加载
      */
-    constructor(options?: FileRouterOptions);
+    constructor(options?: FileRouterOptions, init?: boolean);
     /**
      * 获取项目根目录
      */
     get root(): string;
+    /**
+     * 获取节点树
+     */
+    get nodeTree(): ScanNode[];
+    /**
+     * 获取文件映射表
+     *
+     * 键为文件或目录路径，值为对应的节点对象
+     */
+    get fileMap(): Map<string, ScanNode>;
+    /**
+     * 加载/重新加载文件路由管理器
+     *
+     * @returns {FileRouter} 文件路由管理器实例
+     */
+    reload(): this;
+    /**
+     * 构建路由数组
+     *
+     * @returns 扫描到的页面文件列表
+     */
+    protected scanPages(): ScanNode[];
     /**
      * 扫描页面目录
      *
-     * 扫描所有配置的页面目录，解析页面文件并构建路由树。
-     * 扫描后会清除路由代码缓存。
+     * @param page - 页面配置
+     * @param parent - 父路由
+     * @protected
      */
-    scan(): void;
+    private scanPageDir;
     /**
-     * 清除缓存
+     * 处理目录
      *
-     * 清除路由代码缓存，下次调用 generateRoutes() 会重新生成。
+     * @param filePath - 目录路径
+     * @param fileName - 目录名
+     * @param page - 页面配置
+     * @param parent - 父节点
+     * @private
      */
-    invalidate(): void;
+    private processDir;
     /**
-     * 检查文件是否为页面文件
+     * 解析分组目录的自定义路径和选项
      *
-     * @param file - 文件绝对路径
-     * @returns {boolean} - 是否为页面文件
+     * 通过 groupParser 解析目录名，支持返回字符串路径或包含路径与选项的对象。
+     *
+     * @param fileName - 目录名
+     * @param filePath - 目录完整路径
+     * @returns 解析后的路径和选项
+     * @private
+     */
+    private parseGroupResult;
+    /**
+     * 处理文件
+     *
+     * 根据文件类型分发到对应的处理器。
+     *
+     * @param filePath - 文件路径
+     * @param page - 页面配置
+     * @param pageMapping - 同路径路由映射
+     * @param parent - 父节点
+     * @private
+     */
+    private processFile;
+    /**
+     * 解析文件信息与类型
+     *
+     * 统一入口，避免多处重复调用 extractFileInfo + getPageType。
+     *
+     * @param filePath - 文件路径
+     * @param page - 页面配置
+     * @returns 文件信息与类型
+     */
+    private resolveFile;
+    /**
+     * 处理分组配置文件
+     *
+     * 解析 definePage 宏并合并到父路由选项中。
+     *
+     * @param filePath - 文件路径
+     * @param parent - 父节点
      */
-    isPageFile(file: string): boolean;
+    private processConfigFile;
     /**
-     * 获取页面列表
+     * 处理分组布局文件
      *
-     * @returns - 解析后的页面列表
+     * 将布局组件注册到父路由的 components 中。
+     *
+     * @param filePath - 文件路径
+     * @param fileInfo - 文件信息
+     * @param parent - 父节点
+     */
+    private processLayoutFile;
+    /**
+     * 处理页面文件
+     *
+     * 解析路由路径、视图命名和页面选项，创建或合并路由节点。
+     *
+     * @param filePath - 文件路径
+     * @param fileInfo - 文件信息
+     * @param page - 页面配置
+     * @param pageMapping - 同路径路由映射
+     * @param parent - 父节点
+     * @param [precomputedParsed] - 预计算的解析结果，避免重复调用 parsePageFile
+     * @returns 新创建的路由节点，或 null（合并到已有路由时）
+     */
+    private processPageFile;
+    /**
+     * 在已有路由树中查找同路径路由
+     *
+     * 用于 addPage 场景：新增文件时需要检查是否已存在同路径的路由节点，
+     * 以便将命名视图合并到已有路由而非创建重复路由。
+     *
+     * @param pathKey - 标准化后的路由路径
+     * @param prefix - 路径前缀
+     * @param parent - 父节点
+     * @returns 同路径的路由节点，未找到返回 null
      */
-    getPages(): ParsedPage[];
+    private findSameRoute;
     /**
-     * 获取路由树
+     * 应用路径策略
      *
-     * @returns - 路由树结构
+     * @param path - 路径
+     * @protected
      */
-    getRouteTree(): ParsedPage[];
+    private applyPathStrategy;
     /**
-     * 生成路由代码
+     * 读取文件内容
      *
-     * @returns - 路由生成结果
+     * @param file - 文件绝对路径
      */
-    generateRoutes(): Promise<RoutesResult>;
+    private readFile;
     /**
-     * 生成类型定义
+     * 获取文件类型
+     *
+     * @param file - 文件绝对路径
+     * @param rawName - 文件名（不含扩展名和 @视图命名）
+     * @param pages - 页面配置
+     * @returns 文件类型
+     */
+    private getPageType;
+    /**
+     * 检查文件是否为页面文件
+     *
+     * @param file - 文件绝对路径
+     * @param filter - 过滤配置，默认为 `config.pages`
+     * @returns {boolean} - 是否为页面文件
+     */
+    isPageFile(file: string, filter?: FilterOptions | readonly FilterOptions[]): boolean;
+    /**
+     * 获取文件的完整路由路径
+     *
+     * 判断文件是否为页面文件，如果是则计算其最终生成的路由 fullPath。
+     * 非页面文件（布局文件、配置文件等）返回 null。
      *
-     * @returns - 类型定义内容
+     * @param filePath - 文件绝对路径
+     * @returns 完整路由路径，非页面文件返回 null
      */
-    generateDts(): string;
+    getRouteFullPath(filePath: string): string | null;
     /**
      * 写入类型定义文件
+     */
+    private writeDts;
+    /**
+     * 生成路由
      *
-     * @param dtsPath - 类型定义文件路径，可以是绝对路径或相对于项目根目录的相对路径
-     * @returns 写入结果信息
+     * @returns {GenerateResult} 生成结果，包含routes、dts、code
+     */
+    generate(): GenerateResult;
+    /**
+     * 清空生成结果
      */
-    writeDts(dtsPath: string): WriteDtsResult;
+    clearGenerateResult(): void;
     /**
      * 移除 definePage 宏
      *
-     * 在构建模式下移除页面文件中的 definePage 宏调用。
-     * definePage 作为全局宏使用，无需导入。
+     * 移除页面文件中的 definePage 宏调用。
+     * definePage 在客户端无法运行，必须移除。
      *
      * @param code - 源代码
      * @param filePath - 文件路径
      * @returns 转换后的代码，无需转换返回 null
      */
-    removeDefinePage(code: string, filePath: string): import("@babel/generator").GeneratorResult | null;
+    removeDefinePage(code: string, filePath: string): GeneratorResult | null;
+    /**
+     * 添加页面文件
+     *
+     * 根据文件类型直接调用对应处理器，避免重复类型判断和文件解析。
+     *
+     * @param filePath - 文件路径
+     * @returns 是否创建了新的路由节点
+     */
+    addPage(filePath: string): boolean;
+    /**
+     * 移除指定的文件或目录
+     *
+     * 通常用于在开发模式下，文件内容改变时，移除旧的路由映射，重新生成
+     *
+     * 移除成功后续手动调用 `clearGenerateResult` 方法确保下一次获取新的生成结果！
+     *
+     * @param filePath - 文件/目录路径
+     * @returns {boolean} - 存在则移除并返回 true，不存在则返回 false
+     */
+    removePage(filePath: string): boolean;
+    /**
+     * 更新文件
+     *
+     * 如果文件未被扫描，则会自动添加。
+     *
+     * @param filePath - 文件路径
+     * @returns {boolean} - 是否更新了文件
+     */
+    updatePage(filePath: string): boolean;
+    /**
+     * 处理文件变化
+     *
+     * @param eventName - 文件变化事件名
+     * @param path - 文件路径
+     * @returns {boolean} - 是否影响了路由
+     * @example
+     * ```typescript
+     * router.handleChange('change', '/path/to/file.ts')
+     * // 在vite中使用
+     * server.watcher.on('all', (event,path) => {
+     *   const mod = server.moduleGraph.getModuleById(RESOLVED_ROUTES_ID)
+     *   if (mod) {
+     *     const result = router.handleChange(event, path)
+     *     // 如果 handleChange 返回 true，则表示路由受到影响，需要更新模块
+     *     if(result) server.moduleGraph.invalidateModule(mod)
+     *   }
+     * })
+     * ```
+     */
+    handleChange(eventName: FileWatcherEvent, path: string): boolean;
 }