vitarx-router 4.0.0-beta.6 → 4.0.0-beta.8

package/dist/core/router/checkOptions.d.ts

@@ -0,0 +1,11 @@
+import type { RouterOptions } from '../types/index.js';
+/**
+ * 检查路由器配置选项的合法性
+ *
+ * 在开发环境下对用户传入的 RouterOptions 进行校验，
+ * 确保必填字段存在、类型正确、值合法。
+ *
+ * @param options - 用户传入的路由器配置对象
+ * @throws {Error} 当选项不合法时抛出错误
+ */
+export declare const checkRouterOptions: (options: RouterOptions) => void;

package/dist/core/router/checkOptions.js

@@ -0,0 +1,119 @@
+import { isComponent, isFunction } from 'vitarx';
+import { RouteManager } from './manager.js';
+/**
+ * 检查路由器配置选项的合法性
+ *
+ * 在开发环境下对用户传入的 RouterOptions 进行校验，
+ * 确保必填字段存在、类型正确、值合法。
+ *
+ * @param options - 用户传入的路由器配置对象
+ * @throws {Error} 当选项不合法时抛出错误
+ */
+export const checkRouterOptions = (options) => {
+    // 1. 检查 options 是否为对象
+    if (typeof options !== 'object' || options === null) {
+        throw new Error('[Router] Router options must be an object.');
+    }
+    // 2. 检查 routes 是否存在且为有效类型
+    if (!('routes' in options) || options.routes === undefined) {
+        throw new Error('[Router] "routes" is a required option.');
+    }
+    if (!Array.isArray(options.routes) && !(options.routes instanceof RouteManager)) {
+        throw new Error('[Router] "routes" must be an array or a RouteManager instance.');
+    }
+    // 3. 检查 mode 的值是否合法
+    if ('mode' in options && options.mode !== undefined) {
+        const validModes = ['hash', 'path'];
+        if (!validModes.includes(options.mode)) {
+            throw new Error(`[Router] "mode" must be one of: ${validModes.join(', ')}. Received "${options.mode}".`);
+        }
+    }
+    // 4. 检查 base 的格式
+    if ('base' in options && options.base !== undefined) {
+        if (typeof options.base !== 'string') {
+            throw new Error('[Router] "base" must be a string.');
+        }
+        if (!options.base.startsWith('/')) {
+            throw new Error('[Router] "base" must start with a slash (/).');
+        }
+    }
+    // 5. 检查 suffix 的格式
+    if ('suffix' in options && options.suffix !== undefined) {
+        if (typeof options.suffix !== 'string') {
+            throw new Error('[Router] "suffix" must be a string.');
+        }
+        if (!options.suffix.startsWith('.')) {
+            throw new Error('[Router] "suffix" must start with a dot (.).');
+        }
+        if (options.suffix === '.') {
+            throw new Error('[Router] "suffix" cannot be just a dot, please provide a valid extension like ".html".');
+        }
+    }
+    // 6. 检查 props 的类型
+    if ('props' in options && options.props !== undefined) {
+        if (typeof options.props !== 'boolean' && !isFunction(options.props)) {
+            throw new Error('[Router] "props" must be a boolean or function.');
+        }
+    }
+    // 7. 检查 scrollBehavior 的类型
+    if ('scrollBehavior' in options && options.scrollBehavior !== undefined) {
+        if (!isFunction(options.scrollBehavior)) {
+            throw new Error('[Router] "scrollBehavior" must be a function.');
+        }
+    }
+    // 8. 检查钩子函数的类型
+    if ('beforeEach' in options && options.beforeEach !== undefined) {
+        if (!isFunction(options.beforeEach) && !Array.isArray(options.beforeEach)) {
+            throw new Error('[Router] "beforeEach" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.beforeEach)) {
+            options.beforeEach.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "beforeEach" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    if ('afterEach' in options && options.afterEach !== undefined) {
+        if (!isFunction(options.afterEach) && !Array.isArray(options.afterEach)) {
+            throw new Error('[Router] "afterEach" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.afterEach)) {
+            options.afterEach.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "afterEach" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    if ('onNotFound' in options && options.onNotFound !== undefined) {
+        if (!isFunction(options.onNotFound) && !Array.isArray(options.onNotFound)) {
+            throw new Error('[Router] "onNotFound" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.onNotFound)) {
+            options.onNotFound.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "onNotFound" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    if ('onError' in options && options.onError !== undefined) {
+        if (!isFunction(options.onError) && !Array.isArray(options.onError)) {
+            throw new Error('[Router] "onError" must be a function or an array of functions.');
+        }
+        if (Array.isArray(options.onError)) {
+            options.onError.forEach((hook, index) => {
+                if (!isFunction(hook)) {
+                    throw new Error(`[Router] "onError" must be a function or an array of functions. Index: ${index}`);
+                }
+            });
+        }
+    }
+    // 9. 检查 missing 组件的类型
+    if ('missing' in options && options.missing !== undefined) {
+        if (!isComponent(options.missing)) {
+            throw new Error('[Router] "missing" must be a valid component.');
+        }
+    }
+};

package/dist/core/router/router.d.ts

@@ -1,6 +1,47 @@
 import { App, type ReadonlyObject } from 'vitarx';
 import type { AfterCallback, NavigateResult, NavigationGuard, NavOptions, NavTarget, ResolvedRouterConfig, Route, RouteIndex, RouteLocation, RouteRecord, RouterOptions, ScrollPosition, ScrollTarget, URLHash, URLQuery } from '../types/index.js';
 import { RouteManager } from './manager.js';
+/**
+ * 导航上下文
+ *
+ * 在每次导航过程中创建，封装该次导航所需的所有状态和操作。
+ * 作为各导航阶段处理方法之间的共享数据载体，避免方法间传递大量独立参数。
+ *
+ * @internal
+ */
+export interface NavigationContext {
+    /** 当前导航任务的唯一标识，用于并发导航竞争检测 */
+    taskId: number;
+    /** 导航结果对象，各阶段处理方法可修改其 state 和 message */
+    result: NavigateResult;
+    /** 目标路由位置，匹配失败时为 null */
+    to: RouteLocation | null;
+    /** 来源路由位置 */
+    from: RouteLocation;
+    /** 重定向来源路由位置，仅在重定向链中存在 */
+    redirectFrom: RouteLocation | undefined;
+    /** 是否替换当前历史记录（而非推入新记录） */
+    replace: boolean;
+    /**
+     * 检测重定向循环
+     *
+     * 每次重定向时调用，递增重定向计数器。
+     * 当重定向次数超过最大限制时抛出错误，防止无限循环。
+     *
+     * @param path - 重定向目标路径，用于错误信息
+     * @throws {Error} 当重定向次数超过 MAX_REDIRECTS 时
+     */
+    checkRedirectLoop: (path: string) => void;
+    /**
+     * 检测并发导航竞争
+     *
+     * 判断当前导航任务是否已被更新的导航任务取代。
+     * 如果已被取代，则将结果状态标记为 cancelled。
+     *
+     * @returns true 表示当前导航已被新导航取代，应中止执行
+     */
+    hasChanged: () => boolean;
+}
 /**
  * 路由器抽象基类
  *
@@ -257,8 +298,115 @@ export declare abstract class Router {
      * @returns 返回标准的导航结果 Promise
      */
     private initialNavigation;
+    /**
+     * 创建导航上下文
+     *
+     * 在每次导航开始时构建上下文对象，封装该次导航所需的所有状态：
+     * - 生成唯一任务ID，用于并发导航竞争检测
+     * - 重置重定向计数器（非重定向场景下）
+     * - 执行路由匹配，确定目标路由位置
+     * - 构建 NavigateResult 基础对象
+     * - 提供 checkRedirectLoop 和 hasChanged 闭包方法
+     *
+     * @param target - 导航目标
+     * @param fromRoute - 来源路由，默认使用当前路由位置
+     * @param redirectFrom - 重定向来源路由
+     * @returns 导航上下文对象
+     */
+    private createNavigationContext;
+    /**
+     * 处理路由未匹配（404）场景
+     *
+     * 当目标路由无法匹配时执行：
+     * 1. 触发全局 onNotFound 钩子
+     * 2. 如果钩子返回了新的导航目标，进行重定向
+     * 3. 否则返回 notfound 状态
+     *
+     * @param context - 导航上下文
+     * @param target - 原始导航目标
+     * @returns 导航结果
+     */
+    private handleNotFound;
+    /**
+     * 处理重复路由场景
+     *
+     * 当目标路由与当前路由的 href 和最终匹配记录完全相同时，
+     * 视为重复导航，返回 duplicated 状态，不执行后续流程。
+     *
+     * @param context - 导航上下文
+     * @returns 重复路由结果，或 null 表示非重复路由
+     */
+    private handleDuplicatedRoute;
+    /**
+     * 处理仅 hash 变化场景
+     *
+     * 当路由路径和查询参数相同，仅 hash 部分发生变化时，
+     * 直接更新 hash 值并触发 hashUpdate 回调，不执行完整的导航流程。
+     *
+     * @param context - 导航上下文
+     * @returns hash 变化结果，或 null 表示非仅 hash 变化
+     */
+    private handleHashOnlyChange;
+    /**
+     * 处理路由重定向场景
+     *
+     * 当目标路由配置了 redirect 字段时，解析重定向目标并递归执行导航：
+     * 1. 支持 redirect 为函数（动态重定向）或静态值
+     * 2. 重定向目标可以是路由索引（RouteIndex）或导航目标（NavTarget）
+     * 3. 如果重定向配置无效且无组件定义，抛出错误
+     *
+     * @param context - 导航上下文
+     * @returns 重定向导航结果，或 null 表示无需重定向
+     */
+    private handleRedirect;
+    /**
+     * 执行守卫流程
+     *
+     * 按顺序执行路由离开守卫和全局前置守卫，
+     * 在每个异步守卫执行后进行并发竞争检测。
+     * 如果守卫拦截导航或触发重定向，返回对应结果；
+     * 如果守卫全部通过，返回 null 表示继续导航。
+     *
+     * @param context - 导航上下文
+     * @returns 守卫拦截/重定向结果，或 null 表示守卫全部通过
+     */
+    private executeGuards;
+    /**
+     * 处理前置守卫执行结果
+     *
+     * 根据守卫返回值决定导航走向：
+     * - false: 拦截导航，返回 aborted 状态
+     * - NavTarget: 重定向到新目标
+     * - 其他（true/void）: 放行，继续导航
+     *
+     * @param context - 导航上下文
+     * @param guardResult - 前置守卫的返回值
+     * @returns 拦截/重定向结果，或 null 表示守卫通过
+     */
+    private handleGuardResult;
+    /**
+     * 完成导航流程
+     *
+     * 守卫全部通过后执行最后的导航确认：
+     * 1. 根据替换标记更新历史记录（push 或 replace）
+     * 2. 调用 completeNavigation 更新路由状态、触发后置钩子和滚动行为
+     *
+     * @param context - 导航上下文
+     * @returns 导航成功结果
+     */
+    private finalizeNavigation;
     /**
      * 导航到指定位置
+     *
+     * 作为导航流程的编排器，按顺序协调各场景处理方法的执行：
+     * 1. 创建导航上下文（路由匹配、并发控制初始化）
+     * 2. 处理 404 场景（路由未匹配）
+     * 3. 处理重复路由场景
+     * 4. 处理仅 hash 变化场景
+     * 5. 处理路由重定向场景
+     * 6. 执行守卫流程（离开守卫 → 前置守卫）
+     * 7. 完成导航（更新历史记录、触发后置钩子）
+     *
      * @param target - 导航目标对象 | 路由位置对象
      * @param fromRoute - 来源路由对象
      * @param redirectFrom - 重定向来源对象