@benjavicente/router-core 1.168.9

package/src/stores.ts

@@ -0,0 +1,342 @@
+import { createLRUCache } from './lru-cache'
+import { arraysEqual } from './utils'
+
+import type { AnyRoute } from './route'
+import type { RouterState } from './router'
+import type { FullSearchSchema } from './routeInfo'
+import type { ParsedLocation } from './location'
+import type { AnyRedirect } from './redirect'
+import type { AnyRouteMatch } from './Matches'
+
+export interface RouterReadableStore<TValue> {
+  readonly state: TValue
+}
+
+export interface RouterWritableStore<
+  TValue,
+> extends RouterReadableStore<TValue> {
+  setState: (updater: (prev: TValue) => TValue) => void
+}
+
+export type RouterBatchFn = (fn: () => void) => void
+
+export type MutableStoreFactory = <TValue>(
+  initialValue: TValue,
+) => RouterWritableStore<TValue>
+
+export type ReadonlyStoreFactory = <TValue>(
+  read: () => TValue,
+) => RouterReadableStore<TValue>
+
+export type GetStoreConfig = (opts: { isServer?: boolean }) => StoreConfig
+
+export type StoreConfig = {
+  createMutableStore: MutableStoreFactory
+  createReadonlyStore: ReadonlyStoreFactory
+  batch: RouterBatchFn
+  init?: (stores: RouterStores<AnyRoute>) => void
+}
+
+type MatchStore = RouterWritableStore<AnyRouteMatch> & {
+  routeId?: string
+}
+type ReadableStore<TValue> = RouterReadableStore<TValue>
+
+/** SSR non-reactive createMutableStore */
+export function createNonReactiveMutableStore<TValue>(
+  initialValue: TValue,
+): RouterWritableStore<TValue> {
+  let value = initialValue
+
+  return {
+    get state() {
+      return value
+    },
+    setState(updater: (prev: TValue) => TValue) {
+      value = updater(value)
+    },
+  }
+}
+
+/** SSR non-reactive createReadonlyStore */
+export function createNonReactiveReadonlyStore<TValue>(
+  read: () => TValue,
+): RouterReadableStore<TValue> {
+  return {
+    get state() {
+      return read()
+    },
+  }
+}
+
+export interface RouterStores<in out TRouteTree extends AnyRoute> {
+  status: RouterWritableStore<RouterState<TRouteTree>['status']>
+  loadedAt: RouterWritableStore<number>
+  isLoading: RouterWritableStore<boolean>
+  isTransitioning: RouterWritableStore<boolean>
+  location: RouterWritableStore<ParsedLocation<FullSearchSchema<TRouteTree>>>
+  resolvedLocation: RouterWritableStore<
+    ParsedLocation<FullSearchSchema<TRouteTree>> | undefined
+  >
+  statusCode: RouterWritableStore<number>
+  redirect: RouterWritableStore<AnyRedirect | undefined>
+  matchesId: RouterWritableStore<Array<string>>
+  pendingMatchesId: RouterWritableStore<Array<string>>
+  /** @internal */
+  cachedMatchesId: RouterWritableStore<Array<string>>
+  activeMatchesSnapshot: ReadableStore<Array<AnyRouteMatch>>
+  pendingMatchesSnapshot: ReadableStore<Array<AnyRouteMatch>>
+  cachedMatchesSnapshot: ReadableStore<Array<AnyRouteMatch>>
+  firstMatchId: ReadableStore<string | undefined>
+  hasPendingMatches: ReadableStore<boolean>
+  matchRouteReactivity: ReadableStore<{
+    locationHref: string
+    resolvedLocationHref: string | undefined
+    status: RouterState<TRouteTree>['status']
+  }>
+  __store: RouterReadableStore<RouterState<TRouteTree>>
+
+  activeMatchStoresById: Map<string, MatchStore>
+  pendingMatchStoresById: Map<string, MatchStore>
+  cachedMatchStoresById: Map<string, MatchStore>
+
+  /**
+   * Get a computed store that resolves a routeId to its current match state.
+   * Returns the same cached store instance for repeated calls with the same key.
+   * The computed depends on matchesId + the individual match store, so
+   * subscribers are only notified when the resolved match state changes.
+   */
+  getMatchStoreByRouteId: (
+    routeId: string,
+  ) => RouterReadableStore<AnyRouteMatch | undefined>
+
+  setActiveMatches: (nextMatches: Array<AnyRouteMatch>) => void
+  setPendingMatches: (nextMatches: Array<AnyRouteMatch>) => void
+  setCachedMatches: (nextMatches: Array<AnyRouteMatch>) => void
+}
+
+export function createRouterStores<TRouteTree extends AnyRoute>(
+  initialState: RouterState<TRouteTree>,
+  config: StoreConfig,
+): RouterStores<TRouteTree> {
+  const { createMutableStore, createReadonlyStore, batch, init } = config
+
+  // non reactive utilities
+  const activeMatchStoresById = new Map<string, MatchStore>()
+  const pendingMatchStoresById = new Map<string, MatchStore>()
+  const cachedMatchStoresById = new Map<string, MatchStore>()
+
+  // atoms
+  const status = createMutableStore(initialState.status)
+  const loadedAt = createMutableStore(initialState.loadedAt)
+  const isLoading = createMutableStore(initialState.isLoading)
+  const isTransitioning = createMutableStore(initialState.isTransitioning)
+  const location = createMutableStore(initialState.location)
+  const resolvedLocation = createMutableStore(initialState.resolvedLocation)
+  const statusCode = createMutableStore(initialState.statusCode)
+  const redirect = createMutableStore(initialState.redirect)
+  const matchesId = createMutableStore<Array<string>>([])
+  const pendingMatchesId = createMutableStore<Array<string>>([])
+  const cachedMatchesId = createMutableStore<Array<string>>([])
+
+  // 1st order derived stores
+  const activeMatchesSnapshot = createReadonlyStore(() =>
+    readPoolMatches(activeMatchStoresById, matchesId.state),
+  )
+  const pendingMatchesSnapshot = createReadonlyStore(() =>
+    readPoolMatches(pendingMatchStoresById, pendingMatchesId.state),
+  )
+  const cachedMatchesSnapshot = createReadonlyStore(() =>
+    readPoolMatches(cachedMatchStoresById, cachedMatchesId.state),
+  )
+  const firstMatchId = createReadonlyStore(() => matchesId.state[0])
+  const hasPendingMatches = createReadonlyStore(() =>
+    matchesId.state.some((matchId) => {
+      const store = activeMatchStoresById.get(matchId)
+      return store?.state.status === 'pending'
+    }),
+  )
+  const matchRouteReactivity = createReadonlyStore(() => ({
+    locationHref: location.state.href,
+    resolvedLocationHref: resolvedLocation.state?.href,
+    status: status.state,
+  }))
+
+  // compatibility "big" state store
+  const __store = createReadonlyStore(() => ({
+    status: status.state,
+    loadedAt: loadedAt.state,
+    isLoading: isLoading.state,
+    isTransitioning: isTransitioning.state,
+    matches: activeMatchesSnapshot.state,
+    location: location.state,
+    resolvedLocation: resolvedLocation.state,
+    statusCode: statusCode.state,
+    redirect: redirect.state,
+  }))
+
+  // Per-routeId computed store cache.
+  // Each entry resolves routeId → match state through the signal graph,
+  // giving consumers a single store to subscribe to instead of the
+  // two-level byRouteId → matchStore pattern.
+  //
+  // 64 max size is arbitrary, this is only for active matches anyway so
+  // it should be plenty. And we already have a 32 limit due to route
+  // matching bitmask anyway.
+  const matchStoreByRouteIdCache = createLRUCache<
+    string,
+    RouterReadableStore<AnyRouteMatch | undefined>
+  >(64)
+
+  function getMatchStoreByRouteId(
+    routeId: string,
+  ): RouterReadableStore<AnyRouteMatch | undefined> {
+    let cached = matchStoreByRouteIdCache.get(routeId)
+    if (!cached) {
+      cached = createReadonlyStore(() => {
+        // Reading matchesId.state tracks it as a dependency.
+        // When matchesId changes (navigation), this computed re-evaluates.
+        const ids = matchesId.state
+        for (const id of ids) {
+          const matchStore = activeMatchStoresById.get(id)
+          if (matchStore && matchStore.routeId === routeId) {
+            // Reading matchStore.state tracks it as a dependency.
+            // When the match store's state changes, this re-evaluates.
+            return matchStore.state
+          }
+        }
+        return undefined
+      })
+      matchStoreByRouteIdCache.set(routeId, cached)
+    }
+    return cached
+  }
+
+  const store = {
+    // atoms
+    status,
+    loadedAt,
+    isLoading,
+    isTransitioning,
+    location,
+    resolvedLocation,
+    statusCode,
+    redirect,
+    matchesId,
+    pendingMatchesId,
+    cachedMatchesId,
+
+    // derived
+    activeMatchesSnapshot,
+    pendingMatchesSnapshot,
+    cachedMatchesSnapshot,
+    firstMatchId,
+    hasPendingMatches,
+    matchRouteReactivity,
+
+    // non-reactive state
+    activeMatchStoresById,
+    pendingMatchStoresById,
+    cachedMatchStoresById,
+
+    // compatibility "big" state
+    __store,
+
+    // per-key computed stores
+    getMatchStoreByRouteId,
+
+    // methods
+    setActiveMatches,
+    setPendingMatches,
+    setCachedMatches,
+  }
+
+  // initialize the active matches
+  setActiveMatches(initialState.matches as Array<AnyRouteMatch>)
+  init?.(store)
+
+  // setters to update non-reactive utilities in sync with the reactive stores
+  function setActiveMatches(nextMatches: Array<AnyRouteMatch>) {
+    reconcileMatchPool(
+      nextMatches,
+      activeMatchStoresById,
+      matchesId,
+      createMutableStore,
+      batch,
+    )
+  }
+
+  function setPendingMatches(nextMatches: Array<AnyRouteMatch>) {
+    reconcileMatchPool(
+      nextMatches,
+      pendingMatchStoresById,
+      pendingMatchesId,
+      createMutableStore,
+      batch,
+    )
+  }
+
+  function setCachedMatches(nextMatches: Array<AnyRouteMatch>) {
+    reconcileMatchPool(
+      nextMatches,
+      cachedMatchStoresById,
+      cachedMatchesId,
+      createMutableStore,
+      batch,
+    )
+  }
+
+  return store
+}
+
+function readPoolMatches(
+  pool: Map<string, MatchStore>,
+  ids: Array<string>,
+): Array<AnyRouteMatch> {
+  const matches: Array<AnyRouteMatch> = []
+  for (const id of ids) {
+    const matchStore = pool.get(id)
+    if (matchStore) {
+      matches.push(matchStore.state)
+    }
+  }
+  return matches
+}
+
+function reconcileMatchPool(
+  nextMatches: Array<AnyRouteMatch>,
+  pool: Map<string, MatchStore>,
+  idStore: RouterWritableStore<Array<string>>,
+  createMutableStore: MutableStoreFactory,
+  batch: RouterBatchFn,
+): void {
+  const nextIds = nextMatches.map((d) => d.id)
+  const nextIdSet = new Set(nextIds)
+
+  batch(() => {
+    for (const id of pool.keys()) {
+      if (!nextIdSet.has(id)) {
+        pool.delete(id)
+      }
+    }
+
+    for (const nextMatch of nextMatches) {
+      const existing = pool.get(nextMatch.id)
+      if (!existing) {
+        const matchStore = createMutableStore(nextMatch) as MatchStore
+        matchStore.routeId = nextMatch.routeId
+        pool.set(nextMatch.id, matchStore)
+        continue
+      }
+
+      existing.routeId = nextMatch.routeId
+      if (existing.state !== nextMatch) {
+        existing.setState(() => nextMatch)
+      }
+    }
+
+    if (!arraysEqual(idStore.state, nextIds)) {
+      idStore.setState(() => nextIds)
+    }
+  })
+}

