perf(router-core): reduce navigation promise chains

.changeset/cool-streets-punch.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/router-core': patch
+---
+
+Reduce Promise allocations during client navigation and static server SSR policy resolution. Skip cancellable waits for synchronous beforeLoad results while preserving navigation cancellation.

packages/router-core/INTERNALS.md

@@ -339,6 +339,11 @@ uses the active preload entry as its additional authority.
 
 `beforeLoad` context is not a cache.
 
+Client `beforeLoad` only installs a cancellable wait for Promise results.
+Synchronous context still crosses an `await` before the cancellation check:
+a hook can queue a replacement navigation before its loader is planned.
+Promise detection assumes ordinary Promise behavior.
+
 A completed client preload never stores reusable `beforeLoad` output. When its
 loader data enters the route cache, the merged context is discarded; the
 same-ID route-local `_ctx` may remain reusable. A later navigation rebuilds the

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

@@ -429,15 +429,16 @@ async function contextualize(
     }
     try {
       setFetching(router, match, 'beforeLoad', options[0 /* controller */])
-      const result = await waitFor(
-        beforeLoad({
-          ...common,
-          search: match.search,
-          context: match.context,
-          ...router.options.additionalContext,
-        }),
-        signal,
-      )
+      const value = beforeLoad({
+        ...common,
+        search: match.search,
+        context: match.context,
+        ...router.options.additionalContext,
+      })
+      // Keep the cancellation checkpoint without wrapping synchronous context.
+      const result = await (typeof value?.then === 'function'
+        ? waitFor(value, signal)
+        : value)
       if (signal.aborted) {
         return [index, CANCELED_OUTCOME]
       }
@@ -894,38 +895,39 @@ function createLoaderTask(
           reloadFailure ?? [SUCCESS, match.loaderData],
         )
 
-  // The async wrapper catches synchronous preload failures without deferring work.
-  const chunkOutcome = (async (): Promise<undefined> => {
-    const chunk = loadRouteChunk(route, undefined, onLazyReady)
-    if (chunk) {
-      await waitFor(chunk, options[0 /* controller */].signal)
-    }
-  })().catch((cause): IndexedOutcome | undefined =>
-    lane[1 /* matches */].some(
-      (candidate, candidateIndex) =>
-        candidateIndex <= index &&
-        (candidate.status === 'error' ||
-          candidate.status === 'notFound' ||
-          candidate._notFound),
-    )
-      ? undefined
-      : [index, normalizeLaneError(router, lane, route, cause, options)],
-  )
-  const chunkFailure = chunkOutcome.then((failure) =>
-    outcome.then((result) => {
-      if (
-        blocking &&
-        !failure &&
-        result[0 /* kind */] === SUCCESS &&
-        match.status === 'pending' &&
-        !options[0 /* controller */].signal.aborted
-      ) {
-        match.status = 'success'
-        onReady?.()
+  // Keep thrown preloads and rejected chunks in the same task promise.
+  const chunkFailure = (async (): Promise<IndexedOutcome | undefined> => {
+    let failure: IndexedOutcome | undefined
+    try {
+      const chunk = loadRouteChunk(route, undefined, onLazyReady)
+      if (chunk) {
+        await waitFor(chunk, options[0 /* controller */].signal)
       }
-      return failure
-    }),
-  )
+    } catch (cause) {
+      failure = lane[1 /* matches */].some(
+        (candidate, candidateIndex) =>
+          candidateIndex <= index &&
+          (candidate.status === 'error' ||
+            candidate.status === 'notFound' ||
+            candidate._notFound),
+      )
+        ? undefined
+        : [index, normalizeLaneError(router, lane, route, cause, options)]
+    }
+    // Readiness requires both the component chunk and loader data.
+    const result = await outcome
+    if (
+      blocking &&
+      !failure &&
+      result[0 /* kind */] === SUCCESS &&
+      match.status === 'pending' &&
+      !options[0 /* controller */].signal.aborted
+    ) {
+      match.status = 'success'
+      onReady?.()
+    }
+    return failure
+  })()
   tasks.push([index, outcome, chunkFailure])
   if (!background) {
     return outcome.then((result) => getParentSnapshot(match, result))
@@ -1982,7 +1984,7 @@ export async function loadClientRoute(
     )
   const done = opts?.sync
     ? new Promise<void>((resolve) => (settle = resolve))
-    : Promise.resolve().then(run).then()
+    : Promise.resolve().then(run)
   const tx: LoadTransaction = [
     controller,
     redirects,

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

@@ -155,11 +155,11 @@ function waitFor<T>(value: Promise<T>, signal?: AbortSignal): Promise<T> {
   return signal ? waitForReason(value, signal) : value
 }
 
-async function resolveSsr(
+function resolveSsr(
   router: AnyRouter,
   lane: MatchedLane,
   index: number,
-): Promise<SSROption> {
+): SSROption | Promise<SSROption> {
   const match = lane.matches[index]!
   const route = getRoute(router, match)
   const parentSsr = lane.matches[index - 1]?.ssr
@@ -203,7 +203,14 @@ async function resolveSsr(
       ssr: candidate.ssr,
     })),
   }
-  return inherit((await option(context)) ?? defaultSsr)
+  try {
+    return Promise.resolve(option(context)).then((value) =>
+      inherit(value ?? defaultSsr),
+    )
+  } catch (cause) {
+    // Functional failures keep their asynchronous cancellation checkpoint.
+    return Promise.reject(cause)
+  }
 }
 
 function stampNotFound(
@@ -232,7 +239,9 @@ async function contextualize(
     const match = lane.matches[index]!
     const route = getRoute(router, match)
     try {
-      match.ssr = await resolveSsr(router, lane, index)
+      const ssr = resolveSsr(router, lane, index)
+      // Functional policies are assimilated into a native Promise above.
+      match.ssr = ssr instanceof Promise ? await ssr : ssr
     } catch (cause) {
       signal?.throwIfAborted()
       failure = [

packages/router-core/tests/navigation-awaitable.bench.ts

@@ -0,0 +1,109 @@
+import { createHook } from 'node:async_hooks'
+import { bench, describe, expect } from 'vitest'
+import { createMemoryHistory } from '@tanstack/history'
+import { BaseRootRoute, BaseRoute } from '../src'
+import { createTestRouter } from './routerTestUtils'
+import type { AnyRoute } from '../src'
+
+// Use the same cases on both implementations. Allocation counts are collected
+// outside the timed loop so async-hooks instrumentation cannot bias timings.
+for (const mode of [
+  'none',
+  'sync',
+  'void',
+  'async',
+  'mixed',
+  'chunks',
+  'blocking',
+] as const) {
+  const root = new BaseRootRoute({})
+  let chunkCalls = 0
+  let parent: AnyRoute = root
+  for (let index = 0; index < 8; index++) {
+    const parentRoute = parent
+    const value = { [`level${index}`]: index }
+    const child = new BaseRoute({
+      getParentRoute: () => parentRoute,
+      path: `level${index}`,
+      beforeLoad:
+        mode === 'none' || mode === 'chunks' || mode === 'blocking'
+          ? undefined
+          : () =>
+              mode === 'async' || (mode === 'mixed' && index % 4 === 0)
+                ? Promise.resolve(value)
+                : mode === 'void'
+                  ? undefined
+                  : value,
+      component:
+        mode === 'chunks' || mode === 'blocking'
+          ? (Object.assign(() => null, {
+              preload: () => {
+                chunkCalls++
+                return Promise.resolve()
+              },
+            }) as any)
+          : undefined,
+      shouldReload: mode === 'blocking' ? true : undefined,
+      loader:
+        mode === 'blocking'
+          ? {
+              handler: () => Promise.resolve(value),
+              staleReloadMode: 'blocking',
+            }
+          : undefined,
+    })
+    parent.addChildren([child])
+    parent = child
+  }
+  const router = createTestRouter({
+    routeTree: root,
+    history: createMemoryHistory({
+      initialEntries: [
+        '/level0/level1/level2/level3/level4/level5/level6/level7',
+      ],
+    }),
+  })
+  await router.load()
+  const navigate = () => router.navigate({ to: '.', replace: true })
+  await navigate()
+  expect(router.state.matches).toHaveLength(9)
+  expect(
+    router.state.matches.every((match) => match.status === 'success'),
+  ).toBe(true)
+  if (mode === 'chunks' || mode === 'blocking') {
+    expect(chunkCalls).toBe(16)
+    if (mode === 'blocking') {
+      expect(router.state.matches[8]!.loaderData).toEqual({ level7: 7 })
+    }
+  } else if (mode !== 'none' && mode !== 'void') {
+    expect(router.state.matches[8]!.context).toMatchObject({
+      level0: 0,
+      level7: 7,
+    })
+  }
+
+  let promises = 0
+  const hook = createHook({
+    init(_id, type) {
+      if (type === 'PROMISE') {
+        promises++
+      }
+    },
+  })
+  hook.enable()
+  await navigate()
+  hook.disable()
+  console.info(`${mode}: ${promises} Promises per navigation`)
+
+  describe(`${mode} beforeLoad`, () => {
+    bench(
+      '10 navigations through 8 routes',
+      async () => {
+        for (let index = 0; index < 10; index++) {
+          await navigate()
+        }
+      },
+      { time: 1500, warmupTime: 300 },
+    )
+  })
+}