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

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,36 +4,67 @@
  * 负责将解析后的页面信息转换为可执行的路由配置代码。
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
-import type { ExtendRouteHook, ImportMode, NamingStrategy, ParsedPage } from '../types.js';
+import type { BeforeWriteRoutesHook, ExtendRouteHook, ImportMode, RouteNode, ScanNode } from '../types/index.js';
 /**
  * 路由生成选项
  */
 export interface GenerateRoutesOptions {
+    /**
+     * 是否生成类型代码
+     */
+    dts: boolean;
     /**
      * 组件导入模式
      * - `lazy`: 使用 lazy(() => import(...)) 懒加载组件
      * - `file`: 直接使用文件路径作为组件
      */
-    importMode?: ImportMode;
+    importMode: ImportMode;
     /**
      * 路由扩展钩子
      * 在生成每个路由配置时调用，允许开发者自定义扩展路由配置
      */
     extendRoute?: ExtendRouteHook;
     /**
-     * 自定义导入语句
-     * 允许向虚拟模块注入自定义的导入语句
+     * 路由写入前钩子
+     * 在生成路由代码前调用，允许开发者自定义路由配置
      */
-    imports?: string[];
+    beforeWriteRoutes?: BeforeWriteRoutesHook;
     /**
-     * 路由命名策略
-     * - `kebab`: 将驼峰命名转换为 kebab-case（默认）
-     * - `lowercase`: 简单转换为小写
-     * - `none`: 保持原始命名
-     * @default 'kebab'
+     * 自定义导入语句
+     * 允许向虚拟模块注入自定义的导入语句
      */
-    namingStrategy?: NamingStrategy;
+    imports?: readonly string[];
 }
