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

package/dist/file-router/utils/{namingStrategy.js → pathStrategy.js}

@@ -1,3 +1,13 @@
+/**
+ * @fileoverview 命名策略工具模块
+ *
+ * 提供路由名称和路径的命名转换功能，支持三种策略：
+ * - kebab: 将驼峰命名转换为 kebab-case（默认）
+ * - lowercase: 简单转换为小写
+ * - none: 保持原始命名
+ *
+ * 注意：只处理路径段名称，不处理动态参数变量名。
+ */
 /**
  * 将驼峰命名转换为 kebab-case
  *
@@ -32,22 +42,22 @@ function toKebabCase(str) {
  * applyNamingStrategy('MainHome', 'none')      // => 'MainHome'
  * ```
  */
-export function applyNamingStrategy(str, strategy) {
+function applyStrategy(str, strategy) {
     switch (strategy) {
         case 'kebab':
             return toKebabCase(str);
         case 'lowercase':
             return str.toLowerCase();
-        case 'none':
+        case 'raw':
         default:
             return str;
     }
 }
 /**
  * 动态参数正则表达式
- * 匹配 {paramName} 或 {paramName?} 格式
+ * 匹配 [paramName] 或 [paramName?] 格式
  */
-const DYNAMIC_PARAM_REGEX = /\{([^}]+)}/g;
+const DYNAMIC_PARAM_REGEX = /\[([^]]+)]/g;
 /**
  * 应用命名策略转换路由路径
  *
@@ -60,12 +70,12 @@ const DYNAMIC_PARAM_REGEX = /\{([^}]+)}/g;
  * @example
  * ```typescript
  * applyNamingStrategyToPath('/MainHome', 'kebab')     // => '/main-home'
- * applyNamingStrategyToPath('/User/{userName}', 'kebab')  // => '/user/{userName}'
+ * applyNamingStrategyToPath('/User/[userName]', 'kebab')  // => '/user/[userName]'
  * applyNamingStrategyToPath('/API/UserProfile', 'kebab')  // => '/api/user-profile'
  * ```
  */
