@tanstack/react-start-rsc 0.0.0

package/src/CompositeComponent.tsx

@@ -0,0 +1,165 @@
+'use client'
+
+import { Suspense } from 'react'
+import ReactDOM from 'react-dom'
+
+import { SlotProvider } from './SlotContext'
+import {
+  RSC_PROXY_GET_TREE,
+  RSC_PROXY_PATH,
+  SERVER_COMPONENT_CSS_HREFS,
+  SERVER_COMPONENT_JS_PRELOADS,
+  SERVER_COMPONENT_STREAM,
+} from './ServerComponentTypes'
+import type { AnyCompositeComponent } from './ServerComponentTypes'
+import type { SlotImplementations } from './types'
+
+function splitSlotProps(props?: Record<string, unknown>): {
+  implementations: SlotImplementations
+  strict: boolean
+} {
+  const safeProps = props ?? {}
+  const { children, strict, ...slotProps } = safeProps as {
+    children?: unknown
+    strict?: unknown
+    [key: string]: unknown
+  }
+
+  return {
+    implementations: { ...slotProps, children },
+    strict: strict === true,
+  }
+}
+
+function EmptyFallback() {
+  return null
+}
+
+function CompositeRenderInner({
+  getTree,
+  path,
+  slotProps,
+}: {
+  getTree: () => unknown
+  path: Array<string>
+  slotProps?: Record<string, unknown>
+}): React.ReactNode {
+  let tree: unknown = getTree()
+
+  for (const key of path) {
+    if (tree === null || tree === undefined) return null
+    if (typeof tree !== 'object') return null
+    tree = (tree as Record<string, unknown>)[key]
+  }
+
+  if (tree === null || tree === undefined) return null
+
+  const { implementations, strict } = splitSlotProps(slotProps)
+
+  return (
+    <SlotProvider implementations={implementations} strict={strict}>
+      {tree as React.ReactNode}
+    </SlotProvider>
+  )
+}
+
+function CompositeRenderComponent({
+  getTree,
+  path,
+  slotProps,
+  cssHrefs,
+  jsPreloads,
+}: {
+  getTree: () => unknown
+  path: Array<string>
+  slotProps?: Record<string, unknown>
+  cssHrefs?: ReadonlySet<string>
+  jsPreloads?: ReadonlySet<string>
+}): React.ReactNode {
+  for (const href of cssHrefs ?? []) {
+    ReactDOM.preinit(href, { as: 'style', precedence: 'high' })
+  }
+
+  if (jsPreloads) {
+    for (const href of jsPreloads) {
+      ReactDOM.preloadModule(href)
+    }
+  }
+
+  return (
+    <>
+      <Suspense fallback={<EmptyFallback />}>
+        <CompositeRenderInner
+          getTree={getTree}
+          path={path}
+          slotProps={slotProps}
+        />
+      </Suspense>
+    </>
+  )
+}
+
+/**
+ * Renders composite RSC data with slot support.
+ *
+ * Use this component to render data from `createCompositeComponent`.
+ * Pass slot implementations as props to fill in ClientSlot placeholders.
+ *
+ * @example
+ * ```tsx
+ * const src = await createCompositeComponent((props) => (
+ *   <div>
+ *     <header>{props.header('Dashboard')}</header>
+ *     <main>{props.children}</main>
+ *   </div>
+ * ))
+ *
+ * // In route component
+ * return (
+ *   <CompositeComponent src={src} header={(title) => <h1>{title}</h1>}>
+ *     <p>Main content</p>
+ *   </CompositeComponent>
+ * )
+ * ```
+ */
+export function CompositeComponent<TComp extends AnyCompositeComponent>(
+  props: CompositeComponentProps<TComp>,
+): TComp['~types']['return'] {
+  const { src, ...slotProps } = props
+
+  const stream = src[SERVER_COMPONENT_STREAM]
+
+  if (!stream) {
+    throw new Error(
+      '[tanstack/start] <CompositeComponent> missing RSC stream on src',
+    )
+  }
+
+  const cssHrefs = src[SERVER_COMPONENT_CSS_HREFS]
+  const jsPreloads = src[SERVER_COMPONENT_JS_PRELOADS]
+
+  const path = src[RSC_PROXY_PATH] ?? []
+
+  const getTree = src[RSC_PROXY_GET_TREE]
+
+  if (!getTree) {
+    throw new Error(
+      '[tanstack/start] <CompositeComponent> missing getTree on RSC src. ' +
+        'Make sure src comes from createCompositeComponent().',
+    )
+  }
+
+  return (
+    <CompositeRenderComponent
+      getTree={getTree}
+      path={path}
+      slotProps={slotProps}
+      cssHrefs={cssHrefs}
+      jsPreloads={jsPreloads}
+    />
+  )
+}
+
+export type CompositeComponentProps<TComp extends AnyCompositeComponent> = {
+  src: TComp
+} & TComp['~types']['props']

