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

package/dist/core/shared/route.js

@@ -20,8 +20,7 @@ export function useRoute(global = false) {
         return route;
     }
     const record = route.matched[depth];
-    if (!record) {
+    if (!record)
         return route;
-    }
     return createRouteProxy(route, record);
 }

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

@@ -1,4 +1,4 @@
-import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, ImportMode, PageDirOptions, PathStrategy } from '../types/index.js';
+import type { CodeTransformHook, ExtendRouteHook, FileRouterOptions, ImportMode, PageDirOptions, PathParser, PathStrategy } from '../types/index.js';
 export type PageDirConfig = Required<PageDirOptions>;
 /**
  * 规范化后的配置
@@ -14,6 +14,7 @@ export interface ResolvedConfig {
     configFileName: string;
     transform?: CodeTransformHook;
     extendRoute?: ExtendRouteHook;
+    pathParser?: PathParser;
 }
 /**
  * 规范化文件路由配置

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

@@ -56,7 +56,7 @@ function resolvePageConfigs(pages, root) {
  * @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 { dts = false, root = process.cwd(), pages = DEFAULT_PAGES_DIR, importMode = 'lazy', injectImports = [], pathStrategy = 'kebab', layoutFileName = DEFAULT_LAYOUT_FILE, configFileName = DEFAULT_CONFIG_FILE, transform, extendRoute, pathParser } = options;
     const resolvedPages = resolvePageConfigs(pages, root);
     return {
         dts: typeof dts === 'string' ? dts : dts ? DEFAULT_DTS_FILE : false,
@@ -68,6 +68,7 @@ export function resolveConfig(options) {
         layoutFileName,
         configFileName,
         transform,
-        extendRoute
+        extendRoute,
+        pathParser
     };
 }

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

@@ -19,6 +19,7 @@ import type { FileRouterOptions } from '../types/index.js';
  * 8. configFileName 配置
  * 9. transform 配置
  * 10. extendRoute 配置
+ * 11. pathParser 配置
  *
  * @param opts - 用户提供的配置选项
  * @throws {Error} 当配置无效时抛出错误

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

@@ -198,6 +198,19 @@ function validateExtendRoute(opts) {
         throw new Error('options.extendRoute 必须是函数');
     }
 }
+/**
+ * 验证 pathParser 配置
+ *
+ * @param opts - 配置选项
+ * @throws {Error} 当配置无效时抛出错误
+ */
+function validatePathParser(opts) {
+    if (opts.pathParser === undefined)
+        return;
+    if (typeof opts.pathParser !== 'function') {
+        throw new Error('options.pathParser 必须是函数');
+    }
+}
 /**
  * 验证插件配置选项
  *
@@ -212,6 +225,7 @@ function validateExtendRoute(opts) {
  * 8. configFileName 配置
  * 9. transform 配置
  * 10. extendRoute 配置
+ * 11. pathParser 配置
  *
  * @param opts - 用户提供的配置选项
  * @throws {Error} 当配置无效时抛出错误
@@ -227,4 +241,5 @@ export function validateOptions(opts) {
     validateConfigFileName(opts);
     validateTransform(opts);
     validateExtendRoute(opts);
+    validatePathParser(opts);
 }

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

@@ -126,7 +126,7 @@ function formatComponent(component, importMode, importLines) {
         else {
             expr = `lazy(() => import(${importPath}))`;
         }
-        return `${name}: ${expr}`;
+        return `${JSON.stringify(name)}: ${expr}`;
     });
     return `{ ${entries.join(', ')} }`;
 }

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

@@ -7,6 +7,7 @@
 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, ParsedNode } from './types/index.js';
 export type * from './types/index.js';
 export * from './utils/logger.js';
@@ -66,7 +67,6 @@ export declare class FileRouter {
     /**
      * 处理文件
      * @param filePath - 文件路径
-     * @param fileName - 文件名
      * @param page - 页面配置
      * @param pageMapping - 子路由
      * @param parent - 父节点
@@ -91,7 +91,6 @@ export declare class FileRouter {
      *
      * @param file - 文件绝对路径
      * @param name - 文件名
-     * @param ext - 文件扩展名
      * @param pages - 页面配置，默认为 `config.pages`
      * @returns {string} - 文件类型，可选值有 `layout`、`config`、`page`、`ignore`
      */
