@tanstack/router-core 1.121.34 → 1.121.40

package/src/serializer.ts

@@ -1,10 +1,17 @@
-export interface StartSerializer {
+import { isPlainObject } from './utils'
+
+export interface TsrSerializer {
   stringify: (obj: unknown) => string
   parse: (str: string) => unknown
   encode: <T>(value: T) => T
   decode: <T>(value: T) => T
 }
 
+/**
+ * @deprecated This is re-export of TsrSerializer which is the generic Router serializer interface. Going forward StartSerializer will be used specifically as a Tanstack Start serializer interface.
+ */
+export interface StartSerializer extends TsrSerializer {}
+
 export type SerializerStringifyBy<T, TSerializable> = T extends TSerializable
   ? T
   : T extends (...args: Array<any>) => any
@@ -30,3 +37,169 @@ export type Serializable = Date | undefined | Error | FormData | bigint
 export type SerializerStringify<T> = SerializerStringifyBy<T, Serializable>
 
 export type SerializerParse<T> = SerializerParseBy<T, Serializable>
+export const tsrSerializer: TsrSerializer = {
+  stringify: (value: any) =>
+    JSON.stringify(value, function replacer(key, val) {
+      const ogVal = this[key]
+      const serializer = serializers.find((t) => t.stringifyCondition(ogVal))
+
+      if (serializer) {
+        return serializer.stringify(ogVal)
+      }
+
+      return val
+    }),
+  parse: (value: string) =>
+    JSON.parse(value, function parser(key, val) {
+      const ogVal = this[key]
+      if (isPlainObject(ogVal)) {
+        const serializer = serializers.find((t) => t.parseCondition(ogVal))
+
+        if (serializer) {
+          return serializer.parse(ogVal)
+        }
+      }
+
+      return val
+    }),
+  encode: (value: any) => {
+    // When encoding, dive first
+    if (Array.isArray(value)) {
+      return value.map((v) => tsrSerializer.encode(v))
+    }
+
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, v]) => [key, tsrSerializer.encode(v)]),
+      )
+    }
+
+    const serializer = serializers.find((t) => t.stringifyCondition(value))
+    if (serializer) {
+      return serializer.stringify(value)
+    }
+
+    return value
+  },
+  decode: (value: any) => {
+    // Attempt transform first
+    if (isPlainObject(value)) {
+      const serializer = serializers.find((t) => t.parseCondition(value))
+      if (serializer) {
+        return serializer.parse(value)
+      }
+    }
+
+    if (Array.isArray(value)) {
+      return value.map((v) => tsrSerializer.decode(v))
+    }
+
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, v]) => [key, tsrSerializer.decode(v)]),
+      )
+    }
+
+    return value
+  },
+}
+const createSerializer = <TKey extends string, TInput, TSerialized>(
+  key: TKey,
+  check: (value: any) => value is TInput,
+  toValue: (value: TInput) => TSerialized,
+  fromValue: (value: TSerialized) => TInput,
+) => ({
+  key,
+  stringifyCondition: check,
+  stringify: (value: any) => ({ [`$${key}`]: toValue(value) }),
+  parseCondition: (value: any) => Object.hasOwn(value, `$${key}`),
+  parse: (value: any) => fromValue(value[`$${key}`]),
+})
+// Keep these ordered by predicted frequency
+// Make sure to keep DefaultSerializable in sync with these serializers
+// Also, make sure that they are unit tested in serializer.test.tsx
+const serializers = [
+  createSerializer(
+    // Key
+    'undefined',
+    // Check
+    (v): v is undefined => v === undefined,
+    // To
+    () => 0,
+    // From
+    () => undefined,
+  ),
+  createSerializer(
+    // Key
+    'date',
+    // Check
+    (v): v is Date => v instanceof Date,
+    // To
+    (v) => v.toISOString(),
+    // From
+    (v) => new Date(v),
+  ),
+  createSerializer(
+    // Key
+    'error',
+    // Check
+    (v): v is Error => v instanceof Error,
+    // To
+    (v) => ({
+      ...v,
+      message: v.message,
+      stack: process.env.NODE_ENV === 'development' ? v.stack : undefined,
+      cause: v.cause,
+    }),
+    // From
+    (v) => Object.assign(new Error(v.message), v),
+  ),
+  createSerializer(
+    // Key
+    'formData',
+    // Check
+    (v): v is FormData => v instanceof FormData,
+    // To
+    (v) => {
+      const entries: Record<
+        string,
+        Array<FormDataEntryValue> | FormDataEntryValue
+      > = {}
+      v.forEach((value, key) => {
+        const entry = entries[key]
+        if (entry !== undefined) {
+          if (Array.isArray(entry)) {
+            entry.push(value)
+          } else {
+            entries[key] = [entry, value]
+          }
+        } else {
+          entries[key] = value
+        }
+      })
+      return entries
+    },
+    // From
+    (v) => {
+      const formData = new FormData()
+      Object.entries(v).forEach(([key, value]) => {
+        if (Array.isArray(value)) {
+          value.forEach((val) => formData.append(key, val))
+        } else {
+          formData.append(key, value)
+        }
+      })
+      return formData
+    },
+  ),
+  createSerializer(
+    // Key
+    'bigint',
+    // Check
+    (v): v is bigint => typeof v === 'bigint',
+    // To
+    (v) => v.toString(),
+    // From
+    (v) => BigInt(v),
+  ),
+] as const

