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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tanstack/router-core",
   "author": "Tanner Linsley",
-  "version": "0.0.1-alpha.8",
+  "version": "0.0.1-beta.1",
   "license": "MIT",
   "repository": "tanstack/router",
   "homepage": "https://tanstack.com/router",

package/src/frameworks.ts

@@ -4,7 +4,6 @@ export interface FrameworkGenerics {
   // pre-defined as constraints:
   //
   // Element: any
-  // AsyncElement: any
   // SyncOrAsyncElement?: any
 }
 

package/src/link.ts

@@ -5,7 +5,7 @@ import {
   RouteInfoByPath,
 } from './routeInfo'
 import { Location } from './router'
-import { NoInfer, PickAsRequired, PickRequired, Updater } from './utils'
+import { Expand, NoInfer, PickAsRequired, PickRequired, Updater } from './utils'
 
 export type LinkInfo =
   | {
@@ -35,23 +35,25 @@ type CleanPath<T extends string> = T extends `${infer L}//${infer R}`
   ? `/${CleanPath<L>}`
   : T
 
-export type Split<S, TTrailing = true> = S extends unknown
+export type Split<S, TIncludeTrailingSlash = true> = S extends unknown
   ? string extends S
     ? string[]
     : S extends string
     ? CleanPath<S> extends ''
       ? []
-      : TTrailing extends true
+      : TIncludeTrailingSlash extends true
       ? CleanPath<S> extends `${infer T}/`
-        ? [T, '/']
+        ? [...Split<T>, '/']
         : CleanPath<S> extends `/${infer U}`
-        ? ['/', U]
+        ? Split<U>
         : CleanPath<S> extends `${infer T}/${infer U}`
-        ? [T, ...Split<U>]
+        ? [...Split<T>, ...Split<U>]
         : [S]
       : CleanPath<S> extends `${infer T}/${infer U}`
-      ? [T, ...Split<U>]
-      : [S]
+      ? [...Split<T>, ...Split<U>]
+      : S extends string
+      ? [S]
+      : never
     : never
   : never
 
@@ -128,7 +130,7 @@ export type ToOptions<
   from?: TFrom
   // // When using relative route paths, this option forces resolution from the current path, instead of the route API's path or `from` path
   // fromCurrent?: boolean
-} & CheckPath<TAllRouteInfo, NoInfer<TResolvedTo>> &
+} & CheckPath<TAllRouteInfo, NoInfer<TResolvedTo>, {}> &
   SearchParamOptions<TAllRouteInfo, TFrom, TResolvedTo> &
   PathParamOptions<TAllRouteInfo, TFrom, TResolvedTo>
 
@@ -220,8 +222,10 @@ export type LinkOptions<
   activeOptions?: ActiveOptions
   // If set, will preload the linked route on hover and cache it for this many milliseconds in hopes that the user will eventually navigate there.
   preload?: false | 'intent'
-  // When preloaded and set, will cache the preloaded result for this duration in milliseconds
+  // When preloaded, the preloaded result will be considered "fresh" for this duration in milliseconds
   preloadMaxAge?: number
+  // When preloaded and subsequently inactive, the preloaded result will remain in memory for this duration in milliseconds
+  preloadGcMaxAge?: number
   // Delay intent preloading by this many milliseconds. If the intent exits before this delay, the preload will be cancelled.
   preloadDelay?: number
   // If true, will render the link without the href attribute
@@ -246,19 +250,41 @@ export type CheckRelativePath<
     : {}
   : {}
 
-export type CheckPath<TAllRouteInfo extends AnyAllRouteInfo, TPath> = Exclude<
+export type CheckPath<
+  TAllRouteInfo extends AnyAllRouteInfo,
   TPath,
-  TAllRouteInfo['routePaths']
-> extends never
-  ? {}
+  TPass,
+> = Exclude<TPath, TAllRouteInfo['routePaths']> extends never
+  ? TPass
   : CheckPathError<TAllRouteInfo, Exclude<TPath, TAllRouteInfo['routePaths']>>
 
-export type CheckPathError<TAllRouteInfo extends AnyAllRouteInfo, TInvalids> = {
+export type CheckPathError<
+  TAllRouteInfo extends AnyAllRouteInfo,
+  TInvalids,
+> = Expand<{
   Error: `${TInvalids extends string
     ? TInvalids
     : never} is not a valid route path.`
   'Valid Route Paths': TAllRouteInfo['routePaths']
-}
+}>
+
+export type CheckId<
+  TAllRouteInfo extends AnyAllRouteInfo,
+  TPath,
+  TPass,
+> = Exclude<TPath, TAllRouteInfo['routeIds']> extends never
+  ? TPass
+  : CheckIdError<TAllRouteInfo, Exclude<TPath, TAllRouteInfo['routeIds']>>
+
+export type CheckIdError<
+  TAllRouteInfo extends AnyAllRouteInfo,
+  TInvalids,
+> = Expand<{
+  Error: `${TInvalids extends string
+    ? TInvalids
+    : never} is not a valid route ID.`
+  'Valid Route IDs': TAllRouteInfo['routeIds']
+}>
 
 export type ResolveRelativePath<TFrom, TTo = '.'> = TFrom extends string
   ? TTo extends string
