@tanstack/router-core 1.154.14 → 1.156.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/router-core",
-  "version": "1.154.14",
+  "version": "1.156.0",
   "description": "Modern and scalable routing for React applications",
   "author": "Tanner Linsley",
   "license": "MIT",

package/src/new-process-route-tree.ts

@@ -27,11 +27,17 @@ type ExtendedSegmentKind =
   | typeof SEGMENT_TYPE_INDEX
   | typeof SEGMENT_TYPE_PATHLESS
 
-const PARAM_W_CURLY_BRACES_RE =
-  /^([^{]*)\{\$([a-zA-Z_$][a-zA-Z0-9_$]*)\}([^}]*)$/ // prefix{$paramName}suffix
-const OPTIONAL_PARAM_W_CURLY_BRACES_RE =
-  /^([^{]*)\{-\$([a-zA-Z_$][a-zA-Z0-9_$]*)\}([^}]*)$/ // prefix{-$paramName}suffix
-const WILDCARD_W_CURLY_BRACES_RE = /^([^{]*)\{\$\}([^}]*)$/ // prefix{$}suffix
+function getOpenAndCloseBraces(
+  part: string,
+): [openBrace: number, closeBrace: number] | null {
+  const openBrace = part.indexOf('{')
+  if (openBrace === -1) return null
+  const closeBrace = part.indexOf('}', openBrace)
+  if (closeBrace === -1) return null
+  const afterOpen = openBrace + 1
+  if (afterOpen >= part.length) return null
+  return [openBrace, closeBrace]
+}
 
 type ParsedSegment = Uint16Array & {
   /** segment type (0 = pathname, 1 = param, 2 = wildcard, 3 = optional param) */
@@ -110,47 +116,61 @@ export function parseSegment(
     return output as ParsedSegment
   }
 
-  const wildcardBracesMatch = part.match(WILDCARD_W_CURLY_BRACES_RE)
-  if (wildcardBracesMatch) {
-    const prefix = wildcardBracesMatch[1]!
-    const pLength = prefix.length
-    output[0] = SEGMENT_TYPE_WILDCARD
-    output[1] = start + pLength
-    output[2] = start + pLength + 1 // skip '{'
-    output[3] = start + pLength + 2 // '$'
-    output[4] = start + pLength + 3 // skip '}'
-    output[5] = path.length
-    return output as ParsedSegment
-  }
-
-  const optionalParamBracesMatch = part.match(OPTIONAL_PARAM_W_CURLY_BRACES_RE)
-  if (optionalParamBracesMatch) {
-    const prefix = optionalParamBracesMatch[1]!
-    const paramName = optionalParamBracesMatch[2]!
-    const suffix = optionalParamBracesMatch[3]!
-    const pLength = prefix.length
-    output[0] = SEGMENT_TYPE_OPTIONAL_PARAM
-    output[1] = start + pLength
-    output[2] = start + pLength + 3 // skip '{-$'
-    output[3] = start + pLength + 3 + paramName.length
-    output[4] = end - suffix.length
-    output[5] = end
-    return output as ParsedSegment
-  }
-
-  const paramBracesMatch = part.match(PARAM_W_CURLY_BRACES_RE)
-  if (paramBracesMatch) {
-    const prefix = paramBracesMatch[1]!
-    const paramName = paramBracesMatch[2]!
-    const suffix = paramBracesMatch[3]!
-    const pLength = prefix.length
-    output[0] = SEGMENT_TYPE_PARAM
-    output[1] = start + pLength
-    output[2] = start + pLength + 2 // skip '{$'
-    output[3] = start + pLength + 2 + paramName.length
-    output[4] = end - suffix.length
-    output[5] = end
-    return output as ParsedSegment
+  const braces = getOpenAndCloseBraces(part)
+  if (braces) {
+    const [openBrace, closeBrace] = braces
+    const firstChar = part.charCodeAt(openBrace + 1)
+
+    // Check for {-$...} (optional param)
+    // prefix{-$paramName}suffix
+    // /^([^{]*)\{-\$([a-zA-Z_$][a-zA-Z0-9_$]*)\}([^}]*)$/
+    if (firstChar === 45) {
+      // '-'
+      if (
+        openBrace + 2 < part.length &&
+        part.charCodeAt(openBrace + 2) === 36 // '$'
+      ) {
+        const paramStart = openBrace + 3
+        const paramEnd = closeBrace
+        // Validate param name exists
+        if (paramStart < paramEnd) {
+          output[0] = SEGMENT_TYPE_OPTIONAL_PARAM
+          output[1] = start + openBrace
+          output[2] = start + paramStart
+          output[3] = start + paramEnd
+          output[4] = start + closeBrace + 1
+          output[5] = end
+          return output as ParsedSegment
+        }
+      }
+    } else if (firstChar === 36) {
+      // '$'
+      const dollarPos = openBrace + 1
+      const afterDollar = openBrace + 2
+      // Check for {$} (wildcard)
+      if (afterDollar === closeBrace) {
+        // For wildcard, value should be '$' (from dollarPos to afterDollar)
+        // prefix{$}suffix
+        // /^([^{]*)\{\$\}([^}]*)$/
+        output[0] = SEGMENT_TYPE_WILDCARD
+        output[1] = start + openBrace
+        output[2] = start + dollarPos
+        output[3] = start + afterDollar
+        output[4] = start + closeBrace + 1
+        output[5] = path.length
+        return output as ParsedSegment
+      }
+      // Regular param {$paramName} - value is the param name (after $)
+      // prefix{$paramName}suffix
+      // /^([^{]*)\{\$([a-zA-Z_$][a-zA-Z0-9_$]*)\}([^}]*)$/
+      output[0] = SEGMENT_TYPE_PARAM
+      output[1] = start + openBrace
+      output[2] = start + afterDollar
+      output[3] = start + closeBrace
+      output[4] = start + closeBrace + 1
+      output[5] = end
+      return output as ParsedSegment
+    }
   }
 
   // fallback to static pathname (should never happen)
@@ -758,6 +778,17 @@ export function trimPathRight(path: string) {
   return path === '/' ? path : path.replace(/\/{1,}$/, '')
 }
 
+export interface ProcessRouteTreeResult<
+  TRouteLike extends Extract<RouteLike, { fullPath: string }> & { id: string },
+> {
+  /** Should be considered a black box, needs to be provided to all matching functions in this module. */
+  processedTree: ProcessedTree<TRouteLike, any, any>
+  /** A lookup map of routes by their unique IDs. */
+  routesById: Record<string, TRouteLike>
+  /** A lookup map of routes by their trimmed full paths. */
+  routesByPath: Record<string, TRouteLike>
+}
+
 /**
  * Processes a route tree into a segment trie for efficient path matching.
  * Also builds lookup maps for routes by ID and by trimmed full path.
@@ -771,14 +802,7 @@ export function processRouteTree<
   caseSensitive: boolean = false,
   /** Optional callback invoked for each route during processing. */
   initRoute?: (route: TRouteLike, index: number) => void,
-): {
-  /** Should be considered a black box, needs to be provided to all matching functions in this module. */
-  processedTree: ProcessedTree<TRouteLike, any, any>
-  /** A lookup map of routes by their unique IDs. */
-  routesById: Record<string, TRouteLike>
-  /** A lookup map of routes by their trimmed full paths. */
-  routesByPath: Record<string, TRouteLike>
-} {
+): ProcessRouteTreeResult<TRouteLike> {
   const segmentTree = createStaticNode<TRouteLike>(routeTree.fullPath)
   const data = new Uint16Array(6)
   const routesById = {} as Record<string, TRouteLike>

package/src/path.ts

@@ -197,11 +197,33 @@ export function resolvePath({
   return result
 }
 
+/**
+ * Create a pre-compiled decode config from allowed characters.
+ * This should be called once at router initialization.
+ */
+export function compileDecodeCharMap(
+  pathParamsAllowedCharacters: ReadonlyArray<string>,
+) {
+  const charMap = new Map(
+    pathParamsAllowedCharacters.map((char) => [encodeURIComponent(char), char]),
+  )
+  // Escape special regex characters and join with |
+  const pattern = Array.from(charMap.keys())
+    .map((key) => key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('|')
+  const regex = new RegExp(pattern, 'g')
+  return (encoded: string) =>
+    encoded.replace(regex, (match) => charMap.get(match) ?? match)
+}
+
 interface InterpolatePathOptions {
   path?: string
   params: Record<string, unknown>
-  // Map of encoded chars to decoded chars (e.g. '%40' -> '@') that should remain decoded in path params
-  decodeCharMap?: Map<string, string>
+  /**
+   * A function that decodes a path parameter value.
+   * Obtained from `compileDecodeCharMap(pathParamsAllowedCharacters)`.
+   */
+  decoder?: (encoded: string) => string
 }
 
 type InterPolatePathResult = {
@@ -213,7 +235,7 @@ type InterPolatePathResult = {
 function encodeParam(
   key: string,
   params: InterpolatePathOptions['params'],
-  decodeCharMap: InterpolatePathOptions['decodeCharMap'],
+  decoder: InterpolatePathOptions['decoder'],
 ): any {
   const value = params[key]
   if (typeof value !== 'string') return value
@@ -222,7 +244,7 @@ function encodeParam(
     // the splat/catch-all routes shouldn't have the '/' encoded out
     return encodeURI(value)
   } else {
-    return encodePathParam(value, decodeCharMap)
+    return encodePathParam(value, decoder)
   }
 }
 
@@ -235,7 +257,7 @@ function encodeParam(
 export function interpolatePath({
   path,
   params,
-  decodeCharMap,
+  decoder,
 }: InterpolatePathOptions): InterPolatePathResult {
   // Tracking if any params are missing in the `params` object
   // when interpolating the path
@@ -286,7 +308,7 @@ export function interpolatePath({
         continue
       }
 
-      const value = encodeParam('_splat', params, decodeCharMap)
+      const value = encodeParam('_splat', params, decoder)
       joined += '/' + prefix + value + suffix
       continue
     }
@@ -300,7 +322,7 @@ export function interpolatePath({
 
       const prefix = path.substring(start, segment[1])
       const suffix = path.substring(segment[4], end)
-      const value = encodeParam(key, params, decodeCharMap) ?? 'undefined'
+      const value = encodeParam(key, params, decoder) ?? 'undefined'
       joined += '/' + prefix + value + suffix
       continue
     }
@@ -316,7 +338,7 @@ export function interpolatePath({
 
       const prefix = path.substring(start, segment[1])
       const suffix = path.substring(segment[4], end)
-      const value = encodeParam(key, params, decodeCharMap) ?? ''
+      const value = encodeParam(key, params, decoder) ?? ''
       joined += '/' + prefix + value + suffix
       continue
     }
@@ -329,12 +351,10 @@ export function interpolatePath({
   return { usedParams, interpolatedPath, isMissingParams }
 }
 
-function encodePathParam(value: string, decodeCharMap?: Map<string, string>) {
-  let encoded = encodeURIComponent(value)
-  if (decodeCharMap) {
-    for (const [encodedChar, char] of decodeCharMap) {
-      encoded = encoded.replaceAll(encodedChar, char)
-    }
-  }
-  return encoded
+function encodePathParam(
+  value: string,
+  decoder?: InterpolatePathOptions['decoder'],
+) {
+  const encoded = encodeURIComponent(value)
+  return decoder?.(encoded) ?? encoded
 }

package/src/router.ts

@@ -19,6 +19,7 @@ import {
 } from './new-process-route-tree'
 import {
   cleanPath,
+  compileDecodeCharMap,
   interpolatePath,
   resolvePath,
   trimPath,
@@ -37,7 +38,11 @@ import {
   executeRewriteOutput,
   rewriteBasepath,
 } from './rewrite'
-import type { ProcessedTree } from './new-process-route-tree'
+import type { LRUCache } from './lru-cache'
+import type {
+  ProcessRouteTreeResult,
+  ProcessedTree,
+} from './new-process-route-tree'
 import type { SearchParser, SearchSerializer } from './searchParams'
 import type { AnyRedirect, ResolvedRedirect } from './redirect'
 import type {
@@ -588,7 +593,6 @@ export type SubscribeFn = <TType extends keyof RouterEvents>(
 export interface MatchRoutesOpts {
   preload?: boolean
   throwOnError?: boolean
-  _buildLocation?: boolean
   dest?: BuildNextOptions
 }
 
@@ -872,6 +876,17 @@ export type CreateRouterFn = <
   TDehydrated
 >
 
+declare global {
+  // eslint-disable-next-line no-var
+  var __TSR_CACHE__:
+    | {
+        routeTree: AnyRoute
+        processRouteTreeResult: ProcessRouteTreeResult<AnyRoute>
+        resolvePathCache: LRUCache<string, string>
+      }
+    | undefined
+}
+
 /**
  * Core, framework-agnostic router engine that powers TanStack Router.
  *
@@ -922,8 +937,9 @@ export class RouterCore<
   routesById!: RoutesById<TRouteTree>
   routesByPath!: RoutesByPath<TRouteTree>
   processedTree!: ProcessedTree<TRouteTree, any, any>
+  resolvePathCache!: LRUCache<string, string>
   isServer!: boolean
-  pathParamsDecodeCharMap?: Map<string, string>
+  pathParamsDecoder?: (encoded: string) => string
 
   /**
    * @deprecated Use the `createRouter` function instead
@@ -992,14 +1008,10 @@ export class RouterCore<
 
     this.isServer = this.options.isServer ?? typeof document === 'undefined'
 
-    this.pathParamsDecodeCharMap = this.options.pathParamsAllowedCharacters
-      ? new Map(
-          this.options.pathParamsAllowedCharacters.map((char) => [
-            encodeURIComponent(char),
-            char,
-          ]),
-        )
-      : undefined
+    if (this.options.pathParamsAllowedCharacters)
+      this.pathParamsDecoder = compileDecodeCharMap(
+        this.options.pathParamsAllowedCharacters,
+      )
 
     if (
       !this.history ||
@@ -1030,7 +1042,28 @@ export class RouterCore<
 
     if (this.options.routeTree !== this.routeTree) {
       this.routeTree = this.options.routeTree as TRouteTree
-      this.buildRouteTree()
+      let processRouteTreeResult: ProcessRouteTreeResult<TRouteTree>
+      if (
+        this.isServer &&
+        globalThis.__TSR_CACHE__ &&
+        globalThis.__TSR_CACHE__.routeTree === this.routeTree
+      ) {
+        const cached = globalThis.__TSR_CACHE__
+        this.resolvePathCache = cached.resolvePathCache
+        processRouteTreeResult = cached.processRouteTreeResult as any
+      } else {
+        this.resolvePathCache = createLRUCache(1000)
+        processRouteTreeResult = this.buildRouteTree()
+        // only cache if nothing else is cached yet
+        if (this.isServer && globalThis.__TSR_CACHE__ === undefined) {
+          globalThis.__TSR_CACHE__ = {
+            routeTree: this.routeTree,
+            processRouteTreeResult: processRouteTreeResult as any,
+            resolvePathCache: this.resolvePathCache,
+          }
+        }
+      }
+      this.setRoutes(processRouteTreeResult)
     }
 
     if (!this.__store && this.latestLocation) {
@@ -1113,7 +1146,7 @@ export class RouterCore<
   }
 
   buildRouteTree = () => {
-    const { routesById, routesByPath, processedTree } = processRouteTree(
+    const result = processRouteTree(
       this.routeTree,
       this.options.caseSensitive,
       (route, i) => {
@@ -1123,9 +1156,17 @@ export class RouterCore<
       },
     )
     if (this.options.routeMasks) {
-      processRouteMasks(this.options.routeMasks, processedTree)
+      processRouteMasks(this.options.routeMasks, result.processedTree)
     }
 
+    return result
+  }
+
+  setRoutes({
+    routesById,
+    routesByPath,
+    processedTree,
+  }: ProcessRouteTreeResult<TRouteTree>) {
     this.routesById = routesById as RoutesById<TRouteTree>
     this.routesByPath = routesByPath as RoutesByPath<TRouteTree>
     this.processedTree = processedTree
@@ -1225,8 +1266,6 @@ export class RouterCore<
     return location
   }
 
-  resolvePathCache = createLRUCache<string, string>(1000)
-
   /** Resolve a path against the router basepath and trailing-slash policy. */
   resolvePathWithBase = (from: string, path: string) => {
     const resolvedPath = resolvePath({
@@ -1365,7 +1404,7 @@ export class RouterCore<
       const { interpolatedPath, usedParams } = interpolatePath({
         path: route.fullPath,
         params: routeParams,
-        decodeCharMap: this.pathParamsDecodeCharMap,
+        decoder: this.pathParamsDecoder,
       })
 
       // Waste not, want not. If we already have a match for this route,
@@ -1393,35 +1432,19 @@ export class RouterCore<
       let paramsError: unknown = undefined
 
       if (!existingMatch) {
-        if (route.options.skipRouteOnParseError) {
-          for (const key in usedParams) {
-            if (key in parsedParams!) {
-              strictParams[key] = parsedParams![key]
-            }
+        try {
+          extractStrictParams(route, usedParams, parsedParams!, strictParams)
+        } catch (err: any) {
+          if (isNotFound(err) || isRedirect(err)) {
+            paramsError = err
+          } else {
+            paramsError = new PathParamError(err.message, {
+              cause: err,
+            })
           }
-        } else {
-          const strictParseParams =
-            route.options.params?.parse ?? route.options.parseParams
 
-          if (strictParseParams) {
-            try {
-              Object.assign(
-                strictParams,
-                strictParseParams(strictParams as Record<string, string>),
-              )
-            } catch (err: any) {
-              if (isNotFound(err) || isRedirect(err)) {
-                paramsError = err
-              } else {
-                paramsError = new PathParamError(err.message, {
-                  cause: err,
-                })
-              }
-
-              if (opts?.throwOnError) {
-                throw paramsError
-              }
-            }
+          if (opts?.throwOnError) {
+            throw paramsError
           }
         }
       }
@@ -1522,7 +1545,7 @@ export class RouterCore<
 
       // only execute `context` if we are not calling from router.buildLocation
 
-      if (!existingMatch && opts?._buildLocation !== true) {
+      if (!existingMatch) {
         const parentMatch = matches[index - 1]
         const parentContext = getParentContext(parentMatch)
 
@@ -1566,6 +1589,80 @@ export class RouterCore<
     })
   }
 
+  /**
+   * Lightweight route matching for buildLocation.
+   * Only computes fullPath, accumulated search, and params - skipping expensive
+   * operations like AbortController, ControlledPromise, loaderDeps, and full match objects.
+   */
+  private matchRoutesLightweight(location: ParsedLocation): {
+    matchedRoutes: ReadonlyArray<AnyRoute>
+    fullPath: string
+    search: Record<string, unknown>
+    params: Record<string, unknown>
+  } {
+    const { matchedRoutes, routeParams, parsedParams } = this.getMatchedRoutes(
+      location.pathname,
+    )
+    const lastRoute = last(matchedRoutes)!
+
+    // I don't know if we should run the full search middleware chain, or just validateSearch
+    // // Accumulate search validation through the route chain
+    // const accumulatedSearch: Record<string, unknown> = applySearchMiddleware({
+    //   search: { ...location.search },
+    //   dest: location,
+    //   destRoutes: matchedRoutes,
+    //   _includeValidateSearch: true,
+    // })
+
+    // Accumulate search validation through route chain
+    const accumulatedSearch = { ...location.search }
+    for (const route of matchedRoutes) {
+      try {
+        Object.assign(
+          accumulatedSearch,
+          validateSearch(route.options.validateSearch, accumulatedSearch),
+        )
+      } catch {
+        // Ignore errors, we're not actually routing
+      }
+    }
+
+    // Determine params: reuse from state if possible, otherwise parse
+    const lastStateMatch = last(this.state.matches)
+    const canReuseParams =
+      lastStateMatch &&
+      lastStateMatch.routeId === lastRoute.id &&
+      location.pathname === this.state.location.pathname
+
+    let params: Record<string, unknown>
+    if (canReuseParams) {
+      params = lastStateMatch.params
+    } else {
+      // Parse params through the route chain
+      const strictParams: Record<string, unknown> = { ...routeParams }
+      for (const route of matchedRoutes) {
+        try {
+          extractStrictParams(
+            route,
+            routeParams,
+            parsedParams ?? {},
+            strictParams,
+          )
+        } catch {
+          // Ignore errors, we're not actually routing
+        }
+      }
+      params = strictParams
+    }
+
+    return {
+      matchedRoutes,
+      fullPath: lastRoute.fullPath,
+      search: accumulatedSearch,
+      params,
+    }
+  }
+
   cancelMatch = (id: string) => {
     const match = this.getMatch(id)
 
@@ -1610,13 +1707,9 @@ export class RouterCore<
       const currentLocation =
         dest._fromLocation || this.pendingBuiltLocation || this.latestLocation
 
-      const allCurrentLocationMatches = this.matchRoutes(currentLocation, {
-        _buildLocation: true,
-      })
-
-      // Now let's find the starting pathname
-      // This should default to the current location if no from is provided
-      const lastMatch = last(allCurrentLocationMatches)!
+      // Use lightweight matching - only computes what buildLocation needs
+      // (fullPath, search, params) without creating full match objects
+      const lightweightResult = this.matchRoutesLightweight(currentLocation)
 
       // check that from path exists in the current route tree
       // do this check only on navigations during test or development
@@ -1627,12 +1720,12 @@ export class RouterCore<
       ) {
         const allFromMatches = this.getMatchedRoutes(dest.from).matchedRoutes
 
-        const matchedFrom = findLast(allCurrentLocationMatches, (d) => {
+        const matchedFrom = findLast(lightweightResult.matchedRoutes, (d) => {
           return comparePaths(d.fullPath, dest.from!)
         })
 
         const matchedCurrent = findLast(allFromMatches, (d) => {
-          return comparePaths(d.fullPath, lastMatch.fullPath)
+          return comparePaths(d.fullPath, lightweightResult.fullPath)
         })
 
         // for from to be invalid it shouldn't just be unmatched to currentLocation
@@ -1645,15 +1738,15 @@ export class RouterCore<
       const defaultedFromPath =
         dest.unsafeRelative === 'path'
           ? currentLocation.pathname
-          : (dest.from ?? lastMatch.fullPath)
+          : (dest.from ?? lightweightResult.fullPath)
 
       // ensure this includes the basePath if set
       const fromPath = this.resolvePathWithBase(defaultedFromPath, '.')
 
       // From search should always use the current location
-      const fromSearch = lastMatch.search
+      const fromSearch = lightweightResult.search
       // Same with params. It can't hurt to provide as many as possible
-      const fromParams = { ...lastMatch.params }
+      const fromParams = { ...lightweightResult.params }
 
       // Resolve the next to
       // ensure this includes the basePath if set
@@ -1721,7 +1814,7 @@ export class RouterCore<
             interpolatePath({
               path: nextTo,
               params: nextParams,
-              decodeCharMap: this.pathParamsDecodeCharMap,
+              decoder: this.pathParamsDecoder,
             }).interpolatedPath,
           )
 
@@ -2802,7 +2895,7 @@ function applySearchMiddleware({
   _includeValidateSearch,
 }: {
   search: any
-  dest: BuildNextOptions
+  dest: { search?: unknown }
   destRoutes: ReadonlyArray<AnyRoute>
   _includeValidateSearch: boolean | undefined
 }) {
@@ -2937,3 +3030,25 @@ function findGlobalNotFoundRouteId(
   }
   return rootRouteId
 }
+
+function extractStrictParams(
+  route: AnyRoute,
+  referenceParams: Record<string, unknown>,
+  parsedParams: Record<string, unknown>,
+  accumulatedParams: Record<string, unknown>,
+) {
+  const parseParams = route.options.params?.parse ?? route.options.parseParams
+  if (parseParams) {
+    if (route.options.skipRouteOnParseError) {
+      // Use pre-parsed params from route matching for skipRouteOnParseError routes
+      for (const key in referenceParams) {
+        if (key in parsedParams) {
+          accumulatedParams[key] = parsedParams[key]
+        }
+      }
+    } else {
+      const result = parseParams(accumulatedParams as Record<string, string>)
+      Object.assign(accumulatedParams, result)
+    }
+  }
+}