package/src/ReplayableStream.ts

@@ -0,0 +1,249 @@
+/**
+ * ReplayableStream is used for React Server Components (RSC) / Flight streams.
+ *
+ * In this package the same Flight payload may need to be:
+ * - decoded for SSR (render path), and/or
+ * - serialized for transport to the client for client-side decoding.
+ *
+ * Call sites:
+ * - `src/createServerComponent.ts`: wraps the produced Flight stream once.
+ * - `src/serialization.ts`: uses `createReplayStream()` to transport a fresh stream
+ *   to the client via `RawStream`.
+ *
+ * Constraints:
+ * - Consumption order isn't fixed: SSR decode might start first or transport might
+ *   start first depending on the request path.
+ * - Sometimes only one happens (e.g. when client calls server function directly).
+ *
+ * Why not just `ReadableStream.tee()`?
+ * - tee() must be called up-front before the stream is consumed/locked and only
+ *   creates two live branches (no late "replay from byte 0").
+ * - If one branch is slower or never consumed, the runtime may buffer internally
+ *   to keep branches consistent, which can retain large Flight payloads longer
+ *   than intended and makes cleanup less explicit.
+ *
+ * ReplayableStream reads once, buffers explicitly, can mint replay streams on
+ * demand, and centralizes cancellation so aborting can stop upstream work and
+ * free buffered data deterministically.
+ *
+ * Memory Management:
+ * - Memory is released when the abort signal fires (request cancelled)
+ * - Call `release()` to force immediate cleanup if no more replays are needed
+ * - No automatic release: replays can be created at unpredictable times (SSR decode
+ *   finishes before serialization starts), so we can't safely auto-release
+ */
+
+export interface ReplayableStreamOptions {
+  signal?: AbortSignal
+}
+
+// Use Symbol.for to ensure the same symbol across different module instances
+export const REPLAYABLE_STREAM_MARKER = Symbol.for(
+  'tanstack.rsc.ReplayableStream',
+)
+
+export class ReplayableStream<T = Uint8Array> {
+  // Marker for cross-environment instance checking
+  readonly [REPLAYABLE_STREAM_MARKER] = true
+
+  private chunks: Array<T> = []
+  private done = false
+  private error: unknown = null
+  private waiter: PromiseWithResolvers<void> | null = null
+  private aborted = false
+  private released = false
+
+  private sourceReader: ReadableStreamDefaultReader<T> | null = null
+  private abortSignal: AbortSignal | undefined
+  private abortListener: (() => void) | null = null
+
+  constructor(
+    private source: ReadableStream<T>,
+    private options: ReplayableStreamOptions = {},
+  ) {
+    this.abortSignal = options.signal
+    this.start()
+  }
+
+  private start(): void {
+    const signal = this.abortSignal
+
+    if (signal?.aborted) {
+      this.handleAbort()
+      return
+    }
+
+    const onAbort = () => this.handleAbort()
+    this.abortListener = onAbort
+    signal?.addEventListener('abort', onAbort, { once: true })
+
+    const reader = this.source.getReader()
+    this.sourceReader = reader
+
+    const pump = async () => {
+      try {
+        // Keep reading until upstream ends or we are stopped.
+        while (!this.aborted && !this.released) {
+          const { done, value } = await reader.read()
+          if (done) break
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+          if (this.aborted || this.released) break
+          this.chunks.push(value)
+          this.notify()
+        }
+        this.done = true
+      } catch (err) {
+        if (!this.aborted && !this.released) {
+          this.error = err
+        }
+        this.done = true
+      } finally {
+        this.detachAbortListener()
+        try {
+          reader.releaseLock()
+        } catch {
+          // Ignore
+        }
+        if (this.sourceReader === reader) {
+          this.sourceReader = null
+        }
+        this.notify()
+      }
+    }
+
+    pump()
+  }
+
+  private detachAbortListener(): void {
+    const signal = this.abortSignal
+    const listener = this.abortListener
+    if (signal && listener) {
+      signal.removeEventListener('abort', listener)
+    }
+    this.abortListener = null
+  }
+
+  private cancelSource(reason: unknown): void {
+    const reader = this.sourceReader
+    this.sourceReader = null
+
+    try {
+      reader?.cancel(reason).catch(() => {})
+    } catch {
+      // Ignore
+    }
+  }
+
+  private handleAbort(): void {
+    if (this.aborted) return
+    this.aborted = true
+    this.done = true
+
+    // Try to stop upstream work immediately.
+    // Cancellation during an abort can throw synchronously in some runtimes
+    // (eg when the underlying cancel algorithm throws). Never let that escape
+    // an AbortSignal event handler.
+    const reason =
+      this.abortSignal?.reason ?? new Error('ReplayableStream aborted')
+
+    this.detachAbortListener()
+    this.abortSignal = undefined
+    this.cancelSource(reason)
+
+    this.chunks = [] // Free memory immediately on abort
+    this.released = true
+    this.notify()
+  }
+
+  private notify(): void {
+    if (this.waiter) {
+      this.waiter.resolve()
+      this.waiter = null
+    }
+  }
+
+  private wait(): Promise<void> {
+    if (this.done || this.released) return Promise.resolve()
+    if (!this.waiter) {
+      this.waiter = Promise.withResolvers<void>()
+    }
+    return this.waiter.promise
+  }
+
+  /**
+   * Explicitly release buffered chunks.
+   * Call this when you know no more replay streams will be created.
+   * After calling release(), createReplayStream() will return empty streams.
+   */
+  release(): void {
+    if (this.released) return
+
+    this.released = true
+    this.chunks = []
+
+    // Release should also stop upstream work and wake any waiters.
+    // This is important when a Flight payload is never consumed again
+    // (eg. cached loader data that evicts) to avoid retaining upstream resources.
+    this.detachAbortListener()
+    this.abortSignal = undefined
+    this.cancelSource(new Error('ReplayableStream released'))
+    this.notify()
+  }
+
+  /**
+   * Check if the stream data has been released
+   */
+  isReleased(): boolean {
+    return this.released
+  }
+
+  /**
+   * Create an independent replay stream. Each call returns a fresh reader
+   * that starts from the beginning of the buffered data.
+   *
+   * If the stream has been released, returns a stream that closes immediately.
+   */
+  createReplayStream(): ReadableStream<T> {
+    if (this.released) {
+      return new ReadableStream<T>({
+        start(controller) {
+          controller.close()
+        },
+      })
+    }
+
+    let index = 0
+
+    return new ReadableStream<T>({
+      pull: async (controller) => {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        while (true) {
+          if (this.released) {
+            controller.close()
+            return
+          }
+
+          if (index < this.chunks.length) {
+            controller.enqueue(this.chunks[index++] as T)
+            return
+          }
+
+          if (this.done) {
+            if (this.error && !this.aborted) {
+              controller.error(this.error)
+            } else {
+              controller.close()
+            }
+            return
+          }
+
+          await this.wait()
+        }
+      },
+      cancel: () => {
+        // No-op: consumers canceling a replay should not cancel upstream.
+        // Upstream cancellation is controlled by abort/release.
+      },
+    })
+  }
+}