-export function applyNamingStrategyToPath(path, strategy) {
-    if (strategy === 'none') {
+export function applyPathStrategy(path, strategy) {
+    if (strategy === 'raw') {
         return path;
     }
     const segments = path.split('/');
@@ -80,27 +90,7 @@ export function applyNamingStrategyToPath(path, strategy) {
             DYNAMIC_PARAM_REGEX.lastIndex = 0;
             continue;
         }
-        result.push(applyNamingStrategy(segment, strategy));
+        result.push(applyStrategy(segment, strategy));
     }
     return result.join('/');
 }
-/**
- * 应用命名策略转换路由名称
- *
- * @param name - 路由名称
- * @param strategy - 命名策略
- * @returns 转换后的名称
- *
- * @example
- * ```typescript
- * applyNamingStrategyToName('MainHome', 'kebab')     // => 'main-home'
- * applyNamingStrategyToName('user-MainHome', 'kebab')  // => 'user-main-home'
- * ```
- */
-export function applyNamingStrategyToName(name, strategy) {
-    if (strategy === 'none') {
-        return name;
-    }
-    const parts = name.split('-');
-    return parts.map(part => applyNamingStrategy(part, strategy)).join('-');
-}

package/dist/file-router/utils/pathUtils.d.ts

@@ -20,3 +20,34 @@
  * ```
  */
 export declare function normalizePathSeparator(path: string): string;
+/**
+ * 归一化path
+ *
+ * 去除所有空格、替换重复的斜杠、去除尾部的斜杠
+ *
+ * @example
+ * normalizePath('/  foo') // '/foo'
+ * normalizePath('/foo/') // '/foo'
+ * normalizePath('/foo/bar') // '/foo/bar'
+ * normalizePath('foo/') // '/foo'
+ *
+ * @param {string} path - 路径字符串
+ * @return {string} - 格式化后的路径字符串
+ */
+export declare function normalizeRoutePath(path: string): string;
+/**
+ * 解析文件名
+ *
+ * 提取文件名中的路由信息和动态参数。
+ *
+ * @param path - path
+ * @returns 解析结果
+ */
+export declare function resolvePathVariable(path: string): string;
+/**
+ * 检查路径是否包含动态参数
+ *
+ * @param path - 路由路径
+ * @returns {boolean} 是否包含动态参数
+ */
+export declare function hasDynamicPath(path: string): boolean;

package/dist/file-router/utils/pathUtils.js

@@ -20,5 +20,57 @@
  * ```
  */
 export function normalizePathSeparator(path) {
-    return path.replace(/\\/g, '/');
+    return path.trim().replace(/\\/g, '/').replace(/\/+/g, '/');
+}
+/**
+ * 归一化path
+ *
+ * 去除所有空格、替换重复的斜杠、去除尾部的斜杠
+ *
+ * @example
+ * normalizePath('/  foo') // '/foo'
+ * normalizePath('/foo/') // '/foo'
+ * normalizePath('/foo/bar') // '/foo/bar'
+ * normalizePath('foo/') // '/foo'
+ *
+ * @param {string} path - 路径字符串
+ * @return {string} - 格式化后的路径字符串
+ */
+export function normalizeRoutePath(path) {
+    // 去除所有空格 处理重复//
+    const formated = `/${path.trim()}`.replace(/\s+/g, '').replace(/\/+/g, '/');
+    if (formated === '/')
+        return formated;
+    return formated.replace(/\/$/, '');
+}
+/** 动态参数匹配正则，如 [id]、[slug]、[param?] */
+const DYNAMIC_PARAM_REGEX = /\{([^?}]+)(\?)?}|\[([^\]]+)]/g;
+/**
+ * 解析文件名
+ *
+ * 提取文件名中的路由信息和动态参数。
+ *
+ * @param path - path
+ * @returns 解析结果
+ */
+export function resolvePathVariable(path) {
+    if (!path.includes('['))
+        return path;
+    // 使用 replace 遍历所有匹配项，避免只有第一个参数被替换的问题
+    return path.replace(DYNAMIC_PARAM_REGEX, (_match, braceName, isOptional, bracketName) => {
+        // 获取参数名：如果有 braceName 就用 braceName，否则用 bracketName
+        const paramName = braceName || bracketName;
+        // 处理可选标识：如果有 isOptional(即问号) 就加上 '?'
+        const optionalMark = isOptional ? '?' : '';
+        return `{${paramName}${optionalMark}}`;
+    });
+}
+/**
+ * 检查路径是否包含动态参数
+ *
+ * @param path - 路由路径
+ * @returns {boolean} 是否包含动态参数
+ */
+export function hasDynamicPath(path) {
+    return path.includes('{');
 }

package/dist/plugin-vite/constant.d.ts

@@ -0,0 +1,9 @@
+/** 虚拟模块 ID，用于导入自动生成的路由配置 */
+export declare const VIRTUAL_ROUTES_ID = "virtual:vitarx-router:routes";
+/**
+ * 解析后的路由模块 ID
+ *
+ * Vite 要求虚拟模块的解析 ID 必须以 `\0` 开头，
+ * 这样其他插件就不会尝试处理这个模块
+ */
+export declare const RESOLVED_ROUTES_ID: string;

package/dist/plugin-vite/constant.js

@@ -0,0 +1,9 @@
+/** 虚拟模块 ID，用于导入自动生成的路由配置 */
+export const VIRTUAL_ROUTES_ID = 'virtual:vitarx-router:routes';
+/**
+ * 解析后的路由模块 ID
+ *
+ * Vite 要求虚拟模块的解析 ID 必须以 `\0` 开头，
+ * 这样其他插件就不会尝试处理这个模块
+ */
+export const RESOLVED_ROUTES_ID = '\0' + VIRTUAL_ROUTES_ID;

package/dist/plugin-vite/index.d.ts

