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 the 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,14 @@ 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.
+- `useStore(router.internalStore, (s) => s.pendingMatches)` when you need access to pending route matches.
+
 ### `status` property
 
 - Type: `'pending' | 'idle'`
@@ -41,11 +48,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/useChildMatchesHook.md

@@ -6,7 +6,7 @@ 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`.
+> If the router has pending matches and they are showing their pending component fallbacks, an array of pending matches will be used instead of `router.state.matches`.
 
 ## useChildMatches options
 

docs/router/api/router/useParentMatchesHook.md

@@ -6,7 +6,7 @@ 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`.
+> If the router has pending matches and they are showing their pending component fallbacks, an array of pending matches will be used instead of `router.state.matches`.
 
 ## useParentMatches options
 

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

@@ -136,8 +136,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).toBeGreaterThanOrEqual(10) // WARN: this is flaky, and sometimes (rarely) is 12
-    expect(updates).toBeLessThanOrEqual(13)
+    expect(updates).toBe(8)
   })
 
   test('redirection in preload', async () => {
@@ -155,7 +154,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 +170,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).toBeGreaterThanOrEqual(9) // WARN: this is flaky
-    expect(updates).toBeLessThanOrEqual(12)
+    expect(updates).toBe(5)
   })
 
   test('nothing', async () => {
@@ -183,8 +181,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).toBeGreaterThanOrEqual(6) // WARN: this is flaky, and sometimes (rarely) is 9
-    expect(updates).toBeLessThanOrEqual(9)
+    expect(updates).toBe(3)
   })
 
   test('not found in beforeLoad', async () => {
@@ -199,7 +196,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 +222,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(15)
+    expect(updates).toBe(5)
   })
 
   test('navigate, w/ preloaded & async loaders', async () => {
@@ -241,8 +238,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).toBeGreaterThanOrEqual(7)
-    expect(updates).toBeLessThanOrEqual(8)
+    expect(updates).toBe(3)
   })
 
   test('navigate, w/ preloaded & sync loaders', async () => {
@@ -258,7 +254,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 +270,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 +288,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

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