package/src/RscNodeRenderer.tsx

@@ -0,0 +1,76 @@
+'use client'
+
+import { Suspense } from 'react'
+import ReactDOM from 'react-dom'
+
+import {
+  RSC_PROXY_GET_TREE,
+  RSC_PROXY_PATH,
+  SERVER_COMPONENT_CSS_HREFS,
+  SERVER_COMPONENT_JS_PRELOADS,
+} from './ServerComponentTypes'
+
+function EmptyFallback() {
+  return null
+}
+
+function RscNodeRenderInner({
+  getTree,
+  path,
+}: {
+  getTree: () => unknown
+  path: Array<string>
+}): React.ReactNode {
+  let tree: unknown = getTree()
+
+  for (const key of path) {
+    if (tree === null || tree === undefined) return null
+    if (typeof tree !== 'object') return null
+    tree = (tree as Record<string, unknown>)[key]
+  }
+
+  if (tree === null || tree === undefined) return null
+
+  // No SlotProvider - just return the tree directly
+  return tree as React.ReactNode
+}
+
+/**
+ * Renders a renderable RSC proxy without slot support.
+ * Used internally by the renderable proxy's $$typeof/type masquerade.
+ */
+export function RscNodeRenderer({ data }: { data: any }): React.ReactNode {
+  const cssHrefs = data[SERVER_COMPONENT_CSS_HREFS] as
+    | ReadonlySet<string>
+    | undefined
+  const jsPreloads = data[SERVER_COMPONENT_JS_PRELOADS] as
+    | ReadonlySet<string>
+    | undefined
+
+  const path = (data[RSC_PROXY_PATH] as Array<string> | undefined) ?? []
+
+  const getTree = data[RSC_PROXY_GET_TREE] as (() => unknown) | undefined
+  if (!getTree) {
+    throw new Error(
+      '[tanstack/start] RscNodeRenderer missing getTree on RSC data.',
+    )
+  }
+
+  for (const href of cssHrefs ?? []) {
+    ReactDOM.preinit(href, { as: 'style', precedence: 'high' })
+  }
+
+  if (jsPreloads) {
+    for (const href of jsPreloads) {
+      ReactDOM.preloadModule(href)
+    }
+  }
+
+  return (
+    <>
+      <Suspense fallback={<EmptyFallback />}>
+        <RscNodeRenderInner getTree={getTree} path={path} />
+      </Suspense>
+    </>
+  )
+}

