refactor(router-core): interpolatePath can cache the parsed path template

[Sheraff]

We can squeeze a little more performance out of interpolatePath by caching the parsed representation of the template path to avoid having to call parseSegment again on repeated interpolations of the same path.

Cache is keyed on the path and not the params, so it should have a pretty good hit rate.

This function is not very slow (~1-2MHz), but it is called on buildLocation and matchRoutesInternal (2 hot paths). But I'm not sure this change is worth the 1.4x we get out of it...

bench: 1.4x

 ✓  @tanstack/router-core  tests/interpolate.bench.ts > interpolatePath 1293ms
     name                         hz     min     max    mean     p75     p99    p995    p999     rme  samples
   · old interpolatePath  272,652.50  0.0032  0.8732  0.0037  0.0036  0.0047  0.0050  0.0193  ±0.38%   136327
   · new interpolatePath  413,747.62  0.0022  0.0959  0.0024  0.0024  0.0027  0.0031  0.0034  ±0.13%   206874

 BENCH  Summary

   @tanstack/router-core  new interpolatePath - tests/interpolate.bench.ts > interpolatePath
    1.52x faster than old interpolatePath

Summary by CodeRabbit

• New Features

  • Path interpolation now supports optional caching, improving performance when processing dynamic route parameters
  • Exported ParsedSegment type for advanced TypeScript use cases in custom routing implementations

• Performance Improvements

  • Route matching and path interpolation operations now leverage segment caching for enhanced efficiency across repeated path processing

[coderabbitai]

Walkthrough

The PR exports the ParsedSegment type from the route-tree module, introduces LRU caching to the interpolatePath function to reuse parsed segment data, and integrates a cache instance into RouterCore to optimize path interpolation across multiple route-matching operations.

Changes

Cohort / File(s)	Summary
Type Export packages/router-core/src/new-process-route-tree.ts	Export ParsedSegment type to make it publicly accessible for typed segment data usage.
Path Interpolation with Caching packages/router-core/src/path.ts	Add optional cache parameter to InterpolatePathOptions and interpolatePath function; introduce forEachSegment helper and SEGMENT_DATA_LENGTH constant to batch and reuse parsed segment data; refactor interpolation logic to use caching callback pattern for pathname, wildcard, param, and optional param branches.
Router Cache Integration packages/router-core/src/router.ts	Add private LRU cache (capacity 1000) to RouterCore; pass cache instance to interpolatePath calls in route matching (matchRoutesInternal) and location building (buildLocation).

Sequence Diagram

sequenceDiagram
    participant Router as RouterCore
    participant Path as interpolatePath
    participant Cache as LRU Cache
    participant Helper as forEachSegment

    Router->>Path: interpolatePath(path, options + cache)
    Path->>Helper: forEachSegment(path, cache, callback)
    
    loop For each segment in path
        Helper->>Cache: lookup(segmentKey)
        alt Cache Hit
            Cache-->>Helper: ParsedSegment (cached)
        else Cache Miss
            Helper->>Helper: parse segment
            Helper->>Cache: store(segmentKey, ParsedSegment)
            Cache-->>Helper: ParsedSegment (stored)
        end
        Helper->>Helper: invoke callback with ParsedSegment
    end
    
    Helper-->>Path: completed
    Path-->>Router: interpolated result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20–25 minutes

• Cache logic in path.ts: Verify correct hit/miss behavior, parameter handling (missing, optional) with caching, and segment iteration refactoring
• Cache capacity and eviction: Confirm 1000-capacity LRU is appropriate for typical routing scenarios
• Integration points in router.ts: Ensure cache is passed consistently across all interpolatePath call sites and doesn't introduce unexpected state sharing

Possibly related PRs

• refactor(router-core): use original nextTo path when building location in its route form #5851: Modifies interpolatePath and router-core path/routing logic with overlapping function calls and flow changes
• refactor(router-core): simplify matchId #5807: Updates interpolatePath signature and route matching (removes leaveWildcards, simplifies matchId interpolation)
• refactor(router-core): Process routeTree into segment tree instead of flatRoutes #5722: Introduces/expands ParsedSegment type that this PR now exports and utilizes

Suggested labels

package: router-core, performance

Suggested reviewers

• schiller-manuel
• nlynzaad

Poem

