@tanstack/router-core 0.0.1-beta.8 → 1.20.3-alpha.1

package/src/location.ts

@@ -0,0 +1,13 @@
+import type { ParsedHistoryState } from '@tanstack/history'
+import type { AnySchema } from './validators'
+
+export interface ParsedLocation<TSearchObj extends AnySchema = {}> {
+  href: string
+  pathname: string
+  search: TSearchObj
+  searchStr: string
+  state: ParsedHistoryState
+  hash: string
+  maskedLocation?: ParsedLocation<TSearchObj>
+  unmaskOnReload?: boolean
+}

package/src/manifest.ts

@@ -0,0 +1,32 @@
+export type Manifest = {
+  routes: Record<
+    string,
+    {
+      filePath?: string
+      preloads?: Array<string>
+      assets?: Array<RouterManagedTag>
+    }
+  >
+}
+
+export type RouterManagedTag =
+  | {
+      tag: 'title'
+      attrs?: Record<string, any>
+      children: string
+    }
+  | {
+      tag: 'meta' | 'link'
+      attrs?: Record<string, any>
+      children?: never
+    }
+  | {
+      tag: 'script'
+      attrs?: Record<string, any>
+      children?: string
+    }
+  | {
+      tag: 'style'
+      attrs?: Record<string, any>
+      children?: string
+    }

package/src/not-found.ts

@@ -0,0 +1,29 @@
+import type { RouteIds } from './routeInfo'
+import type { RegisteredRouter } from './router'
+
+export type NotFoundError = {
+  /**
+    @deprecated
+    Use `routeId: rootRouteId` instead
+  */
+  global?: boolean
+  /**
+    @private
+    Do not use this. It's used internally to indicate a path matching error
+  */
+  _global?: boolean
+  data?: any
+  throw?: boolean
+  routeId?: RouteIds<RegisteredRouter['routeTree']>
+  headers?: HeadersInit
+}
+
+export function notFound(options: NotFoundError = {}) {
+  ;(options as any).isNotFound = true
+  if (options.throw) throw options
+  return options
+}
+
+export function isNotFound(obj: any): obj is NotFoundError {
+  return !!obj?.isNotFound
+}

package/src/path.ts

@@ -1,14 +1,23 @@
-import { AnyPathParams } from './routeConfig'
-import { MatchLocation } from './router'
 import { last } from './utils'