package/src/structuralSharing.ts

@@ -0,0 +1,7 @@
+import type { Constrain } from './utils'
+
+export interface OptionalStructuralSharing<TStructuralSharing, TConstraint> {
+  readonly structuralSharing?:
+    | Constrain<TStructuralSharing, TConstraint>
+    | undefined
+}

package/src/typePrimitives.ts

@@ -0,0 +1,181 @@
+import type {
+  FromPathOption,
+  NavigateOptions,
+  PathParamOptions,
+  SearchParamOptions,
+  ToPathOption,
+} from './link'
+import type { RedirectOptions } from './redirect'
+import type { RouteIds } from './routeInfo'
+import type { AnyRouter, RegisteredRouter } from './router'
+import type { UseParamsResult } from './useParams'
+import type { UseSearchResult } from './useSearch'
+import type { Constrain, ConstrainLiteral } from './utils'
+
+export type ValidateFromPath<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TFrom = string,
+> = FromPathOption<TRouter, TFrom>
+
+export type ValidateToPath<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TTo extends string | undefined = undefined,
+  TFrom extends string = string,
+> = ToPathOption<TRouter, TFrom, TTo>
+
+export type ValidateSearch<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TTo extends string | undefined = undefined,
+  TFrom extends string = string,
+> = SearchParamOptions<TRouter, TFrom, TTo>
+
+export type ValidateParams<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TTo extends string | undefined = undefined,
+  TFrom extends string = string,
+> = PathParamOptions<TRouter, TFrom, TTo>
+
+/**
+ * @private
+ */
+export type InferFrom<
+  TOptions,
+  TDefaultFrom extends string = string,
+> = TOptions extends {
+  from: infer TFrom extends string
+}
+  ? TFrom
+  : TDefaultFrom
+
+/**
+ * @private
+ */
+export type InferTo<TOptions> = TOptions extends {
+  to: infer TTo extends string
+}
+  ? TTo
+  : undefined
+
+/**
+ * @private
+ */
+export type InferMaskTo<TOptions> = TOptions extends {
+  mask: { to: infer TTo extends string }
+}
+  ? TTo
+  : ''
+
+export type InferMaskFrom<TOptions> = TOptions extends {
+  mask: { from: infer TFrom extends string }
+}
+  ? TFrom
+  : string
+
+export type ValidateNavigateOptions<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions = unknown,
+  TDefaultFrom extends string = string,
+> = Constrain<
+  TOptions,
+  NavigateOptions<
+    TRouter,
+    InferFrom<TOptions, TDefaultFrom>,
+    InferTo<TOptions>,
+    InferMaskFrom<TOptions>,
+    InferMaskTo<TOptions>
+  >
+>
+
+export type ValidateNavigateOptionsArray<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>,
+  TDefaultFrom extends string = string,
+> = {
+  [K in keyof TOptions]: ValidateNavigateOptions<
+    TRouter,
+    TOptions[K],
+    TDefaultFrom
+  >
+}
+
+export type ValidateRedirectOptions<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions = unknown,
+  TDefaultFrom extends string = string,
+> = Constrain<
+  TOptions,
+  RedirectOptions<
+    TRouter,
+    InferFrom<TOptions, TDefaultFrom>,
+    InferTo<TOptions>,
+    InferMaskFrom<TOptions>,
+    InferMaskTo<TOptions>
+  >
+>
+
+export type ValidateRedirectOptionsArray<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TOptions extends ReadonlyArray<any> = ReadonlyArray<unknown>,
+  TDefaultFrom extends string = string,
+> = {
+  [K in keyof TOptions]: ValidateRedirectOptions<
+    TRouter,
+    TOptions[K],
+    TDefaultFrom
+  >
+}
+
+export type ValidateId<
+  TRouter extends AnyRouter = RegisteredRouter,
+  TId extends string = string,
+> = ConstrainLiteral<TId, RouteIds<TRouter['routeTree']>>
+
+/**
+ * @private
+ */
+export type InferStrict<TOptions> = TOptions extends {
+  strict: infer TStrict extends boolean
+}
+  ? TStrict
+  : true
+
+/**
+ * @private
+ */
+export type InferShouldThrow<TOptions> = TOptions extends {
+  shouldThrow: infer TShouldThrow extends boolean
+}
+  ? TShouldThrow
+  : true
+
+/**
+ * @private
+ */
+export type InferSelected<TOptions> = TOptions extends {
+  select: (...args: Array<any>) => infer TSelected
+}
+  ? TSelected
+  : unknown
+
+export type ValidateUseSearchResult<
+  TOptions,
+  TRouter extends AnyRouter = RegisteredRouter,
+> = UseSearchResult<
+  TRouter,
+  InferFrom<TOptions>,
+  InferStrict<TOptions>,
+  InferSelected<TOptions>
+>
+
+export type ValidateUseParamsResult<
+  TOptions,
+  TRouter extends AnyRouter = RegisteredRouter,
+> = Constrain<
+  TOptions,
+  UseParamsResult<
+    TRouter,
+    InferFrom<TOptions>,
+    InferStrict<TOptions>,
+    InferSelected<TOptions>
+  >
+>

