@tanstack/router-core 1.133.25 → 1.133.28

package/src/path.ts

@@ -1,4 +1,3 @@
-import { rootRouteId } from './root'
 import { last } from './utils'
 import type { LRUCache } from './lru-cache'
 import type { MatchLocation } from './RouterProvider'
@@ -22,6 +21,7 @@ export interface Segment {
   readonly hasStaticAfter?: boolean
 }
 
+/** Join path segments, cleaning duplicate slashes between parts. */
 /** Join path segments, cleaning duplicate slashes between parts. */
 export function joinPaths(paths: Array<string | undefined>) {
   return cleanPath(
@@ -33,22 +33,26 @@ export function joinPaths(paths: Array<string | undefined>) {
   )
 }
 
+/** Remove repeated slashes from a path string. */
 /** Remove repeated slashes from a path string. */
 export function cleanPath(path: string) {
   // remove double slashes
   return path.replace(/\/{2,}/g, '/')
 }
 
+/** Trim leading slashes (except preserving root '/'). */
 /** Trim leading slashes (except preserving root '/'). */
 export function trimPathLeft(path: string) {
   return path === '/' ? path : path.replace(/^\/{1,}/, '')
 }
 
+/** Trim trailing slashes (except preserving root '/'). */
 /** Trim trailing slashes (except preserving root '/'). */
 export function trimPathRight(path: string) {
   return path === '/' ? path : path.replace(/\/{1,}$/, '')
 }
 
+/** Trim both leading and trailing slashes. */
 /** Trim both leading and trailing slashes. */
 export function trimPath(path: string) {
   return trimPathRight(trimPathLeft(path))
@@ -66,6 +70,10 @@ export function removeTrailingSlash(value: string, basepath: string): string {
 // see the usage in the isActive under useLinkProps
 // /sample/path1 = /sample/path1/
 // /sample/path1/some <> /sample/path1
+/**
+ * Compare two pathnames for exact equality after normalizing trailing slashes
+ * relative to the provided `basepath`.
+ */
 /**
  * Compare two pathnames for exact equality after normalizing trailing slashes
  * relative to the provided `basepath`.
@@ -169,8 +177,8 @@ export function resolvePath({
   trailingSlash = 'never',
   parseCache,
 }: ResolvePathOptions) {
-  let baseSegments = parseBasePathSegments(base, parseCache).slice()
-  const toSegments = parseRoutePathSegments(to, parseCache)
+  let baseSegments = parsePathname(base, parseCache).slice()
+  const toSegments = parsePathname(to, parseCache)
 
   if (baseSegments.length > 1 && last(baseSegments)?.value === '/') {
     baseSegments.pop()
@@ -216,16 +224,10 @@ export function resolvePath({
 
 export type ParsePathnameCache = LRUCache<string, ReadonlyArray<Segment>>
 
-export const parseBasePathSegments = (
-  pathname?: string,
-  cache?: ParsePathnameCache,
-): ReadonlyArray<Segment> => parsePathname(pathname, cache, true)
-
-export const parseRoutePathSegments = (
-  pathname?: string,
-  cache?: ParsePathnameCache,
-): ReadonlyArray<Segment> => parsePathname(pathname, cache, false)
-
+/**
+ * Parse a pathname into an array of typed segments used by the router's
+ * matcher. Results are optionally cached via an LRU cache.
+ */
 /**
  * Parse a pathname into an array of typed segments used by the router's
  * matcher. Results are optionally cached via an LRU cache.
@@ -233,12 +235,11 @@ export const parseRoutePathSegments = (
 export const parsePathname = (
   pathname?: string,
   cache?: ParsePathnameCache,
-  basePathValues?: boolean,
 ): ReadonlyArray<Segment> => {
   if (!pathname) return []
   const cached = cache?.get(pathname)
   if (cached) return cached
-  const parsed = baseParsePathname(pathname, basePathValues)
+  const parsed = baseParsePathname(pathname)
   cache?.set(pathname, parsed)
   return parsed
 }
@@ -268,10 +269,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 `$`
  */
-function baseParsePathname(
-  pathname: string,
-  basePathValues?: boolean,
-): ReadonlyArray<Segment> {
+function baseParsePathname(pathname: string): ReadonlyArray<Segment> {
   pathname = cleanPath(pathname)
 
   const segments: Array<Segment> = []
@@ -293,14 +291,8 @@ function baseParsePathname(
 
   segments.push(
     ...split.map((part): Segment => {
-      // strip tailing underscore for non-nested paths
-      const partToMatch =
-        !basePathValues && part !== rootRouteId && part.slice(-1) === '_'
-          ? part.slice(0, -1)
-          : part
-
       // Check for wildcard with curly braces: prefix{$}suffix
-      const wildcardBracesMatch = partToMatch.match(WILDCARD_W_CURLY_BRACES_RE)
+      const wildcardBracesMatch = part.match(WILDCARD_W_CURLY_BRACES_RE)
       if (wildcardBracesMatch) {
         const prefix = wildcardBracesMatch[1]
         const suffix = wildcardBracesMatch[2]
@@ -313,7 +305,7 @@ function baseParsePathname(
       }
 
       // Check for optional parameter format: prefix{-$paramName}suffix
-      const optionalParamBracesMatch = partToMatch.match(
+      const optionalParamBracesMatch = part.match(
         OPTIONAL_PARAM_W_CURLY_BRACES_RE,
       )
       if (optionalParamBracesMatch) {
@@ -329,7 +321,7 @@ function baseParsePathname(
       }
 
       // Check for the new parameter format: prefix{$paramName}suffix
-      const paramBracesMatch = partToMatch.match(PARAM_W_CURLY_BRACES_RE)
+      const paramBracesMatch = part.match(PARAM_W_CURLY_BRACES_RE)
       if (paramBracesMatch) {
         const prefix = paramBracesMatch[1]
         const paramName = paramBracesMatch[2]
@@ -343,8 +335,8 @@ function baseParsePathname(
       }
 
       // Check for bare parameter format: $paramName (without curly braces)
-      if (PARAM_RE.test(partToMatch)) {
-        const paramName = partToMatch.substring(1)
+      if (PARAM_RE.test(part)) {
+        const paramName = part.substring(1)
         return {
           type: SEGMENT_TYPE_PARAM,
           value: '$' + paramName,
@@ -354,7 +346,7 @@ function baseParsePathname(
       }
 
       // Check for bare wildcard: $ (without curly braces)
-      if (WILDCARD_RE.test(partToMatch)) {
+      if (WILDCARD_RE.test(part)) {
         return {
           type: SEGMENT_TYPE_WILDCARD,
           value: '$',
@@ -366,12 +358,12 @@ function baseParsePathname(
       // Handle regular pathname segment
       return {
         type: SEGMENT_TYPE_PATHNAME,
-        value: partToMatch.includes('%25')
-          ? partToMatch
+        value: part.includes('%25')
+          ? part
               .split('%25')
               .map((segment) => decodeURI(segment))
               .join('%25')
-          : decodeURI(partToMatch),
+          : decodeURI(part),
       }
     }),
   )
@@ -409,6 +401,10 @@ type InterPolatePathResult = {
  * - Supports `{-$optional}` segments, `{prefix{$id}suffix}` and `{$}` wildcards
  * - Optionally leaves placeholders or wildcards in place
  */
+/**
+ * Interpolate params and wildcards into a route path template.
+ * Encodes safely and supports optional params and custom decode char maps.
+ */
 export function interpolatePath({
   path,
   params,
@@ -417,7 +413,7 @@ export function interpolatePath({
   decodeCharMap,
   parseCache,
 }: InterpolatePathOptions): InterPolatePathResult {
-  const interpolatedPathSegments = parseRoutePathSegments(path, parseCache)
+  const interpolatedPathSegments = parsePathname(path, parseCache)
 
   function encodeParam(key: string): any {
     const value = params[key]
@@ -535,6 +531,10 @@ function encodePathParam(value: string, decodeCharMap?: Map<string, string>) {
   return encoded
 }
 
+/**
+ * Match a pathname against a route destination and return extracted params
+ * or `undefined`. Uses the same parsing as the router for consistency.
+ */
 /**
  * Match a pathname against a route destination and return extracted params
  * or `undefined`. Uses the same parsing as the router for consistency.
@@ -554,6 +554,7 @@ export function matchPathname(
   return pathParams ?? {}
 }
 
+/** Low-level matcher that compares two path strings and extracts params. */
 /** Low-level matcher that compares two path strings and extracts params. */
 export function matchByPath(
   from: string,
@@ -567,11 +568,11 @@ export function matchByPath(
   const stringTo = to as string
 
   // Parse the from and to
-  const baseSegments = parseBasePathSegments(
+  const baseSegments = parsePathname(
     from.startsWith('/') ? from : `/${from}`,
     parseCache,
   )
-  const routeSegments = parseRoutePathSegments(
+  const routeSegments = parsePathname(
     stringTo.startsWith('/') ? stringTo : `/${stringTo}`,
     parseCache,
   )

package/src/process-route-tree.ts

@@ -3,7 +3,7 @@ import {
   SEGMENT_TYPE_OPTIONAL_PARAM,
   SEGMENT_TYPE_PARAM,
   SEGMENT_TYPE_PATHNAME,
-  parseRoutePathSegments,
+  parsePathname,
   trimPathLeft,
   trimPathRight,
 } from './path'
@@ -70,7 +70,7 @@ function sortRoutes<TRouteLike extends RouteLike>(
     }
 
     const trimmed = trimPathLeft(d.fullPath)
-    let parsed = parseRoutePathSegments(trimmed)
+    let parsed = parsePathname(trimmed)
 
     // Removes the leading slash if it is not the only remaining segment
     let skip = 0

package/src/qss.ts

@@ -47,6 +47,7 @@ export function encode(
  * // Example input: toValue("123")
  * // Expected output: 123
  */
+/** Convert a string into a primitive boolean/number when possible. */
 function toValue(str: unknown) {
   if (!str) return ''
 

package/src/rewrite.ts

@@ -1,6 +1,7 @@
 import { joinPaths, trimPath } from './path'
 import type { LocationRewrite } from './router'
 
+/** Compose multiple rewrite pairs into a single in/out rewrite. */
 /** Compose multiple rewrite pairs into a single in/out rewrite. */
 export function composeRewrites(rewrites: Array<LocationRewrite>) {
   return {
@@ -19,6 +20,7 @@ export function composeRewrites(rewrites: Array<LocationRewrite>) {
   } satisfies LocationRewrite
 }
 
+/** Create a rewrite pair that strips/adds a basepath on input/output. */
 /** Create a rewrite pair that strips/adds a basepath on input/output. */
 export function rewriteBasepath(opts: {
   basepath: string
@@ -56,6 +58,7 @@ export function rewriteBasepath(opts: {
   } satisfies LocationRewrite
 }
 
+/** Execute a location input rewrite if provided. */
 /** Execute a location input rewrite if provided. */
 export function executeRewriteInput(
   rewrite: LocationRewrite | undefined,
@@ -72,6 +75,7 @@ export function executeRewriteInput(
   return url
 }
 
+/** Execute a location output rewrite if provided. */
 /** Execute a location output rewrite if provided. */
 export function executeRewriteOutput(
   rewrite: LocationRewrite | undefined,

package/src/scroll-restoration.ts

@@ -35,6 +35,7 @@ function getSafeSessionStorage() {
 
 /** SessionStorage key used to persist scroll restoration state. */
 /** SessionStorage key used to store scroll positions across navigations. */
+/** SessionStorage key used to store scroll positions across navigations. */
 export const storageKey = 'tsr-scroll-restoration-v1_3'
 
 const throttle = (fn: (...args: Array<any>) => void, wait: number) => {
@@ -72,6 +73,7 @@ function createScrollRestorationCache(): ScrollRestorationCache | null {
   }
 }
 
+/** In-memory handle to the persisted scroll restoration cache. */
 /** In-memory handle to the persisted scroll restoration cache. */
 /** In-memory handle to the persisted scroll restoration cache. */
 export const scrollRestorationCache = createScrollRestorationCache()
@@ -89,6 +91,9 @@ export const scrollRestorationCache = createScrollRestorationCache()
 /**
  * Default scroll restoration cache key: location state key or full href.
  */
+/**
+ * Default scroll restoration cache key: location state key or full href.
+ */
 export const defaultGetScrollRestorationKey = (location: ParsedLocation) => {
   return location.state.__TSR_key! || location.href
 }
@@ -112,6 +117,9 @@ let ignoreScroll = false
 // unless they are passed in as arguments. Why? Because we need to be able to
 // toString() it into a script tag to execute as early as possible in the browser
 // during SSR. Additionally, we also call it from within the router lifecycle
+/**
+ * Restore scroll positions for window/elements based on cached entries.
+ */
 /**
  * Restore scroll positions for window/elements based on cached entries.
  */
@@ -214,6 +222,7 @@ export function restoreScroll({
   ignoreScroll = false
 }
 
+/** Setup global listeners and hooks to support scroll restoration. */
 /** Setup global listeners and hooks to support scroll restoration. */
 export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
   if (!scrollRestorationCache && !router.isServer) {
@@ -388,6 +397,11 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
  * Provides hash scrolling for programmatic navigation when default browser handling is prevented.
  * @param router The router instance containing current location and state
  */
+/**
+ * @private
+ * Handles hash-based scrolling after navigation completes.
+ * To be used in framework-specific Transitioners.
+ */
 export function handleHashScroll(router: AnyRouter) {
   if (typeof document !== 'undefined' && (document as any).querySelector) {
     const hashScrollIntoViewOptions =

package/src/searchParams.ts

@@ -1,9 +1,11 @@
 import { decode, encode } from './qss'
 import type { AnySchema } from './validators'
 
+/** Default `parseSearch` that strips leading '?' and JSON-parses values. */
 /** Default `parseSearch` that strips leading '?' and JSON-parses values. */
 /** Default `parseSearch` that strips leading '?' and JSON-parses values. */
 export const defaultParseSearch = parseSearchWith(JSON.parse)
+/** Default `stringifySearch` using JSON.stringify for complex values. */
 export const defaultStringifySearch = stringifySearchWith(
   JSON.stringify,
   JSON.parse,

package/src/utils.ts

@@ -184,6 +184,10 @@ export type LooseAsyncReturnType<T> = T extends (
     : TReturn
   : never
 
+/**
+ * Return the last element of an array.
+ * Intended for non-empty arrays used within router internals.
+ */
 export function last<T>(arr: Array<T>) {
   return arr[arr.length - 1]
 }
@@ -192,6 +196,10 @@ function isFunction(d: any): d is Function {
   return typeof d === 'function'
 }
 
+/**
+ * Apply a value-or-updater to a previous value.
+ * Accepts either a literal value or a function of the previous value.
+ */
 export function functionalUpdate<TPrevious, TResult = TPrevious>(
   updater: Updater<TPrevious, TResult> | NonNullableUpdater<TPrevious, TResult>,
   previous: TPrevious,
@@ -311,10 +319,17 @@ function hasObjectPrototype(o: any) {
   return Object.prototype.toString.call(o) === '[object Object]'
 }
 
+/**
+ * Check if a value is a "plain" array (no extra enumerable keys).
+ */
 export function isPlainArray(value: unknown): value is Array<unknown> {
   return Array.isArray(value) && value.length === Object.keys(value).length
 }
 
+/**
+ * Perform a deep equality check with options for partial comparison and
+ * ignoring `undefined` values. Optimized for router state comparisons.
+ */
 export function deepEqual(
   a: any,
   b: any,
@@ -407,6 +422,10 @@ export type ControlledPromise<T> = Promise<T> & {
   value?: T
 }
 
+/**
+ * Create a promise with exposed resolve/reject and status fields.
+ * Useful for coordinating async router lifecycle operations.
+ */
 export function createControlledPromise<T>(onResolve?: (value: T) => void) {
   let resolveLoadPromise!: (value: T) => void
   let rejectLoadPromise!: (value: any) => void
@@ -433,6 +452,10 @@ export function createControlledPromise<T>(onResolve?: (value: T) => void) {
   return controlledPromise
 }
 
+/**
+ * Heuristically detect dynamic import "module not found" errors
+ * across major browsers for lazy route component handling.
+ */
 export function isModuleNotFoundError(error: any): boolean {
   // chrome: "Failed to fetch dynamically imported module: http://localhost:5173/src/routes/posts.index.tsx?tsr-split"
   // firefox: "error loading dynamically imported module: http://localhost:5173/src/routes/posts.index.tsx?tsr-split"