@benjavicente/router-core 1.168.9

package/src/not-found.ts

@@ -0,0 +1,41 @@
+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
+}
+
+/**
+ * Create a not-found error object recognized by TanStack Router.
+ *
+ * Throw this from loaders/actions to trigger the nearest `notFoundComponent`.
+ * Use `routeId` to target a specific route's not-found boundary. If `throw`
+ * is true, the error is thrown instead of returned.
+ *
+ * @param options Optional settings including `routeId`, `headers`, and `throw`.
+ * @returns A not-found error object that can be thrown or returned.
+ * @link https://tanstack.com/router/latest/docs/router/framework/react/api/router/notFoundFunction
+ */
+export function notFound(options: NotFoundError = {}) {
+  ;(options as any).isNotFound = true
+  if (options.throw) throw options
+  return options
+}
+
+/** Determine if a value is a TanStack Router not-found error. */
+export function isNotFound(obj: any): obj is NotFoundError {
+  return !!obj?.isNotFound
+}

package/src/path.ts

@@ -0,0 +1,436 @@
+import { isServer } from '@benjavicente/router-core/isServer'
+import { last } from './utils'
+import {
+  SEGMENT_TYPE_OPTIONAL_PARAM,
+  SEGMENT_TYPE_PARAM,
+  SEGMENT_TYPE_PATHNAME,
+  SEGMENT_TYPE_WILDCARD,
+  parseSegment,
+} from './new-process-route-tree'
+import type { LRUCache } from './lru-cache'
+
+/** Join path segments, cleaning duplicate slashes between parts. */
+export function joinPaths(paths: Array<string | undefined>) {
+  return cleanPath(
+    paths
+      .filter((val) => {
+        return val !== undefined
+      })
+      .join('/'),
+  )
+}
+
+/** 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 '/'). */
+export function trimPathLeft(path: string) {
+  return path === '/' ? path : path.replace(/^\/{1,}/, '')
+}
+
+/** Trim trailing slashes (except preserving root '/'). */
+export function trimPathRight(path: string) {
+  const len = path.length
+  return len > 1 && path[len - 1] === '/' ? path.replace(/\/{1,}$/, '') : path
+}
+
+/** Trim both leading and trailing slashes. */
+export function trimPath(path: string) {
+  return trimPathRight(trimPathLeft(path))
+}
+
+/** Remove a trailing slash from value when appropriate for comparisons. */
+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
+/**
+ * Compare two pathnames for exact equality after normalizing trailing slashes
+ * relative to the provided `basepath`.
+ */
+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 {
+  base: string
+  to: string
+  trailingSlash?: 'always' | 'never' | 'preserve'
+  cache?: LRUCache<string, string>
+}
+
+/**
+ * Resolve a destination path against a base, honoring trailing-slash policy
+ * and supporting relative segments (`.`/`..`) and absolute `to` values.
+ */
+export function resolvePath({
+  base,
+  to,
+  trailingSlash = 'never',
+  cache,
+}: ResolvePathOptions) {
+  const isAbsolute = to.startsWith('/')
+  const isBase = !isAbsolute && to === '.'
+
+  let key
+  if (cache) {
+    // `trailingSlash` is static per router, so it doesn't need to be part of the cache key
+    key = isAbsolute ? to : isBase ? base : base + '\0' + to
+    const cached = cache.get(key)
+    if (cached) return cached
+  }
+
+  let baseSegments: Array<string>
+  if (isBase) {
+    baseSegments = base.split('/')
+  } else if (isAbsolute) {
+    baseSegments = to.split('/')
+  } else {
+    baseSegments = base.split('/')
+    while (baseSegments.length > 1 && last(baseSegments) === '') {
+      baseSegments.pop()
+    }
+
+    const toSegments = to.split('/')
+    for (let index = 0, length = toSegments.length; index < length; index++) {
+      const value = toSegments[index]!
+      if (value === '') {
+        if (!index) {
+          // Leading slash
+          baseSegments = [value]
+        } else if (index === length - 1) {
+          // Trailing Slash
+          baseSegments.push(value)
+        } else {
+          // ignore inter-slashes
+        }
+      } else if (value === '..') {
+        baseSegments.pop()
+      } else if (value === '.') {
+        // ignore
+      } else {
+        baseSegments.push(value)
+      }
+    }
+  }
+
+  if (baseSegments.length > 1) {
+    if (last(baseSegments) === '') {
+      if (trailingSlash === 'never') {
+        baseSegments.pop()
+      }
+    } else if (trailingSlash === 'always') {
+      baseSegments.push('')
+    }
+  }
+
+  let segment
+  let joined = ''
+  for (let i = 0; i < baseSegments.length; i++) {
+    if (i > 0) joined += '/'
+    const part = baseSegments[i]!
+    if (!part) continue
+    segment = parseSegment(part, 0, segment)
+    const kind = segment[0]
+    if (kind === SEGMENT_TYPE_PATHNAME) {
+      joined += part
+      continue
+    }
+    const end = segment[5]
+    const prefix = part.substring(0, segment[1])
+    const suffix = part.substring(segment[4], end)
+    const value = part.substring(segment[2], segment[3])
+    if (kind === SEGMENT_TYPE_PARAM) {
+      joined += prefix || suffix ? `${prefix}{$${value}}${suffix}` : `$${value}`
+    } else if (kind === SEGMENT_TYPE_WILDCARD) {
+      joined += prefix || suffix ? `${prefix}{$}${suffix}` : '$'
+    } else {
+      // SEGMENT_TYPE_OPTIONAL_PARAM
+      joined += `${prefix}{-$${value}}${suffix}`
+    }
+  }
+  joined = cleanPath(joined)
+  const result = joined || '/'
+  if (key && cache) cache.set(key, result)
+  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>
+  /**
+   * A function that decodes a path parameter value.
+   * Obtained from `compileDecodeCharMap(pathParamsAllowedCharacters)`.
+   */
+  decoder?: (encoded: string) => string
+  /**
+   * @internal
+   * For testing only, in development mode we use the router.isServer value
+   */
+  server?: boolean
+}
+
+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
+}
+
+function encodeParam(
+  key: string,
+  params: InterpolatePathOptions['params'],
+  decoder: InterpolatePathOptions['decoder'],
+): any {
+  const value = params[key]
+  if (typeof value !== 'string') return value
+
+  if (key === '_splat') {
+    // Early return if value only contains URL-safe characters (performance optimization)
+    if (/^[a-zA-Z0-9\-._~!/]*$/.test(value)) return value
+    // the splat/catch-all routes shouldn't have the '/' encoded out
+    // Use encodeURIComponent for each segment to properly encode spaces,
+    // plus signs, and other special characters that encodeURI leaves unencoded
+    return value
+      .split('/')
+      .map((segment) => encodePathParam(segment, decoder))
+      .join('/')
+  } else {
+    return encodePathParam(value, decoder)
+  }
+}
+
+/**
+ * Interpolate params and wildcards into a route path template.
+ *
+ * - Encodes params safely (configurable allowed characters)
+ * - Supports `{-$optional}` segments, `{prefix{$id}suffix}` and `{$}` wildcards
+ */
+export function interpolatePath({
+  path,
+  params,
+  decoder,
+  // `server` is marked @internal and stripped from .d.ts by `stripInternal`.
+  // We avoid destructuring it in the function signature so the emitted
+  // declaration doesn't reference a property that no longer exists.
+  ...rest
+}: InterpolatePathOptions): InterPolatePathResult {
+  // Tracking if any params are missing in the `params` object
+  // when interpolating the path
+  let isMissingParams = false
+  const usedParams: Record<string, unknown> = Object.create(null)
+
+  if (!path || path === '/')
+    return { interpolatedPath: '/', usedParams, isMissingParams }
+  if (!path.includes('$'))
+    return { interpolatedPath: path, usedParams, isMissingParams }
+
+  if (isServer ?? rest.server) {
+    // Fast path for common templates like `/posts/$id` or `/files/$`.
+    // Braced segments (`{...}`) are more complex (prefix/suffix/optional) and are
+    // handled by the general parser below.
+    if (path.indexOf('{') === -1) {
+      const length = path.length
+      let cursor = 0
+      let joined = ''
+
+      while (cursor < length) {
+        // Skip slashes between segments. '/' code is 47
+        while (cursor < length && path.charCodeAt(cursor) === 47) cursor++
+        if (cursor >= length) break
+
+        const start = cursor
+        let end = path.indexOf('/', cursor)
+        if (end === -1) end = length
+        cursor = end
+
+        const part = path.substring(start, end)
+        if (!part) continue
+
+        // `$id` or `$` (splat). '$' code is 36
+        if (part.charCodeAt(0) === 36) {
+          if (part.length === 1) {
+            const splat = params._splat
+            usedParams._splat = splat
+            // TODO: Deprecate *
+            usedParams['*'] = splat
+
+            if (!splat) {
+              isMissingParams = true
+              continue
+            }
+
+            const value = encodeParam('_splat', params, decoder)
+            joined += '/' + value
+          } else {
+            const key = part.substring(1)
+            if (!isMissingParams && !(key in params)) {
+              isMissingParams = true
+            }
+            usedParams[key] = params[key]
+
+            const value = encodeParam(key, params, decoder) ?? 'undefined'
+            joined += '/' + value
+          }
+        } else {
+          joined += '/' + part
+        }
+      }
+
+      if (path.endsWith('/')) joined += '/'
+
+      const interpolatedPath = joined || '/'
+      return { usedParams, interpolatedPath, isMissingParams }
+    }
+  }
+
+  const length = path.length
+  let cursor = 0
+  let segment
+  let joined = ''
+  while (cursor < length) {
+    const start = cursor
+    segment = parseSegment(path, start, segment)
+    const end = segment[5]
+    cursor = end + 1
+
+    if (start === end) continue
+
+    const kind = segment[0]
+
+    if (kind === SEGMENT_TYPE_PATHNAME) {
+      joined += '/' + path.substring(start, end)
+      continue
+    }
+
+    if (kind === SEGMENT_TYPE_WILDCARD) {
+      const splat = params._splat
+      usedParams._splat = splat
+      // TODO: Deprecate *
+      usedParams['*'] = splat
+
+      const prefix = path.substring(start, segment[1])
+      const suffix = path.substring(segment[4], end)
+
+      // Check if _splat parameter is missing. _splat could be missing if undefined or an empty string or some other falsy value.
+      if (!splat) {
+        isMissingParams = true
+        // For missing splat parameters, just return the prefix and suffix without the wildcard
+        // If there is a prefix or suffix, return them joined, otherwise omit the segment
+        if (prefix || suffix) {
+          joined += '/' + prefix + suffix
+        }
+        continue
+      }
+
+      const value = encodeParam('_splat', params, decoder)
+      joined += '/' + prefix + value + suffix
+      continue
+    }
+
+    if (kind === SEGMENT_TYPE_PARAM) {
+      const key = path.substring(segment[2], segment[3])
+      if (!isMissingParams && !(key in params)) {
+        isMissingParams = true
+      }
+      usedParams[key] = params[key]
+
+      const prefix = path.substring(start, segment[1])
+      const suffix = path.substring(segment[4], end)
+      const value = encodeParam(key, params, decoder) ?? 'undefined'
+      joined += '/' + prefix + value + suffix
+      continue
+    }
+
+    if (kind === SEGMENT_TYPE_OPTIONAL_PARAM) {
+      const key = path.substring(segment[2], segment[3])
+      const valueRaw = params[key]
+
+      // Check if optional parameter is missing or undefined
+      if (valueRaw == null) continue
+
+      usedParams[key] = valueRaw
+
+      const prefix = path.substring(start, segment[1])
+      const suffix = path.substring(segment[4], end)
+      const value = encodeParam(key, params, decoder) ?? ''
+      joined += '/' + prefix + value + suffix
+      continue
+    }
+  }
+
+  if (path.endsWith('/')) joined += '/'
+
+  const interpolatedPath = joined || '/'
+
+  return { usedParams, interpolatedPath, isMissingParams }
+}
+
+function encodePathParam(
+  value: string,
+  decoder?: InterpolatePathOptions['decoder'],
+) {
+  const encoded = encodeURIComponent(value)
+  return decoder?.(encoded) ?? encoded
+}