🐰 Segments now cached in burrows deep,
No parsing twice, the cache we keep!
LRU magic, swift and keen,
Routes interpolate—smooth, pristine! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding caching capability to interpolatePath for parsed path templates to improve performance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch refactor-router-core-interpolate-pach-caching

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cdd2de3 and 6175fe2.

📒 Files selected for processing (3)

• packages/router-core/src/new-process-route-tree.ts (1 hunks)
• packages/router-core/src/path.ts (6 hunks)
• packages/router-core/src/router.ts (4 hunks)

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: nlynzaad
Repo: TanStack/router PR: 5182
File: e2e/react-router/basic-file-based/tests/non-nested-paths.spec.ts:167-172
Timestamp: 2025-09-22T00:56:53.426Z
Learning: In TanStack Router, underscores are intentionally stripped from route segments during path parsing, but preserved in base path segments. This is the expected behavior implemented in PR #5182.

Learnt from: nlynzaad
Repo: TanStack/router PR: 5182
File: e2e/react-router/basic-file-based/src/routes/non-nested/named/$baz_.bar.tsx:3-5
Timestamp: 2025-09-22T00:56:49.237Z
Learning: In TanStack Router, underscores are intentionally stripped from route segments (e.g., `$baz_` becomes `baz` in generated types) but should be preserved in base path segments. This is the correct behavior as of the fix in PR #5182.

📚 Learning: 2025-10-01T18:30:26.591Z

Learnt from: schiller-manuel
Repo: TanStack/router PR: 5330
File: packages/router-core/src/router.ts:2231-2245
Timestamp: 2025-10-01T18:30:26.591Z
Learning: In `packages/router-core/src/router.ts`, the `resolveRedirect` method intentionally strips the router's origin from redirect URLs when they match (e.g., `https://foo.com/bar` → `/bar` for same-origin redirects) while preserving the full URL for cross-origin redirects. This logic should not be removed or simplified to use `location.publicHref` directly.

Applied to files:

• packages/router-core/src/router.ts

🧬 Code graph analysis (2)

packages/router-core/src/router.ts (1)

packages/router-core/src/lru-cache.ts (1)

• createLRUCache (7-74)

packages/router-core/src/path.ts (2)

packages/router-core/src/lru-cache.ts (1)

• LRUCache (1-5)

packages/router-core/src/new-process-route-tree.ts (5)

• ParsedSegment (23-36)
• parseSegment (54-151)
• SEGMENT_TYPE_PATHNAME (6-6)
• SEGMENT_TYPE_PARAM (7-7)
• SEGMENT_TYPE_OPTIONAL_PARAM (9-9)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Preview
• GitHub Check: Test

🔇 Additional comments (8)

packages/router-core/src/new-process-route-tree.ts (1)

23-36: LGTM! Clean type export for inter-module usage.

Exposing ParsedSegment as a public type enables type-safe consumption in the path interpolation module while maintaining the existing implementation. The inline documentation clearly describes the segment data layout.

packages/router-core/src/path.ts (3)

9-9: LGTM! Type-safe cache integration.

The import of ParsedSegment and the optional cache parameter addition maintain backward compatibility while enabling the new caching behavior.

Also applies to: 214-214

---

239-272: Well-structured caching helper.

The forEachSegment function correctly implements segment parsing with LRU caching:

• Caches the flattened Uint16Array representation of all segments in a path
• Extracts cached segments via subarray views to avoid allocations
• Falls back to parseSegment when cache misses occur
• Properly handles cursor advancement and empty segments

The cache keying on the path template (not params) is correct since segment structure is path-dependent only.

---

284-377: Clean refactor to leverage caching.

The interpolatePath function has been successfully refactored to use forEachSegment:

• Replaces the explicit while loop with a callback-based iteration
• Early return statements in the callback replace implicit loop continuation
• Core interpolation logic (param substitution, wildcard handling, encoding) is preserved
• All segment types (pathname, wildcard, param, optional param) are handled correctly

The changes maintain backward compatibility while enabling segment-level caching through the optional cache parameter.

packages/router-core/src/router.ts (4)

1247-1247: Cache instance appropriately scoped.

The private interpolateCache field provides router-instance-level caching with a reasonable capacity of 1000 entries (consistent with resolvePathCache). The cache lifetime is tied to the router instance, which is appropriate since path templates are static within a router's lifetime.

Note: If the route tree can be dynamically updated via router.update({ routeTree }) (line 1014-1017), the cache won't be invalidated. However, path templates changing at runtime is rare, and the LRU eviction will eventually replace stale entries if it occurs.