@@ -272,10 +298,14 @@ export type ResolveRelativePath<TFrom, TTo = '.'> = TFrom extends string
       ? TTo
       : Split<TTo> extends ['..', ...infer ToRest]
       ? Split<TFrom> extends [...infer FromRest, infer FromTail]
-        ? ResolveRelativePath<Join<FromRest>, Join<ToRest>>
+        ? ToRest extends ['/']
+          ? Join<[...FromRest, '/']>
+          : ResolveRelativePath<Join<FromRest>, Join<ToRest>>
         : never
       : Split<TTo> extends ['.', ...infer ToRest]
-      ? ResolveRelativePath<TFrom, Join<ToRest>>
+      ? ToRest extends ['/']
+        ? Join<[TFrom, '/']>
+        : ResolveRelativePath<TFrom, Join<ToRest>>
       : CleanPath<Join<['/', ...Split<TFrom>, ...Split<TTo>]>>
     : never
   : never

package/src/route.ts

@@ -5,7 +5,7 @@ import {
   ResolveRelativePath,
   ToOptions,
 } from './link'
-import { RouteConfig, RouteOptions } from './routeConfig'
+import { LoaderContext, RouteConfig, RouteOptions } from './routeConfig'
 import {
   AnyAllRouteInfo,
   AnyRouteInfo,
@@ -14,7 +14,14 @@ import {
   RouteInfoByPath,
 } from './routeInfo'
 import { RouteMatch } from './routeMatch'
-import { Action, ActionState, MatchRouteOptions, Router } from './router'
+import {
+  Action,
+  ActionState,
+  Loader,
+  LoaderState,
+  MatchRouteOptions,
+  Router,
+} from './router'
 import { NoInfer, replaceEqualDeep } from './utils'
 
 export interface AnyRoute extends Route<any, any> {}
@@ -57,6 +64,21 @@ export interface Route<
         | Action<TRouteInfo['actionPayload'], TRouteInfo['actionResponse']>
         | undefined
     : Action<TRouteInfo['actionPayload'], TRouteInfo['actionResponse']>
+  loader: unknown extends TRouteInfo['routeLoaderData']
+    ?
+        | Action<
+            LoaderContext<
+              TRouteInfo['fullSearchSchema'],
+              TRouteInfo['allParams']
+            >,
+            TRouteInfo['routeLoaderData']
+          >
+        | undefined
+    : Loader<
+        TRouteInfo['fullSearchSchema'],
+        TRouteInfo['allParams'],
+        TRouteInfo['routeLoaderData']
+      >
 }
 
 export function createRoute<
@@ -126,6 +148,45 @@ export function createRoute<
       return router.state.actions[id]!
     })()
 
