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

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

@@ -0,0 +1,279 @@
+import type { BeforeWriteRoutesHook, CodeTransformHook, ExtendRouteHook } from './hooks.js';
+import type { PageOptions } from './route.js';
+/**
+ * 自定义导入模式函数的上下文
+ */
+export interface ImportModeContext {
+    /**
+     * 组件文件路径（已 JSON.stringify）
+     */
+    importPath: string;
+    /**
+     * 组件文件原始路径
+     */
+    filePath: string;
+    /**
+     * 添加导入语句
+     * 用于向生成的代码顶部添加 import 语句
+     */
+    addImport: (statement: string) => void;
+}
+/**
+ * 自定义导入处理函数
+ *
+ * @param context - 导入上下文
+ * @returns 'lazy' | 'sync' | 表达式字符串
+ *
+ * @example
+ * ```ts
+ * // 返回预设模式
+ * (context) => 'lazy'
+ * (context) => 'sync'
+ *
+ * // 返回自定义表达式
+ * (context) => {
+ *   context.addImport(`import { lazy } from 'vitarx'`)
+ *   return `lazy(() => import(${context.importPath}))`
+ * }
+ * ```
+ */
+export type ComponentImportHandler = (context: ImportModeContext) => 'lazy' | 'sync' | string;
+/**
+ * 组件导入模式。
+ *
+ * - 'lazy': 生成懒加载表达式 `lazy(() => import(path))`
+ * - 'sync': 同步加载组件，生成 `import` 语句
+ * - 函数: 自定义导入逻辑
+ */
+export type ImportMode = 'lazy' | 'sync' | ComponentImportHandler;
+/**
+ * 生成路径的策略。
+ */
+export type PathStrategy = 'kebab' | 'lowercase' | 'raw';
+export type PageSource = string | PageDirOptions;
+/**
+ * 路径解析结果
+ */
+export interface PageParseResult {
+    /** 解析后的路径 如：home.jsx -> 'home' */
+    path: string;
+    /**
+     * 页面相关可配置选项
+     */
+    options?: PageOptions;
+    /** 视图名称 如：home.nav.jsx -> 'nav' */
+    viewName?: string;
+}
+export interface GroupParseResult {
+    /**
+     * 用于Route的路径 如：1.group -> 'group'
+     */
+    path: string;
+    /**
+     * 分组相关可配置选项
+     *
+     * @example
+     * ```js
+     * {
+     *   options: {
+     *     meta: {
+     *       order: 1
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    options?: PageOptions;
+}
+/**
+ * 页面文件前置解析器
+ *
+ * @param basename - 文件名称（不包含扩展名)
+ * @param filePath - 完整的文件路径
+ * @returns {PageParseResult | string} 如果返回字符串则交由内置解析器处理，否则返回`FileParseResult`对象
+ */
+export type PageParser = (basename: string, filePath: string) => string | PageParseResult;
+/**
+ * 分组目录前置解析器
+ */
+export type GroupParser = (dirName: string, dirPath: string) => string | GroupParseResult;
+/**
+ * 页面目录选项
+ */
+export interface PageDirOptions {
+    /**
+     * 页面目录
+     */
+    dir: string;
+    /**
+     * 包含规则
+     *
+     * @default ['**\/*.{jsx,tsx}']
+     */
+    include?: readonly string[];
+    /**
+     * 排除规则
+     *
+     * @default ['**\/node_modules\/**', '**\/dist\/**', '**\/.*']
+     */
+    exclude?: readonly string[];
+    /**
+     * 路径前缀（当 group=true 时）
+     * 或字符串前缀（当 group=false 时）
+     */
+    prefix?: string;
+    /**
+     * 是否作为路由分组
+     */
+    group?: boolean;
+}
+/**
+ * 文件路由配置
+ */
+export interface FileRouterOptions {
+    /**
+     * 项目根目录
+     *
+     * @default process.cwd()
+     */
+    root?: string;
+    /**
+     * 页面来源配置
+     *
+     * @default 'src/pages'
+     */
+    pages?: PageSource | readonly PageSource[];
+    /**
+     * 路径转换策略
+     *
+     * - 'kebab': 转换为 kebab-case
+     * - 'lowercase': 转换为 lowercase
+     * - 'raw': 不转换
+     *
+     * @values 'kebab' | 'lowercase' | 'raw'
+     * @default 'kebab'
+     */
+    pathStrategy?: PathStrategy;
+    /**
+     * 组件导入模式
+     *
+     * - 'lazy': 生成懒加载表达式 `lazy(() => import(path))`
+     * - 'sync': 同步加载组件，生成 `import` 语句
+     * - 函数: 自定义导入逻辑
+     *
+     * @example
+     * ```ts
+     * // 使用预设模式
+     * importMode: 'lazy'
+     *
+     * // 使用自定义函数
+     * importMode: (context) => {
+     *   context.addImport(`import { lazy } from 'vitarx'`)
+     *   return `lazy(() => import(${context.importPath}))`
+     * }
+     * ```
+     *
+     * @default 'lazy'
+     */
+    importMode?: ImportMode;
+    /**
+     * 注入在路由虚拟模块顶部的导入语句
+     *
+     * @example
+     * ```js
+     * {
+     *   injectImports: ['import { lazy } from "vitarx"']
+     * }
+     * ```
+     */
+    injectImports?: readonly string[];
+    /**
+     * 是否生成 dts 文件
+     *
+     * - `true`: 生成 dts 文件，文件名为 `router.d.ts`
+     * - `false`: 不生成 dts 文件
+     * - `string`: 生成 dts 文件，支持绝对路径和相对路径（相对于root）如：`'typed-router.d.ts'`
+     *
+     * @default false
+     */
+    dts?: boolean | string;
+    /**
+     * 布局文件名
+     *
+     * @default '_layout'
+     */
+    layoutFileName?: string;
+    /**
+     * 分组配置文件名
+     *
+     * @default '_config'
+     */
+    configFileName?: string;
+    /**
+     * 代码转换
+     *
+     * 通常用于转换 markdown 文件内容为 `EsModule`。
+     *
+     * @example
+     * ```js
+     * {
+     *   transform(content, file) {
+     *     const { ext, name } = path.parse(file)
+     *     if (ext === '.md') {
+     *       const html = markdownToHtml(content)
+     *       return `export default function ${name}() { return ${html} }`
+     *     }
+     *     return content
+     *   }
+     * }
+     * ```
+     */
+    transform?: CodeTransformHook;
+    /**
+     * 扩展路由
+     *
+     * @example
+     * ```js
+     * {
+     *   extendRoute(route) {
+     *      route.meta ??= { auth: true }
+     *   }
+     * }
+     * ```
+     */
+    extendRoute?: ExtendRouteHook;
+    /**
+     * 写入路由之前
+     */
+    beforeWriteRoutes?: BeforeWriteRoutesHook;
+    /**
+     * 页面文件前置解析器
+     *
+     * @see {@linkcode PageParser}
+     */
+    pageParser?: PageParser;
+    /**
+     * 分组目录前置解析器
+     *
+     * @see {@linkcode GroupParser}
+     * @example
+     * ```js
+     * {
+     *   groupParser(dirName) {
+     *     // dirName = '1.group'
+     *     const result = parseOrderAndName(dirName)
+     *     return {
+     *       path: result.name, // 'group'
+     *       options: {
+     *         meta: {
+     *           // 往 meta 中添加 order 字段
+     *           order: result.order // 1
+     *         }
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    groupParser?: GroupParser;
+}

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

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

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

@@ -0,0 +1,114 @@
+/**
+ * 页面可配置路由选项（definePage）
+ */
+import type { RouteMetaData } from '../../core/index.js';
+export interface RedirectConfig {
+    /**
+     * 路由索引，支持path或name
+     */
+    index: string;
+    /**
+     * 查询参数
+     */
+    query?: Record<string, string>;
+    /**
+     * URL动态参数
+     */
+    params?: Record<string, string>;
+}
+export interface PageOptions {
+    /**
+     * 路由名称
+     */
+    name?: string;
+    /**
+     * 路由元数据
+     */
+    meta?: RouteMetaData;
+    /**
+     * 动态参数匹配模式
+     */
+    pattern?: Record<string, RegExp>;
+    /**
+     * 重定向配置
+     */
+    redirect?: string | RedirectConfig;
+    /**
+     * 路由别名
+     */
+    alias?: string | string[];
+}
+/**
+ * 扫描的节点 - 核心 IR 节点
+ */
+export interface ScanNode {
+    /**
+     * 目录配置文件
+     */
+    dirConfigFile?: string;
+    /**
+     * 是否为分组
+     */
+    readonly isGroup: boolean;
+    /**
+     * 文件绝对路径
+     */
+    readonly filePath: string;
+    /**
+     * 当前 path（不含父级）
+     */
+    readonly path: string;
+    /**
+     * 父节点
+     */
+    parent?: ScanNode;
+    /**
+     * 子节点映射
+     */
+    children?: Set<ScanNode>;
+    /**
+     * 组件映射（命名视图）
+     */
+    components?: Record<string, string>;
+    /**
+     * 页面配置选项
+     */
+    options?: PageOptions;
+}
+/**
+ * 路由节点 - 解析后的路由节点
+ */
+export interface RouteNode extends PageOptions {
+    /**
+     * 是否为分组
+     */
+    isGroup: boolean;
+    /**
+     * 文件绝对路径
+     */
+    filePath: string;
+    /**
+     * 当前 path（不含父级）
+     */
+    path: string;
+    /**
+     * 完整 path（含父级）
+     */
+    fullPath: string;
+    /**
+     * 子节点
+     */
+    children?: RouteNode[];
+    /**
+     * 组件映射（命名视图）
+     *
+     * @example
+     * ```js
+     * {
+     *   default: '/src/pages/Home.jsx', // 实际为系统绝对路径！
+     *   sidebar: '/src/pages/Sidebar.jsx'
+     * }
+     * ```
+     */
+    component?: Record<string, string>;
+}

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

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

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

@@ -0,0 +1,11 @@
+import type { CodeTransformHook } from '../types/index.js';
+/**
+ * 读取文件内容
+ *
+ * 根据是否提供自定义读取函数，选择相应的读取方式。
+ *
+ * @param filePath - 文件绝对路径
+ * @param transform - 代码转换钩子
+ * @returns 文件内容
+ */
+export declare function readFileContent(filePath: string, transform?: CodeTransformHook): string;

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

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview 文件读取工具模块
+ *
+ * 提供文件读取的默认实现和自定义读取函数的调用封装。
+ */
+import { readFileSync } from 'node:fs';
+/**
+ * 读取文件内容
+ *
+ * 根据是否提供自定义读取函数，选择相应的读取方式。
+ *
+ * @param filePath - 文件绝对路径
+ * @param transform - 代码转换钩子
+ * @returns 文件内容
+ */
+export function readFileContent(filePath, transform) {
+    const content = readFileSync(filePath, 'utf-8');
+    if (transform) {
+        return transform(content, filePath);
+    }
+    return content;
+}

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

@@ -0,0 +1,8 @@
+import type { RouteNode } from '../types/index.js';
+/**
+ * 查找路由
+ *
+ * @param routes - 路由列表
+ * @param path - 路径
+ */
+export declare function findRoute(routes: RouteNode[], path: string): RouteNode | null;

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

@@ -0,0 +1,22 @@
+/**
+ * 查找路由
+ *
+ * @param routes - 路由列表
+ * @param path - 路径
+ */
+export function findRoute(routes, path) {
+    for (const route of routes) {
+        if (!route.isGroup && route.fullPath === path)
+            return route;
+        if (route.isGroup && route.children) {
+            for (const child of route.children) {
+                if (child.fullPath === path)
+                    return route;
+                if (child.isGroup && child.children) {
+                    return findRoute(child.children, path);
+                }
+            }
+        }
+    }
+    return null;
+}

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

@@ -6,5 +6,7 @@
 export * from './pathUtils.js';
 export * from './babelUtils.js';
 export * from './logger.js';
-export * from './namingStrategy.js';
-export * from './validateOptions.js';
+export * from './pathStrategy.js';
+export * from '../config/validate.js';
+export * from './fileReader.js';
+export * from './findRoute.js';

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

@@ -6,5 +6,7 @@
 export * from './pathUtils.js';
 export * from './babelUtils.js';
 export * from './logger.js';
-export * from './namingStrategy.js';
-export * from './validateOptions.js';
+export * from './pathStrategy.js';
+export * from '../config/validate.js';
+export * from './fileReader.js';
+export * from './findRoute.js';

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

@@ -7,9 +7,9 @@
 /**
  * 设置日志上下文
  *
- * @param context - 上下文名称
+ * @param prefix - 前缀字符串
  */
-export declare function setLogPrefix(context: string): void;
+export declare function setLogPrefix(prefix: string): void;
 /**
  * 启用/禁用调试日志
  *
@@ -24,7 +24,7 @@ export declare function setDebugEnabled(enabled: boolean): void;
  * @param message 日志消息
  * @param details 详细信息（可选）
  */
-export declare function info(message: string, details?: string): void;
+export declare function info(message: string, details?: unknown): void;
 /**
  * 警告级日志
  *
@@ -33,7 +33,7 @@ export declare function info(message: string, details?: string): void;
  * @param message 日志消息
  * @param details 详细信息（可选）
  */
-export declare function warn(message: string, details?: string): void;
+export declare function warn(message: string, details?: unknown): void;
 /**
  * 错误级日志
  *
@@ -42,7 +42,7 @@ export declare function warn(message: string, details?: string): void;
  * @param message 日志消息
  * @param details 详细信息（可选）
  */
-export declare function error(message: string, details?: string): void;
+export declare function error(message: string, details?: unknown): void;
 /**
  * 调试级日志
  *
@@ -51,4 +51,4 @@ export declare function error(message: string, details?: string): void;
  * @param message 日志消息
  * @param details 详细信息（可选）
  */
-export declare function debug(message: string, details?: string): void;
+export declare function debug(message: string, details?: unknown): void;

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

@@ -16,10 +16,10 @@ let debugEnabled = false;
 /**
  * 设置日志上下文
  *
- * @param context - 上下文名称
+ * @param prefix - 前缀字符串
  */
-export function setLogPrefix(context) {
-    globalLogPrefix = context;
+export function setLogPrefix(prefix) {
+    globalLogPrefix = prefix;
 }
 /**
  * 启用/禁用调试日志
@@ -61,6 +61,45 @@ function getLevelColor(level) {
             return chalk.white;
     }
 }
+/**
+ * 格式化错误信息
+ * @param error 错误对象
+ * @returns 格式化后的错误字符串
+ */
+function formatError(error) {
+    const lines = [];
+    lines.push(`${chalk.red(error.name)}: ${error.message}`);
+    if (error.stack) {
+        const stackLines = error.stack
+            .split('\n')
+            .slice(1, 4)
+            .map(line => line.trim())
+            .filter(Boolean);
+        if (stackLines.length > 0) {
+            lines.push(chalk.gray(stackLines.join('\n    ')));
+        }
+    }
+    return lines.join('\n    ');
+}
+/**
+ * 格式化详细信息
+ * @param details 详细信息
+ * @returns 格式化后的字符串
+ */
+function formatDetails(details) {
+    if (details instanceof Error) {
+        return formatError(details);
+    }
+    if (details && (Array.isArray(details) || typeof details === 'object')) {
+        try {
+            return JSON.stringify(details, null, 2);
+        }
+        catch {
+            return String(details);
+        }
+    }
+    return String(details);
+}
 /**
  * 基础日志函数
  * @param level 日志级别
@@ -75,7 +114,8 @@ function log(level, message, details) {
     const levelColor = getLevelColor(level);
     const prefix = `${chalk.gray(timestamp)} ${chalk.cyan(`[${globalLogPrefix}]`)}`;
     const levelTag = chalk.gray(`(${level})`);
-    const detailsPart = details ? `\n    ${chalk.gray(details)}` : '';
+    const formattedDetails = details !== undefined ? formatDetails(details) : '';
+    const detailsPart = formattedDetails ? `\n    ${chalk.gray(formattedDetails)}` : '';
     console.log(`${prefix} ${levelTag} ${levelColor(message)}${detailsPart}`);
 }
 /**

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview 命名策略工具模块
+ *
+ * 提供路由名称和路径的命名转换功能，支持三种策略：
+ * - kebab: 将驼峰命名转换为 kebab-case（默认）
+ * - lowercase: 简单转换为小写
+ * - none: 保持原始命名
+ *
+ * 注意：只处理路径段名称，不处理动态参数变量名。
+ */
+import type { PathStrategy } from '../types/index.js';
+/**
+ * 应用命名策略转换路由路径
+ *
+ * 只处理路径段名称，不处理动态参数变量名。
+ *
+ * @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 applyPathStrategy(path: string, strategy: PathStrategy): string;