---

1364-1369: LGTM! Cache integration in hot path.

Passing the cache to interpolatePath during route matching provides the most performance benefit, as this code path executes on every navigation. The cached parsed segments will be reused across multiple navigations to the same route templates.

---

1663-1667: Correct cache usage in buildLocation.

The cache is appropriately passed when interpolating the destination path (interpolatedNextTo) during location building. This enables cache reuse when building navigations to frequently accessed routes.

---

1689-1694: Complete cache integration.

The cache is correctly passed when computing the final nextPathname. With this change, all three interpolatePath call sites in router.ts consistently utilize the cache, ensuring maximum reuse of parsed segment data.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 6175fe2

Command	Status	Duration	Result
nx affected --targets=test:eslint,test:unit,tes...	✅ Succeeded	8m 42s	View ↗
nx run-many --target=build --exclude=examples/*...	✅ Succeeded	1m 25s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-11-15 13:57:21 UTC

[pkg-pr-new]

More templates

• tanstack-router-react-example-authenticated-routes
• tanstack-router-react-example-authenticated-routes-firebase
• tanstack-router-react-example-basic
• tanstack-router-react-example-basic-default-search-params
• tanstack-router-react-example-basic-devtools-panel
• tanstack-router-react-example-basic-file-based
• tanstack-router-react-example-basic-non-nested-devtools
• tanstack-router-react-example-react-query
• tanstack-router-react-example-basic-react-query-file-based
• tanstack-router-react-example-basic-ssr-file-based
• tanstack-router-react-example-basic-ssr-streaming-file-based
• tanstack-router-react-example-basic-virtual-file-based
• tanstack-router-react-example-basic-virtual-inside-file-based
• tanstack-router-react-example-deferred-data
• tanstack-router-i18n-paraglide
• tanstack-router-react-example-kitchen-sink
• tanstack-router-react-example-kitchen-sink-file-based
• tanstack-router-react-example-kitchen-sink-react-query
• tanstack-router-react-example-kitchen-sink-react-query-file-based
• tanstack-router-react-example-large-file-based
• tanstack-router-react-example-location-masking
• tanstack-router-react-example-navigation-blocking
• tanstack-router-react-example-quickstart
• tanstack-router-react-example-quickstart-esbuild-file-based
• tanstack-router-react-example-quickstart-file-based
• tanstack-router-react-example-quickstart-rspack-file-based
• tanstack-router-react-example-quickstart-webpack-file-based
• router-monorepo-react-query
• router-mono-simple
• router-mono-simple-lazy
• tanstack-router-react-example-scroll-restoration
• tanstack-search-validator-adapters
• tanstack-start-example-bare
• tanstack-start-example-basic
• tanstack-start-example-basic-auth
• tanstack-start-example-basic-cloudflare
• tanstack-start-example-basic-react-query
• tanstack-start-example-basic-static
• tanstack-start-bun-hosting
• tanstack-start-example-clerk-basic
• tanstack-start-example-convex-trellaux
• tanstack-start-example-counter
• tanstack-start-i18n-paraglide
• tanstack-start-example-large
• tanstack-start-example-material-ui
• tanstack-start-streaming-data-from-server-functions
• tanstack-start-example-supabase-basic
• tanstack-start-tailwind-v4
• tanstack-start-example-trellaux
• tanstack-start-example-workos
• tanstack-router-react-example-view-transitions
• tanstack-router-react-example-with-framer-motion
• tanstack-router-react-example-with-trpc
• tanstack-router-react-example-with-trpc-react-query
• tanstack-router-solid-example-authenticated-routes
• tanstack-router-solid-example-authenticated-routes-firebase
• tanstack-router-solid-example-basic
• tanstack-router-solid-example-basic-default-search-params
• tanstack-router-solid-example-basic-devtools-panel
• tanstack-router-solid-example-basic-file-based
• tanstack-router-solid-example-basic-non-nested-devtools
• tanstack-router-solid-example-basic-solid-query
• tanstack-router-solid-example-basic-solid-query-file-based
• tanstack-router-solid-example-basic-ssr-file-based
• tanstack-router-solid-example-basic-ssr-streaming-file-based
• tanstack-router-solid-example-basic-virtual-file-based
• tanstack-router-solid-example-basic-virtual-inside-file-based
• tanstack-router-solid-example-deferred-data
• tanstack-router-solid-i18n-paraglide
• tanstack-router-solid-example-kitchen-sink
• tanstack-router-solid-example-kitchen-sink-file-based
• tanstack-router-solid-example-kitchen-sink-solid-query
• tanstack-router-solid-example-kitchen-sink-solid-query-file-based
• tanstack-router-solid-example-large-file-based
• tanstack-router-solid-example-location-masking
• tanstack-router-solid-example-navigation-blocking
• tanstack-router-solid-example-quickstart
• tanstack-router-solid-example-quickstart-esbuild-file-based
• tanstack-router-solid-example-quickstart-file-based
• tanstack-router-solid-example-quickstart-rspack-file-based
• tanstack-router-solid-example-quickstart-webpack-file-based
• router-solid-mono-simple
• router-solid-mono-simple-lazy
• router-solid-monorepo-solid-query
• tanstack-router-solid-example-scroll-restoration
• tanstack-solid-router-search-validator-adapters
• tanstack-solid-start-example-basic
• tanstack-solid-start-example-basic-auth
• tanstack-solid-start-example-basic-cloudflare
• tanstack-solid-start-example-basic-netlify
• tanstack-solid-start-example-basic-nitro
• tanstack-start-example-basic-solid-query
• tanstack-solid-start-example-basic-static
• tanstack-solid-start-bun-hosting
• tanstack-solid-start-example-convex-better-auth
• tanstack-solid-start-example-counter
• tanstack-solid-start-i18n-paraglide
• tanstack-solid-start-example-large
• tanstack-solid-start-streaming-data-from-server-functions
• tanstack-solid-start-example-supabase-basic
• tanstack-solid-start-tailwind-v4
• tanstack-router-solid-example-view-transitions
• tanstack-router-solid-example-with-framer-motion
• tanstack-router-solid-example-with-trpc

@tanstack/arktype-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/arktype-adapter@5874

@tanstack/directive-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/directive-functions-plugin@5874

@tanstack/eslint-plugin-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/eslint-plugin-router@5874

@tanstack/history

npm i https://pkg.pr.new/TanStack/router/@tanstack/history@5874

@tanstack/nitro-v2-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/nitro-v2-vite-plugin@5874

@tanstack/react-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router@5874

@tanstack/react-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-devtools@5874

@tanstack/react-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-router-ssr-query@5874

@tanstack/react-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start@5874

@tanstack/react-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-client@5874

@tanstack/react-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/react-start-server@5874

@tanstack/router-cli

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-cli@5874

@tanstack/router-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-core@5874

@tanstack/router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools@5874

@tanstack/router-devtools-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-devtools-core@5874

@tanstack/router-generator

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-generator@5874

@tanstack/router-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-plugin@5874

@tanstack/router-ssr-query-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-ssr-query-core@5874

@tanstack/router-utils

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-utils@5874

@tanstack/router-vite-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/router-vite-plugin@5874

@tanstack/server-functions-plugin

npm i https://pkg.pr.new/TanStack/router/@tanstack/server-functions-plugin@5874

@tanstack/solid-router

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router@5874

@tanstack/solid-router-devtools

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-devtools@5874

@tanstack/solid-router-ssr-query

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-router-ssr-query@5874

@tanstack/solid-start

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start@5874

@tanstack/solid-start-client

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-client@5874

@tanstack/solid-start-server

npm i https://pkg.pr.new/TanStack/router/@tanstack/solid-start-server@5874

@tanstack/start-client-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-client-core@5874

@tanstack/start-plugin-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-plugin-core@5874

@tanstack/start-server-core

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-server-core@5874

@tanstack/start-static-server-functions

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-static-server-functions@5874

@tanstack/start-storage-context

npm i https://pkg.pr.new/TanStack/router/@tanstack/start-storage-context@5874

@tanstack/valibot-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/valibot-adapter@5874

@tanstack/virtual-file-routes

npm i https://pkg.pr.new/TanStack/router/@tanstack/virtual-file-routes@5874

@tanstack/zod-adapter

npm i https://pkg.pr.new/TanStack/router/@tanstack/zod-adapter@5874

commit: 6175fe2

[schiller-manuel]

what's the bundle size impact here?

[Sheraff]

what's the bundle size impact here?

I haven't measured (do we have something to measure that?) but yeah that was my blocker too: the perf gains don't really seem worth it here for the increase in code.