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

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

@@ -1,344 +0,0 @@
-/**
- * @fileoverview 类型定义模块
- *
- * 定义文件路由功能所需的所有 TypeScript 类型接口。
- * 这些类型用于描述页面配置、解析结果、路由生成等各个环节的数据结构。
- */
-import type { NavOptions, RouteMetaData } from '../core/index.js';
-/**
- * 页面配置选项
- *
- * 用于 definePage 宏函数，允许开发者在页面组件中自定义路由配置。
- * 仅支持可序列化的配置项。
- *
- * @example
- * ```tsx
- * import { definePage } from 'vitarx-router/auto-routes'
- *
- * definePage({
- *   name: 'user-detail',
- *   meta: { title: '用户详情', requiresAuth: true },
- *   redirect: '/login',
- *   pattern: { id: /^\d+$/ }
- * })
- *
- * export default function UserDetail() {
- *   return <div>User Detail</div>
- * }
- * ```
- */
-export interface PageOptions {
-    /** 自定义路由名称，优先级高于自动生成的名称 */
-    name?: string;
-    /**
-     * 路由元数据，可存储标题、权限等自定义信息
-     *
-     * 注意：meta 必须是可序列化的对象，不支持函数或复杂对象。
-     */
-    meta?: RouteMetaData;
-    /**
-     * 动态参数匹配模式
-     *
-     * 用于为动态路由参数定义更精确的匹配规则。
-     * 键为参数名，值为正则表达式。
-     *
-     * @example
-     * ```typescript
-     * definePage({
-     *   pattern: {
-     *     id: /^\d+$/,           // 匹配纯数字
-     *     slug: /^[a-z-]+$/      // 匹配小写字母和横线
-     *   }
-     * })
-     * ```
-     */
-    pattern?: Record<string, RegExp>;
-    /**
-     * 路由重定向目标
-     *
-     * 支持字符串路径或导航配置对象。
-     *
-     * @example
-     * ```TypeScript
-     * // 字符串路径
-     * definePage({ redirect: '/dashboard' })
-     *
-     * // 导航配置对象
-     * definePage({ redirect: { index: 'home', query: { from: 'old' } } })
-     * ```
-     */
-    redirect?: string | RedirectConfig;
-    /**
-     * 路由的别名，用于匹配多个路径到同一个路由
-     */
-    alias?: string | string[];
-}
-/**
- * 重定向配置对象
- *
- * 与 NavigateOptions 类似，但仅包含可序列化的属性。
- */
-export interface RedirectConfig {
-    /** 路由索引，/开头为路径，否则为名称 */
-    index: string;
-    /** URL 查询参数 */
-    query?: Record<string, string>;
-    /** 路由参数 */
-    params?: Record<string, string>;
-}
-/**
- * 解析后的页面信息
- *
- * 由 parsePageFile 函数生成，包含从文件路径解析出的所有路由相关信息。
- * 这是路由生成流程中的核心数据结构。
- */
-export interface ParsedPage {
-    /** 路由路径，如 '/', '/user', '/user/{id}' */
-    path: string;
-    /** 文件绝对路径 */
-    filePath: string;
-    /** 路由名称，用于编程式导航 */
-    name: string;
-    /** 动态参数名称列表 */
-    params: string[];
-    /** 是否为索引页面（index.tsx） */
-    isIndex: boolean;
-    /** 是否包含动态参数 */
-    isDynamic: boolean;
-    /** 子路由列表 */
-    children: ParsedPage[];
-    /** 路由元数据 */
-    meta?: RouteMetaData;
-    /** 自定义路由名称（通过 definePage 设置） */
-    customName?: string;
-    /** 动态参数匹配模式 */
-    pattern?: Record<string, RegExp>;
-    /** 父级路径 */
-    parentPath: string;
-    /** 路由重定向目标 */
-    redirect?: string | RedirectConfig;
-    /** 路由别名 */
-    alias?: string | string[];
-    /**
-     * 是否为布局文件
-     * 当同名文件和目录同时存在时，文件作为布局组件
-     */
-    isLayoutFile?: boolean;
-    /**
-     * 布局文件路径
-     * 当目录有同名文件时，记录布局文件的路径
-     */
-    layoutFilePath?: string;
-    /**
-     * 命名视图名称
-     * 从文件名解析，如 index@aux.tsx -> aux
-     * 默认为 null，表示默认视图
-     */
-    viewName?: string | null;
-    /**
-     * 命名视图映射
-     * 键为视图名称，值为文件路径
-     */
-    namedViews?: Record<string, string>;
-}
-/**
- * 解析后的路由配置
- *
- * 用于代码生成阶段的中间数据结构，表示一个完整的路由记录。
- */
-export interface ResolvedRoute {
-    /** 路由路径 */
-    path: string;
-    /** 路由名称（分组路由无此属性） */
-    name?: string;
-    /**
-     * 组件文件路径
-     * - 单一组件：字符串形式，如 `/src/pages/index.tsx`
-     * - 命名视图：对象形式，如 `{ default: '/src/pages/index.tsx', sidebar: '/src/pages/index@sidebar.tsx' }`
-     * 注意：这里存储的是文件路径，在代码生成阶段才根据 importMode 转换为代码
-     */
-    component?: string | Record<string, string>;
-    /** 路由元数据 */
-    meta?: RouteMetaData;
-    /** 动态参数匹配模式 */
-    pattern?: Record<string, RegExp>;
-    /** 子路由列表 */
-    children?: ResolvedRoute[];
-    /**
-     * 路由重定向目标
-     */
-    redirect?: string | NavOptions;
-    /**
-     * 路由别名
-     */
-    alias?: string | string[];
-}
-/**
- * 路由扩展钩子
- *
- * 在生成路由配置时调用，允许开发者自定义扩展路由配置。
- * 支持异步操作，可以用于动态获取路由配置。
- *
- * @param route - 解析后的路由配置
- * @returns 扩展后的路由配置或 void（表示不修改）
- *
- * @example
- * ```typescript
- * extendRoute: async (route) => {
- *   const permissions = await fetchPermissions(route.path)
- *   route.meta = { ...route.meta, permissions }
- *   return route
- * }
- * ```
- */
-export type ExtendRouteHook = (route: ResolvedRoute) => ResolvedRoute | void | Promise<ResolvedRoute | void>;
-/**
- * 页面目录配置项
- *
- * 用于配置多个页面目录时，可以为每个目录指定独立的包含/排除规则。
- *
- * @example
- * ```typescript
- * const pagesDirs: PagesDirConfig[] = [
- *   { dir: 'src/pages', exclude: ['components'] },
- *   { dir: 'src/admin', include: ['**\/*.tsx'], prefix: '/admin' }
- * ]
- * ```
- */
-export interface PageConfig {
-    /** 页面目录路径 */
-    dir: string;
-    /**
-     * 要包含的文件/目录 glob 模式列表
-     *
-     * 默认匹配所有文件。只有匹配 include 模式的文件才会被扫描。
-     */
-    include?: string[];
-    /** 要排除的文件/目录 glob 模式列表 */
-    exclude?: string[];
-    /**
-     * 路由路径前缀
-     *
-     * 用于为该目录下的所有路由添加统一的前缀。
-     *
-     * 拼接规则：
-     * 1. 前缀不以 / 开头时，自动添加 / 前缀
-     * 2. 直接拼接前缀和路径（去掉路径开头的 /）
-     *
-     * @default ''
-     *
-     * @example
-     * ```typescript
-     * // src/admin/home.tsx -> /admin/home（需要指定结尾的 /）
-     * { dir: 'src/admin', prefix: '/admin/' }
-     *
-     * // src/admin/home.tsx -> /adminhome（不指定结尾的 / 会直接拼接）
-     * { dir: 'src/admin', prefix: '/admin' }
-     *
-     * // src/promos/black-friday.vue -> /promos-black-friday
-     * { dir: 'src/promos', prefix: 'promos-' }
-     * ```
-     */
-    prefix?: string;
-}
-/**
- * 组件导入模式
- *
- * - `lazy`: 使用 lazy(() => import(...)) 懒加载组件
- * - `file`: 直接使用文件路径作为组件，由用户自行处理导入
- */
-export type ImportMode = 'lazy' | 'file';
-/**
- * 路由命名策略
- *
- * - `kebab`: 将驼峰命名转换为 kebab-case（默认），如 MainHome → main-home
- * - `lowercase`: 简单转换为小写，如 MainHome → mainhome
- * - `none`: 保持原始命名，不进行转换
- */
-export type NamingStrategy = 'kebab' | 'lowercase' | 'none';
-/**
- * 文件路由配置选项（与构建工具无关）
- *
- * 用于配置文件路由的核心行为。
- *
- * @example
- * ```typescript
- * // 基本使用
- * const options: FileRouterOptions = {
- *   pagesDir: 'src/views',
- *   extensions: ['.tsx', '.ts', '.vue'],
- * }
- *
- * // 多个目录
- * const options: FileRouterOptions = {
- *   pagesDir: ['src/pages', 'src/admin']
- * }
- *
- * // 多个目录，每个目录独立配置
- * const options: FileRouterOptions = {
- *   pagesDir: [
- *     { dir: 'src/pages', exclude: ['components'] },
- *     { dir: 'src/admin', include: ['**\/*.tsx'] }
- *   ]
- * }
- * ```
- */
-export interface FileRouterOptions {
-    /**
-     * 项目根目录
-     *
-     * 用于解析相对路径。
-     *
-     * @default process.cwd()
-     */
-    root?: string;
-    /**
-     * 页面目录配置
-     *
-     * 支持四种配置方式：
-     * 1. 字符串：单个页面目录路径
-     * 2. 对象：单个页面目录配置，可以有独立的 include/exclude 规则
-     * 3. 字符串数组：多个页面目录路径，使用全局 include/exclude 规则
-     * 4. 对象数组：多个页面目录，每个目录可以有独立的 include/exclude 规则
-     *
-     * @default 'src/pages'
-     */
-    pages?: string | PageConfig | (PageConfig | string)[];
-    /**
-     * 路由前缀
-     */
-    prefix?: string;
-    /** 支持的文件扩展名，默认为 ['.tsx', '.ts', '.jsx', '.js'] */
-    extensions?: string[];
-    /**
-     * 要包含的文件/目录 glob 模式列表，默认匹配所有文件
-     */
-    include?: string[];
-    /**
-     * 要排除的文件/目录 glob 模式列表
-     */
-    exclude?: string[];
-    /**
-     * 组件导入模式
-     *
-     * - `lazy`: 使用 lazy(() => import(...)) 懒加载组件（默认）
-     * - `file`: 直接使用文件路径作为组件，由用户自行处理导入
-     *
-     * @default 'lazy'
-     */
-    importMode?: ImportMode;
-    /**
-     * 路由扩展钩子
-     */
-    extendRoute?: ExtendRouteHook;
-    /**
-     * 注入自定义导入语句
-     */
-    injectImports?: string[];
-    /**
-     * 路由命名策略
-     *
-     * @default 'kebab'
-     */
-    namingStrategy?: NamingStrategy;
-}

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

