@tanstack/router-core 1.120.7 → 1.121.0-alpha.11

package/src/path.ts

@@ -5,6 +5,9 @@ import type { AnyPathParams } from './route'
 export interface Segment {
   type: 'pathname' | 'param' | 'wildcard'
   value: string
+  // Add a new property to store the static segment if present
+  prefixSegment?: string
+  suffixSegment?: string
 }
 
 export function joinPaths(paths: Array<string | undefined>) {
@@ -137,10 +140,52 @@ export function resolvePath({
     }
   }
 
-  const joined = joinPaths([basepath, ...baseSegments.map((d) => d.value)])
+  const segmentValues = baseSegments.map((segment) => {
+    if (segment.type === 'param') {
+      const param = segment.value.substring(1)
+      if (segment.prefixSegment && segment.suffixSegment) {
+        return `${segment.prefixSegment}{$${param}}${segment.suffixSegment}`
+      } else if (segment.prefixSegment) {
+        return `${segment.prefixSegment}{$${param}}`
+      } else if (segment.suffixSegment) {
+        return `{$${param}}${segment.suffixSegment}`
+      }
+    }
+    if (segment.type === 'wildcard') {
+      if (segment.prefixSegment && segment.suffixSegment) {
+        return `${segment.prefixSegment}{$}${segment.suffixSegment}`
+      } else if (segment.prefixSegment) {
+        return `${segment.prefixSegment}{$}`
+      } else if (segment.suffixSegment) {
+        return `{$}${segment.suffixSegment}`
+      }
+    }
+    return segment.value
+  })
+  const joined = joinPaths([basepath, ...segmentValues])
   return cleanPath(joined)
 }
 