package/src/ssr/client.ts

@@ -0,0 +1,15 @@
+export { mergeHeaders, headersInitToObject } from './headers'
+export { json } from './json'
+export type { JsonResponse } from './json'
+export { hydrate } from './ssr-client'
+export type {
+  DehydratedRouter,
+  ClientExtractedBaseEntry,
+  TsrSsrGlobal,
+  ClientExtractedEntry,
+  SsrMatch,
+  ClientExtractedPromise,
+  ClientExtractedStream,
+  ResolvePromiseState,
+} from './ssr-client'
+export { tsrSerializer } from '../serializer'

package/src/ssr/createRequestHandler.ts

@@ -0,0 +1,74 @@
+import { createMemoryHistory } from '@tanstack/history'
+import { mergeHeaders } from './headers'
+import { attachRouterServerSsrUtils, dehydrateRouter } from './ssr-server'
+import type { HandlerCallback } from './handlerCallback'
+import type { AnyRouter } from '../router'
+import type { Manifest } from '../manifest'
+
+export type RequestHandler<TRouter extends AnyRouter> = (
+  cb: HandlerCallback<TRouter>,
+) => Promise<Response>
+
+export function createRequestHandler<TRouter extends AnyRouter>({
+  createRouter,
+  request,
+  getRouterManifest,
+}: {
+  createRouter: () => TRouter
+  request: Request
+  getRouterManifest?: () => Manifest | Promise<Manifest>
+}): RequestHandler<TRouter> {
+  return async (cb) => {
+    const router = createRouter()
+
+    attachRouterServerSsrUtils(router, await getRouterManifest?.())
+
+    const url = new URL(request.url, 'http://localhost')
+
+    const href = url.href.replace(url.origin, '')
+
+    // Create a history for the router
+    const history = createMemoryHistory({
+      initialEntries: [href],
+    })
+
+    // Update the router with the history and context
+    router.update({
+      history,
+    })
+
+    await router.load()
+
+    dehydrateRouter(router)
+
+    const responseHeaders = getRequestHeaders({
+      router,
+    })
+
+    return cb({
+      request,
+      router,
+      responseHeaders,
+    } as any)
+  }
+}
+
+function getRequestHeaders(opts: { router: AnyRouter }): Headers {
+  let headers = mergeHeaders(
+    {
+      'Content-Type': 'text/html; charset=UTF-8',
+    },
+    ...opts.router.state.matches.map((match) => {
+      return match.headers
+    }),
+  )
+
+  // Handle Redirects
+  const { redirect } = opts.router.state
+
+  if (redirect) {
+    headers = mergeHeaders(headers, redirect.headers)
+  }
+
+  return headers
+}