+import type { MatchLocation } from './RouterProvider'
+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: (string | undefined)[]) {
-  return cleanPath(paths.filter(Boolean).join('/'))
+export function joinPaths(paths: Array<string | undefined>) {
+  return cleanPath(
+    paths
+      .filter((val) => {
+        return val !== undefined
+      })
+      .join('/'),
+  )
 }
 
 export function cleanPath(path: string) {
@@ -28,13 +37,79 @@ export function trimPath(path: string) {
   return trimPathRight(trimPathLeft(path))
 }
 
-export function resolvePath(basepath: string, base: string, to: string) {
-  base = base.replace(new RegExp(`^${basepath}`), '/')
-  to = to.replace(new RegExp(`^${basepath}`), '/')
+export function removeTrailingSlash(value: string, basepath: string): string {
+  if (value?.endsWith('/') && value !== '/' && value !== `${basepath}/`) {
+    return value.slice(0, -1)
+  }
+  return value
+}
+
+// intended to only compare path name
+// see the usage in the isActive under useLinkProps
+// /sample/path1 = /sample/path1/
+// /sample/path1/some <> /sample/path1
+export function exactPathTest(
+  pathName1: string,
+  pathName2: string,
+  basepath: string,
+): boolean {
+  return (
+    removeTrailingSlash(pathName1, basepath) ===
+    removeTrailingSlash(pathName2, basepath)
+  )
+}
+
+// When resolving relative paths, we treat all paths as if they are trailing slash
+// documents. All trailing slashes are removed after the path is resolved.
+// Here are a few examples:
+//
+// /a/b/c + ./d = /a/b/c/d
+// /a/b/c + ../d = /a/b/d
+// /a/b/c + ./d/ = /a/b/c/d
+// /a/b/c + ../d/ = /a/b/d
+// /a/b/c + ./ = /a/b/c
+//
+// Absolute paths that start with `/` short circuit the resolution process to the root
+// path.
+//
+// Here are some examples:
+//
+// /a/b/c + /d = /d
+// /a/b/c + /d/ = /d
+// /a/b/c + / = /
+//
+// Non-.-prefixed paths are still treated as relative paths, resolved like `./`
+//
+// Here are some examples:
+//
+// /a/b/c + d = /a/b/c/d
+// /a/b/c + d/ = /a/b/c/d
+// /a/b/c + d/e = /a/b/c/d/e
+interface ResolvePathOptions {
+  basepath: string
+  base: string
+  to: string
+  trailingSlash?: 'always' | 'never' | 'preserve'
+  caseSensitive?: boolean
+}
+
+export function resolvePath({
+  basepath,
+  base,
+  to,
+  trailingSlash = 'never',
+  caseSensitive,
+}: ResolvePathOptions) {
+  base = removeBasepath(basepath, base, caseSensitive)
+  to = removeBasepath(basepath, to, caseSensitive)
 
   let baseSegments = parsePathname(base)
   const toSegments = parsePathname(to)
 
+  if (baseSegments.length > 1 && last(baseSegments)?.value === '/') {
+    baseSegments.pop()
+  }
+
   toSegments.forEach((toSegment, index) => {
     if (toSegment.value === '/') {
       if (!index) {
@@ -47,31 +122,78 @@ export function resolvePath(basepath: string, base: string, to: string) {
         // ignore inter-slashes
       }
     } else if (toSegment.value === '..') {
-      // Extra trailing slash? pop it off
-      if (baseSegments.length > 1 && last(baseSegments)?.value === '/') {
-        baseSegments.pop()
-      }
       baseSegments.pop()
     } else if (toSegment.value === '.') {
-      return
+      // ignore
     } else {
       baseSegments.push(toSegment)
     }
   })
 
-  const joined = joinPaths([basepath, ...baseSegments.map((d) => d.value)])
+  if (baseSegments.length > 1) {
+    if (last(baseSegments)?.value === '/') {
+      if (trailingSlash === 'never') {
+        baseSegments.pop()
+      }
+    } else if (trailingSlash === 'always') {
+      baseSegments.push({ type: 'pathname', 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)
 }
 
-export function parsePathname(pathname?: string): Segment[] {
+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 []
   }
 
   pathname = cleanPath(pathname)
 
-  const segments: Segment[] = []
+  const segments: Array<Segment> = []
 
   if (pathname.slice(0, 1) === '/') {
     pathname = pathname.substring(1)
@@ -90,23 +212,63 @@ export function parsePathname(pathname?: string): Segment[] {
 
   segments.push(
     ...split.map((part): Segment => {
-      if (part.startsWith('*')) {
+      // 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,
+        }
+      }
+
+      // 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: '' + paramName,
+          prefixSegment: prefix || undefined,
+          suffixSegment: suffix || undefined,
         }
       }
 
-      if (part.charAt(0) === ':') {
+      // Check for bare parameter format: $paramName (without curly braces)
+      if (PARAM_RE.test(part)) {
+        const paramName = part.substring(1)
         return {
           type: 'param',
-          value: part,
+          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,
+        value: part.includes('%25')
+          ? part
+              .split('%25')
+              .map((segment) => decodeURI(segment))
+              .join('%25')
+          : decodeURI(part),
       }
     }),
   )
@@ -122,56 +284,186 @@ export function parsePathname(pathname?: string): Segment[] {
   return segments
 }
 
-export function interpolatePath(
-  path: string | undefined,
-  params: any,
-  leaveWildcard?: boolean,
-) {
+interface InterpolatePathOptions {
+  path?: string
+  params: Record<string, unknown>
+  leaveWildcards?: boolean
+  leaveParams?: boolean
+  // Map of encoded chars to decoded chars (e.g. '%40' -> '@') that should remain decoded in path params
+  decodeCharMap?: Map<string, string>
+}
+
+type InterPolatePathResult = {
+  interpolatedPath: string
+  usedParams: Record<string, unknown>
+  isMissingParams: boolean // true if any params were not available when being looked up in the params object
+}
+export function interpolatePath({
+  path,
+  params,
+  leaveWildcards,
+  leaveParams,
+  decodeCharMap,
+}: InterpolatePathOptions): InterPolatePathResult {
   const interpolatedPathSegments = parsePathname(path)
 
-  return joinPaths(
+  function encodeParam(key: string): any {
+    const value = params[key]
+    const isValueString = typeof value === 'string'
+
+    if (['*', '_splat'].includes(key)) {
+      // the splat/catch-all routes shouldn't have the '/' encoded out
+      return isValueString ? encodeURI(value) : value
+    } else {
+      return isValueString ? encodePathParam(value, decodeCharMap) : value
+    }
+  }
+
+  // Tracking if any params are missing in the `params` object
+  // when interpolating the path
+  let isMissingParams = false
+
+  const usedParams: Record<string, unknown> = {}
+  const interpolatedPath = joinPaths(
     interpolatedPathSegments.map((segment) => {
-      if (segment.value === '*' && !leaveWildcard) {
-        return ''
+      if (segment.type === 'wildcard') {
+        usedParams._splat = params._splat
+        const segmentPrefix = segment.prefixSegment || ''
+        const segmentSuffix = segment.suffixSegment || ''
+        const value = encodeParam('_splat')
+        if (leaveWildcards) {
+          return `${segmentPrefix}${segment.value}${value ?? ''}${segmentSuffix}`
+        }
+        return `${segmentPrefix}${value}${segmentSuffix}`
       }
 
       if (segment.type === 'param') {
-        return params![segment.value.substring(1)] ?? ''
+        const key = segment.value.substring(1)
+        if (!isMissingParams && !(key in params)) {
+          isMissingParams = true
+        }
+        usedParams[key] = params[key]
+
+        const segmentPrefix = segment.prefixSegment || ''
+        const segmentSuffix = segment.suffixSegment || ''
+        if (leaveParams) {
+          const value = encodeParam(segment.value)
+          return `${segmentPrefix}${segment.value}${value ?? ''}${segmentSuffix}`
+        }
+        return `${segmentPrefix}${encodeParam(key) ?? 'undefined'}${segmentSuffix}`
       }
 
       return segment.value
     }),
   )
+  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
 }
 
 export function matchPathname(
+  basepath: string,
   currentPathname: string,
   matchLocation: Pick<MatchLocation, 'to' | 'fuzzy' | 'caseSensitive'>,
 ): AnyPathParams | undefined {
-  const pathParams = matchByPath(currentPathname, matchLocation)
-  // const searchMatched = matchBySearch(currentLocation.search, matchLocation)
+  const pathParams = matchByPath(basepath, currentPathname, matchLocation)
+  // const searchMatched = matchBySearch(location.search, matchLocation)
 
   if (matchLocation.to && !pathParams) {
     return
   }
 
-  // if (matchLocation.search && !searchMatched) {
-  //   return
-  // }
-
   return pathParams ?? {}
 }
 
+export function removeBasepath(
+  basepath: string,
+  pathname: string,
+  caseSensitive: boolean = false,
+) {
+  // normalize basepath and pathname for case-insensitive comparison if needed
+  const normalizedBasepath = caseSensitive ? basepath : basepath.toLowerCase()
+  const normalizedPathname = caseSensitive ? pathname : pathname.toLowerCase()
+
+  switch (true) {
+    // default behaviour is to serve app from the root - pathname
+    // left untouched
+    case normalizedBasepath === '/':
+      return pathname
+
+    // shortcut for removing the basepath if it matches the pathname
+    case normalizedPathname === normalizedBasepath:
+      return ''
+
+    // in case pathname is shorter than basepath - there is
+    // nothing to remove
+    case pathname.length < basepath.length:
+      return pathname
+
+    // avoid matching partial segments - strict equality handled
+    // earlier, otherwise, basepath separated from pathname with
+    // separator, therefore lack of separator means partial
+    // segment match (`/app` should not match `/application`)
+    case normalizedPathname[normalizedBasepath.length] !== '/':
+      return pathname
+
+    // remove the basepath from the pathname if it starts with it
+    case normalizedPathname.startsWith(normalizedBasepath):
+      return pathname.slice(basepath.length)
+
+    // otherwise, return the pathname as is
+    default:
+      return pathname
+  }
+}
+
 export function matchByPath(
+  basepath: string,
   from: string,
   matchLocation: Pick<MatchLocation, 'to' | 'caseSensitive' | 'fuzzy'>,
 ): Record<string, string> | undefined {
+  // check basepath first
+  if (basepath !== '/' && !from.startsWith(basepath)) {
+    return undefined
+  }
+  // Remove the base path from the pathname
+  from = removeBasepath(basepath, from, matchLocation.caseSensitive)
+  // Default to to $ (wildcard)
+  const to = removeBasepath(
+    basepath,
+    `${matchLocation.to ?? '$'}`,
+    matchLocation.caseSensitive,
+  )
+
+  // Parse the from and to
   const baseSegments = parsePathname(from)
-  const routeSegments = parsePathname(`${matchLocation.to ?? '*'}`)
+  const routeSegments = parsePathname(to)
+
+  if (!from.startsWith('/')) {
+    baseSegments.unshift({
+      type: 'pathname',
+      value: '/',
+    })
+  }
+
+  if (!to.startsWith('/')) {
+    routeSegments.unshift({
+      type: 'pathname',
+      value: '/',
+    })
+  }
 
   const params: Record<string, string> = {}
 
-  let isMatch = (() => {
+  const isMatch = (() => {
     for (
       let i = 0;
       i < Math.max(baseSegments.length, routeSegments.length);
@@ -180,16 +472,66 @@ export function matchByPath(
       const baseSegment = baseSegments[i]
       const routeSegment = routeSegments[i]
 
-      const isLastRouteSegment = i === routeSegments.length - 1
-      const isLastBaseSegment = i === baseSegments.length - 1
+      const isLastBaseSegment = i >= baseSegments.length - 1
+      const isLastRouteSegment = i >= routeSegments.length - 1
 
       if (routeSegment) {
         if (routeSegment.type === 'wildcard') {
-          if (baseSegment?.value) {
-            params['*'] = joinPaths(baseSegments.slice(i).map((d) => d.value))
-            return true
+          // 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)),
+            )
           }
-          return false
+
+          // TODO: Deprecate *
+          params['*'] = _splat
+          params['_splat'] = _splat
+          return true
         }
 
         if (routeSegment.type === 'pathname') {
@@ -216,21 +558,55 @@ export function matchByPath(
         }
 
         if (routeSegment.type === 'param') {
-          if (baseSegment?.value === '/') {
+          if (baseSegment.value === '/') {
             return false
           }
-          if (!baseSegment.value.startsWith(':')) {
-            params[routeSegment.value.substring(1)] = 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
         }
       }
 
-      if (isLastRouteSegment && !isLastBaseSegment) {
-        return !!matchLocation.fuzzy
+      if (!isLastBaseSegment && isLastRouteSegment) {
+        params['**'] = joinPaths(baseSegments.slice(i + 1).map((d) => d.value))
+        return !!matchLocation.fuzzy && routeSegment?.value !== '/'
       }
     }
+
     return true
   })()
 
-  return isMatch ? (params as Record<string, string>) : undefined
+  return isMatch ? params : undefined
 }