reafactor(router-core): remove cachedMatches and pendingMatches from store

docs/router/api/router/RouterStateType.md

@@ -3,15 +3,14 @@ id: RouterStateType
 title: RouterState type
 ---
 
-The `RouterState` type represents shape of the internal state of the router. The Router's internal state is useful, if you need to access certain internals of the router, such as any pending matches, is the router in its loading state, etc.
+The `RouterState` type represents shape of the internal state of the router. The Router's internal state is useful if you need to access certain internals of the router, such as whether it is currently loading.
 
 ```tsx
 type RouterState = {
   status: 'pending' | 'idle'
   isLoading: boolean
   isTransitioning: boolean
   matches: Array<RouteMatch>
-  pendingMatches: Array<RouteMatch>
   location: ParsedLocation
   resolvedLocation: ParsedLocation
 }
@@ -21,6 +20,16 @@ type RouterState = {
 
 The `RouterState` type contains all of the properties that are available on the router state.
 
+## Migration notes
+
+If you previously used `router.state.pendingMatches`, use one of these patterns instead:
+
+- `router.state.status === 'pending'` to detect an in-flight navigation.
+- `router.state.isLoading` to detect active loading work.
+- `router.matchRoute(...)` with `{ pending: true }` when you need to match against the pending location.
+
+If you previously used `router.state.cachedMatches`, note that cached matches are now internal router state and are no longer exposed on `RouterState`.
+
 ### `status` property
 
 - Type: `'pending' | 'idle'`
@@ -41,11 +50,6 @@ The `RouterState` type contains all of the properties that are available on the
 - Type: [`Array<RouteMatch>`](./RouteMatchType.md)
 - An array of all of the route matches that have been resolved and are currently active.
 
-### `pendingMatches` property
-
-- Type: [`Array<RouteMatch>`](./RouteMatchType.md)
-- An array of all of the route matches that are currently pending.
-
 ### `location` property
 
 - Type: [`ParsedLocation`](./ParsedLocationType.md)

docs/router/api/router/RouterType.md

@@ -152,6 +152,7 @@ Invalidates route matches by forcing their `beforeLoad` and `load` functions to
 Remove cached route matches.
 
 - Type: `(opts?: {filter?: (d: MakeRouteMatchUnion<TRouter>) => boolean}) => void`
+- Cached matches are stored internally and are no longer exposed on `router.state`.
 - if `filter` is not supplied, all cached matches will be removed
 - if `filter` is supplied, only matches for which `filter` returns `true` will be removed.
 

docs/router/api/router/useChildMatchesHook.md

@@ -5,9 +5,6 @@ title: useChildMatches hook
 
 The `useChildMatches` hook returns all of the child [`RouteMatch`](./RouteMatchType.md) objects from the closest match down to the leaf-most match. **It does not include the current match, which can be obtained using the `useMatch` hook.**
 
-> [!IMPORTANT]
-> If the router has pending matches and they are showing their pending component fallbacks, `router.state.pendingMatches` will used instead of `router.state.matches`.
-
 ## useChildMatches options
 
 The `useChildMatches` hook accepts a single _optional_ argument, an `options` object.

docs/router/api/router/useParentMatchesHook.md

@@ -5,9 +5,6 @@ title: useParentMatches hook
 
 The `useParentMatches` hook returns all of the parent [`RouteMatch`](./RouteMatchType.md) objects from the root down to the immediate parent of the current match in context. **It does not include the current match, which can be obtained using the `useMatch` hook.**
 
-> [!IMPORTANT]
-> If the router has pending matches and they are showing their pending component fallbacks, `router.state.pendingMatches` will used instead of `router.state.matches`.
-
 ## useParentMatches options
 
 The `useParentMatches` hook accepts an optional `options` object.

docs/router/api/router/useRouterStateHook.md

@@ -7,6 +7,8 @@ The `useRouterState` method is a hook that returns the current internal state of
 
 > [!TIP]
 > If you want to access the current location or the current matches, you should try out the [`useLocation`](./useLocationHook.md) and [`useMatches`](./useMatchesHook.md) hooks first. These hooks are designed to be more ergonomic and easier to use than accessing the router state directly.
+>
+> Cached route matches are internal router state and are not exposed through `useRouterState`.
 
 ## useRouterState options
 

packages/react-router/tests/store-updates-during-navigation.test.tsx

@@ -136,8 +136,8 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBeGreaterThanOrEqual(10) // WARN: this is flaky, and sometimes (rarely) is 12
-    expect(updates).toBeLessThanOrEqual(13)
+    expect(updates).toBeGreaterThanOrEqual(8)
+    expect(updates).toBeLessThanOrEqual(11)
   })
 
   test('redirection in preload', async () => {
@@ -155,7 +155,7 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBe(4)
+    expect(updates).toBe(1)
   })
 
   test('sync beforeLoad', async () => {
@@ -171,8 +171,8 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBeGreaterThanOrEqual(9) // WARN: this is flaky
-    expect(updates).toBeLessThanOrEqual(12)
+    expect(updates).toBeGreaterThanOrEqual(4)
+    expect(updates).toBeLessThanOrEqual(6)
   })
 
   test('nothing', async () => {
@@ -183,8 +183,8 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBeGreaterThanOrEqual(6) // WARN: this is flaky, and sometimes (rarely) is 9
-    expect(updates).toBeLessThanOrEqual(9)
+    expect(updates).toBeGreaterThanOrEqual(3)
+    expect(updates).toBeLessThanOrEqual(5)
   })
 
   test('not found in beforeLoad', async () => {
@@ -199,7 +199,7 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBe(7)
+    expect(updates).toBe(2)
   })
 
   test('hover preload, then navigate, w/ async loaders', async () => {
@@ -225,7 +225,8 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBe(16)
+    expect(updates).toBeGreaterThanOrEqual(5)
+    expect(updates).toBeLessThanOrEqual(7)
   })
 
   test('navigate, w/ preloaded & async loaders', async () => {
@@ -241,8 +242,8 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBeGreaterThanOrEqual(7)
-    expect(updates).toBeLessThanOrEqual(8)
+    expect(updates).toBeGreaterThanOrEqual(3)
+    expect(updates).toBeLessThanOrEqual(4)
   })
 
   test('navigate, w/ preloaded & sync loaders', async () => {
@@ -258,7 +259,7 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBe(6)
+    expect(updates).toBe(3)
   })
 
   test('navigate, w/ previous navigation & async loader', async () => {
@@ -274,7 +275,7 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBe(5)
+    expect(updates).toBe(3)
   })
 
   test('preload a preloaded route w/ async loader', async () => {
@@ -292,6 +293,6 @@ describe("Store doesn't update *too many* times during navigation", () => {
     // This number should be as small as possible to minimize the amount of work
     // that needs to be done during a navigation.
     // Any change that increases this number should be investigated.
-    expect(updates).toBe(1)
+    expect(updates).toBe(0)
   })
 })

packages/router-core/src/index.ts

@@ -221,6 +221,7 @@ export type {
   MatchRouteFn,
   RouterContextOptions,
   RouterOptions,
+  InternalStoreState,
   RouterConstructorOptions,
   UpdateFn,
   ParseLocationFn,