feat(react-router): add method to selectively removed cached matches

docs/framework/react/api/router/RouterType.md

@@ -134,9 +134,17 @@ Invalidates route matches by forcing their `beforeLoad` and `load` functions to
 - Type: `(opts?: {filter?: (d: MakeRouteMatch<TRouteTree>) => boolean}) => Promise<void>`
 - This is useful any time your loader data might be out of date or stale. For example, if you have a route that displays a list of posts, and you have a loader function that fetches the list of posts from an API, you might want to invalidate the route matches for that route any time a new post is created so that the list of posts is always up-to-date.
 - if `filter` is not supplied, all matches will be invalidated
-- if `filter` is supplied, only matches for which `filter` returns `true` will be invalidate.
+- if `filter` is supplied, only matches for which `filter` returns `true` will be invalidated.
 - You might also want to invalidate the Router if you imperatively `reset` the router's `CatchBoundary` to trigger loaders again.
 
+### `.removeCachedMatches` method
+
+Remove cached route matches.
+
+- Type: `(opts?: {filter?: (d: MakeRouteMatch<TRouteTree>) => boolean}) => void`
+- 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.
+
 ### `.load` method
 
 Loads all of the currently matched route matches and resolves when they are all loaded and ready to be rendered.

packages/react-router/src/router.ts

@@ -1789,7 +1789,7 @@ export class Router<
           this.__store.batch(() => {
             // this call breaks a route context of destination route after a redirect
             // we should be fine not eagerly calling this since we call it later
-            // this.cleanCache()
+            // this.clearExpiredCache()
 
             // Match the routes
             pendingMatches = this.matchRoutes(next)
@@ -1867,7 +1867,7 @@ export class Router<
                       ],
                     }
                   })
-                  this.cleanCache()
+                  this.clearExpiredCache()
                 })
 
                 //
@@ -2560,31 +2560,47 @@ export class Router<
     return redirect
   }
 
-  cleanCache = () => {
+  clearCache = (opts?: {
+    filter?: (d: MakeRouteMatch<TRouteTree>) => boolean
+  }) => {
+    const filter = opts?.filter
+    if (filter !== undefined) {
+      this.__store.setState((s) => {
+        return {
+          ...s,
+          cachedMatches: s.cachedMatches.filter((m) => !filter(m)),
+        }
+      })
+    } else {
+      this.__store.setState((s) => {
+        return {
+          ...s,
+          cachedMatches: [],
+        }
+      })
+    }
+  }
+
+  clearExpiredCache = () => {
     // This is where all of the garbage collection magic happens
-    this.__store.setState((s) => {
-      return {
-        ...s,
-        cachedMatches: s.cachedMatches.filter((d) => {
-          const route = this.looseRoutesById[d.routeId]!
+    const filter = (d: MakeRouteMatch<TRouteTree>) => {
+      const route = this.looseRoutesById[d.routeId]!
 
-          if (!route.options.loader) {
-            return false
-          }
+      if (!route.options.loader) {
+        return true
+      }
 
-          // If the route was preloaded, use the preloadGcTime
-          // otherwise, use the gcTime
-          const gcTime =
-            (d.preload
-              ? (route.options.preloadGcTime ??
-                this.options.defaultPreloadGcTime)
-              : (route.options.gcTime ?? this.options.defaultGcTime)) ??
-            5 * 60 * 1000
+      // If the route was preloaded, use the preloadGcTime
+      // otherwise, use the gcTime
+      const gcTime =
+        (d.preload
+          ? (route.options.preloadGcTime ?? this.options.defaultPreloadGcTime)
+          : (route.options.gcTime ?? this.options.defaultGcTime)) ??
+        5 * 60 * 1000
 
-          return d.status !== 'error' && Date.now() - d.updatedAt < gcTime
-        }),
-      }
-    })
+      return !(d.status !== 'error' && Date.now() - d.updatedAt < gcTime)
+    }
+    this.clearCache({ filter })
   }
 
   preloadRoute = async <