@tanstack/start-client-core 1.20.3-alpha.1

package/src/envOnly.ts

@@ -0,0 +1,9 @@
+type EnvOnlyFn = <TFn extends (...args: Array<any>) => any>(fn: TFn) => TFn
+
+// A function that will only be available in the server build
+// If called on the client, it will throw an error
+export const serverOnly: EnvOnlyFn = (fn) => fn
+
+// A function that will only be available in the client build
+// If called on the server, it will throw an error
+export const clientOnly: EnvOnlyFn = (fn) => fn

package/src/headers.ts

@@ -0,0 +1,50 @@
+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/index.tsx

@@ -0,0 +1,88 @@
+export { mergeHeaders } from './headers'
+export { startSerializer } from './serializer'
+export {
+  type DehydratedRouter,
+  type ClientExtractedBaseEntry,
+  type StartSsrGlobal,
+  type ClientExtractedEntry,
+  type SsrMatch,
+  type ClientExtractedPromise,
+  type ClientExtractedStream,
+  type ResolvePromiseState,
+  hydrate,
+} from './ssr-client'
+export {
+  createIsomorphicFn,
+  type IsomorphicFn,
+  type ServerOnlyFn,
+  type ClientOnlyFn,
+  type IsomorphicFnBase,
+} from './createIsomorphicFn'
+export { serverOnly, clientOnly } from './envOnly'
+export { type JsonResponse, createServerFn } from './createServerFn'
+export { json } from './json'
+export {
+  createMiddleware,
+  type IntersectAllValidatorInputs,
+  type IntersectAllValidatorOutputs,
+  type FunctionMiddlewareServerFn,
+  type AnyFunctionMiddleware,
+  type FunctionMiddlewareOptions,
+  type FunctionMiddlewareWithTypes,
+  type FunctionMiddlewareValidator,
+  type FunctionMiddlewareServer,
+  type FunctionMiddlewareAfterClient,
+  type FunctionMiddlewareAfterServer,
+  type FunctionMiddleware,
+  type FunctionMiddlewareClientFnOptions,
+  type FunctionMiddlewareClientFnResult,
+  type FunctionMiddlewareClientNextFn,
+  type FunctionClientResultWithContext,
+  type AssignAllClientContextBeforeNext,
+  type AssignAllMiddleware,
+  type AssignAllServerContext,
+  type FunctionMiddlewareAfterValidator,
+  type FunctionMiddlewareClientFn,
+  type FunctionMiddlewareServerFnResult,
+  type FunctionMiddlewareClient,
+  type FunctionMiddlewareServerFnOptions,
+  type FunctionMiddlewareServerNextFn,
+  type FunctionServerResultWithContext,
+  type AnyRequestMiddleware,
+} from './createMiddleware'
+export {
+  registerGlobalMiddleware,
+  globalMiddleware,
+} from './registerGlobalMiddleware'
+export type {
+  ServerFn as FetchFn,
+  ServerFnCtx as FetchFnCtx,
+  CompiledFetcherFnOptions,
+  CompiledFetcherFn,
+  Fetcher,
+  RscStream,
+  FetcherData,
+  FetcherBaseOptions,
+  ServerFn,
+  ServerFnCtx,
+  ServerFnResponseType,
+  MiddlewareFn,
+  ServerFnMiddlewareOptions,
+  ServerFnMiddlewareResult,
+  ServerFnBuilder,
+  ServerFnType,
+  ServerFnBaseOptions,
+  NextFn,
+  Method,
+  StaticCachedResult,
+  OptionalFetcher,
+} from './createServerFn'
+export {
+  applyMiddleware,
+  execValidator,
+  serverFnBaseToMiddleware,
+  extractFormDataContext,
+  flattenMiddlewares,
+  serverFnStaticCache,
+  executeMiddleware,
+} from './createServerFn'

package/src/json.ts

@@ -0,0 +1,15 @@
+import { mergeHeaders } from './headers'
+import type { JsonResponse } from './createServerFn'
+
+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/registerGlobalMiddleware.ts

@@ -0,0 +1,9 @@
+import type { AnyFunctionMiddleware } from './createMiddleware'
+
+export const globalMiddleware: Array<AnyFunctionMiddleware> = []
+
+export function registerGlobalMiddleware(options: {
+  middleware: Array<AnyFunctionMiddleware>
+}) {
+  globalMiddleware.push(...options.middleware)
+}

package/src/serializer.ts