+  const loader =
+    router.state.loaders[id] ||
+    (() => {
+      router.state.loaders[id] = {
+        pending: [],
+        fetch: (async (loaderContext: LoaderContext<any, any>) => {
+          if (!route) {
+            return
+          }
+
+          const loaderState: LoaderState<any, any> = {
+            loadedAt: Date.now(),
+            loaderContext,
+          }
+
+          loader.current = loaderState
+          loader.latest = loaderState
+          loader.pending.push(loaderState)
+
+          // router.state = {
+          //   ...router.state,
+          //   currentAction: loaderState,
+          //   latestAction: loaderState,
+          // }
+
+          router.notify()
+
+          try {
+            return await route.options.loader?.(loaderContext)
+          } finally {
+            loader.pending = loader.pending.filter((d) => d !== loaderState)
+            // router.removeActionQueue.push({ loader, loaderState })
+            router.notify()
+          }
+        }) as any,
+      }
+      return router.state.loaders[id]!
+    })()
+
   let route: Route<TAllRouteInfo, TRouteInfo> = {
     routeId: id,
     routeRouteId: routeId,
@@ -136,6 +197,7 @@ export function createRoute<
     childRoutes: undefined!,
     parentRoute: parent,
     action,
+    loader: loader as any,
 
     buildLink: (options) => {
       return router.buildLink({

package/src/routeConfig.ts

@@ -53,11 +53,18 @@ export type LoaderFn<
   TRouteLoaderData extends AnyLoaderData,
   TFullSearchSchema extends AnySearchSchema = {},
   TAllParams extends AnyPathParams = {},
-> = (loaderContext: {
+> = (
+  loaderContext: LoaderContext<TFullSearchSchema, TAllParams>,
+) => Promise<TRouteLoaderData>
+
+export interface LoaderContext<
+  TFullSearchSchema extends AnySearchSchema = {},
+  TAllParams extends AnyPathParams = {},
+> {
   params: TAllParams
   search: TFullSearchSchema
   signal?: AbortSignal
-}) => Promise<TRouteLoaderData>
+}
 
 export type ActionFn<TActionPayload = unknown, TActionResponse = unknown> = (
   submission: TActionPayload,
@@ -105,58 +112,6 @@ export type RouteOptions<
   pendingMs?: number
   // _If the `pendingElement` is shown_, the minimum duration for which it will be visible.
   pendingMinMs?: number
-  // // An array of child routes
-  // children?: Route<any, any, any, any>[]
-} & (
-    | {
-        parseParams?: never
-        stringifyParams?: never
-      }
-    | {
-        // Parse params optionally receives path params as strings and returns them in a parsed format (like a number or boolean)
-        parseParams: (
-          rawParams: IsAny<TPath, any, Record<ParsePathParams<TPath>, string>>,
-        ) => TParams
-        stringifyParams: (
-          params: TParams,
-        ) => Record<ParsePathParams<TPath>, string>
-      }
-  ) &
-  RouteLoaders<
-    // Route Loaders (see below) can be inline on the route, or resolved async
-    TRouteLoaderData,
-    TLoaderData,
-    TActionPayload,
-    TActionResponse,
-    TFullSearchSchema,
-    TAllParams
-  > & {
-    // If `import` is defined, this route can resolve its elements and loaders in a single asynchronous call
-    // This is particularly useful for code-splitting or module federation
-    import?: (opts: {
-      params: AnyPathParams
-    }) => Promise<
-      RouteLoaders<
-        TRouteLoaderData,
-        TLoaderData,
-        TActionPayload,
-        TActionResponse,
-        TFullSearchSchema,
-        TAllParams
-      >
-    >
-  } & (PickUnsafe<TParentParams, ParsePathParams<TPath>> extends never // Detect if an existing path param is being redefined
-    ? {}
-    : 'Cannot redefined path params in child routes!')
-
-export interface RouteLoaders<
-  TRouteLoaderData extends AnyLoaderData = {},
-  TLoaderData extends AnyLoaderData = {},
-  TActionPayload = unknown,
-  TActionResponse = unknown,
-  TFullSearchSchema extends AnySearchSchema = {},
-  TAllParams extends AnyPathParams = {},
-> {
   // The content to be rendered when the route is matched. If no element is provided, defaults to `<Outlet />`
   element?: GetFrameworkGeneric<'SyncOrAsyncElement'> // , NoInfer<TLoaderData>>
   // The content to be rendered when `loader` encounters an error
@@ -196,7 +151,24 @@ export interface RouteLoaders<
   }) => void
   // An object of whatever you want! This object is accessible anywhere matches are.
   meta?: RouteMeta // TODO: Make this nested and mergeable
-}
+} & (
+    | {
+        parseParams?: never
+        stringifyParams?: never
+      }
+    | {
+        // Parse params optionally receives path params as strings and returns them in a parsed format (like a number or boolean)
+        parseParams: (
+          rawParams: IsAny<TPath, any, Record<ParsePathParams<TPath>, string>>,
+        ) => TParams
+        stringifyParams: (
+          params: TParams,
+        ) => Record<ParsePathParams<TPath>, string>
+      }
+  ) &
+  (PickUnsafe<TParentParams, ParsePathParams<TPath>> extends never // Detect if an existing path param is being redefined
+    ? {}
+    : 'Cannot redefined path params in child routes!')
 
 export type SearchFilter<T, U = T> = (prev: T) => U
 

package/src/routeMatch.ts

@@ -16,7 +16,7 @@ export interface RouteMatch<
 > extends Route<TAllRouteInfo, TRouteInfo> {
   matchId: string
   pathname: string
-  params: AnyPathParams
+  params: TRouteInfo['params']
   parentMatch?: RouteMatch
   childMatches: RouteMatch[]
   routeSearch: TRouteInfo['searchSchema']
@@ -30,6 +30,7 @@ export interface RouteMatch<
   routeLoaderData: TRouteInfo['routeLoaderData']
   isFetching: boolean
   isPending: boolean
+  invalidAt: number
   __: {
     element?: GetFrameworkGeneric<'Element'> // , TRouteInfo['loaderData']>
     errorElement?: GetFrameworkGeneric<'Element'> // , TRouteInfo['loaderData']>
@@ -37,7 +38,6 @@ export interface RouteMatch<
     pendingElement?: GetFrameworkGeneric<'Element'> // , TRouteInfo['loaderData']>
     loadPromise?: Promise<void>
     loaderPromise?: Promise<void>
-    importPromise?: Promise<void>
     elementsPromise?: Promise<void>
     dataPromise?: Promise<void>
     pendingTimeout?: Timeout
@@ -60,7 +60,13 @@ export interface RouteMatch<
     resolve: () => void
   }
   cancel: () => void
-  load: () => Promise<void>
+  load: (
+    loaderOpts?: { withPending?: boolean } & (
+      | { preload: true; maxAge: number; gcMaxAge: number }
+      | { preload?: false; maxAge?: never; gcMaxAge?: never }
+    ),
+  ) => Promise<TRouteInfo['routeLoaderData']>
+  fetch: (opts?: { maxAge?: number }) => Promise<TRouteInfo['routeLoaderData']>
   invalidate: () => void
   hasLoaders: () => boolean
 }
@@ -97,13 +103,10 @@ export function createRouteMatch<
     isPending: false,
     isFetching: false,
     isInvalid: false,
+    invalidAt: Infinity,
     getIsInvalid: () => {
       const now = Date.now()
-      const maxAge =
-        routeMatch.options.loaderMaxAge ??
-        router.options.defaultLoaderMaxAge ??
-        0
-      return routeMatch.isInvalid || routeMatch.updatedAt! + maxAge < now
+      return routeMatch.isInvalid || routeMatch.invalidAt < now
     },
     __: {
       abortController: new AbortController(),
@@ -208,11 +211,42 @@ export function createRouteMatch<
     hasLoaders: () => {
       return !!(
         route.options.loader ||
-        route.options.import ||
         elementTypes.some((d) => typeof route.options[d] === 'function')
       )
     },
-    load: async () => {
+    load: async (loaderOpts) => {
+      const now = Date.now()
+      const minMaxAge = loaderOpts?.preload
+        ? Math.max(loaderOpts?.maxAge, loaderOpts?.gcMaxAge)
+        : 0
+
+      // If this is a preload, add it to the preload cache
+      if (loaderOpts?.preload && minMaxAge > 0) {
+        // If the match is currently active, don't preload it
+        if (
+          router.state.matches.find((d) => d.matchId === routeMatch.matchId)
+        ) {
+          return
+        }
+
+        router.matchCache[routeMatch.matchId] = {
+          gc: now + loaderOpts.gcMaxAge,
+          match: routeMatch as RouteMatch<any, any>,
+        }
+      }
+
+      // If the match is invalid, errored or idle, trigger it to load
+      if (
+        (routeMatch.status === 'success' && routeMatch.getIsInvalid()) ||
+        routeMatch.status === 'error' ||
+        routeMatch.status === 'idle'
+      ) {
+        const maxAge = loaderOpts?.preload ? loaderOpts?.maxAge : undefined
+
+        routeMatch.fetch({ maxAge })
+      }
+    },
+    fetch: async (opts) => {
       const id = '' + Date.now() + Math.random()
       routeMatch.__.latestId = id
 
@@ -233,26 +267,7 @@ export function createRouteMatch<
         routeMatch.__.resolve = resolve as () => void
 
         const loaderPromise = (async () => {
-          const importer = routeMatch.options.import
-
-          // First, run any importers
-          if (importer) {
-            routeMatch.__.importPromise = importer({
-              params: routeMatch.params,
-              // search: routeMatch.search,
-            }).then((imported) => {
-              routeMatch.__ = {
-                ...routeMatch.__,
-                ...imported,
-              }
-            })
-          }
-
-          // Wait for the importer to finish before
-          // attempting to load elements and data
-          await routeMatch.__.importPromise
-
-          // Next, load the elements and data in parallel
+          // Load the elements and data in parallel
 
           routeMatch.__.elementsPromise = (async () => {
             // then run all element and data loaders in parallel
@@ -266,13 +281,9 @@ export function createRouteMatch<
                   return
                 }
 
-                if (typeof routeElement === 'function') {
-                  const res = await (routeElement as any)(routeMatch)
-
-                  routeMatch.__[type] = res
-                } else {
-                  routeMatch.__[type] = routeMatch.options[type] as any
-                }
+                routeMatch.__[type] = await router.options.createElement!(
+                  routeElement,
+                )
               }),
             )
           })()
@@ -298,6 +309,12 @@ export function createRouteMatch<
               routeMatch.error = undefined
               routeMatch.status = 'success'
               routeMatch.updatedAt = Date.now()
+              routeMatch.invalidAt =
+                routeMatch.updatedAt +
+                (opts?.maxAge ??
+                  routeMatch.options.loaderMaxAge ??
+                  router.options.defaultLoaderMaxAge ??
+                  0)
             } catch (err) {
               if (id !== routeMatch.__.latestId) {
                 return routeMatch.__.loaderPromise