@@ -100,10 +99,10 @@ export declare class FileRouter {
      * 检查文件是否为页面文件
      *
      * @param file - 文件绝对路径
-     * @param pages - 页面配置，默认为 `config.pages`
+     * @param filter - 过滤配置，默认为 `config.pages`
      * @returns {boolean} - 是否为页面文件
      */
-    private isPageFile;
+    isPageFile(file: string, filter?: FilterOptions | readonly FilterOptions[]): boolean;
     /**
      * 写入类型定义文件
      */

package/dist/file-router/index.js

@@ -137,7 +137,7 @@ export class FileRouter {
             }
             else {
                 // 处理文件
-                route = this.processFile(filePath, dirent.name, page, pageMapping, parent);
+                route = this.processFile(filePath, page, pageMapping, parent);
             }
             if (route) {
                 children.add(route);
@@ -169,18 +169,15 @@ export class FileRouter {
     /**
      * 处理文件
      * @param filePath - 文件路径
-     * @param fileName - 文件名
      * @param page - 页面配置
      * @param pageMapping - 子路由
      * @param parent - 父节点
      * @private
      */
-    processFile(filePath, fileName, page, pageMapping, parent) {
-        // 获取扩展名称
-        const ext = nodePath.extname(fileName);
-        // 获取文件名
-        const baseName = nodePath.basename(fileName, ext);
-        const fileType = this.getPageType(filePath, baseName, ext, page);
+    processFile(filePath, page, pageMapping, parent) {
+        // 分离出路由 path 和视图命名
+        const { routePath, viewName = 'default' } = parseRoutePath(filePath, this.config.pathParser);
+        const fileType = this.getPageType(filePath, routePath, page);
         if (fileType === 'ignore')
             return null;
         // 处理分组配置文件
@@ -201,8 +198,6 @@ export class FileRouter {
             }
             return null;
         }
-        // 分离出路由 path 和视图命名
-        const { routePath, viewName } = parseRoutePath(baseName);
         // 处理分组布局文件
         if (fileType === 'layout') {
             if (!parent)
@@ -273,15 +268,14 @@ export class FileRouter {
      *
      * @param file - 文件绝对路径
      * @param name - 文件名
-     * @param ext - 文件扩展名
      * @param pages - 页面配置，默认为 `config.pages`
      * @returns {string} - 文件类型，可选值有 `layout`、`config`、`page`、`ignore`
      */
-    getPageType(file, name, ext, pages) {
-        if (name === this.config.layoutFileName || name.startsWith(`${this.config.configFileName}@`)) {
+    getPageType(file, name, pages) {
+        if (name === this.config.layoutFileName) {
             return 'layout';
         }
-        if (name === this.config.configFileName && (ext === '.ts' || ext === '.js')) {
+        if (name === this.config.configFileName && (file.endsWith('.ts') || file.endsWith('.js'))) {
             return 'config';
         }
         if (this.isPageFile(file, pages)) {
@@ -293,16 +287,16 @@ export class FileRouter {
      * 检查文件是否为页面文件
      *
      * @param file - 文件绝对路径
-     * @param pages - 页面配置，默认为 `config.pages`
+     * @param filter - 过滤配置，默认为 `config.pages`
      * @returns {boolean} - 是否为页面文件
      */
-    isPageFile(file, pages) {
-        if (pages) {
-            if (Array.isArray(pages)) {
-                return !!isPageFileInDirs(file, pages);
+    isPageFile(file, filter) {
+        if (filter) {
+            if (Array.isArray(filter)) {
+                return !!isPageFileInDirs(file, filter);
             }
             else {
-                return isPageFile(file, pages);
+                return isPageFile(file, filter);
             }
         }
         return !!isPageFileInDirs(file, this.config.pages);
@@ -376,16 +370,16 @@ export class FileRouter {
         const page = isPageFileInDirs(filePath, this.config.pages);
         if (!page)
             return false;
+        // 分离出路由 path 和视图命名
+        const { routePath, viewName } = parseRoutePath(filePath, this.config.pathParser);
         const dirPath = nodePath.dirname(filePath);
-        const filename = nodePath.basename(filePath);
         const parent = this.fileMap.get(dirPath);
         const pageMapping = new Map();
         const prefix = parent ? '' : page.prefix;
         // 如果是命名文件，则先查找是否存在同名路由，存在则添加到同名路由的 children 中
-        if (filename.includes('@')) {
-            const baseName = filename.split('@')[0];
+        if (viewName) {
             const pages = parent ? parent.children : this.nodeTree;
-            const newRoutePath = this.applyPathStrategy(prefix + baseName);
+            const newRoutePath = this.applyPathStrategy(prefix + routePath);
             let sameRoute = null;
             for (const route of pages) {
                 if (route.path === newRoutePath) {
@@ -394,10 +388,10 @@ export class FileRouter {
                 }
             }
             if (sameRoute) {
-                pageMapping.set(baseName, sameRoute);
+                pageMapping.set(routePath, sameRoute);
             }
         }
-        const route = this.processFile(filePath, filename, {
+        const route = this.processFile(filePath, {
             dir: dirPath,
             include: page.include,
             exclude: page.exclude,

package/dist/file-router/parser/parsePage.d.ts

@@ -1,23 +1,35 @@
+import type { PathParser, PathParseResult } from '../types/index.js';
 /**
- * @fileoverview 页面解析模块
+ * 路径解析错误类
  *
- * 负责解析页面文件路径，提取路由信息，包括：
- * - 路由路径转换
- *
- * 与构建工具无关，可在任何 Node.js 环境中使用。
+ * 提供详细的错误上下文信息，包括文件路径、错误类型和原始值。
  */
-type PathParseResult = {
-    viewName: string;
-    routePath: string;
-};
+export declare class PathParseError extends TypeError {
+    /** 文件路径上下文 */
+    readonly filePath?: string;
+    /** 错误字段名称 */
+    readonly field?: string;
+    /** 原始值 */
+    readonly originalValue?: unknown;
+    constructor(message: string, options?: {
+        filePath?: string;
+        field?: string;
+        originalValue?: unknown;
+        cause?: Error;
+    });
+    /**
+     * 生成详细的错误信息
+     */
+    toString(): string;
+}
 /**
- * 解析视图名称
+ * 解析路由路径和视图名称
  *
- * 从文件名中提取命名视图名称。
+ * 从文件名中提取路由路径和命名视图名称。
  *
- * @param baseName - 文件基础名，不包含后缀
- * @param defaultName - 默认视图名称
- * @returns 视图名称和去除视图名的基础名
+ * @param filePath - 文件路径
+ * @param [parser] - 路径解析器
+ * @returns 路由路径和视图名称
+ * @throws {PathParseError} 当路径解析失败时抛出
  */
-export declare function parseRoutePath(baseName: string, defaultName?: string): PathParseResult;
-export {};
+export declare function parseRoutePath(filePath: string, parser?: PathParser): Exclude<PathParseResult, string>;

package/dist/file-router/parser/parsePage.js

@@ -6,16 +6,215 @@
  *
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
+import path from 'node:path';
 /**
- * 解析视图名称
+ * 路径解析错误类
  *
- * 从文件名中提取命名视图名称。
+ * 提供详细的错误上下文信息，包括文件路径、错误类型和原始值。
+ */
+export class PathParseError extends TypeError {
+    constructor(message, options) {
+        super(message, { cause: options?.cause });
+        /** 文件路径上下文 */
+        Object.defineProperty(this, "filePath", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** 错误字段名称 */
+        Object.defineProperty(this, "field", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** 原始值 */
+        Object.defineProperty(this, "originalValue", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.name = 'PathParseError';
+        this.filePath = options?.filePath;
+        this.field = options?.field;
+        this.originalValue = options?.originalValue;
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, PathParseError);
+        }
+    }
+    /**
+     * 生成详细的错误信息
+     */
+    toString() {
+        let details = `${this.name}: ${this.message}`;
+        if (this.filePath) {
+            details += `\n  File: ${this.filePath}`;
+        }
+        if (this.field) {
+            details += `\n  Field: ${this.field}`;
+        }
+        if (this.originalValue !== undefined) {
+            details += `\n  Value: ${String(this.originalValue)}`;
+        }
+        return details;
+    }
+}
+/**
+ * 解析路由路径和视图名称
+ *
+ * 从文件名中提取路由路径和命名视图名称。
+ *
+ * @param filePath - 文件路径
+ * @param [parser] - 路径解析器
+ * @returns 路由路径和视图名称
+ * @throws {PathParseError} 当路径解析失败时抛出
+ */
+export function parseRoutePath(filePath, parser) {
+    const { basename } = extractFileInfo(filePath);
+    if (!parser) {
+        return parseDefaultRoutePath(basename);
+    }
+    const result = parser(basename, filePath);
+    return parseCustomRouteResult(result, filePath);
+}
+/**
+ * 提取文件信息
+ *
+ * @param filePath - 文件路径
+ * @returns 文件基本信息
+ */
+function extractFileInfo(filePath) {
+    const ext = path.extname(filePath);
+    const basename = path.basename(filePath, ext);
+    return { basename, ext };
+}
+/**
+ * 解析默认路由路径（无自定义解析器）
+ *
+ * @param basename - 文件基本名称
+ * @returns 解析结果
+ */
+function parseDefaultRoutePath(basename) {
+    const [routePath, viewName] = basename.split('@', 2);
+    return {
+        routePath,
+        viewName: viewName || 'default'
+    };
+}
+/**
+ * 解析自定义路由结果
+ *
+ * @param result - 解析器返回的结果
+ * @param filePath - 文件路径（用于错误上下文）
+ * @returns 解析结果
+ * @throws {PathParseError} 当结果无效时抛出
+ */
+function parseCustomRouteResult(result, filePath) {
+    if (typeof result === 'string') {
+        return parseStringResult(result, filePath);
+    }
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+        return parseObjectResult(result, filePath);
+    }
+    throw new PathParseError('pathParser returned invalid result type', {
+        filePath,
+        originalValue: result,
+        field: 'result'
+    });
+}
+/**
+ * 解析字符串类型的结果
+ *
+ * @param result - 字符串结果
+ * @param filePath - 文件路径
+ * @returns 解析结果
+ * @throws {PathParseError} 当路径无效时抛出
+ */
+function parseStringResult(result, filePath) {
+    const routePath = normalizeRoutePath(result);
+    if (!routePath) {
+        throw new PathParseError('pathParser returned empty routePath', {
+            filePath,
+            originalValue: result,
+            field: 'routePath'
+        });
+    }
+    return { routePath, viewName: 'default' };
+}
+/**
+ * 解析对象类型的结果
+ *
+ * @param result - 对象结果
+ * @param filePath - 文件路径
+ * @returns 解析结果
+ * @throws {PathParseError} 当结果无效时抛出
+ */
+function parseObjectResult(result, filePath) {
+    const { routePath: rawRoutePath, viewName } = result;
+    validateRoutePathType(rawRoutePath, filePath);
+    const routePath = normalizeRoutePath(rawRoutePath);
+    if (!routePath) {
+        throw new PathParseError('pathParser returned empty routePath after normalization', {
+            filePath,
+            originalValue: rawRoutePath,
+            field: 'routePath'
+        });
+    }
+    validateViewName(viewName, filePath);
+    return {
+        routePath,
+        viewName: viewName || 'default'
+    };
+}
+/**
+ * 验证路由路径类型
+ *
+ * @param routePath - 路由路径
+ * @param filePath - 文件路径（用于错误上下文）
+ * @throws {PathParseError} 当类型无效时抛出
+ */
+function validateRoutePathType(routePath, filePath) {
+    if (typeof routePath !== 'string') {
+        throw new PathParseError('pathParser returned non-string routePath', {
+            filePath,
+            originalValue: routePath,
+            field: 'routePath'
+        });
+    }
+    if (!routePath.trim()) {
+        throw new PathParseError('pathParser returned empty or whitespace-only routePath', {
+            filePath,
+            originalValue: routePath,
+            field: 'routePath'
+        });
+    }
+}
+/**
+ * 验证视图名称
+ *
+ * @param viewName - 视图名称
+ * @param filePath - 文件路径（用于错误上下文）
+ * @throws {PathParseError} 当视图名称无效时抛出
+ */
+function validateViewName(viewName, filePath) {
+    if (viewName !== undefined && typeof viewName !== 'string') {
+        throw new PathParseError('pathParser returned non-string viewName', {
+            filePath,
+            originalValue: viewName,
+            field: 'viewName'
+        });
+    }
+}
+/**
+ * 标准化路由路径
+ *
+ * 去除路径首尾空白和开头的斜杠。
  *
- * @param baseName - 文件基础名，不包含后缀
- * @param defaultName - 默认视图名称
- * @returns 视图名称和去除视图名的基础名
+ * @param routePath - 原始路由路径
+ * @returns 标准化后的路由路径
  */
-export function parseRoutePath(baseName, defaultName = 'default') {
-    let [routePath, viewName] = baseName.split('@');
-    return { viewName: viewName || defaultName, routePath };
+function normalizeRoutePath(routePath) {
+    return routePath.trim().replace(/^\/+/, '');
 }

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

@@ -11,6 +11,23 @@ export type ImportMode = 'lazy' | 'sync';
  */
 export type PathStrategy = 'kebab' | 'lowercase' | 'raw';
 export type PageSource = string | PageDirOptions;
+/**
+ * 路径解析结果
+ */
+export type PathParseResult = string | {
+    /** 解析后的路径 */
+    routePath: string;
+    /** 视图名称 */
+    viewName?: string;
+};
+/**
+ * 路径解析器
+ *
+ * @param basename - 文件名称（不包含扩展名)
+ * @param filePath - 完整的文件路径
+ * @returns {PathParseResult} 路径解析结果包含路径和视图名称
+ */
+export type PathParser = (basename: string, filePath: string) => PathParseResult;
 /**
  * 页面目录选项
  */
@@ -60,6 +77,11 @@ export interface FileRouterOptions {
     /**
      * 路径转换策略
      *
+     * - 'kebab': 转换为 kebab-case
+     * - 'lowercase': 转换为 lowercase
+     * - 'raw': 不转换
+     *
+     * @values 'kebab' | 'lowercase' | 'raw'
      * @default 'kebab'
      */
     pathStrategy?: PathStrategy;
@@ -135,4 +157,12 @@ export interface FileRouterOptions {
      * ```
      */
     extendRoute?: ExtendRouteHook;
+    /**
+     * 路径解析器
+     *
+     * @param basename - 文件名称（不包含扩展名）或目录名称
+     * @param filePath - 完整的文件路径
+     * @returns {PathParseResult} 返回字符串path，或包含path和viewName的对象
+     */
+    pathParser?: PathParser;
 }

package/dist/plugin-vite/index.js

@@ -14,7 +14,6 @@ export default function VitarxRouter(options = {}) {
     let isPreview = false;
     return {
         name: 'vite-plugin-vitarx-router',
-        enforce: 'pre',
         config(_, env) {
             isPreview = !!env.isPreview;
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitarx-router",
-  "version": "4.0.0-beta.3",
+  "version": "4.0.0-beta.4",
   "description": "Official routing solution for Vitarx framework with declarative routing, navigation guards, dynamic routes, file-based routing with HMR, and full TypeScript support.",
   "author": "ZhuChonglin <8210856@qq.com>",
   "license": "MIT",