@esmx/router 3.0.0-rc.17 → 3.0.0-rc.19

package/dist/router-window-navigation.test.mjs

@@ -0,0 +1,359 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { Router } from "./router.mjs";
+import { RouteType } from "./types.mjs";
+describe("Router Window Navigation Tests", () => {
+  let router;
+  let mockApps;
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockApps = {
+      home: vi.fn(() => ({
+        mount: vi.fn(),
+        unmount: vi.fn(),
+        renderToString: vi.fn().mockResolvedValue("<div>Home</div>")
+      })),
+      about: vi.fn(() => ({
+        mount: vi.fn(),
+        unmount: vi.fn(),
+        renderToString: vi.fn().mockResolvedValue("<div>About</div>")
+      })),
+      user: vi.fn(() => ({
+        mount: vi.fn(),
+        unmount: vi.fn(),
+        renderToString: vi.fn().mockResolvedValue("<div>User</div>")
+      }))
+    };
+    router = new Router({
+      routes: [
+        { path: "/", app: "home" },
+        { path: "/about", app: "about" },
+        { path: "/user/:id", app: "user" }
+      ],
+      apps: mockApps
+    });
+  });
+  function createWindowNavigationTests(methodName, expectedIsPush) {
+    describe(`\u{1FA9F} ${methodName} Core Functionality Tests`, () => {
+      it(`should support using current route path`, async () => {
+        await router.push("/about");
+        const result = await router[methodName]("/about");
+        expect(result.type).toBe(RouteType[methodName]);
+        expect(result.path).toBe("/about");
+        expect(result.isPush).toBe(expectedIsPush);
+        expect(result.handle).not.toBeNull();
+      });
+      it(`should support string path parameters`, async () => {
+        const result = await router[methodName]("/user/123");
+        expect(result.type).toBe(RouteType[methodName]);
+        expect(result.path).toBe("/user/123");
+        expect(result.params.id).toBe("123");
+        expect(result.isPush).toBe(expectedIsPush);
+        expect(result.handle).not.toBeNull();
+      });
+      it(`should support object parameters`, async () => {
+        const result = await router[methodName]({
+          path: "/user/456",
+          query: { tab: "profile" },
+          hash: "section1"
+        });
+        expect(result.type).toBe(RouteType[methodName]);
+        expect(result.path).toBe("/user/456");
+        expect(result.params.id).toBe("456");
+        expect(result.query.tab).toBe("profile");
+        expect(result.url.hash).toBe("#section1");
+        expect(result.isPush).toBe(expectedIsPush);
+        expect(result.handle).not.toBeNull();
+      });
+      it(`should correctly handle complete URLs`, async () => {
+        const result = await router[methodName](
+          "https://example.com/user/789?sort=name#top"
+        );
+        expect(result.type).toBe(RouteType[methodName]);
+        expect(result.url.href).toBe(
+          "https://example.com/user/789?sort=name#top"
+        );
+        expect(result.isPush).toBe(expectedIsPush);
+        expect(result.handle).not.toBeNull();
+      });
+    });
+    describe(`\u{1F3AF} ${methodName} Specific Behavior Tests`, () => {
+      it(`should set correct isPush flag`, async () => {
+        const result = await router[methodName]("/about");
+        expect(result.isPush).toBe(expectedIsPush);
+        expect(result.type).toBe(RouteType[methodName]);
+      });
+      it(`should call location handler`, async () => {
+        let locationCalled = false;
+        let receivedRoute = null;
+        const windowRouter = new Router({
+          routes: [{ path: "/", app: "home" }],
+          apps: mockApps,
+          fallback: (to, from) => {
+            locationCalled = true;
+            receivedRoute = to;
+            return { windowNavigation: true };
+          }
+        });
+        await windowRouter.push("/");
+        const result = await windowRouter[methodName]("/about");
+        expect(locationCalled).toBe(true);
+        expect(receivedRoute.isPush).toBe(expectedIsPush);
+        expect(result.handleResult).toEqual({ windowNavigation: true });
+        windowRouter.destroy();
+      });
+      it(`should not update current route state`, async () => {
+        await router.push("/about");
+        const beforeRoute = router.route;
+        await router[methodName]("/user/123");
+        const afterRoute = router.route;
+        expect(afterRoute.path).toBe(beforeRoute.path);
+        expect(afterRoute.url.href).toBe(beforeRoute.url.href);
+      });
+      it(`should not trigger MicroApp update`, async () => {
+        const updateSpy = vi.spyOn(router.microApp, "_update");
+        await router[methodName]("/user/123");
+        expect(updateSpy).not.toHaveBeenCalled();
+      });
+    });
+    describe(`\u{1F6E1}\uFE0F ${methodName} Route Guards Tests`, () => {
+      it(`should execute beforeEach guards`, async () => {
+        let guardCalled = false;
+        const unregister = router.beforeEach(async (to, from) => {
+          guardCalled = true;
+          expect(to.isPush).toBe(expectedIsPush);
+        });
+        await router[methodName]("/about");
+        expect(guardCalled).toBe(true);
+        unregister();
+      });
+      it(`should abort navigation when guard returns false`, async () => {
+        const unregister = router.beforeEach((to, from) => {
+          return false;
+        });
+        await expect(router[methodName]("/about")).rejects.toThrow(
+          "Navigation was aborted"
+        );
+        unregister();
+      });
+      it(`should support guard redirects`, async () => {
+        const unregister = router.beforeEach(async (to) => {
+          if (to.path === "/about") {
+            return "/user/redirect";
+          }
+        });
+        const result = await router[methodName]("/about");
+        expect(result.path).toBe("/user/redirect");
+        expect(result.params.id).toBe("redirect");
+        unregister();
+      });
+      it(`should execute afterEach guards`, async () => {
+        let guardCalled = false;
+        const unregister = router.afterEach((to, from) => {
+          guardCalled = true;
+          expect(to.isPush).toBe(expectedIsPush);
+        });
+        await router[methodName]("/about");
+        expect(guardCalled).toBe(true);
+        unregister();
+      });
+    });
+    describe(`\u{1F3AD} ${methodName} Edge Cases Tests`, () => {
+      it(`should handle non-existent routes`, async () => {
+        const result = await router[methodName]("/nonexistent");
+        expect(result.handle).not.toBeNull();
+        expect(result.matched.length).toBe(0);
+        expect(result.isPush).toBe(expectedIsPush);
+      });
+      it(`should handle empty string path`, async () => {
+        const result = await router[methodName]("");
+        expect(result.handle).not.toBeNull();
+        expect(result.isPush).toBe(expectedIsPush);
+      });
+      it(`should handle special characters`, async () => {
+        const result = await router[methodName](
+          "/user/\u6D4B\u8BD5\u7528\u6237?name=\u5F20\u4E09&age=25#\u4E2A\u4EBA\u4FE1\u606F"
+        );
+        expect(result.handle).not.toBeNull();
+        expect(result.isPush).toBe(expectedIsPush);
+        expect(result.url.pathname).toContain(
+          "%E6%B5%8B%E8%AF%95%E7%94%A8%E6%88%B7"
+        );
+      });
+    });
+    describe(`\u26A1 ${methodName} Task Cancellation and Concurrency Control`, () => {
+      it(`should support concurrent calls`, async () => {
+        const promises = [
+          router[methodName]("/user/1").catch((err) => err),
+          router[methodName]("/user/2").catch((err) => err),
+          router[methodName]("/user/3").catch((err) => err)
+        ];
+        const results = await Promise.all(promises);
+        const successResults = results.filter(
+          (r) => !(r instanceof Error) && r.handle !== null
+        );
+        const errorResults = results.filter((r) => r instanceof Error);
+        expect(successResults.length).toBeGreaterThan(0);
+        expect(successResults.length + errorResults.length).toBe(3);
+        successResults.forEach((result) => {
+          expect(result.isPush).toBe(expectedIsPush);
+        });
+      });
+      it(`should correctly handle rapid consecutive calls`, async () => {
+        const results = [];
+        for (let i = 0; i < 5; i++) {
+          results.push(await router[methodName](`/user/${i}`));
+        }
+        results.forEach((result, index) => {
+          expect(result.handle).not.toBeNull();
+          expect(result.params.id).toBe(String(index));
+          expect(result.isPush).toBe(expectedIsPush);
+        });
+      });
+    });
+    describe(`\u274C ${methodName} Error Handling`, () => {
+      it(`should handle exceptions in guards`, async () => {
+        const unregister = router.beforeEach(async () => {
+          throw new Error("Guard error");
+        });
+        await expect(router[methodName]("/about")).rejects.toThrow();
+        unregister();
+      });
+      it(`should handle location handler exceptions`, async () => {
+        const windowRouter = new Router({
+          routes: [{ path: "/", app: "home" }],
+          apps: mockApps,
+          fallback: () => {
+            throw new Error("Location handler error");
+          }
+        });
+        await windowRouter.push("/");
+        await expect(
+          windowRouter[methodName]("/about")
+        ).rejects.toThrow();
+        windowRouter.destroy();
+      });
+    });
+    describe(`\u{1F9E9} ${methodName} Async Component Handling`, () => {
+      it(`should correctly handle async components`, async () => {
+        const asyncRouter = new Router({
+          routes: [
+            {
+              path: "/async",
+              app: "home",
+              asyncComponent: async () => {
+                await new Promise(
+                  (resolve) => setTimeout(resolve, 10)
+                );
+                return () => "AsyncComponent";
+              }
+            }
+          ],
+          apps: mockApps,
+          fallback: (to, from) => {
+            return { windowNavigation: true };
+          }
+        });
+        const result = await asyncRouter[methodName]("/async");
+        expect(result.handle).not.toBeNull();
+        expect(result.isPush).toBe(expectedIsPush);
+        expect(result.matched[0].component).toBeUndefined();
+        expect(result.matched[0].asyncComponent).toBeDefined();
+        expect(result.handleResult).toEqual({ windowNavigation: true });
+        asyncRouter.destroy();
+      });
+      it(`should handle async component loading failures`, async () => {
+        const asyncRouter = new Router({
+          routes: [
+            {
+              path: "/async-error",
+              app: "home",
+              asyncComponent: async () => {
+                throw new Error("Component load failed");
+              }
+            }
+          ],
+          apps: mockApps,
+          fallback: (to, from) => {
+            return { fallbackHandled: true };
+          }
+        });
+        const result = await asyncRouter[methodName]("/async-error");
+        expect(result.handle).not.toBeNull();
+        expect(result.matched[0].component).toBeUndefined();
+        expect(result.matched[0].asyncComponent).toBeDefined();
+        expect(result.handleResult).toEqual({ fallbackHandled: true });
+        asyncRouter.destroy();
+      });
+    });
+    describe(`\u{1F527} ${methodName} Differences from Other Methods`, () => {
+      it(`should behave differently from push/replace methods`, async () => {
+        await router.push("/about");
+        const pushResult = await router.push("/user/123");
+        const windowResult = await router[methodName]("/user/456");
+        expect(router.route.path).toBe("/user/123");
+        expect(windowResult.isPush).toBe(expectedIsPush);
+        expect(windowResult.type).toBe(RouteType[methodName]);
+        expect(pushResult.type).toBe(RouteType.push);
+        expect(windowResult.type).toBe(RouteType[methodName]);
+      });
+      it(`should maintain consistency with resolve method in URL parsing`, async () => {
+        const resolvedRoute = router.resolve("/user/789");
+        const windowRoute = await router[methodName]("/user/789");
+        expect(windowRoute.url.href).toBe(resolvedRoute.url.href);
+        expect(windowRoute.params).toEqual(resolvedRoute.params);
+        expect(windowRoute.matched).toEqual(resolvedRoute.matched);
+        expect(windowRoute.type).toBe(RouteType[methodName]);
+        expect(resolvedRoute.type).toBe(RouteType.push);
+        expect(windowRoute.isPush).toBe(expectedIsPush);
+        expect(resolvedRoute.isPush).toBe(true);
+      });
+    });
+  }
+  createWindowNavigationTests("pushWindow", true);
+  createWindowNavigationTests("replaceWindow", false);
+  describe("\u{1F504} pushWindow and replaceWindow Comparison Tests", () => {
+    it("the only difference between the two methods should be the isPush flag", async () => {
+      const pushResult = await router.pushWindow("/user/123");
+      const replaceResult = await router.replaceWindow("/user/123");
+      expect(pushResult.url.href).toBe(replaceResult.url.href);
+      expect(pushResult.params).toEqual(replaceResult.params);
+      expect(pushResult.query).toEqual(replaceResult.query);
+      expect(pushResult.url.hash).toBe(replaceResult.url.hash);
+      expect(pushResult.matched).toEqual(replaceResult.matched);
+      expect(pushResult.isPush).toBe(true);
+      expect(replaceResult.isPush).toBe(false);
+      expect(pushResult.type).toBe(RouteType.pushWindow);
+      expect(replaceResult.type).toBe(RouteType.replaceWindow);
+    });
+    it("both methods should call the same location handler", async () => {
+      const locationCalls = [];
+      const windowRouter = new Router({
+        routes: [{ path: "/", app: "home" }],
+        apps: mockApps,
+        fallback: (to, from) => {
+          locationCalls.push({
+            method: to.type,
+            isPush: to.isPush,
+            path: to.path
+          });
+          return { called: true };
+        }
+      });
+      await windowRouter.push("/");
+      await windowRouter.pushWindow("/test");
+      await windowRouter.replaceWindow("/test");
+      expect(locationCalls).toHaveLength(2);
+      expect(locationCalls[0]).toEqual({
+        method: "pushWindow",
+        isPush: true,
+        path: "/test"
+      });
+      expect(locationCalls[1]).toEqual({
+        method: "replaceWindow",
+        isPush: false,
+        path: "/test"
+      });
+      windowRouter.destroy();
+    });
+  });
+});

