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

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

@@ -1,12 +1,59 @@
-import type { NamingStrategy, ParsedPage } from '../types.js';
+import type { PageParser, PageParseResult } from '../types/index.js';
 /**
- * 解析页面文件
+ * 路径解析错误类
  *
- * @param filePath - 文件绝对路径
- * @param pagesDir - 页面目录绝对路径
- * @param parentPath - 父级路径（用于嵌套路由）
- * @param namingStrategy - 命名策略，默认为 'kebab'
- * @param pathPrefix - 路由路径前缀，默认为 ''
- * @returns 解析后的页面信息，解析失败或无有效导出返回 null
+ * 提供详细的错误上下文信息，包括文件路径、错误类型和原始值。
  */
-export declare function parsePageFile(filePath: string, pagesDir: string, parentPath: string, namingStrategy?: NamingStrategy, pathPrefix?: string): ParsedPage | null;
+export declare class PageParseError 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 filePath - 文件路径
+ * @param [parser] - 自定义解析器
+ * @param [precomputed] - 预计算的文件信息，避免重复解析文件路径
+ * @returns 路径解析结果
+ * @throws {PageParseError} 当路径解析失败时抛出
+ */
+export declare function parsePageFile(filePath: string, parser?: PageParser, precomputed?: FileInfo): PageParseResult;
+/**
+ * 文件信息
+ *
+ * 从文件路径中提取的结构化信息，作为文件名解析的唯一来源。
+ */
+export interface FileInfo {
+    /** 文件名（不含扩展名），如 home@sidebar → home@sidebar */
+    basename: string;
+    /** 路由名（@之前的部分），如 home@sidebar → home */
+    rawName: string;
+    /** 视图名称（@之后的部分），如 home@sidebar → sidebar */
+    viewName: string | undefined;
+}
+/**
+ * 提取文件信息
+ *
+ * 从文件路径中提取文件名、路由名和视图名称。
+ * 这是文件名解析的唯一入口，其他模块应复用此函数而非重复实现。
+ *
+ * @param filePath - 文件路径
+ * @returns 文件信息
+ */
+export declare function extractFileInfo(filePath: string): FileInfo;

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

@@ -3,209 +3,231 @@
  *
  * 负责解析页面文件路径，提取路由信息，包括：
  * - 路由路径转换
- * - 动态参数识别
- * - 路由名称生成
  *
  * 与构建工具无关，可在任何 Node.js 环境中使用。
  */
 import path from 'node:path';
-import { parseDefinePage } from '../macros/index.js';
-import { warn } from '../utils/logger.js';
-import { applyNamingStrategyToName, applyNamingStrategyToPath } from '../utils/namingStrategy.js';
-import { normalizePathSeparator } from '../utils/pathUtils.js';
-import { checkDefaultExport, shouldCheckExport } from './exportChecker.js';
-/** 动态参数匹配正则，如 [id]、[slug]、[param?] */
-const DYNAMIC_PARAM_REGEX = /^\[(.+?)(\?)?]$/;
 /**
- * 解析文件名
+ * 路径解析错误类
  *
- * 提取文件名中的路由信息和动态参数。
+ * 提供详细的错误上下文信息，包括文件路径、错误类型和原始值。
+ */
+export class PageParseError 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, PageParseError);
+        }
+    }
+    /**
+     * 生成详细的错误信息
+     */
+    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 fileName - 文件名（不含扩展名）
+ * 从文件名中提取路由路径和命名视图名称。
+ *
+ * @param filePath - 文件路径
+ * @param [parser] - 自定义解析器
+ * @param [precomputed] - 预计算的文件信息，避免重复解析文件路径
+ * @returns 路径解析结果
+ * @throws {PageParseError} 当路径解析失败时抛出
+ */
+export function parsePageFile(filePath, parser, precomputed) {
+    const info = precomputed ?? extractFileInfo(filePath);
+    if (!parser) {
+        return defaultPageParser(info.rawName, info.viewName);
+    }
+    const result = parser(info.basename, filePath);
+    return parseCustomResult(result, filePath);
+}
+/**
+ * 提取文件信息
+ *
+ * 从文件路径中提取文件名、路由名和视图名称。
+ * 这是文件名解析的唯一入口，其他模块应复用此函数而非重复实现。
+ *
+ * @param filePath - 文件路径
+ * @returns 文件信息
+ */
+export function extractFileInfo(filePath) {
+    const ext = path.extname(filePath);
+    const basename = path.basename(filePath, ext);
+    const [rawName, viewName] = basename.split('@', 2);
+    return { basename, rawName, viewName };
+}
+/**
+ * 解析默认路由路径（无自定义解析器）
+ *
+ * @param rawName - 路由名（@之前的部分）
+ * @param viewName - 视图名称（@之后的部分）
  * @returns 解析结果
  */