package/src/useLoaderData.ts

@@ -0,0 +1,20 @@
+import type { AllLoaderData, RouteById } from './routeInfo'
+import type { AnyRouter } from './router'
+import type { Expand } from './utils'
+
+export type ResolveUseLoaderData<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? AllLoaderData<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['loaderData']>
+
+export type UseLoaderDataResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveUseLoaderData<TRouter, TFrom, TStrict>
+  : TSelected

package/src/useLoaderDeps.ts

@@ -0,0 +1,13 @@
+import type { RouteById } from './routeInfo'
+import type { AnyRouter } from './router'
+import type { Expand } from './utils'
+
+export type ResolveUseLoaderDeps<TRouter extends AnyRouter, TFrom> = Expand<
+  RouteById<TRouter['routeTree'], TFrom>['types']['loaderDeps']
+>
+
+export type UseLoaderDepsResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TSelected,
+> = unknown extends TSelected ? ResolveUseLoaderDeps<TRouter, TFrom> : TSelected

package/src/useNavigate.ts

@@ -0,0 +1,13 @@
+import type { NavigateOptions } from './link'
+import type { RegisteredRouter } from './router'
+
+export type UseNavigateResult<TDefaultFrom extends string> = <
+  TRouter extends RegisteredRouter,
+  TTo extends string | undefined,
+  TFrom extends string = TDefaultFrom,
+  TMaskFrom extends string = TFrom,
+  TMaskTo extends string = '',
+>({
+  from,
+  ...rest
+}: NavigateOptions<TRouter, TFrom, TTo, TMaskFrom, TMaskTo>) => Promise<void>