+export interface GenerateResult {
+    routes: RouteNode[];
+    code: string;
+    dts: string;
+}
+/**
+ * 根据绝对路径生成一个唯一的名称
+ *
+ * @param absolutePath
+ */
+export declare function pathToUniqueName(absolutePath: string): string;
+/**
+ * 构建解析后的路由配置列表
+ *
+ * @param pages - 页面列表
+ * @param extendRoute - 路由扩展钩子
+ * @param parent - 父路由
+ * @returns 路由配置列表
+ */
+export declare function buildRoutes(pages: Iterable<ScanNode>, extendRoute?: ExtendRouteHook, parent?: RouteNode): RouteNode[];
+/**
+ * 生成路由代码字符串
+ *
+ * @param routes - 路由配置列表
+ * @param importMode - 导入模式
+ * @param customImports - 自定义导入语句
+ * @param indent - 缩进字符串
+ * @returns {string} 完整的路由模块代码
+ */
+export declare function generateRoutesCode(routes: RouteNode[], importMode?: ImportMode, customImports?: readonly string[], indent?: string): string;
 /**
  * 生成路由配置代码
  *
@@ -41,6 +72,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: ScanNode[], options: GenerateRoutesOptions): GenerateResult;

package/dist/file-router/generator/generateRoutes.js

@@ -1,59 +1,111 @@
+/**
+ * @fileoverview 路由代码生成模块
+ *
+ * 负责将解析后的页面信息转换为可执行的路由配置代码。
+ * 与构建工具无关，可在任何 Node.js 环境中使用。
+ */
+import { createHash } from 'node:crypto';
+import { normalizeRoutePath } from '../utils/index.js';
+import { generateDtsCode } from './generateTypes.js';
+const IMPORT_QUOTE_REGEX = /from\s+(['"])([^'"]*)\1/g;
+const IMPORT_NORMALIZE_REGEX = /\s+/g;
+/**
+ * 规范化导入语句
+ *
+ * @param statement
+ */
+function normalizeImportStatement(statement) {
+    let result = statement.trim();
+    result = result.replace(IMPORT_QUOTE_REGEX, 'from "$2"');
+    result = result.replace(IMPORT_NORMALIZE_REGEX, ' ');
+    result = result.replace(/import\s*\{/g, 'import {');
+    result = result.replace(/}\s*from/g, '} from');
+    return result;
+}
+/**
+ * 根据绝对路径生成一个唯一的名称
+ *
+ * @param absolutePath
+ */
+export function pathToUniqueName(absolutePath) {
+    // md5 碰撞概率在现实场景中为 0，且生成速度极快
+    const hash = createHash('md5').update(absolutePath).digest('hex');
+    // 加上 '_' 前缀，因为 hash 结果可能是数字开头（如 '1a2b3c...'），
+    // 数字开头的标识符在 JS 中不能直接作为变量名。
+    return `_${hash}`;
+}
+/**
+ * 生成路由名称
+ *
+ * @returns 路由名称
+ */
+function generateRouteName(fullPath) {
+    return (fullPath
+        // 1. 去除首尾斜杠
+        .replace(/^\/+|\/+$/g, '')
+        // 2. 直接删除花括号和问号（不替换为-，保护静态路径的连续中划线）
+        .replace(/[{}?]/g, '')
+        // 3. 仅将斜杠替换为中划线
+        .replace(/\//g, '-'));
+}
 /**
  * 构建单个路由配置
  *
  * @param page - 页面信息
- * @param options - 生成选项
+ * @param parent
+ * @param extendRoute - 路由扩展钩子
  * @returns 解析后的路由配置
  */
-async function buildResolvedRoute(page, options) {
-    const { extendRoute } = options;
+function buildRouteNode(page, extendRoute, parent) {
     // 创建基础路由配置
     const route = {
-        path: page.path
+        isGroup: page.isGroup,
+        filePath: page.filePath,
+        path: page.path,
+        fullPath: normalizeRoutePath(parent ? `${parent.fullPath}/${page.path}` : page.path)
     };
     // 处理组件配置
-    if (page.filePath && page.filePath.trim() !== '') {
-        if (page.namedViews) {
-            // 处理命名视图
-            const components = {
-                default: JSON.stringify(page.filePath)
-            };
-            for (const [viewName, viewPath] of Object.entries(page.namedViews)) {
-                components[viewName] = JSON.stringify(viewPath);
-            }
-            route.component = components;
+    if (page.components) {
+        // 处理命名视图
+        const components = {
+            default: JSON.stringify(page.filePath)
+        };
+        for (const [viewName, viewPath] of Object.entries(page.components)) {
+            components[viewName] = viewPath;
         }
-        else {
-            // 处理普通组件
-            route.component = JSON.stringify(page.filePath);
-        }
-    }
-    // 处理其他路由配置
-    if (page.meta && Object.keys(page.meta).length > 0) {
-        route.meta = page.meta;
-    }
-    if (page.pattern && Object.keys(page.pattern).length > 0) {
-        route.pattern = page.pattern;
+        route.component = components;
     }
-    if (page.redirect !== undefined) {
-        route.redirect = page.redirect;
-    }
-    if (page.alias !== undefined) {
-        route.alias = page.alias;
+    // 处理路由配置
+    if (page.options) {
+        const { name, meta, pattern, redirect, alias } = page.options;
+        if (name?.trim()) {
+            route.name = name;
+        }
+        // 处理其他路由配置
+        if (meta && Object.keys(meta).length > 0) {
+            route.meta = { ...meta };
+        }
+        if (pattern && Object.keys(pattern).length > 0) {
+            route.pattern = { ...pattern };
+        }
+        if (redirect !== undefined) {
+            route.redirect = typeof redirect === 'object' ? { ...redirect } : redirect;
+        }
+        if (alias !== undefined) {
+            route.alias = Array.isArray(alias) ? Array.from(alias) : alias;
+        }
     }
-    if (page.children.length > 0) {
+    // 应用路由扩展钩子
+    if (extendRoute)
+        extendRoute(route);
+    // 处理子路由
+    if (page.children && page.children.size > 0) {
         // 递归处理子路由
-        route.children = await buildResolvedRoutes(page.children, options);
+        route.children = buildRoutes(page.children.values(), extendRoute, route);
     }
-    // 为叶子路由或重定向路由添加名称
-    if (page.children.length === 0 || page.redirect !== undefined) {
-        route.name = page.name;
-    }
-    // 应用路由扩展钩子
-    if (extendRoute) {
-        const result = await extendRoute(route);
-        if (result)
-            return result;
+    // 动态路由不存在name时生成一个name
+    if (!route.name && route.fullPath.includes('{')) {
+        route.name = generateRouteName(route.fullPath);
     }
     return route;
 }
@@ -61,33 +113,59 @@ async function buildResolvedRoute(page, options) {
  * 构建解析后的路由配置列表
  *
  * @param pages - 页面列表
- * @param options - 生成选项
+ * @param extendRoute - 路由扩展钩子
+ * @param parent - 父路由
  * @returns 路由配置列表
  */
-async function buildResolvedRoutes(pages, options) {
+export function buildRoutes(pages, extendRoute, parent) {
     const routes = [];
     for (const page of pages) {
-        const route = await buildResolvedRoute(page, options);
+        const route = buildRouteNode(page, extendRoute, parent);
         routes.push(route);
     }
     return routes;
 }
+/**
+ * 解析组件导入表达式
+ *
+ * @param file - 组件文件路径
+ * @param importPath - JSON.stringify 后的文件路径
+ * @param mode - 解析后的导入模式（'lazy' | 'sync' | 自定义表达式）
+ * @param importLines - 导入语句集合
+ * @returns 组件表达式代码
+ */
+function resolveComponentExpr(file, importPath, mode, importLines) {
+    if (mode === 'sync') {
+        const expr = pathToUniqueName(file);
+        importLines.add(normalizeImportStatement(`import ${expr} from ${importPath}`));
+        return expr;
+    }
+    if (mode === 'lazy') {
+        importLines.add(normalizeImportStatement(`import { lazy } from 'vitarx'`));
+        return `lazy(() => import(${importPath}))`;
+    }
+    return mode;
+}
 /**
  * 格式化组件表达式
  *
  * @param component - 组件路径或命名视图映射
  * @param importMode - 导入模式
+ * @param importLines - 导入语句集合
  * @returns 格式化后的组件表达式代码
  */
-function formatComponent(component, importMode) {
-    if (typeof component === 'string') {
-        // 处理单个组件
-        return importMode === 'file' ? component : `lazy(() => import(${component}))`;
-    }
-    // 处理命名视图
-    const entries = Object.entries(component).map(([name, value]) => {
-        const expr = importMode === 'file' ? value : `lazy(() => import(${value}))`;
-        return `${name}: ${expr}`;
+function formatComponent(component, importMode, importLines) {
+    const entries = Object.entries(component).map(([name, file]) => {
+        const importPath = JSON.stringify(file);
+        const mode = typeof importMode === 'function'
+            ? importMode({
+                importPath,
+                filePath: file,
+                addImport: statement => importLines.add(normalizeImportStatement(statement))
+            })
+            : importMode;
+        const expr = resolveComponentExpr(file, importPath, mode, importLines);
+        return `${JSON.stringify(name)}: ${expr}`;
     });
     return `{ ${entries.join(', ')} }`;
 }
@@ -110,9 +188,10 @@ function generatePatternCode(pattern) {
  * @param indent - 缩进字符串
  * @param isLast - 是否为最后一个元素
  * @param importMode - 导入模式
+ * @param importLines - 导入语句集合
  * @returns 代码行数组
  */
-function generateRouteCode(route, indent, isLast, importMode) {
+function generateRouteCode(route, indent, isLast, importMode, importLines) {
     const lines = [];
     const comma = isLast ? '' : ',';
     // 开始路由对象
@@ -126,7 +205,7 @@ function generateRouteCode(route, indent, isLast, importMode) {
     // 添加组件配置
     if (route.component) {
         lines[lines.length - 1] += ',';
-        lines.push(`${indent}  component: ${formatComponent(route.component, importMode)}`);
+        lines.push(`${indent}  component: ${formatComponent(route.component, importMode, importLines)}`);
     }
     // 添加 meta 配置
     if (route.meta) {
@@ -155,7 +234,7 @@ function generateRouteCode(route, indent, isLast, importMode) {
         for (let i = 0; i < route.children.length; i++) {
             const child = route.children[i];
             // 递归生成子路由代码
-            lines.push(...generateRouteCode(child, indent + '    ', i === route.children.length - 1, importMode));
+            lines.push(...generateRouteCode(child, indent + '    ', i === route.children.length - 1, importMode, importLines));
         }
         lines.push(`${indent}  ]`);
     }
@@ -170,32 +249,25 @@ function generateRouteCode(route, indent, isLast, importMode) {
  * @param importMode - 导入模式
  * @param customImports - 自定义导入语句
  * @param indent - 缩进字符串
- * @returns 完整的路由模块代码
+ * @returns {string} 完整的路由模块代码
  */
-function generateRoutesCode(routes, importMode = 'lazy', customImports, indent = '  ') {
-    const lines = [];
-    // 添加 lazy 导入（如果需要）
-    if (importMode === 'lazy') {
-        lines.push(`import { lazy } from 'vitarx'`);
-    }
-    // 添加自定义导入语句
+export function generateRoutesCode(routes, importMode = 'lazy', customImports, indent = '  ') {
+    const importLines = new Set();
+    const codeLines = [];
     if (customImports && customImports.length > 0) {
-        for (const imp of customImports) {
-            lines.push(imp);
-        }
-    }
-    // 添加空行
-    if (importMode === 'lazy' || (customImports && customImports.length > 0)) {
-        lines.push('');
+        customImports.forEach(imp => importLines.add(normalizeImportStatement(imp)));
     }
-    // 生成路由数组
-    lines.push('export default [');
+    codeLines.push('export default [');
     for (let i = 0; i < routes.length; i++) {
         const route = routes[i];
-        lines.push(...generateRouteCode(route, indent, i === routes.length - 1, importMode));
+        codeLines.push(...generateRouteCode(route, indent, i === routes.length - 1, importMode, importLines));
     }
-    lines.push(']');
-    return lines.join('\n');
+    codeLines.push(']');
+    const allImports = Array.from(importLines.values());
+    if (allImports.length > 0) {
+        allImports.push('');
+    }
+    return allImports.concat(codeLines).join('\n');
 }
 /**
  * 生成路由配置代码
@@ -204,11 +276,18 @@ function generateRoutesCode(routes, importMode = 'lazy', customImports, indent =
  *
  * @param pages - 解析后的页面列表
  * @param options - 路由生成选项
- * @returns Promise 包含可执行路由配置代码字符串
+ * @returns { GenerateResult } 包含routes、code、dts的路由配置结果
  */
-export async function generateRoutes(pages, options = {}) {
+export function generateRoutes(pages, options) {
     // 构建解析后的路由配置
-    const routes = await buildResolvedRoutes(pages, options);
+    let routes = buildRoutes(pages, options.extendRoute);
+    if (options.beforeWriteRoutes) {
+        const result = options.beforeWriteRoutes(routes);
+        if (Array.isArray(result))
+            routes = result;
+    }
     // 生成最终的路由代码
-    return generateRoutesCode(routes, options.importMode, options.imports);
+    const code = generateRoutesCode(routes, options.importMode, options.imports);
+    const dts = options.dts ? generateDtsCode(routes) : '';
+    return { routes, code, dts };
 }

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

@@ -4,37 +4,11 @@
  * 负责生成路由的 TypeScript 类型定义，用于提供 IDE 类型提示和编译时类型检查。
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
-import type { ParsedPage } from '../types.js';
-/**
- * 路由索引映射表
- *
- * 将路由名称和路径映射到对应的类型信息。
- * 支持通过名称或路径两种方式进行类型安全的导航。
- *
- * @example
- * ```typescript
- * // 生成的类型示例
- * interface RouteIndexMap {
- *   'home': {},
- *   '/': {},
- *   'user-id': { params: { id: string } },
- *   '/user/{id}': { params: { id: string } }
- * }
- *
- * // 使用示例
- * router.push({ index: 'user-id', params: { id: '123' } })
- * ```
- */
-export interface ParsedRouteIndexMap {
-    [key: string]: {
-        /** 动态参数类型映射 */
-        params?: Record<string, string | number>;
-    };
-}
+import type { RouteNode } from '../types/index.js';
 /**
  * 生成完整的 .d.ts 声明文件内容
  *
- * @param pages - 解析后的页面列表
+ * @param routes - 解析后的页面列表
  * @returns 完整的 .d.ts 文件内容
  */
-export declare function generateFullDtsFile(pages: ParsedPage[]): string;
+export declare function generateDtsCode(routes: RouteNode[]): string;

package/dist/file-router/generator/generateTypes.js

@@ -1,3 +1,10 @@
+/**
+ * @fileoverview 类型生成模块
+ *
+ * 负责生成路由的 TypeScript 类型定义，用于提供 IDE 类型提示和编译时类型检查。
+ * 与构建工具无关，可在任何 Node.js 环境中使用。
+ */
+import { hasDynamicPath } from '../utils/index.js';
 /**
  * 从路径中提取动态参数
  *
@@ -13,26 +20,16 @@ function extractParamsFromPath(path) {
     }
     return params;
 }
-/**
- * 检查路径是否包含动态参数
- *
- * @param path - 路由路径
- * @returns 是否包含动态参数
- */
-function hasDynamicParams(path) {
-    return /\{[^}]+}/.test(path);
-}
 /**
  * 判断路由是否需要注册
  *
- * @param page - 页面信息
- * @returns 是否需要注册
+ * @param route - 路由信息
+ * @returns {boolean} 是否需要注册
  */
-function shouldRegisterRoute(page) {
-    const hasComponent = page.filePath && page.filePath.trim() !== '';
-    const hasChildren = page.children.length > 0;
-    const hasRedirect = page.redirect !== undefined;
-    return (hasComponent && !hasChildren) || hasRedirect;
+function shouldRegisterRoute(route) {
+    const isGroup = route.children?.length;
+    const hasRedirect = route.redirect !== undefined;
+    return !isGroup || hasRedirect;
 }
 /**
  * 解析 alias 路径
@@ -74,49 +71,47 @@ function formatRouteIndexEntry(key, value) {
  * 递归处理单个页面及其子页面
  *
  * @param map - 路由索引映射表
- * @param page - 页面信息
+ * @param route - 页面信息
  * @param parentFullPath - 父级完整路径
  */
-function processPage(map, page, parentFullPath = '') {
-    if (shouldRegisterRoute(page)) {
-        const params = extractParamsFromPath(page.path);
+function processPage(map, route, parentFullPath = '') {
+    const currentPath = route.fullPath;
+    if (shouldRegisterRoute(route)) {
+        const params = extractParamsFromPath(route.fullPath);
         const entry = params.length > 0
             ? { params: params.reduce((acc, p) => ({ ...acc, [p]: 'string | number' }), {}) }
             : {};
-        map[page.name] = entry;
-        if (!hasDynamicParams(page.path)) {
-            let fullPath = page.path;
-            if (page.path === '' && parentFullPath) {
-                fullPath = parentFullPath;
-            }
-            if (fullPath) {
-                map[fullPath] = entry;
-            }
+        // 命名路由
+        if (route.name)
+            map[route.name] = entry;
+        if (!hasDynamicPath(currentPath)) {
+            map[currentPath] = entry;
         }
-        if (page.alias) {
-            const aliases = Array.isArray(page.alias) ? page.alias : [page.alias];
+        if (route.alias) {
+            const aliases = Array.isArray(route.alias) ? route.alias : [route.alias];
             for (const alias of aliases) {
                 const aliasPath = resolveAliasPath(alias, parentFullPath);
-                if (aliasPath && !hasDynamicParams(aliasPath)) {
+                if (aliasPath && !hasDynamicPath(aliasPath)) {
                     map[aliasPath] = entry;
                 }
             }
         }
     }
-    const currentFullPath = page.path === '' ? parentFullPath : page.path || parentFullPath;
-    for (const child of page.children) {
-        processPage(map, child, currentFullPath);
+    if (route.children) {
+        for (const child of route.children) {
+            processPage(map, child, currentPath);
+        }
     }
 }
 /**
  * 构建路由索引映射表
  *
- * @param pages - 页面列表
+ * @param routes - 页面列表
  * @returns 路由索引映射表
  */
-function buildRouteIndexMap(pages) {
+function buildRouteIndexMap(routes) {
     const map = {};
-    for (const page of pages) {
+    for (const page of routes) {
         processPage(map, page);
     }
     return map;
@@ -124,12 +119,12 @@ function buildRouteIndexMap(pages) {
 /**
  * 生成完整的 .d.ts 声明文件内容
  *
- * @param pages - 解析后的页面列表
+ * @param routes - 解析后的页面列表
  * @returns 完整的 .d.ts 文件内容
  */
-export function generateFullDtsFile(pages) {
+export function generateDtsCode(routes) {
     const moduleName = 'vitarx-router';
-    const indexMap = buildRouteIndexMap(pages);
+    const indexMap = buildRouteIndexMap(routes);
     const lines = [];
     lines.push('/// <reference types="vitarx-router/global" />');
     lines.push('/* eslint-disable */');

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

@@ -19,7 +19,7 @@
  * /// <reference types="vitarx-router/global" />
  * ```
  */
-import type { PageOptions } from './types.js';
+import type { PageOptions } from './types/index.js';
 declare global {
     /**
      * 文件路由全局宏函数