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

package/README.md

@@ -10,7 +10,7 @@ Vitarx 前端框架官方路由解决方案，提供声明式路由配置、导
 ## 特性
 
 - 🚀 **多种路由模式** - 支持 Hash、History、Memory 三种路由模式
-- 📁 **文件路由** - 基于 Vite 插件的文件系统路由自动生成
+- 📁 **文件路由** - 基于 Vite 插件的文件系统路由自动生成，HMR 热更新支持
 - 🔒 **导航守卫** - 完整的路由守卫机制，支持权限控制
 - 🔄 **动态路由** - 支持动态参数、正则约束、可选参数
 - 📦 **懒加载** - 内置组件懒加载支持
@@ -403,7 +403,10 @@ import VitarxRouter from 'vitarx-router/vite'
 export default defineConfig({
   plugins: [
     VitarxRouter({
-      pagesDir: 'src/pages'
+      pages: 'src/pages',
+      pathStrategy: 'kebab',
+      importMode: 'lazy',
+      dts: 'router.d.ts'
     })
   ]
 })
@@ -418,7 +421,21 @@ import { createRouter } from 'vitarx-router'
 export const router = createRouter({ routes })
 ```
 
-详细配置请参考 [Vite 插件文档](src/plugin-vite/README.md)。
+### 文件路由配置选项
+
+| 选项               | 类型                                    | 默认值           | 说明       |
+|------------------|---------------------------------------|---------------|----------|
+| `pages`          | `PageSource \| readonly PageSource[]` | `'src/pages'` | 页面来源配置   |
+| `pathStrategy`   | `'kebab' \| 'lowercase' \| 'raw'`     | `'kebab'`     | 路径命名策略   |
+| `importMode`     | `'lazy' \| 'sync'`                    | `'lazy'`      | 组件导入模式   |
+| `injectImports`  | `readonly string[]`                   | -             | 自定义导入语句  |
+| `dts`            | `boolean \| string`                   | `false`       | 类型声明文件配置 |
+| `layoutFileName` | `string`                              | `'_layout'`   | 布局文件名    |
+| `configFileName` | `string`                              | `'_config'`   | 分组配置文件名  |
+| `transform`      | `CodeTransformHook`                   | -             | 代码转换钩子   |
+| `extendRoute`    | `ExtendRouteHook`                     | -             | 路由扩展钩子   |
+
+详细配置请参考 [File Router 文档](src/file-router/README.md)。
 
 ## TypeScript 支持
 

package/dist/{plugin-vite/auto-routes → auto-routes}/handleHotUpdate.d.ts

@@ -1,4 +1,4 @@
-import type { Route, Router } from '../../core/index.js';
+import type { Route, Router } from '../core/index.js';
 /**
  * 处理路由热更新函数
  *

package/dist/core/router/manager.js

@@ -200,6 +200,7 @@ export class RouteManager {
         const candidates = this.dynamicRoutes.get(length);
         if (candidates) {
             for (const { regex, route } of candidates) {
+                regex.lastIndex = 0;
                 // 执行正则匹配
                 const match = regex.exec(formattedPath);
                 if (match) {
@@ -248,6 +249,7 @@ export class RouteManager {
         // 3. 动态路由：参数校验与序列化
         const resolvedParams = {};
         for (const paramDef of route.pattern) {
+            paramDef.regex.lastIndex = 0;
             const value = params[paramDef.name];
             const rawValue = String(value ?? ''); // 统一转字符串处理
             // 3.1 必填参数校验

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

@@ -3,4 +3,5 @@
  *
  * 导出所有配置相关功能，提供统一的访问入口。
  */
-export * from './configUtils.js';
+export * from './resolve.js';
+export * from './validate.js';

package/dist/file-router/config/index.js

@@ -3,4 +3,5 @@
  *
  * 导出所有配置相关功能，提供统一的访问入口。
  */
-export * from './configUtils.js';
+export * from './resolve.js';
+export * from './validate.js';

package/dist/file-router/config/resolve.d.ts

@@ -0,0 +1,26 @@
+import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, ImportMode, PageDirOptions, PathStrategy } from '../types/index.js';
+export type PageDirConfig = Required<PageDirOptions>;
+/**
+ * 规范化后的配置
+ */
+export interface ResolvedConfig {
+    root: string;
+    pages: readonly PageDirConfig[];
+    pathStrategy: PathStrategy;
+    importMode: ImportMode;
+    injectImports: readonly string[];
+    dts: false | string;
+    layoutFileName: string;
+    configFileName: string;
+    transform?: CodeTransformHook;
+    extendRoute?: ExtendRouteHook;
+}
+/**
+ * 规范化文件路由配置
+ *
+ * 将用户提供的配置转换为内部统一格式。
+ *
+ * @param options - 用户提供的配置选项
+ * @returns - 规范化后的配置对象
+ */
+export declare function resolveConfig(options: FileRouterOptions): ResolvedConfig;

package/dist/file-router/config/resolve.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview 配置处理工具模块
+ *
+ * 提供页面目录配置的处理和文件检查功能。
+ * 与构建工具无关，可在任何 Node.js 环境中使用。
+ */
+import { accessSync, constants } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_CONFIG_FILE, DEFAULT_DTS_FILE, DEFAULT_EXCLUDE, DEFAULT_INCLUDE, DEFAULT_LAYOUT_FILE, DEFAULT_PAGES_DIR } from '../constants.js';
+const DEFAULT_PAGE_CONFIG = {
+    exclude: DEFAULT_EXCLUDE,
+    include: DEFAULT_INCLUDE,
+    prefix: '/',
+    group: false
+};
+/**
+ * 将 pages 配置规范化为 PageConfig 数组
+ *
+ * 支持四种输入格式：
+ * 1. 字符串：单个目录路径
+ * 2. 对象：单个目录配置
+ * 3. 字符串数组：多个目录路径
+ * 4. 对象数组：每个目录独立配置
+ *
+ * @param pages - 用户配置的 pages
+ * @param root - 项目根目录路径（用于解析相对路径）
+ * @returns - 规范化后的目录配置数组
+ */
+function resolvePageConfigs(pages, root) {
+    const list = Array.isArray(pages) ? pages : [pages];
+    return list.map(page => {
+        const config = typeof page === 'string' ? { dir: page } : page;
+        const resolved = {
+            ...DEFAULT_PAGE_CONFIG,
+            ...config,
+            dir: path.isAbsolute(config.dir) ? config.dir : path.resolve(root, config.dir)
+        };
+        if (resolved.prefix !== '/' && !resolved.prefix.startsWith('/')) {
+            resolved.prefix = '/' + resolved.prefix;
+        }
+        try {
+            accessSync(resolved.dir, constants.R_OK | constants.W_OK);
+        }
+        catch (error) {
+            throw new Error(`File router: Pages directory "${resolved.dir}" does not exist or is not accessible`);
+        }
+        return resolved;
+    });
+}
+/**
+ * 规范化文件路由配置
+ *
+ * 将用户提供的配置转换为内部统一格式。
+ *
+ * @param options - 用户提供的配置选项
+ * @returns - 规范化后的配置对象
+ */
+export function resolveConfig(options) {
+    const { dts = false, root = process.cwd(), pages = DEFAULT_PAGES_DIR, importMode = 'lazy', injectImports = [], pathStrategy = 'kebab', layoutFileName = DEFAULT_LAYOUT_FILE, configFileName = DEFAULT_CONFIG_FILE, transform, extendRoute } = options;
+    const resolvedPages = resolvePageConfigs(pages, root);
+    return {
+        dts: typeof dts === 'string' ? dts : dts ? DEFAULT_DTS_FILE : false,
+        root,
+        pages: resolvedPages,
+        importMode,
+        injectImports,
+        pathStrategy,
+        layoutFileName,
+        configFileName,
+        transform,
+        extendRoute
+    };
+}

package/dist/file-router/{utils/validateOptions.d.ts → config/validate.d.ts}

@@ -4,21 +4,21 @@
  * 提供文件路由配置选项的验证功能，确保用户提供的配置符合要求。
  * 当配置无效时抛出明确的错误信息，帮助用户快速定位问题。
  */
-import type { FileRouterOptions } from '../types.js';
+import type { FileRouterOptions } from '../types/index.js';
 /**
  * 验证插件配置选项
  *
  * 验证顺序：
  * 1. root 配置
- * 2. prefix 配置
- * 3. pages 配置
- * 4. extensions 配置
- * 5. include 配置
- * 6. exclude 配置
- * 7. importMode 配置
- * 8. extendRoute 配置
- * 9. injectImports 配置
- * 10. namingStrategy 配置
+ * 2. pages 配置
+ * 3. pathStrategy 配置
+ * 4. importMode 配置
+ * 5. injectImports 配置
+ * 6. dts 配置
+ * 7. layoutFileName 配置
+ * 8. configFileName 配置
+ * 9. transform 配置
+ * 10. extendRoute 配置
  *
  * @param opts - 用户提供的配置选项
  * @throws {Error} 当配置无效时抛出错误

package/dist/file-router/{utils/validateOptions.js → config/validate.js}

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview 配置验证工具模块
+ *
+ * 提供文件路由配置选项的验证功能，确保用户提供的配置符合要求。
+ * 当配置无效时抛出明确的错误信息，帮助用户快速定位问题。
+ */
 /**
  * 验证 pages 配置
  *
@@ -9,20 +15,20 @@ function validatePagesDir(opts) {
         return;
     if (typeof opts.pages === 'string') {
         if (opts.pages.trim() === '') {
-            throw new Error('options.pagesDir 不能为空字符串');
+            throw new Error('options.pages 不能为空字符串');
         }
         return;
     }
     if (Array.isArray(opts.pages)) {
         if (opts.pages.length === 0) {
-            throw new Error('options.pagesDir 数组不能为空');
+            throw new Error('options.pages 数组不能为空');
         }
         opts.pages.forEach((item, i) => {
             validatePagesDirItem(item, i);
         });
         return;
     }
-    throw new Error('options.pagesDir 必须是字符串、字符串数组或对象数组');
+    throw new Error('options.pages 必须是字符串、字符串数组或对象数组');
 }
 /**
  * 验证 pages 数组中的单个项目
@@ -34,171 +40,162 @@ function validatePagesDir(opts) {
 function validatePagesDirItem(item, index) {
     if (typeof item === 'string') {
         if (item.trim() === '') {
-            throw new Error(`options.pagesDir[${index}] 不能为空字符串`);
+            throw new Error(`options.pages[${index}] 不能为空字符串`);
         }
         return;
     }
     if (typeof item === 'object' && item !== null) {
         const config = item;
         if (!config.dir || typeof config.dir !== 'string' || config.dir.trim() === '') {
-            throw new Error(`options.pagesDir[${index}].dir 必须是非空字符串`);
+            throw new Error(`options.pages[${index}].dir 必须是非空字符串`);
         }
         if (config.include !== undefined && !Array.isArray(config.include)) {
-            throw new Error(`options.pagesDir[${index}].include 必须是数组`);
+            throw new Error(`options.pages[${index}].include 必须是数组`);
         }
         if (config.exclude !== undefined && !Array.isArray(config.exclude)) {
-            throw new Error(`options.pagesDir[${index}].exclude 必须是数组`);
+            throw new Error(`options.pages[${index}].exclude 必须是数组`);
         }
         return;
     }
-    throw new Error(`options.pagesDir[${index}] 必须是字符串或对象`);
+    throw new Error(`options.pages[${index}] 必须是字符串或对象`);
 }
 /**
- * 验证 extensions 配置
+ * 验证 root 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateExtensions(opts) {
-    if (opts.extensions === undefined)
+function validateRoot(opts) {
+    if (opts.root === undefined)
         return;
-    if (!Array.isArray(opts.extensions)) {
-        throw new Error('options.extensions 必须是数组');
+    if (typeof opts.root !== 'string') {
+        throw new Error('options.root 必须是字符串');
     }
-    if (opts.extensions.length === 0) {
-        throw new Error('options.extensions 数组不能为空');
+    if (opts.root.trim() === '') {
+        throw new Error('options.root 不能为空字符串');
     }
-    opts.extensions.forEach((ext, i) => {
-        if (typeof ext !== 'string') {
-            throw new Error(`options.extensions[${i}] 必须是字符串`);
-        }
-        if (!ext.startsWith('.')) {
-            throw new Error(`options.extensions[${i}] "${ext}" 必须以 "." 开头`);
-        }
-    });
 }
 /**
- * 验证 include 配置
+ * 验证 importMode 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateInclude(opts) {
-    if (opts.include === undefined)
+function validateImportMode(opts) {
+    if (opts.importMode === undefined)
         return;
-    if (!Array.isArray(opts.include)) {
-        throw new Error('options.include 必须是数组');
+    const validModes = ['lazy', 'sync'];
+    if (!validModes.includes(opts.importMode)) {
+        throw new Error(`options.importMode 必须是 'lazy' 或 'sync'`);
     }
-    opts.include.forEach((item, i) => {
-        if (typeof item !== 'string') {
-            throw new Error(`options.include[${i}] 必须是字符串`);
-        }
-    });
 }
 /**
- * 验证 exclude 配置
+ * 验证 injectImports 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateExclude(opts) {
-    if (opts.exclude === undefined)
+function validateInjectImports(opts) {
+    if (opts.injectImports === undefined)
         return;
-    if (!Array.isArray(opts.exclude)) {
-        throw new Error('options.exclude 必须是数组');
+    if (!Array.isArray(opts.injectImports)) {
+        throw new Error('options.injectImports 必须是数组');
     }
-    opts.exclude.forEach((item, i) => {
-        if (typeof item !== 'string') {
-            throw new Error(`options.exclude[${i}] 必须是字符串`);
+    opts.injectImports.forEach((imp, i) => {
+        if (typeof imp !== 'string') {
+            throw new Error(`options.injectImports[${i}] 必须是字符串`);
         }
     });
 }
 /**
- * 验证 root 配置
+ * 验证 namingStrategy 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateRoot(opts) {
-    if (opts.root === undefined)
+function validatePathStrategy(opts) {
+    if (opts.pathStrategy === undefined)
         return;
-    if (typeof opts.root !== 'string') {
-        throw new Error('options.root 必须是字符串');
-    }
-    if (opts.root.trim() === '') {
-        throw new Error('options.root 不能为空字符串');
+    const validStrategies = ['kebab', 'lowercase', 'raw'];
+    if (!validStrategies.includes(opts.pathStrategy)) {
+        throw new Error(`options.pathStrategy 必须是 'kebab'、'lowercase' 或 'raw'`);
     }
 }
 /**
- * 验证 prefix 配置
+ * 验证 dts 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validatePrefix(opts) {
-    if (opts.prefix === undefined)
+function validateDts(opts) {
+    if (opts.dts === undefined)
+        return;
+    if (typeof opts.dts === 'boolean')
+        return;
+    if (typeof opts.dts === 'string') {
+        if (opts.dts.trim() === '') {
+            throw new Error('options.dts 为字符串时不能为空字符串');
+        }
         return;
-    if (typeof opts.prefix !== 'string') {
-        throw new Error('options.prefix 必须是字符串');
     }
+    throw new Error('options.dts 必须是 boolean 或 string');
 }
 /**
- * 验证 importMode 配置
+ * 验证 layoutFileName 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateImportMode(opts) {
-    if (opts.importMode === undefined)
+function validateLayoutFileName(opts) {
+    if (opts.layoutFileName === undefined)
         return;
-    const validModes = ['lazy', 'file'];
-    if (!validModes.includes(opts.importMode)) {
-        throw new Error(`options.importMode 必须是 'lazy' 或 'file'`);
+    if (typeof opts.layoutFileName !== 'string') {
+        throw new Error('options.layoutFileName 必须是字符串');
+    }
+    if (opts.layoutFileName.trim() === '') {
+        throw new Error('options.layoutFileName 不能为空字符串');
     }
 }
 /**
- * 验证 extendRoute 配置
+ * 验证 configFileName 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateExtendRoute(opts) {
-    if (opts.extendRoute === undefined)
+function validateConfigFileName(opts) {
+    if (opts.configFileName === undefined)
         return;
-    if (typeof opts.extendRoute !== 'function') {
-        throw new Error('options.extendRoute 必须是函数');
+    if (typeof opts.configFileName !== 'string') {
+        throw new Error('options.configFileName 必须是字符串');
+    }
+    if (opts.configFileName.trim() === '') {
+        throw new Error('options.configFileName 不能为空字符串');
     }
 }
 /**
- * 验证 injectImports 配置
+ * 验证 transform 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateInjectImports(opts) {
-    if (opts.injectImports === undefined)
+function validateTransform(opts) {
+    if (opts.transform === undefined)
         return;
-    if (!Array.isArray(opts.injectImports)) {
-        throw new Error('options.injectImports 必须是数组');
+    if (typeof opts.transform !== 'function') {
+        throw new Error('options.transform 必须是函数');
     }
-    opts.injectImports.forEach((imp, i) => {
-        if (typeof imp !== 'string') {
-            throw new Error(`options.injectImports[${i}] 必须是字符串`);
-        }
-    });
 }
 /**
- * 验证 namingStrategy 配置
+ * 验证 extendRoute 配置
  *
  * @param opts - 配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
-function validateNamingStrategy(opts) {
-    if (opts.namingStrategy === undefined)
+function validateExtendRoute(opts) {
+    if (opts.extendRoute === undefined)
         return;
-    const validStrategies = ['kebab', 'lowercase', 'none'];
-    if (!validStrategies.includes(opts.namingStrategy)) {
-        throw new Error(`options.namingStrategy 必须是 'kebab'、'lowercase' 或 'none'`);
+    if (typeof opts.extendRoute !== 'function') {
+        throw new Error('options.extendRoute 必须是函数');
     }
 }
 /**
@@ -206,28 +203,28 @@ function validateNamingStrategy(opts) {
  *
  * 验证顺序：
  * 1. root 配置
- * 2. prefix 配置
- * 3. pages 配置
- * 4. extensions 配置
- * 5. include 配置
- * 6. exclude 配置
- * 7. importMode 配置
- * 8. extendRoute 配置
- * 9. injectImports 配置
- * 10. namingStrategy 配置
+ * 2. pages 配置
+ * 3. pathStrategy 配置
+ * 4. importMode 配置
+ * 5. injectImports 配置
+ * 6. dts 配置
+ * 7. layoutFileName 配置
+ * 8. configFileName 配置
+ * 9. transform 配置
+ * 10. extendRoute 配置
  *
  * @param opts - 用户提供的配置选项
  * @throws {Error} 当配置无效时抛出错误
  */
 export function validateOptions(opts) {
     validateRoot(opts);
-    validatePrefix(opts);
     validatePagesDir(opts);
-    validateExtensions(opts);
-    validateInclude(opts);
-    validateExclude(opts);
+    validatePathStrategy(opts);
     validateImportMode(opts);
-    validateExtendRoute(opts);
     validateInjectImports(opts);
-    validateNamingStrategy(opts);
+    validateDts(opts);
+    validateLayoutFileName(opts);
+    validateConfigFileName(opts);
+    validateTransform(opts);
+    validateExtendRoute(opts);
 }

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

@@ -3,9 +3,19 @@
  *
  * 定义文件路由的默认配置常量。
  */
-/** 支持的页面文件扩展名列表 */
-export declare const DEFAULT_EXTENSIONS: string[];
 /** 默认的页面目录路径 */
 export declare const DEFAULT_PAGES_DIR = "src/pages";
+/** 默认的类型定义文件路径 */
+export declare const DEFAULT_DTS_FILE = "router.d.ts";
 /** 默认的包含模式 */
 export declare const DEFAULT_INCLUDE: string[];
+/** 默认的排除模式 */
+export declare const DEFAULT_EXCLUDE: string[];
+/**
+ * 布局文件名前缀
+ */
+export declare const DEFAULT_LAYOUT_FILE = "_layout";
+/**
+ * 配置文件名
+ */
+export declare const DEFAULT_CONFIG_FILE = "_config";

package/dist/file-router/constants.js

@@ -3,9 +3,19 @@
  *
  * 定义文件路由的默认配置常量。
  */
-/** 支持的页面文件扩展名列表 */
-export const DEFAULT_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js'];
 /** 默认的页面目录路径 */
 export const DEFAULT_PAGES_DIR = 'src/pages';
+/** 默认的类型定义文件路径 */
+export const DEFAULT_DTS_FILE = 'router.d.ts';
 /** 默认的包含模式 */
-export const DEFAULT_INCLUDE = ['**/*'];
+export const DEFAULT_INCLUDE = ['**/*.{jsx,tsx}'];
+/** 默认的排除模式 */
+export const DEFAULT_EXCLUDE = ['**/node_modules/**', '**/dist/**', '**/.*'];
+/**
+ * 布局文件名前缀
+ */
+export const DEFAULT_LAYOUT_FILE = '_layout';
+/**
+ * 配置文件名
+ */
+export const DEFAULT_CONFIG_FILE = '_config';

package/dist/file-router/generator/generateRoutes.d.ts

@@ -4,17 +4,21 @@
  * 负责将解析后的页面信息转换为可执行的路由配置代码。
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
-import type { ExtendRouteHook, ImportMode, NamingStrategy, ParsedPage } from '../types.js';
+import type { ExtendRouteHook, ImportMode, ParsedNode, RouteNode } from '../types/index.js';
 /**
  * 路由生成选项
  */
 export interface GenerateRoutesOptions {
+    /**
+     * 是否生成类型代码
+     */
+    dts: boolean;
     /**
      * 组件导入模式
      * - `lazy`: 使用 lazy(() => import(...)) 懒加载组件
      * - `file`: 直接使用文件路径作为组件
      */
-    importMode?: ImportMode;
+    importMode: ImportMode;
     /**
      * 路由扩展钩子
      * 在生成每个路由配置时调用，允许开发者自定义扩展路由配置
@@ -24,16 +28,17 @@ export interface GenerateRoutesOptions {
      * 自定义导入语句
      * 允许向虚拟模块注入自定义的导入语句
      */
-    imports?: string[];
-    /**
-     * 路由命名策略
-     * - `kebab`: 将驼峰命名转换为 kebab-case（默认）
-     * - `lowercase`: 简单转换为小写
-     * - `none`: 保持原始命名
-     * @default 'kebab'
-     */
-    namingStrategy?: NamingStrategy;
+    imports?: readonly string[];
 }
+export interface GenerateResult {
+    routes: RouteNode[];
+    code: string;
+    dts: string;
+}
+/**
+ * 将绝对路径转换为百分百唯一、合法的 import 变量名
+ */
+export declare function pathToUniqueName(absolutePath: string): string;
 /**
  * 生成路由配置代码
  *
@@ -41,6 +46,6 @@ export interface GenerateRoutesOptions {
  *
  * @param pages - 解析后的页面列表
  * @param options - 路由生成选项
- * @returns Promise 包含可执行路由配置代码字符串
+ * @returns { GenerateResult } 包含routes、code、dts的路由配置结果
  */
-export declare function generateRoutes(pages: ParsedPage[], options?: GenerateRoutesOptions): Promise<string>;
+export declare function generateRoutes(pages: ParsedNode[], options: GenerateRoutesOptions): GenerateResult;