package/src/useParams.ts

@@ -0,0 +1,20 @@
+import type { AllParams, RouteById } from './routeInfo'
+import type { AnyRouter } from './router'
+import type { Expand } from './utils'
+
+export type ResolveUseParams<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? AllParams<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['allParams']>
+
+export type UseParamsResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveUseParams<TRouter, TFrom, TStrict>
+  : TSelected

package/src/useRouteContext.ts

@@ -0,0 +1,39 @@
+import type { AllContext, RouteById } from './routeInfo'
+import type { AnyRouter } from './router'
+import type { Expand, StrictOrFrom } from './utils'
+
+export interface UseRouteContextBaseOptions<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> {
+  select?: (
+    search: ResolveUseRouteContext<TRouter, TFrom, TStrict>,
+  ) => TSelected
+}
+
+export type UseRouteContextOptions<
+  TRouter extends AnyRouter,
+  TFrom extends string | undefined,
+  TStrict extends boolean,
+  TSelected,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+  UseRouteContextBaseOptions<TRouter, TFrom, TStrict, TSelected>
+
+export type ResolveUseRouteContext<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? AllContext<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['allContext']>
+
+export type UseRouteContextResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveUseRouteContext<TRouter, TFrom, TStrict>
+  : TSelected

package/src/useSearch.ts

@@ -0,0 +1,20 @@
+import type { FullSearchSchema, RouteById } from './routeInfo'
+import type { AnyRouter } from './router'
+import type { Expand } from './utils'
+
+export type UseSearchResult<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+  TSelected,
+> = unknown extends TSelected
+  ? ResolveUseSearch<TRouter, TFrom, TStrict>
+  : TSelected
+
+export type ResolveUseSearch<
+  TRouter extends AnyRouter,
+  TFrom,
+  TStrict extends boolean,
+> = TStrict extends false
+  ? FullSearchSchema<TRouter['routeTree']>
+  : Expand<RouteById<TRouter['routeTree'], TFrom>['types']['fullSearchSchema']>