@@ -1,24 +1,4 @@
-import type { Plugin } from 'vite';
-import type { FileRouterOptions } from '../file-router/types.js';
-/** 默认的类型声明文件路径 */
-export declare const DEFAULT_DTS_FILE = "typed-router.d.ts";
-/**
- * Vite 插件配置选项
- *
- * 扩展自 FileRouterOptions，添加 Vite 特有的配置项。
- */
-export interface RouterPluginOptions extends FileRouterOptions {
-    /**
-     * 类型声明文件路径，设为 false 可禁用生成
-     *
-     * @default 'typed-router.d.ts'
-     */
-    dts?: string | false;
-}
-/**
- * 创建 Vitarx Router Vite 插件
- *
- * @param options - 插件配置选项
- * @returns Vite 插件实例
- */
-export default function VitarxRouter(options?: RouterPluginOptions): Plugin;
+import vitarxRouter from './plugin.js';
+export * from './constant.js';
+export * from './watcher.js';
+export default vitarxRouter;

package/dist/plugin-vite/index.js

@@ -1,94 +1,4 @@
-/**
- * @fileoverview Vite 插件入口模块
- *
- * 这是 vitarx-router 文件路由功能的 Vite 插件主入口。
- * 提供基于文件系统的自动路由生成能力，支持热更新和 TypeScript 类型生成。
- *
- * ## 安装使用
- * ```typescript
- * // vite.config.ts
- * import VitarxRouter from 'vitarx-router/vite'
- *
- * export default defineConfig({
- *   plugins: [
- *     VitarxRouter({
- *       pagesDir: 'src/pages',
- *       extensions: ['.tsx', '.ts'],
- *       dts: 'typed-router.d.ts'
- *     })
- *   ]
- * })
- * ```
- *
- * ## 虚拟模块
- * - `virtual:vitarx-router:routes` - 自动生成的路由配置
- *
- * @module vite
- */
-import chalk from 'chalk';
-import { FileRouter, info } from '../file-router/index.js';
-/** 默认的类型声明文件路径 */
-export const DEFAULT_DTS_FILE = 'typed-router.d.ts';
-/** 虚拟模块 ID：路由配置 */
-const VIRTUAL_ROUTES_ID = 'virtual:vitarx-router:routes';
-/** 解析后的路由模块 ID（Vite 内部使用） */
-const RESOLVED_ROUTES_ID = '\0' + VIRTUAL_ROUTES_ID;
-/**
- * 创建 Vitarx Router Vite 插件
- *
- * @param options - 插件配置选项
- * @returns Vite 插件实例
- */
-export default function VitarxRouter(options = {}) {
-    const dts = options.dts ?? DEFAULT_DTS_FILE;
-    const router = new FileRouter(options);
-    return {
-        name: 'vite-plugin-vitarx-router',
-        enforce: 'pre',
-        configResolved() {
-            router.scan();
-            if (dts) {
-                const result = router.writeDts(dts);
-                info(`✨ generate type definitions:\n${chalk.yellow(result.path)}`);
-            }
-        },
-        resolveId(id) {
-            if (id === VIRTUAL_ROUTES_ID) {
-                return RESOLVED_ROUTES_ID;
-            }
-            return null;
-        },
-        async load(id) {
-            if (id === RESOLVED_ROUTES_ID) {
-                const { code } = await router.generateRoutes();
-                return code;
-            }
-            return null;
-        },
-        transform(code, id) {
-            return router.removeDefinePage(code, id);
-        },
-        configureServer(server) {
-            const absolutePagesDirs = router.config.pages;
-            for (const dirConfig of absolutePagesDirs) {
-                server.watcher.add(dirConfig.dir);
-            }
-            const handlePageFileChange = (file, server) => {
-                if (router.isPageFile(file)) {
-                    router.invalidate();
-                    router.scan();
-                    if (dts) {
-                        router.writeDts(dts);
-                    }
-                    const mod = server.moduleGraph.getModuleById(RESOLVED_ROUTES_ID);
-                    if (mod) {
-                        server.moduleGraph.invalidateModule(mod);
-                    }
-                }
-            };
-            server.watcher.on('add', file => handlePageFileChange(file, server));
-            server.watcher.on('unlink', file => handlePageFileChange(file, server));
-            server.watcher.on('change', file => handlePageFileChange(file, server));
-        }
-    };
-}
+import vitarxRouter from './plugin.js';
+export * from './constant.js';
+export * from './watcher.js';
+export default vitarxRouter;

