@esmx/router 3.0.0-rc.27 → 3.0.0-rc.30

package/README.zh-CN.md

@@ -65,6 +65,87 @@ await router.push('/about');
 
 访问[官方文档](https://www.esmnext.com)获取详细的使用指南和 API 参考。
 
+### 路由导航时大致的流程说明
+
+```mermaid
+flowchart TD
+  start(["Start"]):::Terminal --> normalizeURL["normalizeURL"]
+  normalizeURL --> isExternalUrl{"是站内地址"}:::Decision
+  isExternalUrl -- Yes --> matchInRouteTable["在路由表内匹配"]
+  isExternalUrl -- No --> fallback["fallback"] --> End
+  matchInRouteTable --> isExist{"存在匹配项"}:::Decision
+  isExist -- No --> fallback
+  isExist -- Yes --> execGuard["执行其他回调钩子/守卫"] --> End(["End"]):::Terminal
+  classDef Terminal fill:#FFF9C4,color:#000
+  classDef Decision fill:#C8E6C9,color:#000
+```
+
+#### 路由钩子管道
+
+|  | fallback | override | beforeLeave | beforeEach | beforeUpdate | beforeEnter | asyncComponent | confirm |
+|---------|----------|----------|-------------|------------|--------------|-------------|----------------|---------|
+| `push` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `replace` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `pushWindow` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| `pushLayer` | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| `replaceWindow` | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ |
+| `restartApp` | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `unknown` | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+
+```mermaid
+gantt
+  title 路由钩子执行对比
+  dateFormat X
+  axisFormat %s
+  section push<br>replace
+    fallback      :0, 1
+    override      :1, 2
+    beforeLeave   :2, 3
+    beforeEach    :3, 4
+    beforeUpdate  :4, 5
+    beforeEnter   :5, 6
+    asyncComponent:6, 7
+    confirm       :7, 8
+  section pushWindow<br>pushLayer
+    fallback      :0, 1
+    override      :1, 2
+    beforeEach    :3, 4
+    confirm       :7, 8
+  section replaceWindow
+    fallback      :0, 1
+    override      :1, 2
+    beforeLeave   :2, 3
+    beforeEach    :3, 4
+    confirm       :7, 8
+  section restartApp<br>unknown
+    fallback      :0, 1
+    beforeLeave   :2, 3
+    beforeEach    :3, 4
+    beforeUpdate  :4, 5
+    beforeEnter   :5, 6
+    asyncComponent:6, 7
+    confirm       :7, 8
+```
+
+#### 钩子函数说明
+
+- **fallback**: 处理未匹配的路由
+- **override**: 允许路由重写逻辑
+- **beforeLeave**: 离开当前路由前执行
+- **beforeEach**: 全局导航守卫
+- **beforeUpdate**: 路由更新前执行（相同组件）
+- **beforeEnter**: 进入新路由前执行
+- **asyncComponent**: 加载异步组件
+- **confirm**: 最终确认和导航执行
+
+#### 路由类型特点
+
+- **标准导航** (`push`、`replace`): 执行完整的钩子链
+- **窗口操作** (`pushWindow`、`replaceWindow`): 简化的钩子链，主要用于窗口级别的导航
+- **层级操作** (`pushLayer`): 最简化的钩子链，用于层级导航
+- **应用重启** (`restartApp`): 完整钩子链但跳过 override
+- **未知类型** (`unknown`): 完整钩子链但跳过 override，作为默认处理
+
 ## 📄 许可证
 
-MIT © [Esmx Team](https://github.com/esmnext/esmx) 
+MIT © [Esmx Team](https://github.com/esmnext/esmx)

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 export { Router } from './router';
 export { Route } from './route';
-export { RouteTransition, ROUTE_TYPE_HANDLERS } from './route-transition';
-export { type Awaitable, RouterMode, RouteType, type RouteConfirmHook, type RouteConfirmHookResult, type RouteVerifyHook, type RouteHandleHook, type RouteNotifyHook, type RouteMeta, type RouteState, type RouteHandleResult, type RouteMatchType, type RouteLocation, type RouteLocationInput, type RouteConfig, type RouteParsedConfig, type RouteMatchResult, type RouteMatcher, type RouteOptions, type RouteLayerOptions, type RouteLayerResult, type RouterLayerOptions, type RouterMicroApp, type RouterMicroAppCallback, type RouterMicroAppOptions, type RouterOptions, type RouterParsedOptions, type RouterLinkType, type RouterLinkAttributes, type RouterLinkProps, type RouterLinkResolved } from './types';
+export { RouterMode, RouteType, type RouteConfirmHook, type RouteConfirmHookResult, type RouteVerifyHook, type RouteHandleHook, type RouteNotifyHook, type RouteMeta, type RouteState, type RouteHandleResult, type RouteMatchType, type RouteLocation, type RouteLocationInput, type RouteConfig, type RouteParsedConfig, type RouteMatchResult, type RouteMatcher, type RouteOptions, type RouteLayerOptions, type RouteLayerResult, type RouterLayerOptions, type RouterMicroApp, type RouterMicroAppCallback, type RouterMicroAppOptions, type RouterOptions, type RouterParsedOptions, type RouterLinkType, type RouterLinkAttributes, type RouterLinkProps, type RouterLinkResolved } from './types';
 export { RouteError, RouteTaskCancelledError, RouteTaskExecutionError, RouteNavigationAbortedError, RouteSelfRedirectionError } from './error';

package/dist/index.mjs

@@ -1,6 +1,5 @@
 export { Router } from "./router.mjs";
 export { Route } from "./route.mjs";
-export { RouteTransition, ROUTE_TYPE_HANDLERS } from "./route-transition.mjs";
 export {
   RouterMode,
   RouteType

package/package.json

@@ -32,8 +32,8 @@
     },
     "devDependencies": {
         "@biomejs/biome": "1.9.4",
-        "@esmx/lint": "3.0.0-rc.27",
-        "@types/node": "^24.0.10",
+        "@esmx/lint": "3.0.0-rc.30",
+        "@types/node": "^24.0.0",
         "@vitest/coverage-v8": "3.2.4",
         "happy-dom": "^18.0.1",
         "stylelint": "16.21.0",
@@ -41,7 +41,7 @@
         "unbuild": "3.5.0",
         "vitest": "3.2.4"
     },
-    "version": "3.0.0-rc.27",
+    "version": "3.0.0-rc.30",
     "type": "module",
     "private": false,
     "exports": {
@@ -60,5 +60,5 @@
         "template",
         "public"
     ],
-    "gitHead": "79ce8ceea4a9c738d9ebeb4607d925fc411d3df1"
+    "gitHead": "0bc6815e4a805e552e67a245201a4a75599f58f5"
 }

package/src/index.ts

@@ -1,9 +1,6 @@
 export { Router } from './router';
 export { Route } from './route';
-export { RouteTransition, ROUTE_TYPE_HANDLERS } from './route-transition';
 export {
-    // Utility types
-    type Awaitable,
     // Core enums
     RouterMode,
     RouteType,

package/dist/index.test.d.ts

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

package/dist/index.test.mjs

@@ -1,8 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { Router as IndexRouter } from "./index.mjs";
-import { Router } from "./router.mjs";
-describe("index exports", () => {
-  it("should export Router correctly", () => {
-    expect(IndexRouter).toBe(Router);
-  });
-});

package/dist/location.test.d.ts

@@ -1,8 +0,0 @@
-declare module 'vitest' {
-    interface ToEqURLMatchers {
-        toEqURL(expected: URL | string): void;
-    }
-    interface Assertion extends ToEqURLMatchers {
-    }
-}
-export {};

package/dist/location.test.mjs

@@ -1,370 +0,0 @@
-import { describe, expect, test } from "vitest";
-import { normalizeURL, parseLocation } from "./location.mjs";
-expect.extend({
-  toEqURL: (received, expected) => {
-    if (!(received instanceof URL)) {
-      return {
-        message: () => "expected ".concat(received, " to be an instance of URL"),
-        pass: false
-      };
-    }
-    (received = new URL(received)).searchParams.sort();
-    (expected = new URL(expected)).searchParams.sort();
-    received.hash = received.hash;
-    expected.hash = expected.hash;
-    return {
-      message: () => "expected ".concat(received.href, " to be ").concat(expected.href),
-      pass: received.href === expected.href
-    };
-  }
-});
-describe("normalizeURL", () => {
-  const testCases = [
-    {
-      input: "//example.com/path",
-      base: "https://github.com",
-      expected: "http://example.com/path",
-      description: "should handle protocol-relative URLs (starting with //)"
-    },
-    {
-      input: "http://github.com/path?a#h",
-      base: "http://example.com",
-      expected: "http://github.com/path?a#h",
-      description: "should handle absolute URLs"
-    },
-    {
-      input: "/path",
-      base: "http://example.com/en/",
-      expected: "http://example.com/en/path",
-      description: "should handle relative paths with a base URL"
-    },
-    {
-      input: "github.com",
-      base: "http://example.com",
-      expected: "http://example.com/github.com",
-      description: "should treat bare domains as relative paths"
-    },
-    {
-      input: new URL("http://example.com/path"),
-      base: "http://example.com",
-      expected: "http://example.com/path",
-      description: "should handle URL objects"
-    },
-    {
-      input: "-a://example.com",
-      base: "http://example.com",
-      expected: "http://example.com/-a://example.com",
-      description: "should treat strings that fail to parse as a protocol as relative paths"
-    }
-  ];
-  testCases.forEach(({ input, base, expected, description }) => {
-    test(description, () => {
-      const result = normalizeURL(input, new URL(base));
-      expect(result).toEqURL(expected);
-    });
-  });
-});
-describe("parseLocation", () => {
-  const testCases = [
-    {
-      input: "/products",
-      base: "http://example.com",
-      expected: "http://example.com/products",
-      description: "should handle string paths"
-    },
-    {
-      input: { path: "/products" },
-      base: "http://example.com",
-      expected: "http://example.com/products",
-      description: "should handle objects with a path property"
-    },
-    {
-      input: { url: "/products" },
-      base: "http://example.com",
-      expected: "http://example.com/products",
-      description: "should handle objects with a url property"
-    },
-    {
-      input: {
-        path: "/products",
-        query: { id: "123", category: "electronics" }
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=123&category=electronics",
-      description: "should handle objects with query parameters"
-    },
-    {
-      input: { path: "/products", query: { id: "123" }, hash: "details" },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=123#details",
-      description: "should handle objects with a hash"
-    },
-    {
-      input: { path: "/products", queryArray: { tag: ["new", "sale"] } },
-      base: "http://example.com",
-      expected: "http://example.com/products?tag=new&tag=sale",
-      description: "should handle objects with queryArray"
-    },
-    {
-      input: {
-        path: "/products",
-        query: { id: "123", category: "electronics" },
-        queryArray: { tag: ["new", "sale"] },
-        hash: "details"
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=123&category=electronics&tag=new&tag=sale#details",
-      description: "should handle complex objects with all properties"
-    },
-    {
-      input: {
-        path: "/products",
-        hash: "#a?a"
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products#a?a",
-      description: "should handle special hash characters correctly"
-    },
-    {
-      input: {
-        path: "/products",
-        hash: "#a?a#b"
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products#a?a#b",
-      description: "should handle special hash characters correctly"
-    },
-    {
-      input: {
-        path: "/products",
-        query: {
-          id: null,
-          category: void 0,
-          symbol: Symbol(),
-          fn: async () => "",
-          obj: { a: 10 },
-          big: /* @__PURE__ */ BigInt("12345678901234567891234567890123456789"),
-          a: Number.NaN,
-          b: "",
-          c: "0",
-          d: 0,
-          e: 1
-        }
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products?symbol=Symbol()&fn=".concat(String(
-        async () => ""
-      ), "&obj=").concat(String({}), "&big=12345678901234567891234567890123456789&b&c=0&d=0&e=1"),
-      description: "should ignore null, undefined, and NaN query parameters"
-    },
-    {
-      input: { path: "/products", queryArray: { tag: [] } },
-      base: "http://example.com",
-      expected: "http://example.com/products",
-      description: "should handle empty queryArray"
-    },
-    {
-      input: {
-        path: "/products?id=path&a",
-        query: { id: "query" }
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=query&a",
-      description: "query value should override query parameter in path"
-    },
-    {
-      input: {
-        path: "/products?id=path&a",
-        query: { id: "query" },
-        queryArray: { id: ["queryArray"] }
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=queryArray&a",
-      description: "queryArray value should override query and path parameters"
-    },
-    {
-      input: {
-        path: "/products?id=path&a",
-        queryArray: { id: ["queryArray"] }
-      },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=queryArray&a",
-      description: "queryArray value should override query parameter in path"
-    },
-    {
-      input: {
-        path: "?a&a=&a&a",
-        query: { a: "" },
-        queryArray: { a: ["", ""] }
-      },
-      base: "http://example.com",
-      expected: "http://example.com?a&a",
-      description: "should handle empty strings and duplicate query parameters correctly"
-    },
-    {
-      input: { path: "/products?id=123", url: "/products?id=456" },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=123",
-      description: "path should take priority over url when both are present"
-    },
-    {
-      input: { url: "/products?id=456" },
-      base: "http://example.com",
-      expected: "http://example.com/products?id=456",
-      description: "url should be used when path is not present"
-    },
-    {
-      input: {},
-      base: "http://example.com",
-      expected: "http://example.com/",
-      description: "empty input object should default to base URL"
-    }
-  ];
-  testCases.forEach(({ input, base, expected, description }) => {
-    test(description, () => {
-      const result = parseLocation(input, new URL(base));
-      expect(result).toEqURL(expected);
-    });
-  });
-});
-describe("normalizeURL more", () => {
-  describe.for(
-    // biome-ignore format:
-    Object.entries({
-      "https://www.esmx.dev": {
-        "/": "https://www.esmx.dev/",
-        "/new": "https://www.esmx.dev/new",
-        "/new/": "https://www.esmx.dev/new/",
-        "/new/100": "https://www.esmx.dev/new/100",
-        "/new/100/": "https://www.esmx.dev/new/100/",
-        "..": "https://www.esmx.dev/",
-        "../": "https://www.esmx.dev/",
-        "../new": "https://www.esmx.dev/new",
-        "../new/": "https://www.esmx.dev/new/",
-        "../new/100": "https://www.esmx.dev/new/100",
-        "../new/100/": "https://www.esmx.dev/new/100/",
-        "": "https://www.esmx.dev/",
-        "new": "https://www.esmx.dev/new",
-        "new/": "https://www.esmx.dev/new/",
-        "new/100": "https://www.esmx.dev/new/100",
-        "new/100/": "https://www.esmx.dev/new/100/",
-        ".": "https://www.esmx.dev/",
-        "./": "https://www.esmx.dev/",
-        "./new": "https://www.esmx.dev/new",
-        "./new/": "https://www.esmx.dev/new/",
-        "./new/100": "https://www.esmx.dev/new/100",
-        "./new/100/": "https://www.esmx.dev/new/100/",
-        ".a": "https://www.esmx.dev/.a",
-        "..a": "https://www.esmx.dev/..a",
-        ".a/": "https://www.esmx.dev/.a/",
-        "..a/": "https://www.esmx.dev/..a/",
-        "new/../.": "https://www.esmx.dev/"
-      },
-      "https://www.esmx.dev/": {
-        "/": "https://www.esmx.dev/",
-        "/new": "https://www.esmx.dev/new",
-        "/new/": "https://www.esmx.dev/new/",
-        "/new/100": "https://www.esmx.dev/new/100",
-        "/new/100/": "https://www.esmx.dev/new/100/",
-        "..": "https://www.esmx.dev/",
-        "../": "https://www.esmx.dev/",
-        "../new": "https://www.esmx.dev/new",
-        "../new/": "https://www.esmx.dev/new/",
-        "../new/100": "https://www.esmx.dev/new/100",
-        "../new/100/": "https://www.esmx.dev/new/100/",
-        "": "https://www.esmx.dev/",
-        "new": "https://www.esmx.dev/new",
-        "new/": "https://www.esmx.dev/new/",
-        "new/100": "https://www.esmx.dev/new/100",
-        "new/100/": "https://www.esmx.dev/new/100/",
-        ".": "https://www.esmx.dev/",
-        "./": "https://www.esmx.dev/",
-        "./new": "https://www.esmx.dev/new",
-        "./new/": "https://www.esmx.dev/new/",
-        "./new/100": "https://www.esmx.dev/new/100",
-        "./new/100/": "https://www.esmx.dev/new/100/",
-        ".a": "https://www.esmx.dev/.a",
-        "..a": "https://www.esmx.dev/..a",
-        ".a/": "https://www.esmx.dev/.a/",
-        "..a/": "https://www.esmx.dev/..a/",
-        "new/../.": "https://www.esmx.dev/"
-      },
-      "https://www.esmx.dev/a/b/c": {
-        "/": "https://www.esmx.dev/a/b/",
-        "/new": "https://www.esmx.dev/a/b/new",
-        "/new/": "https://www.esmx.dev/a/b/new/",
-        "/new/100": "https://www.esmx.dev/a/b/new/100",
-        "/new/100/": "https://www.esmx.dev/a/b/new/100/",
-        "..": "https://www.esmx.dev/a/",
-        "../": "https://www.esmx.dev/a/",
-        "../new": "https://www.esmx.dev/a/new",
-        "../new/": "https://www.esmx.dev/a/new/",
-        "../new/100": "https://www.esmx.dev/a/new/100",
-        "../new/100/": "https://www.esmx.dev/a/new/100/",
-        "": "https://www.esmx.dev/a/b/c",
-        "new": "https://www.esmx.dev/a/b/new",
-        "new/": "https://www.esmx.dev/a/b/new/",
-        "new/100": "https://www.esmx.dev/a/b/new/100",
-        "new/100/": "https://www.esmx.dev/a/b/new/100/",
-        ".": "https://www.esmx.dev/a/b/",
-        "./": "https://www.esmx.dev/a/b/",
-        "./new": "https://www.esmx.dev/a/b/new",
-        "./new/": "https://www.esmx.dev/a/b/new/",
-        "./new/100": "https://www.esmx.dev/a/b/new/100",
-        "./new/100/": "https://www.esmx.dev/a/b/new/100/",
-        ".a": "https://www.esmx.dev/a/b/.a",
-        "..a": "https://www.esmx.dev/a/b/..a",
-        ".a/": "https://www.esmx.dev/a/b/.a/",
-        "..a/": "https://www.esmx.dev/a/b/..a/",
-        "new/../.": "https://www.esmx.dev/a/b/",
-        "new/.././a/../../x/": "https://www.esmx.dev/a/x/"
-      },
-      "https://www.esmx.dev/a/b/c/": {
-        "/": "https://www.esmx.dev/a/b/c/",
-        "/new": "https://www.esmx.dev/a/b/c/new",
-        "/new/": "https://www.esmx.dev/a/b/c/new/",
-        "/new/100": "https://www.esmx.dev/a/b/c/new/100",
-        "/new/100/": "https://www.esmx.dev/a/b/c/new/100/",
-        "..": "https://www.esmx.dev/a/b/",
-        "../": "https://www.esmx.dev/a/b/",
-        "../new": "https://www.esmx.dev/a/b/new",
-        "../new/": "https://www.esmx.dev/a/b/new/",
-        "../new/100": "https://www.esmx.dev/a/b/new/100",
-        "../new/100/": "https://www.esmx.dev/a/b/new/100/",
-        "": "https://www.esmx.dev/a/b/c/",
-        "new": "https://www.esmx.dev/a/b/c/new",
-        "new/": "https://www.esmx.dev/a/b/c/new/",
-        "new/100": "https://www.esmx.dev/a/b/c/new/100",
-        "new/100/": "https://www.esmx.dev/a/b/c/new/100/",
-        ".": "https://www.esmx.dev/a/b/c/",
-        "./": "https://www.esmx.dev/a/b/c/",
-        "./new": "https://www.esmx.dev/a/b/c/new",
-        "./new/": "https://www.esmx.dev/a/b/c/new/",
-        "./new/100": "https://www.esmx.dev/a/b/c/new/100",
-        "./new/100/": "https://www.esmx.dev/a/b/c/new/100/",
-        ".a": "https://www.esmx.dev/a/b/c/.a",
-        "..a": "https://www.esmx.dev/a/b/c/..a",
-        ".a/": "https://www.esmx.dev/a/b/c/.a/",
-        "..a/": "https://www.esmx.dev/a/b/c/..a/",
-        "new/.././": "https://www.esmx.dev/a/b/c/",
-        "new/.././a/../../x/": "https://www.esmx.dev/a/b/x/"
-      }
-    })
-  )("base: $0", ([base, cases]) => {
-    test.each(Object.entries(cases))("input: $0", (input, expected) => {
-      const url = normalizeURL(input, new URL(base));
-      expect(url).toEqURL(expected);
-      const pathSuffix = "?a&b=1&c=2&a=&a=4&base=10#hash";
-      const urlWithSuffix = normalizeURL(
-        input + pathSuffix,
-        new URL(base)
-      );
-      expect(urlWithSuffix).toEqURL(expected + pathSuffix);
-      const urlWithBaseSuffix = normalizeURL(
-        input + pathSuffix,
-        new URL(base + "?base=base#base")
-      );
-      expect(urlWithBaseSuffix).toEqURL(expected + pathSuffix);
-    });
-  });
-});

package/dist/matcher.test.d.ts

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