package/dist/router.d.ts

@@ -1,111 +1,118 @@
-import { type HistoryState, type NavigationGuard, type NavigationGuardAfter, type RegisteredConfig, type RegisteredConfigMap, type Route, type RouteRecord, type RouterBase, type RouterHistory, type RouterInitOptions, type RouterInstance, type RouterMatcher, RouterMode, type RouterOptions, type RouterRawLocation, type RouterScrollBehavior } from './types';
-/**
- * 路由类
- */
-export declare class Router implements RouterInstance {
-    /**
-     * 当前路由对象的上级路由对象
-     */
-    parent: RouterInstance | null;
-    options: RouterOptions;
-    /**
-     * 路由固定前置路径
-     * 需要注意的是如果使用函数返回 base，需要尽量保证相同的路径返回相同base
-     */
-    base: RouterBase;
-    mode: RouterMode;
-    matcher: RouterMatcher;
-    history: RouterHistory;
-    scrollBehavior: RouterScrollBehavior;
-    route: Route;
+import { MicroApp } from './micro-app';
+import { Navigation } from './navigation';
+import { Route } from './route';
+import { RouteTransition } from './route-transition';
+import { RouteType } from './types';
+import type { RouteConfirmHook, RouteLayerResult, RouteLocationInput, RouteMatchType, RouteNotifyHook, RouterLinkProps, RouterLinkResolved, RouterOptions, RouterParsedOptions } from './types';
+export declare class Router {
+    readonly options: RouterOptions;
+    readonly parsedOptions: RouterParsedOptions;
+    readonly isLayer: boolean;
+    readonly navigation: Navigation;
+    readonly microApp: MicroApp;
+    readonly transition: RouteTransition;
+    get route(): Route;
+    get root(): string | HTMLElement;
+    get req(): import("http").IncomingMessage | null;
+    get res(): import("http").ServerResponse<import("http").IncomingMessage> | null;
     constructor(options: RouterOptions);
-    updateRoute(route: RouteRecord): void;
-    protected applyRoute(route: RouteRecord): void;
-    resolve(location: RouterRawLocation): RouteRecord;
+    push(toInput: RouteLocationInput): Promise<Route>;
+    replace(toInput: RouteLocationInput): Promise<Route>;
+    pushWindow(toInput: RouteLocationInput): Promise<Route>;
+    replaceWindow(toInput: RouteLocationInput): Promise<Route>;
+    restartApp(toInput?: RouteLocationInput): Promise<Route>;
+    back(): Promise<Route | null>;
+    go(index: number): Promise<Route | null>;
+    forward(): Promise<Route | null>;
     /**
-     * 新增单个路由匹配规则
+     * Parse route location without performing actual navigation
+     *
+     * This method is used to parse route configuration and return the corresponding route object,
+     * but does not trigger actual page navigation. It is mainly used for the following scenarios:
+     * - Generate link URLs without jumping
+     * - Pre-check route matching
+     * - Get route parameters, meta information, etc.
+     * - Test the validity of route configuration
+     *
+     * @param toInput Target route location, can be a string path or route configuration object
+     * @returns Parsed route object containing complete route information
+     *
+     * @example
+     * ```typescript
+     * // Parse string path
+     * const route = router.resolve('/user/123');
+     * const url = route.url.href; // Get complete URL
+     *
+     * // Parse named route
+     * const userRoute = router.resolve({
+     *   name: 'user',
+     *   params: { id: '123' }
+     * });
+     * console.log(userRoute.params.id); // '123'
+     *
+     * // Check route validity
+     * const testRoute = router.resolve('/some/path');
+     * if (testRoute.matched.length > 0) {
+     *   // Route matched successfully
+     * }
+     * ```
      */
+    resolve(toInput: RouteLocationInput, toType?: RouteType): Route;
     /**
-     * 新增多个路由匹配规则
+     * Check if the route matches the current route
+     *
+     * @param targetRoute Target route object to compare
+     * @param matchType Match type
+     * - 'route': Route-level matching, compare if route configurations are the same
+     * - 'exact': Exact matching, compare if paths are completely the same
+     * - 'include': Include matching, check if current path contains target path
+     * @returns Whether it matches
      */
-    init(options?: RouterInitOptions): Promise<void>;
+    isRouteMatched(targetRoute: Route, matchType?: RouteMatchType): boolean;
     /**
-     * 卸载方法
+     * Resolve router link configuration and return complete link data
+     *
+     * This method analyzes router link properties and returns a comprehensive
+     * link resolution result including route information, navigation functions,
+     * HTML attributes, and event handlers. It's primarily used for:
+     * - Framework-agnostic link component implementation
+     * - Generating link attributes and navigation handlers
+     * - Computing active states and CSS classes
+     * - Creating event handlers for different frameworks
+     *
+     * @param props Router link configuration properties
+     * @returns Complete link resolution result with all necessary data
+     *
+     * @example
+     * ```typescript
+     * // Basic link resolution
+     * const linkData = router.resolveLink({
+     *   to: '/user/123',
+     *   type: 'push'
+     * });
+     *
+     * // Access resolved data
+     * console.log(linkData.route.path); // '/user/123'
+     * console.log(linkData.attributes.href); // Full href URL
+     * console.log(linkData.isActive); // Active state
+     *
+     * // Use navigation function
+     * linkData.navigate(); // Programmatic navigation
+     *
+     * // Get event handlers for React
+     * const handlers = linkData.getEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
+     * // handlers.onClick for React
+     * ```
      */
-    destroy(): Promise<void>;
-    registeredConfigMap: RegisteredConfigMap;
-    register(name: string, config: (router: RouterInstance) => RegisteredConfig): void;
-    readonly guards: {
-        beforeEach: NavigationGuard[];
-        afterEach: NavigationGuardAfter[];
-    };
-    beforeEach(guard: NavigationGuard): void;
-    unBindBeforeEach(guard: NavigationGuard): void;
-    afterEach(guard: NavigationGuardAfter): void;
-    unBindAfterEach(guard: NavigationGuardAfter): void;
-    push(location: RouterRawLocation): Promise<void>;
-    replace(location: RouterRawLocation): Promise<void>;
-    /**
-     * 当前路由弹层id，用于区分不同的路由弹层
-     */
-    layerId: number;
-    /**
-     * 路由弹层配置
-     * key为路由弹层id
-     */
-    layerConfigList: Array<{
-        /**
-         * 路由弹层id
-         */
-        id: number;
-        /**
-         * 路由弹层深度
-         */
-        depth: number;
-    }>;
-    /**
-     * 路由弹层id与路由实例的map
-     */
-    layerMap: Record<number, {
-        router: RouterInstance;
-        config: RegisteredConfig;
-        destroyed: boolean;
+    resolveLink(props: RouterLinkProps): RouterLinkResolved;
+    createLayer(toInput: RouteLocationInput): Promise<{
+        promise: Promise<RouteLayerResult>;
+        router: Router;
     }>;
-    /**
-     * 路由是否冻结
-     */
-    isFrozen: boolean;
-    /**
-     * 路由冻结方法
-     */
-    freeze(): void;
-    /**
-     * 路由解冻方法
-     */
-    unfreeze(): void;
-    /**
-     * 打开路由弹层方法，会创建新的路由实例并调用注册的 register 方法
-     * 服务端会使用 push 作为替代
-     */
-    pushLayer(location: RouterRawLocation): Promise<void>;
-    /**
-     * 更新路由弹层方法
-     * @param state 参数为history.state
-     * @description 没有传入 state 时使用当前配置更新 history.state，传入了 state 时使用传入的 state 更新当前配置
-     */
-    checkLayerState(state: HistoryState): boolean;
-    updateLayerState(route: RouteRecord): void;
-    /**
-     * 新开浏览器窗口的方法，在服务端会调用 push 作为替代
-     */
-    pushWindow(location: RouterRawLocation): void;
-    /**
-     * 替换当前浏览器窗口的方法，在服务端会调用 replace 作为替代
-     */
-    replaceWindow(location: RouterRawLocation): void;
-    go(delta?: number): void;
-    forward(): void;
-    back(): void;
-    getRoutes(): any;
+    pushLayer(toInput: RouteLocationInput): Promise<RouteLayerResult>;
+    closeLayer(data?: any): void;
+    renderToString(throwError?: boolean): Promise<string | null>;
+    beforeEach(guard: RouteConfirmHook): () => void;
+    afterEach(guard: RouteNotifyHook): () => void;
+    destroy(): void;
 }
-export declare function createRouter(options: RouterOptions): RouterInstance;