package/dist/plugin-vite/plugin.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @fileoverview Vite 插件入口模块
+ *
+ * 这是 vitarx-router 文件路由功能的 Vite 插件主入口。
+ * 提供基于文件系统的自动路由生成能力，支持热更新和 TypeScript 类型生成。
+ *
+ * ## 核心功能
+ * - **虚拟模块**: 通过 `virtual:vitarx-router:routes` 提供自动生成的路由配置
+ * - **热更新**: 监听文件变化，自动更新路由配置
+ * - **代码转换**: 移除页面文件中的 `definePage` 宏调用
+ * - **类型生成**: 支持生成 TypeScript 类型定义文件
+ *
+ * ## 安装使用
+ * ```typescript
+ * // vite.config.ts
+ * import VitarxRouter from 'vitarx-router/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     VitarxRouter({
+ *       pagesDir: 'src/pages',
+ *       extensions: ['.tsx', '.ts'],
+ *       dts: 'typed-router.d.ts'
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * ## 虚拟模块
+ * - `virtual:vitarx-router:routes` - 自动生成的路由配置
+ *
+ * ## 插件生命周期
+ * 1. `config` - 识别是否为预览模式
+ * 2. `configResolved` - 创建 FileRouter 实例
+ * 3. `resolveId` - 解析虚拟模块 ID
+ * 4. `load` - 加载虚拟模块内容
+ * 5. `transform` - 转换页面文件代码
+ * 6. `configureServer` - 配置开发服务器文件监听
+ * 7. `closeBundle` - 清理资源
+ *
+ * @module vite
+ * @see {@link https://router.vitarx.cn 官方文档}
+ */
+import type { Plugin } from 'vite';
+import { type FileRouterOptions } from '../file-router/index.js';
+/**
+ * Vite 插件配置选项
+ *
+ * 继承自 FileRouterOptions，未添加额外的 Vite 特有配置项
+ *
+ * @see {@link FileRouterOptions} 文件路由配置选项
+ */
+export interface RouterPluginOptions extends FileRouterOptions {
+}
+/**
+ * 创建 Vitarx Router Vite 插件
+ *
+ * 这是插件的主入口函数，返回一个标准的 Vite 插件对象。
+ * 插件通过虚拟模块提供自动生成的路由配置，支持热更新和代码转换。
+ *
+ * ## 功能特性
+ * - 自动扫描页面目录生成路由配置
+ * - 支持热模块替换（HMR）
+ * - 自动移除 `definePage` 宏调用
+ * - 支持 TypeScript 类型定义生成
+ *
+ * @param options - 插件配置选项
+ * @returns Vite 插件实例
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import VitarxRouter from 'vitarx-router/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     VitarxRouter({
+ *       pages: 'src/pages',
+ *       pathStrategy: 'kebab',
+ *       dts: 'typed-router.d.ts'
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+export default function vitarxRouter(options?: RouterPluginOptions): Plugin;

package/dist/plugin-vite/plugin.js

@@ -0,0 +1,181 @@
+import { FileRouter, info, warn } from '../file-router/index.js';
+import { RESOLVED_ROUTES_ID, VIRTUAL_ROUTES_ID } from './constant.js';
+import { setupWatcher } from './watcher.js';
+/** 插件名称，用于日志输出和调试 */
+const PLUGIN_NAME = 'vite-plugin-vitarx-router';
+/**
+ * 创建插件初始状态
+ *
+ * 工厂函数，用于创建干净的插件状态对象
+ *
+ * @returns 初始化的插件状态对象
+ */
+function createInitialState() {
+    return {
+        router: null,
+        isPreview: false,
+        watcherHandler: null
+    };
+}
+/**
+ * 创建 Vitarx Router Vite 插件
+ *
+ * 这是插件的主入口函数，返回一个标准的 Vite 插件对象。
+ * 插件通过虚拟模块提供自动生成的路由配置，支持热更新和代码转换。
+ *
+ * ## 功能特性
+ * - 自动扫描页面目录生成路由配置
+ * - 支持热模块替换（HMR）
+ * - 自动移除 `definePage` 宏调用
+ * - 支持 TypeScript 类型定义生成
+ *
+ * @param options - 插件配置选项
+ * @returns Vite 插件实例
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import VitarxRouter from 'vitarx-router/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     VitarxRouter({
+ *       pages: 'src/pages',
+ *       pathStrategy: 'kebab',
+ *       dts: 'typed-router.d.ts'
+ *     })
+ *   ]
+ * })
+ * ```
+ */
+export default function vitarxRouter(options = {}) {
+    const state = createInitialState();
+    return {
+        name: PLUGIN_NAME,
+        /**
+         * 配置钩子
+         *
+         * 在 Vite 解析配置前调用，用于识别是否为预览模式。
+         * 预览模式下插件不执行任何操作，因为路由已在构建时生成。
+         *
+         * @param _config - Vite 配置对象（未使用）
+         * @param env - 环境配置，包含命令模式和模式名称
+         */
+        config(_config, env) {
+            state.isPreview = !!env.isPreview;
+        },
+        /**
+         * 配置解析完成钩子
+         *
+         * 在 Vite 配置解析完成后调用，此时可以访问完整的配置。
+         * 用于创建 FileRouter 实例，初始化路由扫描。
+         *
+         * @throws 当 FileRouter 创建失败时抛出错误
+         */
+        async configResolved() {
+            if (state.isPreview)
+                return;
+            try {
+                state.router = new FileRouter(options);
+                info(`✨ File Router Manager created`);
+            }
+            catch (error) {
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                warn(`Failed to create FileRouter: ${errorMessage}`);
+                throw error;
+            }
+        },
+        /**
+         * 模块 ID 解析钩子
+         *
+         * 用于解析虚拟模块 ID，将 `virtual:vitarx-router:routes`
+         * 转换为内部使用的 `\0virtual:vitarx-router:routes`。
+         *
+         * @param id - 模块 ID
+         * @returns 解析后的模块 ID，不匹配则返回 null
+         */
+        resolveId(id) {
+            if (id === VIRTUAL_ROUTES_ID) {
+                return RESOLVED_ROUTES_ID;
+            }
+            return null;
+        },
+        /**
+         * 模块加载钩子
+         *
+         * 加载虚拟模块内容，生成路由配置代码。
+         * 返回的代码会被 Vite 作为模块内容使用。
+         *
+         * @param id - 模块 ID
+         * @returns 模块内容，不匹配则返回 null
+         * @throws 当路由生成失败时抛出错误
+         */
+        load(id) {
+            if (!state.router)
+                return null;
+            if (id !== RESOLVED_ROUTES_ID)
+                return null;
+            return state.router.generate().code;
+        },
+        /**
+         * 代码转换钩子
+         *
+         * 转换页面文件代码，移除 `definePage` 宏调用。
+         * `definePage` 作为全局宏使用，无需导入，构建时需要移除。
+         *
+         * @param code - 源代码
+         * @param id - 文件路径
+         * @returns 转换后的代码，无需转换则返回 null
+         */
+        transform(code, id) {
+            if (!state.router)
+                return null;
+            try {
+                return state.router.removeDefinePage(code, id);
+            }
+            catch (error) {
+                warn(`Failed to transform ${id}:`, error);
+                return null;
+            }
+        },
+        /**
+         * 配置开发服务器钩子
+         *
+         * 配置开发服务器的文件监听，实现热更新功能。
+         * 当页面文件发生变化时，自动更新路由配置并触发 HMR。
+         *
+         * @param server - Vite 开发服务器实例
+         */
+        configureServer(server) {
+            if (!state.router)
+                return;
+            const router = state.router;
+            state.watcherHandler = setupWatcher(state.router, server, (event, file) => {
+                try {
+                    const mod = server.moduleGraph.getModuleById(RESOLVED_ROUTES_ID);
+                    if (!mod)
+                        return;
+                    const isRouteAffected = router.handleChange(event, file);
+                    if (isRouteAffected) {
+                        server.moduleGraph.invalidateModule(mod);
+                    }
+                }
+                catch (error) {
+                    warn(`Failed to handle file change for ${file}:`, error);
+                }
+            });
+        },
+        /**
+         * 构建结束钩子
+         *
+         * 在构建结束时清理资源，防止内存泄漏。
+         * 清理文件监听器引用和路由管理器实例。
+         */
+        closeBundle() {
+            if (state.watcherHandler) {
+                state.watcherHandler = null;
+            }
+            state.router = null;
+        }
+    };
+}

