refactor(router-core): flatten loadRouteMatch, can run synchronously

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

@@ -131,7 +131,9 @@ type loader = (
     location: ParsedLocation
     params: TAllParams
     preload: boolean
-    parentMatchPromise: Promise<MakeRouteMatchFromRoute<TParentRoute>>
+    parentMatchPromise:
+      | Promise<MakeRouteMatchFromRoute<TParentRoute>>
+      | MakeRouteMatchFromRoute<TParentRoute>
     navigate: NavigateFn<AnyRoute> // @deprecated
     route: AnyRoute
   },
@@ -144,6 +146,7 @@ type loader = (
 - If this function returns a promise, the route will be put into a pending state and cause rendering to suspend until the promise resolves. If this route's pendingMs threshold is reached, the `pendingComponent` will be shown until it resolves. If the promise rejects, the route will be put into an error state and the error will be thrown during render.
 - If this function returns a `TLoaderData` object, that object will be stored on the route match until the route match is no longer active. It can be accessed using the `useLoaderData` hook in any component that is a child of the route match before another `<Outlet />` is rendered.
 - Deps must be returned by your `loaderDeps` function in order to appear.
+- `parentMatchPromise` is a promise _if_ the parent route's `loader` returns a promise as well, otherwise it is the resolved parent match object.
 
 > 🚧 `opts.navigate` has been deprecated and will be removed in the next major release. Use `throw redirect({ to: '/somewhere' })` instead. Read more about the `redirect` function [here](../redirectFunction.md).
 

packages/router-core/src/load-matches.ts

@@ -4,6 +4,7 @@ import { createControlledPromise, isPromise } from './utils'
 import { isNotFound } from './not-found'
 import { rootRouteId } from './root'
 import { isRedirect } from './redirect'
+import type { Awaitable } from './utils'
 import type { NotFoundError } from './not-found'
 import type { ParsedLocation } from './location'
 import type {
@@ -34,7 +35,7 @@ type InnerLoadContext = {
   onReady?: () => Promise<void>
   sync?: boolean
   /** mutable state, scoped to a `loadMatches` call */
-  matchPromises: Array<Promise<AnyRouteMatch>>
+  matchPromises: Array<Awaitable<AnyRouteMatch>>
 }
 
 const triggerOnReady = (inner: InnerLoadContext): void | Promise<void> => {
@@ -703,135 +704,167 @@ const runLoader = async (
   }
 }
 
-const loadRouteMatch = async (
+const loadRouteMatch = (
   inner: InnerLoadContext,
   index: number,
-): Promise<AnyRouteMatch> => {
+): Awaitable<AnyRouteMatch> => {
   const { id: matchId, routeId } = inner.matches[index]!
-  let loaderShouldRunAsync = false
-  let loaderIsRunningAsync = false
   const route = inner.router.looseRoutesById[routeId]!
+  const prevMatch = inner.router.getMatch(matchId)!
+  let loaderIsRunningAsync = false
+  let nextPreload: undefined | boolean
 
   if (shouldSkipLoader(inner, matchId)) {
     if (inner.router.isServer) {
       const headResult = executeHead(inner, matchId, route)
       if (headResult) {
-        const head = await headResult
-        inner.updateMatch(matchId, (prev) => ({
-          ...prev,
-          ...head,
-        }))
+        return headResult.then((head) => {
+          inner.updateMatch(matchId, (prev) => ({
+            ...prev,
+            ...head,
+          }))
+          return inner.router.getMatch(matchId)!
+        })
       }
-      return inner.router.getMatch(matchId)!
+      return prevMatch
     }
-  } else {
-    const prevMatch = inner.router.getMatch(matchId)!
-    // there is a loaderPromise, so we are in the middle of a load
-    if (prevMatch._nonReactive.loaderPromise) {
-      // do not block if we already have stale data we can show
-      // but only if the ongoing load is not a preload since error handling is different for preloads
-      // and we don't want to swallow errors
-      if (prevMatch.status === 'success' && !inner.sync && !prevMatch.preload) {
-        return prevMatch
-      }
-      await prevMatch._nonReactive.loaderPromise
+    return settleLoadRouteMatch()
+  }
+
+  // there is a loaderPromise, so we are in the middle of a load
+  if (prevMatch._nonReactive.loaderPromise) {
+    // do not block if we already have stale data we can show
+    // but only if the ongoing load is not a preload since error handling is different for preloads
+    // and we don't want to swallow errors
+    if (prevMatch.status === 'success' && !inner.sync && !prevMatch.preload) {
+      return prevMatch
+    }
+    return prevMatch._nonReactive.loaderPromise.then(() => {
       const match = inner.router.getMatch(matchId)!
       if (match.error) {
         handleRedirectAndNotFound(inner, match, match.error)
       }
-    } else {
-      // This is where all of the stale-while-revalidate magic happens
-      const age = Date.now() - prevMatch.updatedAt
-
-      const preload = resolvePreload(inner, matchId)
-
-      const staleAge = preload
-        ? (route.options.preloadStaleTime ??
-          inner.router.options.defaultPreloadStaleTime ??
-          30_000) // 30 seconds for preloads by default
-        : (route.options.staleTime ??
-          inner.router.options.defaultStaleTime ??
-          0)
-
-      const shouldReloadOption = route.options.shouldReload
-
-      // Default to reloading the route all the time
-      // Allow shouldReload to get the last say,
-      // if provided.
-      const shouldReload =
-        typeof shouldReloadOption === 'function'
-          ? shouldReloadOption(getLoaderContext(inner, matchId, index, route))
-          : shouldReloadOption
-
-      const nextPreload =
-        !!preload && !inner.router.state.matches.some((d) => d.id === matchId)
-      const match = inner.router.getMatch(matchId)!
-      match._nonReactive.loaderPromise = createControlledPromise<void>()
-      if (nextPreload !== match.preload) {
-        inner.updateMatch(matchId, (prev) => ({
-          ...prev,
-          preload: nextPreload,
-        }))
-      }
+      return settleLoadRouteMatch()
+    })
+  }
+
+  // This is where all of the stale-while-revalidate magic happens
+  const age = Date.now() - prevMatch.updatedAt
+
+  const preload = resolvePreload(inner, matchId)
 
-      // If the route is successful and still fresh, just resolve
-      const { status, invalid } = match
-      loaderShouldRunAsync =
-        status === 'success' && (invalid || (shouldReload ?? age > staleAge))
-      if (preload && route.options.preload === false) {
-        // Do nothing
-      } else if (loaderShouldRunAsync && !inner.sync) {
-        loaderIsRunningAsync = true
-        ;(async () => {
-          try {
-            await runLoader(inner, matchId, index, route)
-            const match = inner.router.getMatch(matchId)!
-            match._nonReactive.loaderPromise?.resolve()
-            match._nonReactive.loadPromise?.resolve()
-            match._nonReactive.loaderPromise = undefined
-          } catch (err) {
-            if (isRedirect(err)) {
-              await inner.router.navigate(err.options)
-            }
-          }
-        })()
-      } else if (status !== 'success' || (loaderShouldRunAsync && inner.sync)) {
+  const staleAge = preload
+    ? (route.options.preloadStaleTime ??
+      inner.router.options.defaultPreloadStaleTime ??
+      30_000) // 30 seconds for preloads by default
+    : (route.options.staleTime ?? inner.router.options.defaultStaleTime ?? 0)
+
+  const shouldReloadOption = route.options.shouldReload
+
+  // Default to reloading the route all the time
+  // Allow shouldReload to get the last say,
+  // if provided.
+  const shouldReload =
+    typeof shouldReloadOption === 'function'
+      ? shouldReloadOption(getLoaderContext(inner, matchId, index, route))
+      : shouldReloadOption
+
+  nextPreload =
+    !!preload && !inner.router.state.matches.some((d) => d.id === matchId)
+  prevMatch._nonReactive.loaderPromise = createControlledPromise<void>()
+
+  if (preload && route.options.preload === false) {
+    // Do nothing
+    return settleLoadRouteMatch()
+  }
+
+  // If the route is successful and still fresh, just resolve
+  const { status, invalid } = prevMatch
+  const loaderShouldRunAsync =
+    status === 'success' && (invalid || (shouldReload ?? age > staleAge))
+  if (loaderShouldRunAsync && !inner.sync) {
+    loaderIsRunningAsync = true
+    ;(async () => {
+      try {
         await runLoader(inner, matchId, index, route)
-      } else {
-        // if the loader did not run, still update head.
-        // reason: parent's beforeLoad may have changed the route context
-        // and only now do we know the route context (and that the loader would not run)
-        const headResult = executeHead(inner, matchId, route)
-        if (headResult) {
-          const head = await headResult
-          inner.updateMatch(matchId, (prev) => ({
-            ...prev,
-            ...head,
-          }))
+        const match = inner.router.getMatch(matchId)!
+        match._nonReactive.loaderPromise?.resolve()
+        match._nonReactive.loadPromise?.resolve()
+        match._nonReactive.loaderPromise = undefined
+      } catch (err) {
+        if (isRedirect(err)) {
+          await inner.router.navigate(err.options)
         }
       }
-    }
+    })()
+    return settleLoadRouteMatch()
   }
-  const match = inner.router.getMatch(matchId)!
-  if (!loaderIsRunningAsync) {
-    match._nonReactive.loaderPromise?.resolve()
-    match._nonReactive.loadPromise?.resolve()
+
+  if (status !== 'success' || (loaderShouldRunAsync && inner.sync)) {
+    updatePreload()
+    return runLoader(inner, matchId, index, route).then(settleLoadRouteMatch)
   }
 
-  clearTimeout(match._nonReactive.pendingTimeout)
-  match._nonReactive.pendingTimeout = undefined
-  if (!loaderIsRunningAsync) match._nonReactive.loaderPromise = undefined
-  match._nonReactive.dehydrated = undefined
-  const nextIsFetching = loaderIsRunningAsync ? match.isFetching : false
-  if (nextIsFetching !== match.isFetching || match.invalid !== false) {
-    inner.updateMatch(matchId, (prev) => ({
-      ...prev,
-      isFetching: nextIsFetching,
-      invalid: false,
-    }))
+  // if the loader did not run, still update head.
+  // reason: parent's beforeLoad may have changed the route context
+  // and only now do we know the route context (and that the loader would not run)
+  const headResult = executeHead(inner, matchId, route)
+  if (headResult) {
+    return headResult.then((head) => {
+      let result: ReturnType<typeof settleLoadRouteMatch>
+      batch(() => {
+        inner.updateMatch(matchId, (prev) => ({
+          ...prev,
+          ...head,
+        }))
+        result = settleLoadRouteMatch()
+      })
+      return result!
+    })
+  }
+
+  return settleLoadRouteMatch()
+
+  function updatePreload() {
+    if (nextPreload === undefined) return
+    if (nextPreload !== prevMatch.preload) {
+      const preload = nextPreload
+      inner.updateMatch(matchId, (prev) => ({
+        ...prev,
+        preload,
+      }))
+    }
+    nextPreload = undefined
+  }
+
+  function settleLoadRouteMatch() {
+    const match = inner.router.getMatch(matchId)!
+
+    if (!loaderIsRunningAsync) {
+      match._nonReactive.loaderPromise?.resolve()
+      match._nonReactive.loadPromise?.resolve()
+      match._nonReactive.loaderPromise = undefined
+    }
+
+    clearTimeout(match._nonReactive.pendingTimeout)
+    match._nonReactive.pendingTimeout = undefined
+    match._nonReactive.dehydrated = undefined
+
+    const nextIsFetching = loaderIsRunningAsync ? match.isFetching : false
+    if (nextIsFetching !== match.isFetching || match.invalid !== false) {
+      batch(() => {
+        updatePreload()
+        inner.updateMatch(matchId, (prev) => ({
+          ...prev,
+          isFetching: nextIsFetching,
+          invalid: false,
+        }))
+      })
+    } else {
+      updatePreload()
+    }
+
     return inner.router.getMatch(matchId)!
-  } else {
-    return match
   }
 }
 

packages/router-core/src/route.ts

@@ -24,6 +24,7 @@ import type {
   Expand,
   IntersectAssign,
   LooseAsyncReturnType,
+  LooseIsReturnPromise,
   LooseReturnType,
   NoInfer,
 } from './utils'
@@ -421,6 +422,11 @@ export interface RouteTypes<
   children: TChildren
   loaderData: ResolveLoaderData<TLoaderFn>
   loaderDeps: TLoaderDeps
+  asyncLoaderFn: unknown extends TLoaderFn
+    ? boolean
+    : LooseIsReturnPromise<TLoaderFn> extends never
+      ? boolean
+      : LooseIsReturnPromise<TLoaderFn>
   fileRouteTypes: TFileRouteTypes
 }
 
@@ -1236,7 +1242,9 @@ export interface LoaderFnContext<
   // root route does not have a parent match
   parentMatchPromise: TId extends RootRouteId
     ? never
-    : Promise<MakeRouteMatchFromRoute<TParentRoute>>
+    : TParentRoute['types']['asyncLoaderFn'] extends true
+      ? Promise<MakeRouteMatchFromRoute<TParentRoute>>
+      : MakeRouteMatchFromRoute<TParentRoute>
   cause: 'preload' | 'enter' | 'stay'
   route: AnyRoute
 }

packages/router-core/src/utils.ts

@@ -184,6 +184,14 @@ export type LooseAsyncReturnType<T> = T extends (
     : TReturn
   : never
 
+export type LooseIsReturnPromise<T> = T extends (
+  ...args: Array<any>
+) => infer TReturn
+  ? TReturn extends Promise<any>
+    ? true
+    : false
+  : never
+
 export function last<T>(arr: Array<T>) {
   return arr[arr.length - 1]
 }