@@ -1,57 +0,0 @@
-/**
- * @fileoverview 命名策略工具模块
- *
- * 提供路由名称和路径的命名转换功能，支持三种策略：
- * - kebab: 将驼峰命名转换为 kebab-case（默认）
- * - lowercase: 简单转换为小写
- * - none: 保持原始命名
- *
- * 注意：只处理路径段名称，不处理动态参数变量名。
- */
-import type { NamingStrategy } from '../types.js';
-/**
- * 应用命名策略转换字符串
- *
- * @param str - 输入字符串
- * @param strategy - 命名策略
- * @returns 转换后的字符串
- *
- * @example
- * ```typescript
- * applyNamingStrategy('MainHome', 'kebab')     // => 'main-home'
- * applyNamingStrategy('MainHome', 'lowercase') // => 'mainhome'
- * applyNamingStrategy('MainHome', 'none')      // => 'MainHome'
- * ```
- */
-export declare function applyNamingStrategy(str: string, strategy: NamingStrategy): string;
-/**
- * 应用命名策略转换路由路径
- *
- * 只处理路径段名称，不处理动态参数变量名。
- *
- * @param path - 路由路径
- * @param strategy - 命名策略
- * @returns 转换后的路径
- *
- * @example
- * ```typescript
- * applyNamingStrategyToPath('/MainHome', 'kebab')     // => '/main-home'
- * applyNamingStrategyToPath('/User/{userName}', 'kebab')  // => '/user/{userName}'
- * applyNamingStrategyToPath('/API/UserProfile', 'kebab')  // => '/api/user-profile'
- * ```
- */
-export declare function applyNamingStrategyToPath(path: string, strategy: NamingStrategy): string;
-/**
- * 应用命名策略转换路由名称
- *
- * @param name - 路由名称
- * @param strategy - 命名策略
- * @returns 转换后的名称
- *
- * @example
- * ```typescript
- * applyNamingStrategyToName('MainHome', 'kebab')     // => 'main-home'
- * applyNamingStrategyToName('user-MainHome', 'kebab')  // => 'user-main-home'
- * ```
- */
-export declare function applyNamingStrategyToName(name: string, strategy: NamingStrategy): string;

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

