@tanstack/router-core 1.132.0-alpha.3 → 1.132.0-alpha.8

package/src/router.ts

@@ -84,6 +84,8 @@ import type { Manifest } from './manifest'
 import type { AnySchema, AnyValidator } from './validators'
 import type { NavigateOptions, ResolveRelativePath, ToOptions } from './link'
 import type { NotFoundError } from './not-found'
+import type { AnySerializationAdapter } from './ssr/serializer/transformer'
+import type { AnyRouterConfig } from './config'
 
 export type ControllablePromise<T = any> = Promise<T> & {
   resolve: (value: T) => void
@@ -94,6 +96,8 @@ export type InjectedHtmlEntry = Promise<string>
 
 export interface DefaultRegister {
   router: AnyRouter
+  config: AnyRouterConfig
+  ssr: SSROption
 }
 
 export interface Register extends DefaultRegister {
@@ -111,13 +115,14 @@ export interface DefaultRouterOptionsExtensions {}
 export interface RouterOptionsExtensions
   extends DefaultRouterOptionsExtensions {}
 
+export type SSROption = boolean | 'data-only'
+
 export interface RouterOptions<
   TRouteTree extends AnyRoute,
   TTrailingSlashOption extends TrailingSlashOption,
   TDefaultStructuralSharingOption extends boolean = false,
   TRouterHistory extends RouterHistory = RouterHistory,
   TDehydrated extends Record<string, any> = Record<string, any>,
-  TTransformerConfig = any,
 > extends RouterOptionsExtensions {
   /**
    * The history object that will be used to manage the browser history.
@@ -355,7 +360,7 @@ export interface RouterOptions<
    *
    * @default true
    */
-  defaultSsr?: boolean | 'data-only'
+  defaultSsr?: SSROption
 
   search?: {
     /**
@@ -391,7 +396,9 @@ export interface RouterOptions<
    *
    * @default false
    */
-  scrollRestoration?: boolean
+  scrollRestoration?:
+    | boolean
+    | ((opts: { location: ParsedLocation }) => boolean)
 
   /**
    * A function that will be called to get the key for the scroll restoration cache.
@@ -423,7 +430,7 @@ export interface RouterOptions<
    */
   disableGlobalCatchBoundary?: boolean
 
-  serializationAdapters?: TTransformerConfig
+  serializationAdapters?: ReadonlyArray<AnySerializationAdapter>
 }
 
 export interface RouterState<
@@ -532,15 +539,13 @@ export type RouterConstructorOptions<
   TDefaultStructuralSharingOption extends boolean,
   TRouterHistory extends RouterHistory,
   TDehydrated extends Record<string, any>,
-  TTransformerConfig,
 > = Omit<
   RouterOptions<
     TRouteTree,
     TTrailingSlashOption,
     TDefaultStructuralSharingOption,
     TRouterHistory,
-    TDehydrated,
-    TTransformerConfig
+    TDehydrated
   >,
   'context'
 > &
@@ -600,15 +605,13 @@ export type UpdateFn<
   TDefaultStructuralSharingOption extends boolean,
   TRouterHistory extends RouterHistory,
   TDehydrated extends Record<string, any>,
-  TTransformerConfig extends any,
 > = (
   newOptions: RouterConstructorOptions<
     TRouteTree,
     TTrailingSlashOption,
     TDefaultStructuralSharingOption,
     TRouterHistory,
-    TDehydrated,
-    TTransformerConfig
+    TDehydrated
   >,
 ) => void
 
@@ -619,8 +622,8 @@ export type InvalidateFn<TRouter extends AnyRouter> = (opts?: {
 }) => Promise<void>
 
 export type ParseLocationFn<TRouteTree extends AnyRoute> = (
+  locationToParse: HistoryLocation,
   previousLocation?: ParsedLocation<FullSearchSchema<TRouteTree>>,
-  locationToParse?: HistoryLocation,
 ) => ParsedLocation<FullSearchSchema<TRouteTree>>
 
 export type GetMatchRoutesFn = (
@@ -693,11 +696,10 @@ export type AnyRouterWithContext<TContext> = RouterCore<
   any,
   any,
   any,
-  any,
   any
 >
 
-export type AnyRouter = RouterCore<any, any, any, any, any, any>
+export type AnyRouter = RouterCore<any, any, any, any, any>
 
 export interface ViewTransitionOptions {
   types:
@@ -751,7 +753,6 @@ export type CreateRouterFn = <
   TDefaultStructuralSharingOption extends boolean = false,
   TRouterHistory extends RouterHistory = RouterHistory,
   TDehydrated extends Record<string, any> = Record<string, any>,
-  TTransformerConfig = any,
 >(
   options: undefined extends number
     ? 'strictNullChecks must be enabled in tsconfig.json'
@@ -760,16 +761,14 @@ export type CreateRouterFn = <
         TTrailingSlashOption,
         TDefaultStructuralSharingOption,
         TRouterHistory,
-        TDehydrated,
-        TTransformerConfig
+        TDehydrated
       >,
 ) => RouterCore<
   TRouteTree,
   TTrailingSlashOption,
   TDefaultStructuralSharingOption,
   TRouterHistory,
-  TDehydrated,
-  TTransformerConfig
+  TDehydrated
 >
 
 export class RouterCore<
@@ -778,7 +777,6 @@ export class RouterCore<
   in out TDefaultStructuralSharingOption extends boolean,
   in out TRouterHistory extends RouterHistory = RouterHistory,
   in out TDehydrated extends Record<string, any> = Record<string, any>,
-  in out TTransformerConfig = any,
 > {
   // Option-independent properties
   tempLocationKey: string | undefined = `${Math.round(
@@ -800,8 +798,7 @@ export class RouterCore<
       TTrailingSlashOption,
       TDefaultStructuralSharingOption,
       TRouterHistory,
-      TDehydrated,
-      TTransformerConfig
+      TDehydrated
     >,
     'stringifySearch' | 'parseSearch' | 'context'
   >
@@ -824,8 +821,7 @@ export class RouterCore<
       TTrailingSlashOption,
       TDefaultStructuralSharingOption,
       TRouterHistory,
-      TDehydrated,
-      TTransformerConfig
+      TDehydrated
     >,
   ) {
     this.update({
@@ -863,8 +859,7 @@ export class RouterCore<
     TTrailingSlashOption,
     TDefaultStructuralSharingOption,
     TRouterHistory,
-    TDehydrated,
-    TTransformerConfig
+    TDehydrated
   > = (newOptions) => {
     if (newOptions.notFoundRoute) {
       console.warn(
@@ -915,7 +910,7 @@ export class RouterCore<
               initialEntries: [this.basepath || '/'],
             })
           : createBrowserHistory()) as TRouterHistory)
-      this.latestLocation = this.parseLocation()
+      this.updateLatestLocation()
     }
 
     if (this.options.routeTree !== this.routeTree) {
@@ -949,10 +944,17 @@ export class RouterCore<
     }
   }
 
-  get state() {
+  get state(): RouterState<TRouteTree> {
     return this.__store.state
   }
 
+  updateLatestLocation = () => {
+    this.latestLocation = this.parseLocation(
+      this.history.location,
+      this.latestLocation,
+    )
+  }
+
   buildRouteTree = () => {
     const { routesById, routesByPath, flatRoutes } = processRouteTree({
       routeTree: this.routeTree,
@@ -999,8 +1001,8 @@ export class RouterCore<
   }
 
   parseLocation: ParseLocationFn<TRouteTree> = (
-    previousLocation,
     locationToParse,
+    previousLocation,
   ) => {
     const parse = ({
       pathname,
@@ -1021,7 +1023,7 @@ export class RouterCore<
       }
     }
 
-    const location = parse(locationToParse ?? this.history.location)
+    const location = parse(locationToParse)
 
     const { __tempLocation, __tempKey } = location.state
 
@@ -1423,50 +1425,44 @@ export class RouterCore<
         _buildLocation: true,
       })
 
+      // Now let's find the starting pathname
+      // This should default to the current location if no from is provided
       const lastMatch = last(allCurrentLocationMatches)!
 
-      // First let's find the starting pathname
-      // By default, start with the current location
-      let fromPath = this.resolvePathWithBase(lastMatch.fullPath, '.')
-      const toPath = dest.to
-        ? this.resolvePathWithBase(fromPath, `${dest.to}`)
-        : this.resolvePathWithBase(fromPath, '.')
-
-      const routeIsChanging =
-        !!dest.to &&
-        !comparePaths(dest.to.toString(), fromPath) &&
-        !comparePaths(toPath, fromPath)
-
-      // If the route is changing we need to find the relative fromPath
-      if (dest.unsafeRelative === 'path') {
-        fromPath = currentLocation.pathname
-      } else if (routeIsChanging && dest.from) {
-        fromPath = dest.from
-
-        // do this check only on navigations during test or development
-        if (process.env.NODE_ENV !== 'production' && dest._isNavigate) {
-          const allFromMatches = this.getMatchedRoutes(
-            dest.from,
-            undefined,
-          ).matchedRoutes
+      // check that from path exists in the current route tree
+      // do this check only on navigations during test or development
+      if (
+        dest.from &&
+        process.env.NODE_ENV !== 'production' &&
+        dest._isNavigate
+      ) {
+        const allFromMatches = this.getMatchedRoutes(
+          dest.from,
+          undefined,
+        ).matchedRoutes
 
-          const matchedFrom = findLast(allCurrentLocationMatches, (d) => {
-            return comparePaths(d.fullPath, fromPath)
-          })
+        const matchedFrom = findLast(allCurrentLocationMatches, (d) => {
+          return comparePaths(d.fullPath, dest.from!)
+        })
 
-          const matchedCurrent = findLast(allFromMatches, (d) => {
-            return comparePaths(d.fullPath, currentLocation.pathname)
-          })
+        const matchedCurrent = findLast(allFromMatches, (d) => {
+          return comparePaths(d.fullPath, lastMatch.fullPath)
+        })
 
-          // for from to be invalid it shouldn't just be unmatched to currentLocation
-          // but the currentLocation should also be unmatched to from
-          if (!matchedFrom && !matchedCurrent) {
-            console.warn(`Could not find match for from: ${fromPath}`)
-          }
+        // for from to be invalid it shouldn't just be unmatched to currentLocation
+        // but the currentLocation should also be unmatched to from
+        if (!matchedFrom && !matchedCurrent) {
+          console.warn(`Could not find match for from: ${dest.from}`)
         }
       }
 
-      fromPath = this.resolvePathWithBase(fromPath, '.')
+      const defaultedFromPath =
+        dest.unsafeRelative === 'path'
+          ? currentLocation.pathname
+          : (dest.from ?? lastMatch.fullPath)
+
+      // ensure this includes the basePath if set
+      const fromPath = this.resolvePathWithBase(defaultedFromPath, '.')
 
       // From search should always use the current location
       const fromSearch = lastMatch.search
@@ -1474,6 +1470,7 @@ export class RouterCore<
       const fromParams = { ...lastMatch.params }
 
       // Resolve the next to
+      // ensure this includes the basePath if set
       const nextTo = dest.to
         ? this.resolvePathWithBase(fromPath, `${dest.to}`)
         : this.resolvePathWithBase(fromPath, '.')
@@ -1812,7 +1809,7 @@ export class RouterCore<
   beforeLoad = () => {
     // Cancel any pending matches
     this.cancelMatches()
-    this.latestLocation = this.parseLocation(this.latestLocation)
+    this.updateLatestLocation()
 
     if (this.isServer) {
       // for SPAs on the initial load, this is handled by the Transitioner

package/src/scroll-restoration.ts

@@ -47,10 +47,10 @@ const throttle = (fn: (...args: Array<any>) => void, wait: number) => {
   }
 }
 
-function createScrollRestorationCache(): ScrollRestorationCache | undefined {
+function createScrollRestorationCache(): ScrollRestorationCache | null {
   const safeSessionStorage = getSafeSessionStorage()
   if (!safeSessionStorage) {
-    return undefined
+    return null
   }
 
   const persistedState = safeSessionStorage.getItem(storageKey)
@@ -125,7 +125,7 @@ export function restoreScroll({
     return
   }
 
-  const resolvedKey = key || window.history.state?.key
+  const resolvedKey = key || window.history.state?.__TSR_key
   const elementEntries = byKey[resolvedKey]
 
   //
@@ -201,7 +201,7 @@ export function restoreScroll({
 }
 
 export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
-  if (scrollRestorationCache === undefined) {
+  if (!scrollRestorationCache && !router.isServer) {
     return
   }
   const shouldScrollRestoration =
@@ -211,7 +211,11 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
     router.isScrollRestoring = true
   }
 
-  if (typeof document === 'undefined' || router.isScrollRestorationSetup) {
+  if (
+    router.isServer ||
+    router.isScrollRestorationSetup ||
+    !scrollRestorationCache
+  ) {
     return
   }
 
@@ -324,6 +328,14 @@ export function setupScrollRestoration(router: AnyRouter, force?: boolean) {
       router.resetNextScroll = true
       return
     }
+    if (typeof router.options.scrollRestoration === 'function') {
+      const shouldRestore = router.options.scrollRestoration({
+        location: router.latestLocation,
+      })
+      if (!shouldRestore) {
+        return
+      }
+    }
 
     restoreScroll({
       storageKey,

package/src/ssr/serializer/transformer.ts

@@ -1,39 +1,111 @@
 import { createPlugin } from 'seroval'
 import { GLOBAL_TSR } from '../constants'
-import type { SerovalNode } from 'seroval'
+import type { Plugin, SerovalNode } from 'seroval'
+import type { Register, SSROption } from '../../router'
+import type { LooseReturnType } from '../../utils'
+import type { AnyRoute, ResolveAllSSR } from '../../route'
 
-export type Transformer<TInput, TTransformed> = {
+export type Serializable =
+  | number
+  | string
+  | boolean
+  | null
+  | undefined
+  | bigint
+  | Date
+
+export function createSerializationAdapter<
+  TInput = unknown,
+  TOutput = unknown /* we need to check that this type is actually serializable taking into account all seroval native types and any custom plugin WE=router/start add!!! */,
+>(
+  opts: CreateSerializationAdapterOptions<TInput, TOutput>,
+): SerializationAdapter<TInput, TOutput> {
+  return opts as unknown as SerializationAdapter<TInput, TOutput>
+}
+
+export interface CreateSerializationAdapterOptions<TInput, TOutput> {
   key: string
-  test: (value: any) => value is TInput
-  toSerializable: (value: TInput) => TTransformed
-  fromSerializable: (value: TTransformed) => TInput
+  test: (value: unknown) => value is TInput
+  toSerializable: (value: TInput) => ValidateSerializable<TOutput, Serializable>
+  fromSerializable: (value: TOutput) => TInput
 }
 
-export type AnyTransformer = Transformer<any, any>
+export type ValidateSerializable<T, TSerializable> = T extends TSerializable
+  ? T
+  : T extends (...args: Array<any>) => any
+    ? 'Function is not serializable'
+    : T extends Promise<any>
+      ? ValidateSerializablePromise<T, TSerializable>
+      : T extends ReadableStream<any>
+        ? ValidateReadableStream<T, TSerializable>
+        : T extends Set<any>
+          ? ValidateSerializableSet<T, TSerializable>
+          : T extends Map<any, any>
+            ? ValidateSerializableMap<T, TSerializable>
+            : {
+                [K in keyof T]: ValidateSerializable<T[K], TSerializable>
+              }
 
-export function createSerializationAdapter<
-  TKey extends string,
-  TInput,
-  TTransformed /* we need to check that this type is actually serializable taking into account all seroval native types and any custom plugin WE=router/start add!!! */,
->(opts: {
-  key: TKey
-  test: (value: any) => value is TInput
-  toSerializable: (value: TInput) => TTransformed
-  fromSerializable: (value: TTransformed) => TInput
-}): Transformer<TInput, TTransformed> {
-  return opts
+export type ValidateSerializablePromise<T, TSerializable> =
+  T extends Promise<infer TAwaited>
+    ? Promise<ValidateSerializable<TAwaited, TSerializable>>
+    : never
+
+export type ValidateReadableStream<T, TSerializable> =
+  T extends ReadableStream<infer TStreamed>
+    ? ReadableStream<ValidateSerializable<TStreamed, TSerializable>>
+    : never
+
+export type ValidateSerializableSet<T, TSerializable> =
+  T extends Set<infer TItem>
+    ? Set<ValidateSerializable<TItem, TSerializable>>
+    : never
+
+export type ValidateSerializableMap<T, TSerializable> =
+  T extends Map<infer TKey, infer TValue>
+    ? Map<
+        ValidateSerializable<TKey, TSerializable>,
+        ValidateSerializable<TValue, TSerializable>
+      >
+    : never
+
+export type RegisteredReadableStream =
+  unknown extends SerializerExtensions['ReadableStream']
+    ? never
+    : SerializerExtensions['ReadableStream']
+
+export interface DefaultSerializerExtensions {
+  ReadableStream: unknown
+}
+
+export interface SerializerExtensions extends DefaultSerializerExtensions {}
+
+export interface SerializationAdapter<TInput, TOutput> {
+  '~types': SerializationAdapterTypes<TInput, TOutput>
+  key: string
+  test: (value: unknown) => value is TInput
+  toSerializable: (value: TInput) => TOutput
+  fromSerializable: (value: TOutput) => TInput
+  makePlugin: (options: { didRun: boolean }) => Plugin<TInput, SerovalNode>
+}
+
+export interface SerializationAdapterTypes<TInput, TOutput> {
+  input: TInput
+  output: TOutput
 }
 
-export function makeSsrSerovalPlugin<TInput, TTransformed>(
-  transformer: Transformer<TInput, TTransformed>,
+export type AnySerializationAdapter = SerializationAdapter<any, any>
+
+export function makeSsrSerovalPlugin<TInput, TOutput>(
+  serializationAdapter: SerializationAdapter<TInput, TOutput>,
   options: { didRun: boolean },
 ) {
   return createPlugin<TInput, SerovalNode>({
-    tag: '$TSR/t/' + transformer.key,
-    test: transformer.test,
+    tag: '$TSR/t/' + serializationAdapter.key,
+    test: serializationAdapter.test,
     parse: {
       stream(value, ctx) {
-        return ctx.parse(transformer.toSerializable(value))
+        return ctx.parse(serializationAdapter.toSerializable(value))
       },
     },
     serialize(node, ctx) {
@@ -41,7 +113,7 @@ export function makeSsrSerovalPlugin<TInput, TTransformed>(
       return (
         GLOBAL_TSR +
         '.t.get("' +
-        transformer.key +
+        serializationAdapter.key +
         '")(' +
         ctx.serialize(node) +
         ')'
@@ -52,27 +124,92 @@ export function makeSsrSerovalPlugin<TInput, TTransformed>(
   })
 }
 
-export function makeSerovalPlugin<TInput, TTransformed>(
-  transformer: Transformer<TInput, TTransformed>,
+export function makeSerovalPlugin<TInput, TOutput>(
+  serializationAdapter: SerializationAdapter<TInput, TOutput>,
 ) {
   return createPlugin<TInput, SerovalNode>({
-    tag: '$TSR/t/' + transformer.key,
-    test: transformer.test,
+    tag: '$TSR/t/' + serializationAdapter.key,
+    test: serializationAdapter.test,
     parse: {
       sync(value, ctx) {
-        return ctx.parse(transformer.toSerializable(value))
+        return ctx.parse(serializationAdapter.toSerializable(value))
       },
       async async(value, ctx) {
-        return await ctx.parse(transformer.toSerializable(value))
+        return await ctx.parse(serializationAdapter.toSerializable(value))
       },
       stream(value, ctx) {
-        return ctx.parse(transformer.toSerializable(value))
+        return ctx.parse(serializationAdapter.toSerializable(value))
       },
     },
     // we don't generate JS code outside of SSR (for now)
     serialize: undefined as never,
     deserialize(node, ctx) {
-      return transformer.fromSerializable(ctx.deserialize(node) as TTransformed)
+      return serializationAdapter.fromSerializable(
+        ctx.deserialize(node) as TOutput,
+      )
     },
   })
 }
+
+export type ValidateSerializableInput<
+  TRegister extends Register,
+  T,
+> = ValidateSerializable<T, RegisteredSerializableInput<TRegister>>
+
+export type RegisteredSerializableInput<TRegister extends Register> =
+  | (unknown extends RegisteredSerializationAdapters<TRegister>
+      ? never
+      : RegisteredSerializationAdapters<TRegister> extends ReadonlyArray<AnySerializationAdapter>
+        ? RegisteredSerializationAdapters<TRegister>[number]['~types']['input']
+        : never)
+  | Serializable
+
+export type RegisteredSerializationAdapters<TRegister extends Register> =
+  TRegister['config']['~types']['serializationAdapters']
+
+export type ValidateSerializableInputResult<
+  TRegister extends Register,
+  T,
+> = ValidateSerializableResult<T, RegisteredSerializableInput<TRegister>>
+
+export type ValidateSerializableResult<T, TSerializable> =
+  T extends TSerializable
+    ? T
+    : unknown extends SerializerExtensions['ReadableStream']
+      ? { [K in keyof T]: ValidateSerializableResult<T[K], TSerializable> }
+      : T extends SerializerExtensions['ReadableStream']
+        ? ReadableStream
+        : { [K in keyof T]: ValidateSerializableResult<T[K], TSerializable> }
+
+export type RegisteredSSROption<TRegister extends Register> =
+  unknown extends TRegister['config']['~types']['defaultSsr']
+    ? SSROption
+    : TRegister['config']['~types']['defaultSsr']
+
+export type ValidateSerializableLifecycleResult<
+  TRegister extends Register,
+  TParentRoute extends AnyRoute,
+  TSSR,
+  TFn,
+> = false extends TRegister['ssr']
+  ? any
+  : ValidateSerializableLifecycleResultSSR<
+        TRegister,
+        TParentRoute,
+        TSSR,
+        TFn
+      > extends infer TInput
+    ? TInput
+    : never
+
+export type ValidateSerializableLifecycleResultSSR<
+  TRegister extends Register,
+  TParentRoute extends AnyRoute,
+  TSSR,
+  TFn,
+> =
+  ResolveAllSSR<TParentRoute, TSSR> extends false
+    ? any
+    : RegisteredSSROption<TRegister> extends false
+      ? any
+      : ValidateSerializableInput<TRegister, LooseReturnType<TFn>>

package/src/ssr/server.ts

@@ -8,3 +8,9 @@ export {
   transformReadableStreamWithRouter,
 } from './transformStreamWithRouter'
 export { attachRouterServerSsrUtils } from './ssr-server'
+
+declare module '../router' {
+  export interface Register {
+    ssr: true
+  }
+}

package/src/ssr/ssr-client.ts

@@ -5,7 +5,7 @@ import type { AnyRouteMatch, MakeRouteMatch } from '../Matches'
 import type { AnyRouter } from '../router'
 import type { Manifest } from '../manifest'
 import type { RouteContextOptions } from '../route'
-import type { AnyTransformer } from './serializer/transformer'
+import type { AnySerializationAdapter } from './serializer/transformer'
 import type { GLOBAL_TSR } from './constants'
 
 declare global {
@@ -63,7 +63,7 @@ export async function hydrate(router: AnyRouter): Promise<any> {
   )
 
   const serializationAdapters = router.options.serializationAdapters as
-    | Array<AnyTransformer>
+    | Array<AnySerializationAdapter>
     | undefined
 
   if (serializationAdapters?.length) {

package/src/ssr/ssr-server.ts

@@ -10,7 +10,7 @@ import type { DehydratedMatch } from './ssr-client'
 import type { DehydratedRouter } from './client'
 import type { AnyRouteMatch } from '../Matches'
 import type { Manifest } from '../manifest'
-import type { AnyTransformer } from './serializer/transformer'
+import type { AnySerializationAdapter } from './serializer/transformer'
 
 declare module '../router' {
   interface ServerSsr {
@@ -109,7 +109,7 @@ export function attachRouterServerSsrUtils(
       const plugins =
         (
           router.options.serializationAdapters as
-            | Array<AnyTransformer>
+            | Array<AnySerializationAdapter>
             | undefined
         )?.map((t) => makeSsrSerovalPlugin(t, trackPlugins)) ?? []
       crossSerializeStream(dehydratedRouter, {