package/src/ssr/handlerCallback.ts

@@ -0,0 +1,15 @@
+import type { AnyRouter } from '../router'
+
+export interface HandlerCallback<TRouter extends AnyRouter> {
+  (ctx: {
+    request: Request
+    router: TRouter
+    responseHeaders: Headers
+  }): Response | Promise<Response>
+}
+
+export function defineHandlerCallback<TRouter extends AnyRouter>(
+  handler: HandlerCallback<TRouter>,
+): HandlerCallback<TRouter> {
+  return handler
+}

package/src/ssr/headers.ts

@@ -0,0 +1,51 @@
+import { splitSetCookieString } from 'cookie-es'
+import type { OutgoingHttpHeaders } from 'node:http2'
+
+// A utility function to turn HeadersInit into an object
+export function headersInitToObject(
+  headers: HeadersInit,
+): Record<keyof OutgoingHttpHeaders, string> {
+  const obj: Record<keyof OutgoingHttpHeaders, string> = {}
+  const headersInstance = new Headers(headers)
+  for (const [key, value] of headersInstance.entries()) {
+    obj[key] = value
+  }
+  return obj
+}
+
+type AnyHeaders =
+  | Headers
+  | HeadersInit
+  | Record<string, string>
+  | Array<[string, string]>
+  | OutgoingHttpHeaders
+  | undefined
+
+// Helper function to convert various HeaderInit types to a Headers instance
+function toHeadersInstance(init: AnyHeaders) {
+  if (init instanceof Headers) {
+    return new Headers(init)
+  } else if (Array.isArray(init)) {
+    return new Headers(init)
+  } else if (typeof init === 'object') {
+    return new Headers(init as HeadersInit)
+  } else {
+    return new Headers()
+  }
+}
+
+// Function to merge headers with proper overrides
+export function mergeHeaders(...headers: Array<AnyHeaders>) {
+  return headers.reduce((acc: Headers, header) => {
+    const headersInstance = toHeadersInstance(header)
+    for (const [key, value] of headersInstance.entries()) {
+      if (key === 'set-cookie') {
+        const splitCookies = splitSetCookieString(value)
+        splitCookies.forEach((cookie) => acc.append('set-cookie', cookie))
+      } else {
+        acc.set(key, value)
+      }
+    }
+    return acc
+  }, new Headers())
+}

package/src/ssr/json.ts

@@ -0,0 +1,18 @@
+import { mergeHeaders } from './headers'
+
+export interface JsonResponse<TData> extends Response {
+  json: () => Promise<TData>
+}
+
+export function json<TData>(
+  payload: TData,
+  init?: ResponseInit,
+): JsonResponse<TData> {
+  return new Response(JSON.stringify(payload), {
+    ...init,
+    headers: mergeHeaders(
+      { 'content-type': 'application/json' },
+      init?.headers,
+    ),
+  })
+}

package/src/ssr/server.ts

@@ -0,0 +1,23 @@
+export { createRequestHandler } from './createRequestHandler'
+export type { RequestHandler } from './createRequestHandler'
+export { defineHandlerCallback } from './handlerCallback'
+export type { HandlerCallback } from './handlerCallback'
+export {
+  transformPipeableStreamWithRouter,
+  transformStreamWithRouter,
+  transformReadableStreamWithRouter,
+} from './transformStreamWithRouter'
+export {
+  attachRouterServerSsrUtils,
+  dehydrateRouter,
+  extractAsyncLoaderData,
+  onMatchSettled,
+  replaceBy,
+} from './ssr-server'
+export type {
+  ServerExtractedBaseEntry,
+  ServerExtractedEntry,
+  ServerExtractedPromise,
+  ServerExtractedStream,
+} from './ssr-server'
+export * from './tsrScript'

