refactor(router-core): add LRU cache in front of parsePathname (#4752)

Sheraff · web-flow · commit 182df4d316a6 · 2025-07-23T11:16:59.000+02:00
We noticed that `parsePathname` is a performance bottleneck during navigation events. Here's a flamegraph from an application w/ ~300 routes around a navigation event: <img width="853" height="372" alt="Screenshot 2025-07-22 at 19 36 24" src="https://github.com/user-attachments/assets/7ed2e09a-8ea9-4170-862a-2d53c3eb4793" /> This PR proposes a basic least-recently-used cache implementation (that data structure is about 4-5x slower than a `Map` according to benchmarks, and it uses a little more memory). We can add caching to `parsePathname` now that what it returns is readonly (#4705), which should improve the performance of this bottleneck. The cache is set to a size of 1000. When / if we end up making a pre-built matcher (WIP #4714), we maybe can reduce this size. But `parsePathname` is still called w/ built pathnames so we probably shouldn't remove the cache entirely. When benchmarking `matchPathname` with and without the cache, we notice a ~9x increase in throughput with the cache. ``` ✓ @tanstack/router-core tests/cache.bench.ts > cache.bench 7191ms name hz min max mean p75 p99 p995 p999 rme samples · original 1,795.61 0.5055 0.7022 0.5569 0.5604 0.6234 0.6464 0.7022 ±0.22% 898 · cached 16,307.87 0.0562 0.2294 0.0613 0.0608 0.0767 0.1007 0.1152 ±0.17% 8154 fastest BENCH Summary @tanstack/router-core cached - tests/cache.bench.ts > cache.bench 9.08x faster than original ``` Assuming this 9x increase translates to a proportional reduction of the self-time seen in the flamegraph, it would go from 55ms to 6ms.
diff --git a/packages/router-core/src/lru-cache.ts b/packages/router-core/src/lru-cache.ts
@@ -0,0 +1,68 @@
+export type LRUCache<TKey, TValue> = {
+  get: (key: TKey) => TValue | undefined
+  set: (key: TKey, value: TValue) => void
+}
+
+export function createLRUCache<TKey, TValue>(
+  max: number,
+): LRUCache<TKey, TValue> {
+  type Node = { prev?: Node; next?: Node; key: TKey; value: TValue }
+  const cache = new Map<TKey, Node>()
+  let oldest: Node | undefined
+  let newest: Node | undefined
+
+  const touch = (entry: Node) => {
+    if (!entry.next) return
+    if (!entry.prev) {
+      entry.next.prev = undefined
+      oldest = entry.next
+      entry.next = undefined
+      if (newest) {
+        entry.prev = newest
+        newest.next = entry
+      }
+    } else {
+      entry.prev.next = entry.next
+      entry.next.prev = entry.prev
+      entry.next = undefined
+      if (newest) {
+        newest.next = entry
+        entry.prev = newest
+      }
+    }
+    newest = entry
+  }
+
+  return {
+    get(key) {
+      const entry = cache.get(key)
+      if (!entry) return undefined
+      touch(entry)
+      return entry.value
+    },
+    set(key, value) {
+      if (cache.size >= max && oldest) {
+        const toDelete = oldest
+        cache.delete(toDelete.key)
+        if (toDelete.next) {
+          oldest = toDelete.next
+          toDelete.next.prev = undefined
+        }
+        if (toDelete === newest) {
+          newest = undefined
+        }
+      }
+      const existing = cache.get(key)
+      if (existing) {
+        existing.value = value
+        touch(existing)
+      } else {
+        const entry: Node = { key, value, prev: newest }
+        if (newest) newest.next = entry
+        newest = entry
+        if (!oldest) oldest = entry
+        cache.set(key, entry)
+      }
+    },
+  }
+}
diff --git a/packages/router-core/src/path.ts b/packages/router-core/src/path.ts
@@ -1,4 +1,5 @@
 import { last } from './utils'
+import type { LRUCache } from './lru-cache'
 import type { MatchLocation } from './RouterProvider'
 import type { AnyPathParams } from './route'
 
@@ -101,6 +102,7 @@ interface ResolvePathOptions {
   to: string
   trailingSlash?: 'always' | 'never' | 'preserve'
   caseSensitive?: boolean
+  parseCache?: ParsePathnameCache
 }
 
 function segmentToString(segment: Segment): string {
@@ -154,12 +156,13 @@ export function resolvePath({
   to,
   trailingSlash = 'never',
   caseSensitive,
+  parseCache,
 }: ResolvePathOptions) {
   base = removeBasepath(basepath, base, caseSensitive)
   to = removeBasepath(basepath, to, caseSensitive)
 
-  let baseSegments = parsePathname(base).slice()
-  const toSegments = parsePathname(to)
+  let baseSegments = parsePathname(base, parseCache).slice()
+  const toSegments = parsePathname(to, parseCache)
 
   if (baseSegments.length > 1 && last(baseSegments)?.value === '/') {
     baseSegments.pop()
@@ -202,6 +205,19 @@ export function resolvePath({
   return joined
 }
 
+export type ParsePathnameCache = LRUCache<string, ReadonlyArray<Segment>>
+export const parsePathname = (
+  pathname?: string,
+  cache?: ParsePathnameCache,
+): ReadonlyArray<Segment> => {
+  if (!pathname) return []
+  const cached = cache?.get(pathname)
+  if (cached) return cached
+  const parsed = baseParsePathname(pathname)
+  cache?.set(pathname, parsed)
+  return parsed
+}
+
 const PARAM_RE = /^\$.{1,}$/ // $paramName
 const PARAM_W_CURLY_BRACES_RE = /^(.*?)\{(\$[a-zA-Z_$][a-zA-Z0-9_$]*)\}(.*)$/ // prefix{$paramName}suffix
 const OPTIONAL_PARAM_W_CURLY_BRACES_RE =
@@ -227,11 +243,7 @@ const WILDCARD_W_CURLY_BRACES_RE = /^(.*?)\{\$\}(.*)$/ // prefix{$}suffix
  * - `/foo/[$]{$foo} - Dynamic route with a static prefix of `$`
  * - `/foo/{$foo}[$]` - Dynamic route with a static suffix of `$`
  */
-export function parsePathname(pathname?: string): ReadonlyArray<Segment> {
-  if (!pathname) {
-    return []
-  }
-
+function baseParsePathname(pathname: string): ReadonlyArray<Segment> {
   pathname = cleanPath(pathname)
 
   const segments: Array<Segment> = []
@@ -348,6 +360,7 @@ interface InterpolatePathOptions {
   leaveParams?: boolean
   // Map of encoded chars to decoded chars (e.g. '%40' -> '@') that should remain decoded in path params
   decodeCharMap?: Map<string, string>
+  parseCache?: ParsePathnameCache
 }
 
 type InterPolatePathResult = {
@@ -361,8 +374,9 @@ export function interpolatePath({
   leaveWildcards,
   leaveParams,
   decodeCharMap,
+  parseCache,
 }: InterpolatePathOptions): InterPolatePathResult {
-  const interpolatedPathSegments = parsePathname(path)
+  const interpolatedPathSegments = parsePathname(path, parseCache)
 
   function encodeParam(key: string): any {
     const value = params[key]
@@ -480,8 +494,14 @@ export function matchPathname(
   basepath: string,
   currentPathname: string,
   matchLocation: Pick<MatchLocation, 'to' | 'fuzzy' | 'caseSensitive'>,
+  parseCache?: ParsePathnameCache,
 ): AnyPathParams | undefined {
-  const pathParams = matchByPath(basepath, currentPathname, matchLocation)
+  const pathParams = matchByPath(
+    basepath,
+    currentPathname,
+    matchLocation,
+    parseCache,
+  )
   // const searchMatched = matchBySearch(location.search, matchLocation)
 
   if (matchLocation.to && !pathParams) {
@@ -540,6 +560,7 @@ export function matchByPath(
     fuzzy,
     caseSensitive,
   }: Pick<MatchLocation, 'to' | 'caseSensitive' | 'fuzzy'>,
+  parseCache?: ParsePathnameCache,
 ): Record<string, string> | undefined {
   // check basepath first
   if (basepath !== '/' && !from.startsWith(basepath)) {
@@ -551,8 +572,14 @@ export function matchByPath(
   to = removeBasepath(basepath, `${to ?? '$'}`, caseSensitive)
 
   // Parse the from and to
-  const baseSegments = parsePathname(from.startsWith('/') ? from : `/${from}`)
-  const routeSegments = parsePathname(to.startsWith('/') ? to : `/${to}`)
+  const baseSegments = parsePathname(
+    from.startsWith('/') ? from : `/${from}`,
+    parseCache,
+  )
+  const routeSegments = parsePathname(
+    to.startsWith('/') ? to : `/${to}`,
+    parseCache,
+  )
 
   const params: Record<string, string> = {}
 
diff --git a/packages/router-core/src/router.ts b/packages/router-core/src/router.ts
@@ -33,7 +33,8 @@ import { setupScrollRestoration } from './scroll-restoration'
 import { defaultParseSearch, defaultStringifySearch } from './searchParams'
 import { rootRouteId } from './root'
 import { isRedirect, redirect } from './redirect'
-import type { Segment } from './path'
+import { createLRUCache } from './lru-cache'
+import type { ParsePathnameCache, Segment } from './path'
 import type { SearchParser, SearchSerializer } from './searchParams'
 import type { AnyRedirect, ResolvedRedirect } from './redirect'
 import type {
@@ -1014,6 +1015,7 @@ export class RouterCore<
       to: cleanPath(path),
       trailingSlash: this.options.trailingSlash,
       caseSensitive: this.options.caseSensitive,
+      parseCache: this.parsePathnameCache,
     })
     return resolvedPath
   }
@@ -1195,6 +1197,7 @@ export class RouterCore<
           params: routeParams,
           leaveWildcards: true,
           decodeCharMap: this.pathParamsDecodeCharMap,
+          parseCache: this.parsePathnameCache,
         }).interpolatedPath + loaderDepsHash
 
       // Waste not, want not. If we already have a match for this route,
@@ -1333,6 +1336,9 @@ export class RouterCore<
     return matches
   }
 
+  /** a cache for `parsePathname` */
+  private parsePathnameCache: ParsePathnameCache = createLRUCache(1000)
+
   getMatchedRoutes: GetMatchRoutesFn = (
     pathname: string,
     routePathname: string | undefined,
@@ -1345,6 +1351,7 @@ export class RouterCore<
       routesByPath: this.routesByPath,
       routesById: this.routesById,
       flatRoutes: this.flatRoutes,
+      parseCache: this.parsePathnameCache,
     })
   }
 
@@ -1452,6 +1459,7 @@ export class RouterCore<
       const interpolatedNextTo = interpolatePath({
         path: nextTo,
         params: nextParams ?? {},
+        parseCache: this.parsePathnameCache,
       }).interpolatedPath
 
       const destRoutes = this.matchRoutes(
@@ -1484,6 +1492,7 @@ export class RouterCore<
         leaveWildcards: false,
         leaveParams: opts.leaveParams,
         decodeCharMap: this.pathParamsDecodeCharMap,
+        parseCache: this.parsePathnameCache,
       }).interpolatedPath
 
       // Resolve the next search
@@ -1567,11 +1576,16 @@ export class RouterCore<
         let params = {}
 
         const foundMask = this.options.routeMasks?.find((d) => {
-          const match = matchPathname(this.basepath, next.pathname, {
-            to: d.from,
-            caseSensitive: false,
-            fuzzy: false,
-          })
+          const match = matchPathname(
+            this.basepath,
+            next.pathname,
+            {
+              to: d.from,
+              caseSensitive: false,
+              fuzzy: false,
+            },
+            this.parsePathnameCache,
+          )
 
           if (match) {
             params = match
@@ -2971,10 +2985,15 @@ export class RouterCore<
       ? this.latestLocation
       : this.state.resolvedLocation || this.state.location
 
-    const match = matchPathname(this.basepath, baseLocation.pathname, {
-      ...opts,
-      to: next.pathname,
-    }) as any
+    const match = matchPathname(
+      this.basepath,
+      baseLocation.pathname,
+      {
+        ...opts,
+        to: next.pathname,
+      },
+      this.parsePathnameCache,
+    ) as any
 
     if (!match) {
       return false
@@ -3368,6 +3387,7 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
   routesByPath,
   routesById,
   flatRoutes,
+  parseCache,
 }: {
   pathname: string
   routePathname?: string
@@ -3376,16 +3396,22 @@ export function getMatchedRoutes<TRouteLike extends RouteLike>({
   routesByPath: Record<string, TRouteLike>
   routesById: Record<string, TRouteLike>
   flatRoutes: Array<TRouteLike>
+  parseCache?: ParsePathnameCache
 }) {
   let routeParams: Record<string, string> = {}
   const trimmedPath = trimPathRight(pathname)
   const getMatchedParams = (route: TRouteLike) => {
-    const result = matchPathname(basepath, trimmedPath, {
-      to: route.fullPath,
-      caseSensitive: route.options?.caseSensitive ?? caseSensitive,
-      // we need fuzzy matching for `notFoundMode: 'fuzzy'`
-      fuzzy: true,
-    })
+    const result = matchPathname(
+      basepath,
+      trimmedPath,
+      {
+        to: route.fullPath,
+        caseSensitive: route.options?.caseSensitive ?? caseSensitive,
+        // we need fuzzy matching for `notFoundMode: 'fuzzy'`
+        fuzzy: true,
+      },
+      parseCache,
+    )
     return result
   }
 
diff --git a/packages/router-core/tests/lru.test.ts b/packages/router-core/tests/lru.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+import { createLRUCache } from '../src/lru-cache'
+
+describe('LRU Cache', () => {
+  it('evicts oldest set', () => {
+    const cache = createLRUCache<string, number>(3)
+    cache.set('a', 1)
+    cache.set('b', 2)
+    cache.set('c', 3)
+    cache.set('d', 4) // 'a' should be evicted
+    expect(cache.get('a')).toBeUndefined()
+    expect(cache.get('b')).toBe(2)
+  })
+  it('evicts oldest used', () => {
+    const cache = createLRUCache<string, number>(3)
+    cache.set('a', 1)
+    cache.set('b', 2)
+    cache.set('c', 3)
+    cache.get('a') // 'a' is now the most recently used
+    cache.set('d', 4) // 'b' should be evicted
+    expect(cache.get('b')).toBeUndefined()
+    expect(cache.get('a')).toBe(1)
+  })
+})