@@ -0,0 +1,177 @@
+import { isPlainObject } from '@tanstack/router-core'
+import type { StartSerializer } from '@tanstack/router-core'
+
+export const startSerializer: StartSerializer = {
+  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) => startSerializer.encode(v))
+    }
+
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, v]) => [
+          key,
+          startSerializer.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) => startSerializer.decode(v))
+    }
+
+    if (isPlainObject(value)) {
+      return Object.fromEntries(
+        Object.entries(value).map(([key, v]) => [
+          key,
+          startSerializer.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.tsx

@@ -0,0 +1,243 @@
+import { isPlainObject } from '@tanstack/router-core'
+
+import invariant from 'tiny-invariant'
+
+import { startSerializer } from './serializer'
+import type {
+  AnyRouter,
+  ControllablePromise,
+  DeferredPromiseState,
+  MakeRouteMatch,
+  Manifest,
+  RouteContextOptions,
+} from '@tanstack/router-core'
+
+declare global {
+  interface Window {
+    __TSR_SSR__?: StartSsrGlobal
+  }
+}
+
+export interface StartSsrGlobal {
+  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
+}
+
+export function hydrate(router: AnyRouter) {
+  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 } = startSerializer.parse(
+    window.__TSR_SSR__.dehydrated,
+  ) as DehydratedRouter
+
+  router.ssr = {
+    manifest,
+    serializer: startSerializer,
+  }
+
+  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) {
+      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)
+      })
+    } else {
+      Object.assign(match, {
+        status: 'success',
+        updatedAt: Date.now(),
+      })
+    }
+
+    return match
+  })
+
+  router.__store.setState((s) => {
+    return {
+      ...s,
+      matches,
+    }
+  })
+
+  // Allow the user to handle custom hydration data
+  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
+  router.state.matches.forEach((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 = route.options.head?.(assetContext)
+
+    const scripts = route.options.scripts?.(assetContext)
+
+    match.meta = headFnContent?.meta
+    match.links = headFnContent?.links
+    match.headScripts = headFnContent?.scripts
+    match.scripts = scripts
+  })
+
+  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)
+  }
+}

package/src/tests/createIsomorphicFn.test-d.ts

@@ -0,0 +1,72 @@
+import { expectTypeOf, test } from 'vitest'
+import { createIsomorphicFn } from '../createIsomorphicFn'
+
+test('createIsomorphicFn with no implementations', () => {
+  const fn = createIsomorphicFn()
+
+  expectTypeOf(fn).toBeCallableWith()
+  expectTypeOf(fn).returns.toBeUndefined()
+
+  expectTypeOf(fn).toHaveProperty('server')
+  expectTypeOf(fn).toHaveProperty('client')
+})
+
+test('createIsomorphicFn with server implementation', () => {
+  const fn = createIsomorphicFn().server(() => 'data')
+
+  expectTypeOf(fn).toBeCallableWith()
+  expectTypeOf(fn).returns.toEqualTypeOf<string | undefined>()
+
+  expectTypeOf(fn).toHaveProperty('client')
+  expectTypeOf(fn).not.toHaveProperty('server')
+})
+
+test('createIsomorphicFn with client implementation', () => {
+  const fn = createIsomorphicFn().client(() => 'data')
+
+  expectTypeOf(fn).toBeCallableWith()
+  expectTypeOf(fn).returns.toEqualTypeOf<string | undefined>()
+
+  expectTypeOf(fn).toHaveProperty('server')
+  expectTypeOf(fn).not.toHaveProperty('client')
+})
+
+test('createIsomorphicFn with server and client implementation', () => {
+  const fn = createIsomorphicFn()
+    .server(() => 'data')
+    .client(() => 'data')
+
+  expectTypeOf(fn).toBeCallableWith()
+  expectTypeOf(fn).returns.toEqualTypeOf<string>()
+
+  expectTypeOf(fn).not.toHaveProperty('server')
+  expectTypeOf(fn).not.toHaveProperty('client')
+})
+
+test('createIsomorphicFn with varying returns', () => {
+  const fn = createIsomorphicFn()
+    .server(() => 'data')
+    .client(() => 1)
+  expectTypeOf(fn).toBeCallableWith()
+  expectTypeOf(fn).returns.toEqualTypeOf<string | number>()
+})
+
+test('createIsomorphicFn with arguments', () => {
+  const fn = createIsomorphicFn()
+    .server((a: number, b: string) => 'data')
+    .client((...args) => {
+      expectTypeOf(args).toEqualTypeOf<[number, string]>()
+      return 1
+    })
+  expectTypeOf(fn).toBeCallableWith(1, 'a')
+  expectTypeOf(fn).returns.toEqualTypeOf<string | number>()
+
+  const fn2 = createIsomorphicFn()
+    .client((a: number, b: string) => 'data')
+    .server((...args) => {
+      expectTypeOf(args).toEqualTypeOf<[number, string]>()
+      return 1
+    })
+  expectTypeOf(fn2).toBeCallableWith(1, 'a')
+  expectTypeOf(fn2).returns.toEqualTypeOf<string | number>()
+})