@@ -1,233 +0,0 @@
-/**
- * 验证 pages 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validatePagesDir(opts) {
-    if (opts.pages === undefined)
-        return;
-    if (typeof opts.pages === 'string') {
-        if (opts.pages.trim() === '') {
-            throw new Error('options.pagesDir 不能为空字符串');
-        }
-        return;
-    }
-    if (Array.isArray(opts.pages)) {
-        if (opts.pages.length === 0) {
-            throw new Error('options.pagesDir 数组不能为空');
-        }
-        opts.pages.forEach((item, i) => {
-            validatePagesDirItem(item, i);
-        });
-        return;
-    }
-    throw new Error('options.pagesDir 必须是字符串、字符串数组或对象数组');
-}
-/**
- * 验证 pages 数组中的单个项目
- *
- * @param item - 数组项
- * @param index - 数组索引
- * @throws {Error} 当配置无效时抛出错误
- */
-function validatePagesDirItem(item, index) {
-    if (typeof item === 'string') {
-        if (item.trim() === '') {
-            throw new Error(`options.pagesDir[${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 必须是非空字符串`);
-        }
-        if (config.include !== undefined && !Array.isArray(config.include)) {
-            throw new Error(`options.pagesDir[${index}].include 必须是数组`);
-        }
-        if (config.exclude !== undefined && !Array.isArray(config.exclude)) {
-            throw new Error(`options.pagesDir[${index}].exclude 必须是数组`);
-        }
-        return;
-    }
-    throw new Error(`options.pagesDir[${index}] 必须是字符串或对象`);
-}
-/**
- * 验证 extensions 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateExtensions(opts) {
-    if (opts.extensions === undefined)
-        return;
-    if (!Array.isArray(opts.extensions)) {
-        throw new Error('options.extensions 必须是数组');
-    }
-    if (opts.extensions.length === 0) {
-        throw new Error('options.extensions 数组不能为空');
-    }
-    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 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateInclude(opts) {
-    if (opts.include === undefined)
-        return;
-    if (!Array.isArray(opts.include)) {
-        throw new Error('options.include 必须是数组');
-    }
-    opts.include.forEach((item, i) => {
-        if (typeof item !== 'string') {
-            throw new Error(`options.include[${i}] 必须是字符串`);
-        }
-    });
-}
-/**
- * 验证 exclude 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateExclude(opts) {
-    if (opts.exclude === undefined)
-        return;
-    if (!Array.isArray(opts.exclude)) {
-        throw new Error('options.exclude 必须是数组');
-    }
-    opts.exclude.forEach((item, i) => {
-        if (typeof item !== 'string') {
-            throw new Error(`options.exclude[${i}] 必须是字符串`);
-        }
-    });
-}
-/**
- * 验证 root 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateRoot(opts) {
-    if (opts.root === undefined)
-        return;
-    if (typeof opts.root !== 'string') {
-        throw new Error('options.root 必须是字符串');
-    }
-    if (opts.root.trim() === '') {
-        throw new Error('options.root 不能为空字符串');
-    }
-}
-/**
- * 验证 prefix 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validatePrefix(opts) {
-    if (opts.prefix === undefined)
-        return;
-    if (typeof opts.prefix !== 'string') {
-        throw new Error('options.prefix 必须是字符串');
-    }
-}
-/**
- * 验证 importMode 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateImportMode(opts) {
-    if (opts.importMode === undefined)
-        return;
-    const validModes = ['lazy', 'file'];
-    if (!validModes.includes(opts.importMode)) {
-        throw new Error(`options.importMode 必须是 'lazy' 或 'file'`);
-    }
-}
-/**
- * 验证 extendRoute 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateExtendRoute(opts) {
-    if (opts.extendRoute === undefined)
-        return;
-    if (typeof opts.extendRoute !== 'function') {
-        throw new Error('options.extendRoute 必须是函数');
-    }
-}
-/**
- * 验证 injectImports 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateInjectImports(opts) {
-    if (opts.injectImports === undefined)
-        return;
-    if (!Array.isArray(opts.injectImports)) {
-        throw new Error('options.injectImports 必须是数组');
-    }
-    opts.injectImports.forEach((imp, i) => {
-        if (typeof imp !== 'string') {
-            throw new Error(`options.injectImports[${i}] 必须是字符串`);
-        }
-    });
-}
-/**
- * 验证 namingStrategy 配置
- *
- * @param opts - 配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-function validateNamingStrategy(opts) {
-    if (opts.namingStrategy === undefined)
-        return;
-    const validStrategies = ['kebab', 'lowercase', 'none'];
-    if (!validStrategies.includes(opts.namingStrategy)) {
-        throw new Error(`options.namingStrategy 必须是 'kebab'、'lowercase' 或 'none'`);
-    }
-}
-/**
- * 验证插件配置选项
- *
- * 验证顺序：
- * 1. root 配置
- * 2. prefix 配置
- * 3. pages 配置
- * 4. extensions 配置
- * 5. include 配置
- * 6. exclude 配置
- * 7. importMode 配置
- * 8. extendRoute 配置
- * 9. injectImports 配置
- * 10. namingStrategy 配置
- *
- * @param opts - 用户提供的配置选项
- * @throws {Error} 当配置无效时抛出错误
- */
-export function validateOptions(opts) {
-    validateRoot(opts);
-    validatePrefix(opts);
-    validatePagesDir(opts);
-    validateExtensions(opts);
-    validateInclude(opts);
-    validateExclude(opts);
-    validateImportMode(opts);
-    validateExtendRoute(opts);
-    validateInjectImports(opts);
-    validateNamingStrategy(opts);
-}