package/dist/plugin-vite/watcher.d.ts

@@ -0,0 +1,15 @@
+import type { ViteDevServer } from 'vite';
+import { FileRouter, type FileWatcherEvent } from '../file-router/index.js';
+/**
+ * 设置文件监听器
+ *
+ * 为开发服务器配置文件监听，监听页面目录下的文件变化。
+ * 当文件发生变化时，自动更新路由配置并触发 HMR。
+ *
+ * @param router - 文件路由管理器实例
+ * @param server - Vite 开发服务器实例
+ * @param handleFileChange - 文件变化处理函数
+ * @param delay - 节流延迟时间（毫秒）
+ * @returns 文件监听器处理函数，用于后续清理
+ */
+export declare function setupWatcher(router: FileRouter, server: ViteDevServer, handleFileChange: (event: FileWatcherEvent, file: string) => void, delay?: number): (event: FileWatcherEvent, file: string) => void;

package/dist/plugin-vite/watcher.js

@@ -0,0 +1,65 @@
+/**
+ * 创建批量节流处理函数
+ *
+ * 在指定时间窗口内收集所有变化事件，然后批量处理。
+ * 同一文件的多次变更会被合并，只保留最后一次事件。
+ * 这可以避免在短时间内多次触发路由重新生成，同时确保
+ * 所有文件变化都被正确处理，不会丢失任何更新。
+ *
+ * @param callback - 需要节流的回调函数
+ * @param delay - 节流延迟时间（毫秒）
+ * @returns 节流后的处理函数
+ *
+ * @example
+ * ```typescript
+ * const batchHandler = createBatchThrottledHandler(
+ *   (event, file) => console.log(event, file),
+ *   100
+ * )
+ *
+ * // 快速调用多次，同文件变更会被合并
+ * batchHandler('change', 'a.ts')
+ * batchHandler('change', 'b.ts')
+ * batchHandler('unlink', 'a.ts')  // 覆盖之前的 a.ts change
+ * // 100ms 后，只处理 a.ts unlink 和 b.ts change
+ * ```
+ */
+function createBatchThrottledHandler(callback, delay) {
+    let pending = false;
+    const pendingChanges = new Map();
+    return (event, file) => {
+        pendingChanges.set(file, event);
+        if (pending)
+            return;
+        pending = true;
+        setTimeout(() => {
+            pending = false;
+            const changes = new Map(pendingChanges);
+            pendingChanges.clear();
+            for (const [f, e] of changes) {
+                callback(e, f);
+            }
+        }, delay);
+    };
+}
+/**
+ * 设置文件监听器
+ *
+ * 为开发服务器配置文件监听，监听页面目录下的文件变化。
+ * 当文件发生变化时，自动更新路由配置并触发 HMR。
+ *
+ * @param router - 文件路由管理器实例
+ * @param server - Vite 开发服务器实例
+ * @param handleFileChange - 文件变化处理函数
+ * @param delay - 节流延迟时间（毫秒）
+ * @returns 文件监听器处理函数，用于后续清理
+ */
+export function setupWatcher(router, server, handleFileChange, delay = 100) {
+    const pagesDirs = router.config.pages;
+    for (const dirConfig of pagesDirs) {
+        server.watcher.add(dirConfig.dir);
+    }
+    const handler = createBatchThrottledHandler(handleFileChange, delay);
+    server.watcher.on('all', handler);
+    return handler;
+}