+const PARAM_RE = /^\$.{1,}$/ // $paramName
+const PARAM_W_CURLY_BRACES_RE = /^(.*?)\{(\$[a-zA-Z_$][a-zA-Z0-9_$]*)\}(.*)$/ // prefix{$paramName}suffix
+const WILDCARD_RE = /^\$$/ // $
+const WILDCARD_W_CURLY_BRACES_RE = /^(.*?)\{\$\}(.*)$/ // prefix{$}suffix
+
+/**
+ * Required: `/foo/$bar` ✅
+ * Prefix and Suffix: `/foo/prefix${bar}suffix` ✅
+ * Wildcard: `/foo/$` ✅
+ * Wildcard with Prefix and Suffix: `/foo/prefix{$}suffix` ✅
+ *
+ * Future:
+ * Optional: `/foo/{-bar}`
+ * Optional named segment: `/foo/{bar}`
+ * Optional named segment with Prefix and Suffix: `/foo/prefix{-bar}suffix`
+ * Escape special characters:
+ * - `/foo/[$]` - Static route
+ * - `/foo/[$]{$foo} - Dynamic route with a static prefix of `$`
+ * - `/foo/{$foo}[$]` - Dynamic route with a static suffix of `$`
+ */
 export function parsePathname(pathname?: string): Array<Segment> {
   if (!pathname) {
     return []
@@ -167,20 +212,55 @@ export function parsePathname(pathname?: string): Array<Segment> {
 
   segments.push(
     ...split.map((part): Segment => {
-      if (part === '$' || part === '*') {
+      // Check for wildcard with curly braces: prefix{$}suffix
+      const wildcardBracesMatch = part.match(WILDCARD_W_CURLY_BRACES_RE)
+      if (wildcardBracesMatch) {
+        const prefix = wildcardBracesMatch[1]
+        const suffix = wildcardBracesMatch[2]
         return {
           type: 'wildcard',
-          value: part,
+          value: '$',
+          prefixSegment: prefix || undefined,
+          suffixSegment: suffix || undefined,
         }
       }
 
-      if (part.charAt(0) === '$') {
+      // Check for the new parameter format: prefix{$paramName}suffix
+      const paramBracesMatch = part.match(PARAM_W_CURLY_BRACES_RE)
+      if (paramBracesMatch) {
+        const prefix = paramBracesMatch[1]
+        const paramName = paramBracesMatch[2]
+        const suffix = paramBracesMatch[3]
         return {
           type: 'param',
-          value: part,
+          value: '' + paramName,
+          prefixSegment: prefix || undefined,
+          suffixSegment: suffix || undefined,
         }
       }
 
+      // Check for bare parameter format: $paramName (without curly braces)
+      if (PARAM_RE.test(part)) {
+        const paramName = part.substring(1)
+        return {
+          type: 'param',
+          value: '$' + paramName,
+          prefixSegment: undefined,
+          suffixSegment: undefined,
+        }
+      }
+
+      // Check for bare wildcard: $ (without curly braces)
+      if (WILDCARD_RE.test(part)) {
+        return {
+          type: 'wildcard',
+          value: '$',
+          prefixSegment: undefined,
+          suffixSegment: undefined,
+        }
+      }
+
+      // Handle regular pathname segment
       return {
         type: 'pathname',
         value: part.includes('%25')
@@ -248,9 +328,13 @@ export function interpolatePath({
     interpolatedPathSegments.map((segment) => {
       if (segment.type === 'wildcard') {
         usedParams._splat = params._splat
+        const segmentPrefix = segment.prefixSegment || ''
+        const segmentSuffix = segment.suffixSegment || ''
         const value = encodeParam('_splat')
-        if (leaveWildcards) return `${segment.value}${value ?? ''}`
-        return value
+        if (leaveWildcards) {
+          return `${segmentPrefix}${segment.value}${value ?? ''}${segmentSuffix}`
+        }
+        return `${segmentPrefix}${value}${segmentSuffix}`
       }
 
       if (segment.type === 'param') {
@@ -259,11 +343,14 @@ export function interpolatePath({
           isMissingParams = true
         }
         usedParams[key] = params[key]
+
+        const segmentPrefix = segment.prefixSegment || ''
+        const segmentSuffix = segment.suffixSegment || ''
         if (leaveParams) {
           const value = encodeParam(segment.value)
-          return `${segment.value}${value ?? ''}`
+          return `${segmentPrefix}${segment.value}${value ?? ''}${segmentSuffix}`
         }
-        return encodeParam(key) ?? 'undefined'
+        return `${segmentPrefix}${encodeParam(key) ?? 'undefined'}${segmentSuffix}`
       }
 
       return segment.value
@@ -390,9 +477,57 @@ export function matchByPath(
 
       if (routeSegment) {
         if (routeSegment.type === 'wildcard') {
-          const _splat = decodeURI(
-            joinPaths(baseSegments.slice(i).map((d) => d.value)),
-          )
+          // Capture all remaining segments for a wildcard
+          const remainingBaseSegments = baseSegments.slice(i)
+
+          let _splat: string
+
+          // If this is a wildcard with prefix/suffix, we need to handle the first segment specially
+          if (routeSegment.prefixSegment || routeSegment.suffixSegment) {
+            if (!baseSegment) return false
+
+            const prefix = routeSegment.prefixSegment || ''
+            const suffix = routeSegment.suffixSegment || ''
+
+            // Check if the base segment starts with prefix and ends with suffix
+            const baseValue = baseSegment.value
+            if ('prefixSegment' in routeSegment) {
+              if (!baseValue.startsWith(prefix)) {
+                return false
+              }
+            }
+            if ('suffixSegment' in routeSegment) {
+              if (
+                !baseSegments[baseSegments.length - 1]?.value.endsWith(suffix)
+              ) {
+                return false
+              }
+            }
+
+            let rejoinedSplat = decodeURI(
+              joinPaths(remainingBaseSegments.map((d) => d.value)),
+            )
+
+            // Remove the prefix and suffix from the rejoined splat
+            if (prefix && rejoinedSplat.startsWith(prefix)) {
+              rejoinedSplat = rejoinedSplat.slice(prefix.length)
+            }
+
+            if (suffix && rejoinedSplat.endsWith(suffix)) {
+              rejoinedSplat = rejoinedSplat.slice(
+                0,
+                rejoinedSplat.length - suffix.length,
+              )
+            }
+
+            _splat = rejoinedSplat
+          } else {
+            // If no prefix/suffix, just rejoin the remaining segments
+            _splat = decodeURI(
+              joinPaths(remainingBaseSegments.map((d) => d.value)),
+            )
+          }
+
           // TODO: Deprecate *
           params['*'] = _splat
           params['_splat'] = _splat
@@ -426,11 +561,41 @@ export function matchByPath(
           if (baseSegment.value === '/') {
             return false
           }
-          if (baseSegment.value.charAt(0) !== '$') {
-            params[routeSegment.value.substring(1)] = decodeURIComponent(
-              baseSegment.value,
-            )
+
+          let _paramValue: string
+
+          // If this param has prefix/suffix, we need to extract the actual parameter value
+          if (routeSegment.prefixSegment || routeSegment.suffixSegment) {
+            const prefix = routeSegment.prefixSegment || ''
+            const suffix = routeSegment.suffixSegment || ''
+
+            // Check if the base segment starts with prefix and ends with suffix
+            const baseValue = baseSegment.value
+            if (prefix && !baseValue.startsWith(prefix)) {
+              return false
+            }
+            if (suffix && !baseValue.endsWith(suffix)) {
+              return false
+            }
+
+            let paramValue = baseValue
+            if (prefix && paramValue.startsWith(prefix)) {
+              paramValue = paramValue.slice(prefix.length)
+            }
+            if (suffix && paramValue.endsWith(suffix)) {
+              paramValue = paramValue.slice(
+                0,
+                paramValue.length - suffix.length,
+              )
+            }
+
+            _paramValue = decodeURIComponent(paramValue)
+          } else {
+            // If no prefix/suffix, just decode the base segment value
+            _paramValue = decodeURIComponent(baseSegment.value)
           }
+
+          params[routeSegment.value.substring(1)] = _paramValue
         }
       }
 

package/src/redirect.ts

@@ -1,6 +1,5 @@
 import type { NavigateOptions } from './link'
 import type { AnyRouter, RegisteredRouter } from './router'
-import type { PickAsRequired } from './utils'
 
 export type AnyRedirect = Redirect<any, any, any, any, any>
 
@@ -13,6 +12,17 @@ export type Redirect<
   TTo extends string | undefined = undefined,
   TMaskFrom extends string = TFrom,
   TMaskTo extends string = '.',
+> = Response & {
+  options: NavigateOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>
+  redirectHandled?: boolean
+}
+
+export type RedirectOptions<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom extends string = string,
+  TTo extends string | undefined = undefined,
+  TMaskFrom extends string = TFrom,
+  TMaskTo extends string = '.',
 > = {
   href?: string
   /**
@@ -42,12 +52,7 @@ export type ResolvedRedirect<
   TTo extends string = '',
   TMaskFrom extends string = TFrom,
   TMaskTo extends string = '',
-> = PickAsRequired<
-  Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
-  'code' | 'statusCode' | 'headers'
-> & {
-  href: string
-}
+> = Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>
 
 export function redirect<
   TRouter extends AnyRouter = RegisteredRouter,
@@ -56,30 +61,48 @@ export function redirect<
   const TMaskFrom extends string = TFrom,
   const TMaskTo extends string = '',
 >(
-  opts: Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
+  opts: RedirectOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>,
 ): Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo> {
-  ;(opts as any).isRedirect = true
   opts.statusCode = opts.statusCode || opts.code || 307
-  opts.headers = opts.headers || {}
+
   if (!opts.reloadDocument) {
-    opts.reloadDocument = false
     try {
       new URL(`${opts.href}`)
       opts.reloadDocument = true
     } catch {}
   }
 
+  const headers = new Headers(opts.headers || {})
+
+  const response = new Response(null, {
+    status: opts.statusCode,
+    headers,
+  })
+
+  ;(response as Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>).options =
+    opts
+
   if (opts.throw) {
-    throw opts
+    throw response
   }
 
-  return opts
+  return response as Redirect<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>
 }
 
 export function isRedirect(obj: any): obj is AnyRedirect {
-  return !!obj?.isRedirect
+  return obj instanceof Response && !!(obj as any).options
 }
 
-export function isResolvedRedirect(obj: any): obj is ResolvedRedirect {
-  return !!obj?.isRedirect && obj.href
+export function isResolvedRedirect(
+  obj: any,
+): obj is AnyRedirect & { options: { href: string } } {
+  return isRedirect(obj) && !!obj.options.href
+}
+
+export function parseRedirect(obj: any) {
+  if (typeof obj === 'object' && obj.isSerializedRedirect) {
+    return redirect(obj)
+  }
+
+  return undefined
 }

package/src/route.ts

@@ -1,3 +1,4 @@
+import invariant from 'tiny-invariant'
 import { joinPaths, trimPathLeft } from './path'
 import { notFound } from './not-found'
 import { rootRouteId } from './root'
@@ -17,9 +18,12 @@ import type { AnyRouter, RegisteredRouter } from './router'
 import type { BuildLocationFn, NavigateFn } from './RouterProvider'
 import type {
   Assign,
+  Awaitable,
   Constrain,
   Expand,
   IntersectAssign,
+  LooseAsyncReturnType,
+  LooseReturnType,
   NoInfer,
 } from './utils'
 import type {
@@ -150,27 +154,24 @@ export type ResolveSearchSchema<TSearchValidator> =
           ? ResolveSearchSchemaFn<TSearchValidator['parse']>
           : ResolveSearchSchemaFn<TSearchValidator>
 
-export type ParseSplatParams<TPath extends string> = TPath &
-  `${string}$` extends never
-  ? TPath & `${string}$/${string}` extends never
-    ? never
-    : '_splat'
-  : '_splat'
+export type ResolveRequiredParams<TPath extends string, T> = {
+  [K in ParsePathParams<TPath>['required']]: T
+}
 
-export interface SplatParams {
-  _splat?: string
+export type ResolveOptionalParams<TPath extends string, T> = {
+  [K in ParsePathParams<TPath>['optional']]?: T
 }
 
-export type ResolveParams<TPath extends string> =
-  ParseSplatParams<TPath> extends never
-    ? Record<ParsePathParams<TPath>, string>
-    : Record<ParsePathParams<TPath>, string> & SplatParams
+export type ResolveParams<
+  TPath extends string,
+  T = string,
+> = ResolveRequiredParams<TPath, T> & ResolveOptionalParams<TPath, T>
 
 export type ParseParamsFn<in out TPath extends string, in out TParams> = (
-  rawParams: ResolveParams<TPath>,
-) => TParams extends Record<ParsePathParams<TPath>, any>
+  rawParams: Expand<ResolveParams<TPath>>,
+) => TParams extends ResolveParams<TPath, any>
   ? TParams
-  : Record<ParsePathParams<TPath>, any>
+  : ResolveParams<TPath, any>
 
 export type StringifyParamsFn<in out TPath extends string, in out TParams> = (
   params: TParams,
@@ -270,20 +271,6 @@ export type TrimPathRight<T extends string> = T extends '/'
     ? TrimPathRight<U>
     : T
 
-export type LooseReturnType<T> = T extends (
-  ...args: Array<any>
-) => infer TReturn
-  ? TReturn
-  : never
-
-export type LooseAsyncReturnType<T> = T extends (
-  ...args: Array<any>
-) => infer TReturn
-  ? TReturn extends Promise<infer TReturn>
-    ? TReturn
-    : TReturn
-  : never
-
 export type ContextReturnType<TContextFn> = unknown extends TContextFn
   ? TContextFn
   : LooseReturnType<TContextFn> extends never
@@ -448,7 +435,7 @@ export interface RouteExtensions<in out TId, in out TFullPath> {
 }
 
 export type RouteLazyFn<TRoute extends AnyRoute> = (
-  lazyFn: () => Promise<LazyRoute>,
+  lazyFn: () => Promise<LazyRoute<TRoute>>,
 ) => TRoute
 
 export type RouteAddChildrenFn<
@@ -602,7 +589,26 @@ export interface Route<
   >
   isRoot: TParentRoute extends AnyRoute ? true : false
   _componentsPromise?: Promise<Array<void>>
-  lazyFn?: () => Promise<LazyRoute>
+  lazyFn?: () => Promise<
+    LazyRoute<
+      Route<
+        TParentRoute,
+        TPath,
+        TFullPath,
+        TCustomId,
+        TId,
+        TSearchValidator,
+        TParams,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn,
+        TLoaderDeps,
+        TLoaderFn,
+        TChildren,
+        TFileRouteTypes
+      >
+    >
+  >
   _lazyPromise?: Promise<void>
   rank: number
   to: TrimPathRight<TFullPath>
@@ -1100,7 +1106,7 @@ export interface UpdatableRouteOptions<
       TBeforeLoadFn,
       TLoaderDeps
     >,
-  ) => Record<string, string>
+  ) => Awaitable<Record<string, string>>
   head?: (
     ctx: AssetFnContextOptions<
       TRouteId,
@@ -1114,11 +1120,11 @@ export interface UpdatableRouteOptions<
       TBeforeLoadFn,
       TLoaderDeps
     >,
-  ) => {
+  ) => Awaitable<{
     links?: AnyRouteMatch['links']
     scripts?: AnyRouteMatch['headScripts']
     meta?: AnyRouteMatch['meta']
-  }
+  }>
   scripts?: (
     ctx: AssetFnContextOptions<
       TRouteId,
@@ -1132,7 +1138,7 @@ export interface UpdatableRouteOptions<
       TBeforeLoadFn,
       TLoaderDeps
     >,
-  ) => AnyRouteMatch['scripts']
+  ) => Awaitable<AnyRouteMatch['scripts']>
   ssr?: boolean
   codeSplitGroupings?: Array<
     Array<
@@ -1298,7 +1304,24 @@ export class BaseRoute<
   in out TLoaderFn = undefined,
   in out TChildren = unknown,
   in out TFileRouteTypes = unknown,
-> {
+> implements
+    Route<
+      TParentRoute,
+      TPath,
+      TFullPath,
+      TCustomId,
+      TId,
+      TSearchValidator,
+      TParams,
+      TRouterContext,
+      TRouteContextFn,
+      TBeforeLoadFn,
+      TLoaderDeps,
+      TLoaderFn,
+      TChildren,
+      TFileRouteTypes
+    >
+{
   isRoot: TParentRoute extends AnyRoute ? true : false
   options: RouteOptions<
     TParentRoute,
@@ -1347,7 +1370,26 @@ export class BaseRoute<
   children?: TChildren
   originalIndex?: number
   rank!: number
-  lazyFn?: () => Promise<LazyRoute>
+  lazyFn?: () => Promise<
+    LazyRoute<
+      Route<
+        TParentRoute,
+        TPath,
+        TFullPath,
+        TCustomId,
+        TId,
+        TSearchValidator,
+        TParams,
+        TRouterContext,
+        TRouteContextFn,
+        TBeforeLoadFn,
+        TLoaderDeps,
+        TLoaderFn,
+        TChildren,
+        TFileRouteTypes
+      >
+    >
+  >
   _lazyPromise?: Promise<void>
   _componentsPromise?: Promise<Array<void>>
 
@@ -1420,7 +1462,8 @@ export class BaseRoute<
     if (isRoot) {
       this._path = rootRouteId as TPath
     } else if (!this.parentRoute) {
-      throw new Error(
+      invariant(
+        false,
         `Child Route instances must pass a 'getParentRoute: () => ParentRoute' option that returns a Route instance.`,
       )
     }
@@ -1460,6 +1503,16 @@ export class BaseRoute<
     this._ssr = options?.ssr ?? opts.defaultSsr ?? true
   }
 
+  clone = (other: typeof this) => {
+    this._path = other._path
+    this._id = other._id
+    this._fullPath = other._fullPath
+    this._to = other._to
+    this._ssr = other._ssr
+    this.options.getParentRoute = other.options.getParentRoute
+    this.children = other.children
+  }
+
   addChildren: RouteAddChildrenFn<
     TParentRoute,
     TPath,
@@ -1608,32 +1661,6 @@ export class BaseRouteApi<TId, TRouter extends AnyRouter = RegisteredRouter> {
   }
 }
 
-export interface RootRoute<
-  in out TSearchValidator = undefined,
-  in out TRouterContext = {},
-  in out TRouteContextFn = AnyContext,
-  in out TBeforeLoadFn = AnyContext,
-  in out TLoaderDeps extends Record<string, any> = {},
-  in out TLoaderFn = undefined,
-  in out TChildren = unknown,
-  in out TFileRouteTypes = unknown,
-> extends Route<
-    any, // TParentRoute
-    '/', // TPath
-    '/', // TFullPath
-    string, // TCustomId
-    RootRouteId, // TId
-    TSearchValidator, // TSearchValidator
-    {}, // TParams
-    TRouterContext,
-    TRouteContextFn,
-    TBeforeLoadFn,
-    TLoaderDeps,
-    TLoaderFn,
-    TChildren, // TChildren
-    TFileRouteTypes
-  > {}
-
 export class BaseRootRoute<
   in out TSearchValidator = undefined,
   in out TRouterContext = {},