package/src/qss.ts

@@ -0,0 +1,81 @@
+/**
+ * Program is a reimplementation of the `qss` package:
+ * Copyright (c) Luke Edwards luke.edwards05@gmail.com, MIT License
+ * https://github.com/lukeed/qss/blob/master/license.md
+ *
+ * This reimplementation uses modern browser APIs
+ * (namely URLSearchParams) and TypeScript while still
+ * maintaining the original functionality and interface.
+ *
+ * Update: this implementation has also been mangled to
+ * fit exactly our use-case (single value per key in encoding).
+ */
+
+/**
+ * Encodes an object into a query string.
+ * @param obj - The object to encode into a query string.
+ * @param stringify - An optional custom stringify function.
+ * @returns The encoded query string.
+ * @example
+ * ```
+ * // Example input: encode({ token: 'foo', key: 'value' })
+ * // Expected output: "token=foo&key=value"
+ * ```
+ */
+export function encode(
+  obj: Record<string, any>,
+  stringify: (value: any) => string = String,
+): string {
+  const result = new URLSearchParams()
+
+  for (const key in obj) {
+    const val = obj[key]
+    if (val !== undefined) {
+      result.set(key, stringify(val))
+    }
+  }
+
+  return result.toString()
+}
+
+/**
+ * Converts a string value to its appropriate type (string, number, boolean).
+ * @param mix - The string value to convert.
+ * @returns The converted value.
+ * @example
+ * // Example input: toValue("123")
+ * // Expected output: 123
+ */
+function toValue(str: unknown) {
+  if (!str) return ''
+
+  if (str === 'false') return false
+  if (str === 'true') return true
+  return +str * 0 === 0 && +str + '' === str ? +str : str
+}
+/**
+ * Decodes a query string into an object.
+ * @param str - The query string to decode.
+ * @returns The decoded key-value pairs in an object format.
+ * @example
+ * // Example input: decode("token=foo&key=value")
+ * // Expected output: { "token": "foo", "key": "value" }
+ */
+export function decode(str: any): any {
+  const searchParams = new URLSearchParams(str)
+
+  const result: Record<string, unknown> = Object.create(null)
+
+  for (const [key, value] of searchParams.entries()) {
+    const previousValue = result[key]
+    if (previousValue == null) {
+      result[key] = toValue(value)
+    } else if (Array.isArray(previousValue)) {
+      previousValue.push(toValue(value))
+    } else {
+      result[key] = [previousValue, toValue(value)]
+    }
+  }
+
+  return result
+}