package/src/ServerComponentTypes.ts

@@ -0,0 +1,226 @@
+import type {
+  Constrain,
+  LooseAsyncReturnType,
+  LooseReturnType,
+  ValidateSerializable,
+} from '@tanstack/router-core'
+import type { ComponentProps, ComponentType } from 'react'
+
+export interface ServerComponentStream {
+  createReplayStream: () => ReadableStream<Uint8Array>
+}
+
+// Symbol to attach stream to component for serialization
+export const SERVER_COMPONENT_STREAM = Symbol.for('tanstack.rsc.stream')
+
+// Symbol to attach collected CSS hrefs to component
+export const SERVER_COMPONENT_CSS_HREFS = Symbol.for('tanstack.rsc.cssHrefs')
+
+// Symbol to attach collected JS modulepreload hrefs to component
+export const SERVER_COMPONENT_JS_PRELOADS = Symbol.for(
+  'tanstack.rsc.jsPreloads',
+)
+
+// Symbol to attach a nested selection path to the RSC data proxy
+export const RSC_PROXY_PATH = Symbol.for('tanstack.rsc.path')
+
+// Symbol to attach the root tree getter to every nested proxy
+export const RSC_PROXY_GET_TREE = Symbol.for('tanstack.rsc.getTree')
+
+// Symbol to mark a proxy as "renderable" (for renderServerComponent output)
+// When true: from renderServerComponent (directly renderable)
+// When false/undefined: from createCompositeComponent (needs <CompositeComponent src={...} />)
+export const RENDERABLE_RSC = Symbol.for('tanstack.rsc.renderable')
+
+// Dev-only: collected slot usage data for devtools (client-side cache)
+export const RSC_SLOT_USAGES = Symbol.for('tanstack.rsc.slotUsages')
+
+// Dev-only: stream of slot usage preview events for devtools
+export const RSC_SLOT_USAGES_STREAM = Symbol.for(
+  'tanstack.rsc.slotUsages.stream',
+)
+
+export type RscSlotUsageEvent = {
+  slot: string
+  // Raw args passed to the slot call (must be serializable by the transport)
+  args?: Array<any>
+}
+
+/**
+ * Type guard to check if a value is a ServerComponent (Proxy with attached stream).
+ * The value can be either an object (proxy target) or a function (stub for server functions).
+ */
+export function isServerComponent(
+  value: unknown,
+): value is AnyCompositeComponent {
+  if (value === null || value === undefined) return false
+  if (typeof value !== 'object' && typeof value !== 'function') return false
+  return (
+    SERVER_COMPONENT_STREAM in value &&
+    (value as any)[SERVER_COMPONENT_STREAM] !== undefined
+  )
+}
+
+/**
+ * Type guard to check if a value is a RenderableRsc (renderable proxy from renderServerComponent).
+ * The value can be either an object (proxy target) or a function (stub for server functions).
+ */
+export function isRenderableRsc(value: unknown): boolean {
+  if (value === null || value === undefined) return false
+  if (typeof value !== 'object' && typeof value !== 'function') return false
+  return RENDERABLE_RSC in value && (value as any)[RENDERABLE_RSC] === true
+}
+
+export type ValidateCompositeComponent<TComp> = Constrain<
+  TComp,
+  (
+    props: ValidateCompositeComponentProps<TComp>,
+  ) => ValidateCompositeComponentReturnType<TComp>
+>
+
+export type ValidateCompositeComponentProps<TComp> = unknown extends TComp
+  ? TComp
+  : ValidateCompositeComponentPropsObject<CompositeComponentProps<TComp>>
+
+export type ValidateCompositeComponentPropsObject<TProps> =
+  unknown extends TProps
+    ? TProps
+    : {
+        [TKey in keyof TProps]: ValidateCompositeComponentProp<TProps[TKey]>
+      }
+
+export type CompositeComponentProps<TComp> = TComp extends (
+  props: infer TProps,
+) => any
+  ? TProps
+  : unknown
+
+export type ValidateCompositeComponentProp<TProp> = TProp extends (
+  ...args: Array<any>
+) => any
+  ? (...args: ValidateReactSerializable<Parameters<TProp>>) => React.ReactNode
+  : TProp extends ComponentType<any>
+    ? ComponentType<ValidateReactSerializable<ComponentProps<TProp>>>
+    : TProp extends React.ReactNode
+      ? TProp
+      : React.ReactNode
+
+export type ValidateReactSerializable<T> = ValidateSerializable<
+  T,
+  ReactSerializable
+>
+
+export type ReactSerializable =
+  | number
+  | string
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | React.ReactNode
+
+export type ValidateCompositeComponentReturnType<TComp> = unknown extends TComp
+  ? React.ReactNode
+  : ValidateCompositeComponentResult<LooseReturnType<TComp>>
+
+export type ValidateCompositeComponentResult<TNode> =
+  ValidateServerComponentResult<TNode>
+
+export type ValidateServerComponentResult<TNode> =
+  TNode extends Promise<any>
+    ? ValidateCompositeComponentPromiseResult<TNode>
+    : TNode extends React.ReactNode
+      ? TNode
+      : TNode extends (...args: Array<any>) => any
+        ? React.ReactNode
+        : TNode extends object
+          ? ValidateCompositeComponentObjectResult<TNode>
+          : React.ReactNode
+
+export type ValidateCompositeComponentPromiseResult<TPromise> =
+  TPromise extends Promise<infer T>
+    ? Promise<ValidateCompositeComponentResult<T>>
+    : never
+
+export type ValidateCompositeComponentObjectResult<TObject> = {
+  [TKey in keyof TObject]: ValidateCompositeComponentResult<TObject[TKey]>
+}
+
+export type CompositeComponentResult<TComp> = CompositeComponentBuilder<
+  TComp,
+  LooseAsyncReturnType<TComp>
+>
+
+export type CompositeComponentBuilder<TComp, TReturn> =
+  TReturn extends React.ReactNode
+    ? CompositeComponent<TComp, TReturn>
+    : {
+        [TKey in keyof TReturn]: CompositeComponentBuilder<TComp, TReturn[TKey]>
+      }
+
+export interface CompositeComponent<in out TComp, in out TReturn> {
+  '~types': {
+    props: CompositeComponentProps<TComp>
+    return: TReturn
+  }
+
+  [SERVER_COMPONENT_STREAM]?: ServerComponentStream
+
+  /**
+   * Root decoded tree getter.
+   */
+  [RSC_PROXY_GET_TREE]?: () => unknown
+  /**
+   * Nested selection path (eg ['content','Stats']).
+   * Used by <CompositeComponent/> to render a sub-tree.
+   */
+  [RSC_PROXY_PATH]?: Array<string>
+  /**
+   * CSS hrefs collected from the RSC stream.
+   * Can be used for preloading in <head> or emitting 103 Early Hints.
+   */
+  [SERVER_COMPONENT_CSS_HREFS]?: ReadonlySet<string>
+
+  /**
+   * JS hrefs collected from the RSC stream.
+   * Emitted as modulepreload links only if the decoded tree is rendered in SSR.
+   */
+  [SERVER_COMPONENT_JS_PRELOADS]?: ReadonlySet<string>
+
+  /**
+   * Dev-only: async stream of slot usage preview events.
+   * Used by devtools to show slot names and previewed call args without
+   * buffering/draining the Flight stream.
+   */
+  [RSC_SLOT_USAGES_STREAM]?: ReadableStream<RscSlotUsageEvent>
+}
+
+export type ValidateRenderableServerComponent<TNode> =
+  ValidateServerComponentResult<TNode>
+
+export type RenderableServerComponentBuilder<T> = T extends React.ReactNode
+  ? RenderableServerComponent<T>
+  : { [TKey in keyof T]: RenderableServerComponentBuilder<T[TKey]> }
+
+export type RenderableServerComponent<TNode extends React.ReactNode> = TNode &
+  RenderableServerComponentAttributes<TNode>
+
+export interface RenderableServerComponentAttributes<TNode> {
+  '~types': {
+    node: TNode
+  }
+  [SERVER_COMPONENT_STREAM]: ServerComponentStream
+  [RENDERABLE_RSC]: true
+}
+
+declare module '@tanstack/router-core' {
+  export interface SerializableExtensions {
+    CompositeComponent: AnyCompositeComponent
+    RenderableServerComponent: AnyRenderableServerComponent
+  }
+}
+
+export type AnyCompositeComponent = CompositeComponent<any, any>
+
+export type AnyRenderableServerComponent =
+  RenderableServerComponentAttributes<any>