package/src/ssr/ssr-client.ts

@@ -0,0 +1,244 @@
+import invariant from 'tiny-invariant'
+import { isPlainObject } from '../utils'
+import { tsrSerializer } from '../serializer'
+import type { DeferredPromiseState } from '../defer'
+import type { MakeRouteMatch } from '../Matches'
+import type { AnyRouter, ControllablePromise } from '../router'
+import type { Manifest } from '../manifest'
+import type { RouteContextOptions } from '../route'
+
+declare global {
+  interface Window {
+    __TSR_SSR__?: TsrSsrGlobal
+  }
+}
+
+export interface TsrSsrGlobal {
+  matches: Array<SsrMatch>
+  streamedValues: Record<
+    string,
+    {
+      value: any
+      parsed: any
+    }
+  >
+  cleanScripts: () => void
+  dehydrated?: any
+  initMatch: (match: SsrMatch) => void
+  resolvePromise: (opts: {
+    matchId: string
+    id: number
+    promiseState: DeferredPromiseState<any>
+  }) => void
+  injectChunk: (opts: { matchId: string; id: number; chunk: string }) => void
+  closeStream: (opts: { matchId: string; id: number }) => void
+}
+
+export interface SsrMatch {
+  id: string
+  __beforeLoadContext: string
+  loaderData?: string
+  error?: string
+  extracted?: Array<ClientExtractedEntry>
+  updatedAt: MakeRouteMatch['updatedAt']
+  status: MakeRouteMatch['status']
+}
+
+export type ClientExtractedEntry =
+  | ClientExtractedStream
+  | ClientExtractedPromise
+
+export interface ClientExtractedPromise extends ClientExtractedBaseEntry {
+  type: 'promise'
+  value?: ControllablePromise<any>
+}
+
+export interface ClientExtractedStream extends ClientExtractedBaseEntry {
+  type: 'stream'
+  value?: ReadableStream & { controller?: ReadableStreamDefaultController }
+}
+
+export interface ClientExtractedBaseEntry {
+  type: string
+  path: Array<string>
+}
+
+export interface ResolvePromiseState {
+  matchId: string
+  id: number
+  promiseState: DeferredPromiseState<any>
+}
+
+export interface DehydratedRouter {
+  manifest: Manifest | undefined
+  dehydratedData: any
+  lastMatchId: string
+}
+
+export async function hydrate(router: AnyRouter): Promise<any> {
+  invariant(
+    window.__TSR_SSR__?.dehydrated,
+    'Expected to find a dehydrated data on window.__TSR_SSR__.dehydrated... but we did not. Please file an issue!',
+  )
+
+  const { manifest, dehydratedData, lastMatchId } = tsrSerializer.parse(
+    window.__TSR_SSR__.dehydrated,
+  ) as DehydratedRouter
+
+  router.ssr = {
+    manifest,
+    serializer: tsrSerializer,
+  }
+
+  router.clientSsr = {
+    getStreamedValue: <T>(key: string): T | undefined => {
+      if (router.isServer) {
+        return undefined
+      }
+
+      const streamedValue = window.__TSR_SSR__?.streamedValues[key]
+
+      if (!streamedValue) {
+        return
+      }
+
+      if (!streamedValue.parsed) {
+        streamedValue.parsed = router.ssr!.serializer.parse(streamedValue.value)
+      }
+
+      return streamedValue.parsed
+    },
+  }
+
+  // Hydrate the router state
+  const matches = router.matchRoutes(router.state.location)
+
+  // kick off loading the route chunks
+  const routeChunkPromise = Promise.all(
+    matches.map((match) => {
+      const route = router.looseRoutesById[match.routeId]!
+      return router.loadRouteChunk(route)
+    }),
+  )
+
+  // Right after hydration and before the first render, we need to rehydrate each match
+  // First step is to reyhdrate loaderData and __beforeLoadContext
+  matches.forEach((match) => {
+    const dehydratedMatch = window.__TSR_SSR__!.matches.find(
+      (d) => d.id === match.id,
+    )
+
+    if (!dehydratedMatch) {
+      return
+    }
+
+    Object.assign(match, dehydratedMatch)
+
+    // Handle beforeLoadContext
+    if (dehydratedMatch.__beforeLoadContext) {
+      match.__beforeLoadContext = router.ssr!.serializer.parse(
+        dehydratedMatch.__beforeLoadContext,
+      ) as any
+    }
+
+    // Handle loaderData
+    if (dehydratedMatch.loaderData) {
+      match.loaderData = router.ssr!.serializer.parse(
+        dehydratedMatch.loaderData,
+      )
+    }
+
+    // Handle error
+    if (dehydratedMatch.error) {
+      match.error = router.ssr!.serializer.parse(dehydratedMatch.error)
+    }
+
+    // Handle extracted
+    ;(match as unknown as SsrMatch).extracted?.forEach((ex) => {
+      deepMutableSetByPath(match, ['loaderData', ...ex.path], ex.value)
+    })
+
+    return match
+  })
+
+  router.__store.setState((s) => {
+    return {
+      ...s,
+      matches,
+    }
+  })
+
+  // Allow the user to handle custom hydration data
+  await router.options.hydrate?.(dehydratedData)
+
+  // now that all necessary data is hydrated:
+  // 1) fully reconstruct the route context
+  // 2) execute `head()` and `scripts()` for each match
+  await Promise.all(
+    router.state.matches.map(async (match) => {
+      const route = router.looseRoutesById[match.routeId]!
+
+      const parentMatch = router.state.matches[match.index - 1]
+      const parentContext = parentMatch?.context ?? router.options.context ?? {}
+
+      // `context()` was already executed by `matchRoutes`, however route context was not yet fully reconstructed
+      // so run it again and merge route context
+      const contextFnContext: RouteContextOptions<any, any, any, any> = {
+        deps: match.loaderDeps,
+        params: match.params,
+        context: parentContext,
+        location: router.state.location,
+        navigate: (opts: any) =>
+          router.navigate({ ...opts, _fromLocation: router.state.location }),
+        buildLocation: router.buildLocation,
+        cause: match.cause,
+        abortController: match.abortController,
+        preload: false,
+        matches,
+      }
+      match.__routeContext = route.options.context?.(contextFnContext) ?? {}
+
+      match.context = {
+        ...parentContext,
+        ...match.__routeContext,
+        ...match.__beforeLoadContext,
+      }
+
+      const assetContext = {
+        matches: router.state.matches,
+        match,
+        params: match.params,
+        loaderData: match.loaderData,
+      }
+      const headFnContent = await route.options.head?.(assetContext)
+
+      const scripts = await route.options.scripts?.(assetContext)
+
+      match.meta = headFnContent?.meta
+      match.links = headFnContent?.links
+      match.headScripts = headFnContent?.scripts
+      match.scripts = scripts
+    }),
+  )
+
+  if (matches[matches.length - 1]!.id !== lastMatchId) {
+    return await Promise.all([routeChunkPromise, router.load()])
+  }
+
+  return routeChunkPromise
+}
+
+function deepMutableSetByPath<T>(obj: T, path: Array<string>, value: any) {
+  // mutable set by path retaining array and object references
+  if (path.length === 1) {
+    ;(obj as any)[path[0]!] = value
+  }
+
+  const [key, ...rest] = path
+
+  if (Array.isArray(obj)) {
+    deepMutableSetByPath(obj[Number(key)], rest, value)
+  } else if (isPlainObject(obj)) {
+    deepMutableSetByPath((obj as any)[key!], rest, value)
+  }
+}