-function parseFileName(fileName) {
-    const params = [];
-    let isDynamic = false;
-    // 匹配动态参数模式
-    const dynamicMatch = fileName.match(DYNAMIC_PARAM_REGEX);
-    if (dynamicMatch) {
-        isDynamic = true;
-        const paramName = dynamicMatch[1];
-        // 检查是否为可选参数（以 ? 结尾）
-        const isOptional = !!dynamicMatch[2];
-        params.push(paramName);
-        // 生成路由参数格式：{param} 或 {param?}
-        return { name: `{${paramName}${isOptional ? '?' : ''}}`, params, isDynamic };
+function defaultPageParser(rawName, viewName) {
+    const routePath = normalizeRoutePath(rawName);
+    if (!routePath) {
+        throw new PageParseError('PageParser returned empty path', {
+            filePath: rawName,
+            originalValue: rawName,
+            field: 'path'
+        });
     }
-    return { name: fileName, params, isDynamic };
+    return {
+        path: routePath,
+        viewName
+    };
 }
 /**
- * 生成路由名称
+ * 解析自定义解析器结果
  *
- * @param relativePath - 相对于页面目录的路径
- * @param baseName - 文件基础名
- * @param pathPrefix - 路径前缀
- * @returns 路由名称
+ * @param result - 解析器返回的结果
+ * @param filePath - 文件路径（用于错误上下文）
+ * @returns 解析结果
+ * @throws {PageParseError} 当结果无效时抛出
  */
-function generateRouteName(relativePath, baseName, pathPrefix = '') {
-    const dirPath = path.dirname(relativePath);
-    const segments = [];
-    // 处理路径前缀
-    if (pathPrefix) {
-        const prefixName = pathPrefix
-            .trim()
-            .replace(/^\/+/, '')
-            .replace(/[-\/]+$/, '')
-            .trim();
-        if (prefixName) {
-            segments.push(prefixName);
-        }
+function parseCustomResult(result, filePath) {
+    if (typeof result === 'string') {
+        const [rawName, viewName] = result.split('@', 2);
+        return defaultPageParser(rawName, viewName);
     }
-    // 处理目录路径
-    if (dirPath !== '.') {
-        segments.push(...normalizePathSeparator(dirPath).split('/'));
+    if (result && typeof result === 'object' && !Array.isArray(result)) {
+        return parseObjectResult(result, filePath);
     }
-    // 处理文件名
-    if (baseName !== 'index' || dirPath === '.') {
-        if (baseName === 'index' && dirPath === '.' && !pathPrefix) {
-            segments.push('index');
-        }
-        else if (baseName !== 'index') {
-            // 处理动态参数
-            const dynamicMatch = baseName.match(DYNAMIC_PARAM_REGEX);
-            if (dynamicMatch) {
-                segments.push(dynamicMatch[1]);
-            }
-            else {
-                segments.push(baseName);
-            }
-        }
-    }
-    return segments.join('-');
+    throw new PageParseError('PageParser returned invalid result type', {
+        filePath,
+        originalValue: result
+    });
 }
 /**
- * 构建路由路径
+ * 解析对象类型的结果
  *
- * @param isIndex - 是否为索引页面
- * @param dirPath - 目录路径
- * @param routeName - 路由名称
- * @param pathPrefix - 路径前缀
- * @returns 完整的路由路径
+ * @param result - 对象结果
+ * @param filePath - 文件路径
+ * @returns 解析结果
+ * @throws {PageParseError} 当结果无效时抛出
  */
-function buildRoutePath(isIndex, dirPath, routeName, pathPrefix) {
-    let routePath;
-    // 构建基础路由路径
-    if (isIndex) {
-        if (dirPath === '.') {
-            routePath = '/';
-        }
-        else {
-            routePath = '/' + normalizePathSeparator(dirPath);
-        }
+function parseObjectResult(result, filePath) {
+    const { path: rawRoutePath, viewName, options } = result;
+    validateRoutePathType(rawRoutePath, filePath);
+    const routePath = normalizeRoutePath(rawRoutePath);
+    if (!routePath) {
+        throw new PageParseError('PageParser returned empty path after normalization', {
+            filePath,
+            originalValue: rawRoutePath,
+            field: 'path'
+        });
     }
-    else {
-        if (dirPath === '.') {
-            routePath = '/' + routeName;
-        }
-        else {
-            routePath = '/' + normalizePathSeparator(dirPath) + '/' + routeName;
-        }
+    validateViewName(viewName, filePath);
+    validateOptions(options, filePath);
+    return {
+        ...result,
+        path: routePath
+    };
+}
+/**
+ * 验证路由路径类型
+ *
+ * @param routePath - 路由路径
+ * @param filePath - 文件路径（用于错误上下文）
+ * @throws {PageParseError} 当类型无效时抛出
+ */
+function validateRoutePathType(routePath, filePath) {
+    if (typeof routePath !== 'string') {
+        throw new PageParseError('PageParser returned non-string path', {
+            filePath,
+            originalValue: routePath,
+            field: 'path'
+        });
     }
-    // 处理路径前缀
-    pathPrefix = pathPrefix.trim() === '/' ? '' : pathPrefix.trim();
-    if (pathPrefix) {
-        const normalizedPrefix = pathPrefix.startsWith('/') ? pathPrefix : `/${pathPrefix}`;
-        if (routePath === '/') {
-            routePath = normalizedPrefix.replace(/\/+$/, '');
-        }
-        else {
-            routePath = normalizedPrefix + routePath.slice(1);
-        }
+    if (!routePath.trim()) {
+        throw new PageParseError('PageParser returned empty or whitespace-only path', {
+            filePath,
+            originalValue: routePath,
+            field: 'path'
+        });
     }
-    return routePath;
 }
 /**
- * 解析视图名称
+ * 验证视图名称
  *
- * 从文件名中提取命名视图名称。
- *
- * @param baseName - 文件基础名
- * @returns 视图名称和去除视图名的基础名
+ * @param viewName - 视图名称
+ * @param filePath - 文件路径（用于错误上下文）
+ * @throws {PageParseError} 当视图名称无效时抛出
  */
-function parseViewName(baseName) {
-    // 查找 @ 分隔符
-    const viewSeparatorIndex = baseName.indexOf('@');
-    if (viewSeparatorIndex > -1) {
-        return {
-            baseWithoutView: baseName.slice(0, viewSeparatorIndex),
-            viewName: baseName.slice(viewSeparatorIndex + 1)
-        };
+function validateViewName(viewName, filePath) {
+    if (viewName !== undefined && typeof viewName !== 'string') {
+        throw new PageParseError('PageParser returned non-string viewName', {
+            filePath,
+            originalValue: viewName,
+            field: 'viewName'
+        });
     }
-    return { viewName: null, baseWithoutView: baseName };
 }
 /**
- * 解析页面文件
+ * 验证选项
  *
- * @param filePath - 文件绝对路径
- * @param pagesDir - 页面目录绝对路径
- * @param parentPath - 父级路径（用于嵌套路由）
- * @param namingStrategy - 命名策略，默认为 'kebab'
- * @param pathPrefix - 路由路径前缀，默认为 ''
- * @returns 解析后的页面信息，解析失败或无有效导出返回 null
+ * @param options - 选项
+ * @param filePath - 文件路径
  */
-export function parsePageFile(filePath, pagesDir, parentPath, namingStrategy = 'kebab', pathPrefix = '') {
-    // 提取文件名和扩展名
-    const fileName = path.basename(filePath);
-    const ext = path.extname(fileName);
-    const baseName = fileName.slice(0, -ext.length);
-    // 解析视图名称
-    const { viewName, baseWithoutView } = parseViewName(baseName);
-    // 检查文件导出
-    if (shouldCheckExport(ext)) {
-        const exportCheck = checkDefaultExport(filePath);
-        if (exportCheck.warning) {
-            const pageOptions = parseDefinePage(filePath);
-            // 检查是否有默认导出或 redirect 配置
-            if (!exportCheck.hasDefaultExport || !exportCheck.isFunctionOrClass) {
-                if (!pageOptions?.redirect) {
-                    warn('页面文件缺少有效导出且未定义 redirect', `${filePath}\n    ${exportCheck.warning}`);
-                    return null;
-                }
-            }
-        }
+function validateOptions(options, filePath) {
+    if (options !== undefined && Object.prototype.toString.call(options) !== '[object Object]') {
+        throw new PageParseError('PageParser returned invalid options type', {
+            filePath,
+            originalValue: options,
+            field: 'options'
+        });
     }
-    // 计算相对路径
-    const relativePath = path.relative(pagesDir, filePath);
-    const dirPath = path.dirname(relativePath);
-    // 检查是否为索引页面
-    const isIndex = baseWithoutView === 'index';
-    // 解析文件名，提取动态参数
-    const { name: routeName, params, isDynamic } = parseFileName(baseWithoutView);
-    // 构建完整路由路径
-    const routePath = buildRoutePath(isIndex, dirPath, routeName, pathPrefix);
-    // 解析 definePage 配置
-    const pageOptions = parseDefinePage(filePath);
-    // 生成路由名称
-    const name = pageOptions?.name || generateRouteName(relativePath, baseWithoutView, pathPrefix);
-    // 应用命名策略
-    const finalPath = applyNamingStrategyToPath(routePath, namingStrategy);
-    const finalName = applyNamingStrategyToName(name, namingStrategy);
-    // 返回解析结果
-    return {
-        path: finalPath,
-        filePath,
-        name: finalName,
-        params,
-        isIndex,
-        isDynamic,
-        children: [],
-        meta: pageOptions?.meta,
-        pattern: pageOptions?.pattern,
-        customName: pageOptions?.name,
-        parentPath,
-        redirect: pageOptions?.redirect,
-        alias: pageOptions?.alias,
-        viewName
-    };
+}
+/**
+ * 标准化路由路径
+ *
+ * 去除路径首尾空白和首尾的斜杠，将 . # 等不利于 URL 的字符替换为 -。
+ *
+ * @param routePath - 原始路由路径
+ * @returns 标准化后的路由路径
+ */
+function normalizeRoutePath(routePath) {
+    return routePath
+        .trim()
+        .replace(/^\/+|\/+$/g, '')
+        .replace(/[.#]/g, '-');
 }

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

@@ -0,0 +1,22 @@
+import { type PageDirConfig } from '../config/resolve.js';
+import type { PageParser, PathStrategy, ScanNode } from '../types/index.js';
+import { type FileInfo } from './parsePage.js';
+interface RouteFullPathContext {
+    fileMap: Map<string, ScanNode>;
+    pages: readonly PageDirConfig[];
+    pageParser?: PageParser;
+    pathStrategy: PathStrategy;
+}
+/**
+ * 计算文件的完整路由路径
+ *
+ * 判断文件是否为页面文件，如果是则计算其最终生成的路由 fullPath。
+ * 非页面文件（布局文件、配置文件等）返回 null。
+ *
+ * @param filePath - 文件绝对路径
+ * @param fileInfo - 文件信息
+ * @param context - 路由计算上下文
+ * @returns 完整路由路径，非页面文件返回 null
+ */
+export declare function computeRouteFullPath(filePath: string, fileInfo: FileInfo, context: RouteFullPathContext): string | null;
+export {};

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

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview 路由路径计算辅助函数
+ *
+ * 从文件路径计算最终生成的路由 fullPath，
+ * 支持已跟踪（在路由树中）和未跟踪（尚未扫描）两种场景。
+ */
+import nodePath from 'node:path';
+import { applyPathStrategy } from '../utils/pathStrategy.js';
+import { normalizeRoutePath, resolvePathVariable } from '../utils/pathUtils.js';
+import { isPageFileInDirs } from './filterUtils.js';
+import { parsePageFile } from './parsePage.js';
+/**
+ * 应用路径策略（命名转换 + 动态参数转换）
+ *
+ * @param path - 路径
+ * @param strategy - 路径策略
+ * @returns 转换后的路径
+ */
+function applyFullPathStrategy(path, strategy) {
+    return resolvePathVariable(applyPathStrategy(path, strategy));
+}
+/**
+ * 从节点树计算完整路由路径
+ *
+ * 沿 parent 链向上拼接所有节点的 path，与生成阶段 fullPath 的计算逻辑一致。
+ *
+ * @param node - 路由节点
+ * @returns 完整路由路径
+ */
+function computeNodeFullPath(node) {
+    const segments = [];
+    let current = node;
+    while (current) {
+        segments.unshift(current.path);
+        current = current.parent;
+    }
+    return normalizeRoutePath(segments.join('/'));
+}
+/**
+ * 计算文件的完整路由路径
+ *
+ * 判断文件是否为页面文件，如果是则计算其最终生成的路由 fullPath。
+ * 非页面文件（布局文件、配置文件等）返回 null。
+ *
+ * @param filePath - 文件绝对路径
+ * @param fileInfo - 文件信息
+ * @param context - 路由计算上下文
+ * @returns 完整路由路径，非页面文件返回 null
+ */
+export function computeRouteFullPath(filePath, fileInfo, context) {
+    const { fileMap, pages, pageParser, pathStrategy } = context;
+    const node = fileMap.get(filePath);
+    if (node) {
+        return computeNodeFullPath(node);
+    }
+    const page = isPageFileInDirs(filePath, pages);
+    if (!page)
+        return null;
+    const parsed = parsePageFile(filePath, pageParser, fileInfo);
+    const pathSegment = parsed.path === 'index' ? '' : applyFullPathStrategy(parsed.path, pathStrategy);
+    const segments = pathSegment ? [pathSegment] : [];
+    let dirPath = nodePath.dirname(filePath);
+    while (dirPath.length > page.dir.length) {
+        const dirNode = fileMap.get(dirPath);
+        if (dirNode) {
+            const parentFullPath = computeNodeFullPath(dirNode);
+            return normalizeRoutePath(parentFullPath + '/' + segments.join('/'));
+        }
+        segments.unshift(applyFullPathStrategy(nodePath.basename(dirPath), pathStrategy));
+        dirPath = nodePath.dirname(dirPath);
+    }
+    const prefix = page.prefix ? applyFullPathStrategy(page.prefix, pathStrategy) : '';
+    return normalizeRoutePath(prefix + '/' + segments.join('/'));
+}

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

@@ -0,0 +1,52 @@
+import type { RouteNode } from './route.js';
+/**
+ * 扩展路由的钩子
+ *
+ * 支持对 route 的数据直接进行修改，
+ * 但此时分组路由的children还未赋值！
+ * 特殊需求可通过BeforeWriteRoutesHook钩子处理。
+ *
+ * @param route - 生成的路由节点
+ * @param parsed - 解析的路由节点
+ *
+ * @example
+ * ```js
+ * {
+ *   extendRoute(route) {
+ *     if (route.path === '/home') {
+ *       route.meta ??= { auth: true }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type ExtendRouteHook = (route: RouteNode) => void;
+/**
+ * 写入路由文件前的钩子
+ *
+ * 支持对 routes 直接进行修改亦可以返回新的路由数组。
+ *
+ * @param routes - 路由数组
+ *
+ * @example
+ * ```js
+ * {
+ *   beforeWriteRoutes(routes) {
+ *     routes.forEach(route => {
+ *       if (route.path === '/') {
+ *         route.path = '/home'
+ *       }
+ *     })
+ *   }
+ * }
+ * ```
+ */
+export type BeforeWriteRoutesHook = (routes: RouteNode[]) => void | RouteNode[];
+/**
+ * 代码转换函数
+ *
+ * @param content - 代码内容
+ * @param file - 文件路径
+ * @returns - 转换后的代码内容
+ */
+export type CodeTransformHook = (content: string, file: string) => string;

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

@@ -0,0 +1,3 @@
+export type * from './options.js';
+export type * from './route.js';
+export type * from './hooks.js';

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

@@ -0,0 +1 @@
+export {};