npm - @tanstack/react-start-rsc - Versions diffs - 0.0.0 - Mend

@tanstack/react-start-rsc 0.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (101) hide show

package/dist/esm/ClientSlot.js +19 -0
package/dist/esm/ClientSlot.js.map +1 -0
package/dist/esm/CompositeComponent.js +93 -0
package/dist/esm/CompositeComponent.js.map +1 -0
package/dist/esm/ReplayableStream.js +147 -0
package/dist/esm/ReplayableStream.js.map +1 -0
package/dist/esm/RscNodeRenderer.js +46 -0
package/dist/esm/RscNodeRenderer.js.map +1 -0
package/dist/esm/ServerComponentTypes.js +22 -0
package/dist/esm/ServerComponentTypes.js.map +1 -0
package/dist/esm/SlotContext.js +30 -0
package/dist/esm/SlotContext.js.map +1 -0
package/dist/esm/awaitLazyElements.js +41 -0
package/dist/esm/awaitLazyElements.js.map +1 -0
package/dist/esm/createCompositeComponent.js +205 -0
package/dist/esm/createCompositeComponent.js.map +1 -0
package/dist/esm/createCompositeComponent.stub.js +15 -0
package/dist/esm/createCompositeComponent.stub.js.map +1 -0
package/dist/esm/createRscProxy.js +138 -0
package/dist/esm/createRscProxy.js.map +1 -0
package/dist/esm/createServerComponentFromStream.js +74 -0
package/dist/esm/createServerComponentFromStream.js.map +1 -0
package/dist/esm/entry/rsc.js +21 -0
package/dist/esm/entry/rsc.js.map +1 -0
package/dist/esm/flight.js +56 -0
package/dist/esm/flight.js.map +1 -0
package/dist/esm/flight.rsc.js +2 -0
package/dist/esm/flight.stub.js +15 -0
package/dist/esm/flight.stub.js.map +1 -0
package/dist/esm/index.js +7 -0
package/dist/esm/index.rsc.js +6 -0
package/dist/esm/plugin/vite.js +172 -0
package/dist/esm/plugin/vite.js.map +1 -0
package/dist/esm/reactSymbols.js +8 -0
package/dist/esm/reactSymbols.js.map +1 -0
package/dist/esm/renderServerComponent.js +58 -0
package/dist/esm/renderServerComponent.js.map +1 -0
package/dist/esm/renderServerComponent.stub.js +16 -0
package/dist/esm/renderServerComponent.stub.js.map +1 -0
package/dist/esm/serialization.client.js +21 -0
package/dist/esm/serialization.client.js.map +1 -0
package/dist/esm/serialization.server.js +121 -0
package/dist/esm/serialization.server.js.map +1 -0
package/dist/esm/slotUsageSanitizer.js +33 -0
package/dist/esm/slotUsageSanitizer.js.map +1 -0
package/dist/esm/src/ClientSlot.d.ts +5 -0
package/dist/esm/src/CompositeComponent.d.ts +28 -0
package/dist/esm/src/ReplayableStream.d.ts +76 -0
package/dist/esm/src/RscNodeRenderer.d.ts +7 -0
package/dist/esm/src/ServerComponentTypes.d.ts +99 -0
package/dist/esm/src/SlotContext.d.ts +21 -0
package/dist/esm/src/awaitLazyElements.d.ts +17 -0
package/dist/esm/src/createCompositeComponent.d.ts +32 -0
package/dist/esm/src/createCompositeComponent.stub.d.ts +9 -0
package/dist/esm/src/createRscProxy.d.ts +18 -0
package/dist/esm/src/createServerComponentFromStream.d.ts +24 -0
package/dist/esm/src/entry/rsc.d.ts +7 -0
package/dist/esm/src/flight.d.ts +41 -0
package/dist/esm/src/flight.rsc.d.ts +17 -0
package/dist/esm/src/flight.stub.d.ts +8 -0
package/dist/esm/src/index.d.ts +7 -0
package/dist/esm/src/index.rsc.d.ts +6 -0
package/dist/esm/src/plugin/vite.d.ts +9 -0
package/dist/esm/src/reactSymbols.d.ts +3 -0
package/dist/esm/src/renderServerComponent.d.ts +33 -0
package/dist/esm/src/renderServerComponent.stub.d.ts +9 -0
package/dist/esm/src/rscSsrHandler.d.ts +24 -0
package/dist/esm/src/serialization.client.d.ts +11 -0
package/dist/esm/src/serialization.server.d.ts +10 -0
package/dist/esm/src/slotUsageSanitizer.d.ts +1 -0
package/dist/esm/src/types.d.ts +13 -0
package/dist/plugin/entry/rsc.tsx +23 -0
package/package.json +108 -0
package/src/ClientSlot.tsx +34 -0
package/src/CompositeComponent.tsx +165 -0
package/src/ReplayableStream.ts +249 -0
package/src/RscNodeRenderer.tsx +76 -0
package/src/ServerComponentTypes.ts +226 -0
package/src/SlotContext.tsx +42 -0
package/src/awaitLazyElements.ts +91 -0
package/src/createCompositeComponent.stub.ts +20 -0
package/src/createCompositeComponent.ts +338 -0
package/src/createRscProxy.tsx +294 -0
package/src/createServerComponentFromStream.ts +105 -0
package/src/entry/rsc.tsx +23 -0
package/src/entry/virtual-modules.d.ts +12 -0
package/src/flight.rsc.ts +17 -0
package/src/flight.stub.ts +15 -0
package/src/flight.ts +68 -0
package/src/global.d.ts +75 -0
package/src/index.rsc.ts +25 -0
package/src/index.ts +26 -0
package/src/plugin/vite.ts +241 -0
package/src/reactSymbols.ts +6 -0
package/src/renderServerComponent.stub.ts +26 -0
package/src/renderServerComponent.ts +110 -0
package/src/rscSsrHandler.ts +39 -0
package/src/serialization.client.ts +43 -0
package/src/serialization.server.ts +193 -0
package/src/slotUsageSanitizer.ts +62 -0
package/src/types.ts +15 -0

package/src/SlotContext.tsx ADDED Viewed

@@ -0,0 +1,42 @@
+'use client'
+import { createContext, use } from 'react'
+import type { SlotImplementations } from './types'
+export interface SlotContextValue {
+  implementations: SlotImplementations
+  strict: boolean
+}
+const SlotContext = createContext<SlotContextValue | null>(null)
+/**
+ * Hook to access slot implementations from within ClientSlot.
+ */
+export function useSlotContext(): SlotContextValue | null {
+  return use(SlotContext)
+}
+export interface SlotProviderProps {
+  implementations: SlotImplementations
+  strict?: boolean
+  children?: React.ReactNode
+}
+/**
+ * SlotProvider - makes slot implementations available to ClientSlot components.
+ *
+ * Must wrap the decoded RSC content so that ClientSlot components can
+ * access their slot implementations via React Context.
+ */
+export function SlotProvider({
+  implementations,
+  strict,
+  children,
+}: SlotProviderProps) {
+  return (
+    <SlotContext value={{ implementations, strict: strict ?? false }}>
+      {children}
+    </SlotContext>
+  )
+}

package/src/awaitLazyElements.ts ADDED Viewed

@@ -0,0 +1,91 @@
+import { ReactElement, ReactLazy, ReactSuspense } from './reactSymbols'
+/**
+ * Optional callback for collecting CSS hrefs during tree traversal.
+ * Only called server-side when processing <link rel="stylesheet" data-rsc-css-href>
+ */
+export type CssHrefCollector = (href: string) => void
+/**
+ * Yields pending lazy element payloads from a tree, stopping at Suspense boundaries.
+ * Also collects CSS hrefs from <link rel="stylesheet" data-rsc-css-href> elements.
+ */
+function* findPendingLazyPayloads(
+  obj: unknown,
+  seen = new Set(),
+  cssCollector?: CssHrefCollector,
+): Generator<PromiseLike<unknown>> {
+  if (!obj || typeof obj !== 'object') return
+  if (seen.has(obj)) return
+  seen.add(obj)
+  const el = obj as any
+  // Stop at Suspense boundaries - lazy elements inside are intentionally deferred
+  if (el.$$typeof === ReactElement && el.type === ReactSuspense) {
+    return
+  }
+  // Collect CSS hrefs from <link rel="stylesheet" data-rsc-css-href>
+  // The active RSC bundler adapter injects these for CSS module imports
+  if (
+    el.$$typeof === ReactElement &&
+    el.type === 'link' &&
+    el.props?.rel === 'stylesheet'
+  ) {
+    const cssHref = el.props['data-rsc-css-href'] as string | undefined
+    if (cssHref && cssCollector) {
+      cssCollector(cssHref)
+    }
+  }
+  // Yield pending lazy element payload
+  if (el.$$typeof === ReactLazy) {
+    const payload = el._payload
+    if (
+      payload &&
+      typeof payload === 'object' &&
+      (payload.status === 'pending' || payload.status === 'blocked') &&
+      typeof payload.then === 'function'
+    ) {
+      yield payload
+    }
+  }
+  // Recurse into children
+  if (Array.isArray(obj)) {
+    for (const item of obj) {
+      yield* findPendingLazyPayloads(item, seen, cssCollector)
+    }
+  } else {
+    for (const key of Object.keys(obj)) {
+      if (key !== '_owner' && key !== '_store') {
+        yield* findPendingLazyPayloads(el[key], seen, cssCollector)
+      }
+    }
+  }
+}
+/**
+ * Wait for all lazy elements in a tree to be resolved.
+ * This ensures client component chunks are fully loaded before rendering,
+ * preventing Suspense boundaries from flashing during SWR navigation.
+ *
+ * Also collects CSS hrefs from <link rel="stylesheet" data-rsc-css-href>
+ * elements for preloading in <head>.
+ *
+ * @param tree - The tree to process
+ * @param cssCollector - Optional callback to collect CSS hrefs (server-only)
+ */
+export async function awaitLazyElements(
+  tree: unknown,
+  cssCollector?: CssHrefCollector,
+): Promise<void> {
+  for (const payload of findPendingLazyPayloads(
+    tree,
+    new Set(),
+    cssCollector,
+  )) {
+    await Promise.resolve(payload).catch(() => {})
+  }
+}

package/src/createCompositeComponent.stub.ts ADDED Viewed

@@ -0,0 +1,20 @@
+import type {
+  CompositeComponentResult,
+  ValidateCompositeComponent,
+} from './ServerComponentTypes'
+/**
+ * Client stub for createCompositeComponent.
+ *
+ * This function should never be called at runtime on the client.
+ * It exists only to satisfy bundler imports in client bundles.
+ * The real implementation only runs inside server functions.
+ */
+export function createCompositeComponent<TComp>(
+  _component: ValidateCompositeComponent<TComp>,
+): Promise<CompositeComponentResult<TComp>> {
+  throw new Error(
+    'createCompositeComponent cannot be called on the client. ' +
+      'This function should only be called inside a server function or route loader.',
+  )
+}

package/src/createCompositeComponent.ts ADDED Viewed

@@ -0,0 +1,338 @@
+import { createElement } from 'react'
+import { renderToReadableStream } from 'virtual:tanstack-rsc-runtime'
+import { getRequest } from '@tanstack/start-server-core'
+import { getStartContext } from '@tanstack/start-storage-context'
+import { sanitizeSlotArgs } from './slotUsageSanitizer'
+import { ReplayableStream } from './ReplayableStream'
+import { ClientSlot } from './ClientSlot'
+import {
+  RSC_SLOT_USAGES_STREAM,
+  SERVER_COMPONENT_STREAM,
+} from './ServerComponentTypes'
+import type {
+  AnyCompositeComponent,
+  CompositeComponentResult,
+  RscSlotUsageEvent,
+  ServerComponentStream,
+  ValidateCompositeComponent,
+} from './ServerComponentTypes'
+import './rscSsrHandler' // Import for global declaration side effect
+/**
+ * Creates a composite server component with slot support.
+ *
+ * Supports returning:
+ * - A ReactNode directly
+ * - An object structure with ReactNodes: accessed as `src.Foo`
+ * - Nested structures: accessed as `src.x.Bar`
+ *
+ * Props that are functions become slots - they render as ClientSlot placeholders
+ * in the RSC output, filled in by the consumer with actual implementations.
+ *
+ * The returned value is NOT directly renderable. Use `<CompositeComponent src={...} />`.
+ *
+ * @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 async function createCompositeComponent<TComp>(
+  component: ValidateCompositeComponent<TComp>,
+): Promise<CompositeComponentResult<TComp>> {
+  const isDev = process.env.NODE_ENV === 'development'
+  // Dev-only: stream slot usage events (slot + raw args)
+  const slotUsagesEmitter = isDev
+    ? createReadableStreamEmitter<RscSlotUsageEvent>()
+    : null
+  // Create a wrapper component that will be rendered inside React's Flight context.
+  // This ensures React.cache works properly since the component is called during
+  // renderToReadableStream's render phase, not before it.
+  const { proxy: proxyProps } = createSlotProxy<{}>({
+    onSlotCall: slotUsagesEmitter
+      ? (name, args) => {
+          const sanitizedArgs = sanitizeSlotArgs(args)
+          slotUsagesEmitter.emit({
+            slot: name,
+            args: sanitizedArgs.length ? sanitizedArgs : undefined,
+          })
+        }
+      : undefined,
+  })
+  // Wrapper that renders the user's component inside Flight render context
+  async function ServerComponentWrapper() {
+    return (component as React.FC)(proxyProps)
+  }
+  // Render using createElement so React calls our component during Flight rendering
+  // This is critical for React.cache to work - the component must be invoked
+  // during renderToReadableStream's execution, not before
+  const flightStream = renderToReadableStream(
+    createElement(ServerComponentWrapper),
+  )
+  // Check if this is an SSR request (router) or a direct server function call
+  const ctx = getStartContext({ throwIfNotFound: false })
+  const isRouterRequest = ctx?.handlerType === 'router'
+  const ssrHandler = globalThis.__RSC_SSR__
+  // SSR path: buffer stream for replay, pre-decode for synchronous rendering
+  if (isRouterRequest && ssrHandler) {
+    const signal = getRequest().signal
+    const stream = new ReplayableStream(flightStream, { signal })
+    // Pre-decode during loader phase for synchronous SSR rendering
+    const decoded = await ssrHandler.decode(stream)
+    // For SSR we know decode fully consumed the Flight stream.
+    slotUsagesEmitter?.close()
+    const proxy = ssrHandler.createCompositeProxy(
+      stream,
+      decoded,
+      slotUsagesEmitter?.stream,
+    )
+    return proxy as CompositeComponentResult<TComp>
+  }
+  // Server function call path:
+  // The serialization adapter will stream to the client.
+  const monitoredFlightStream =
+    isDev && slotUsagesEmitter
+      ? wrapReadableStream(flightStream, {
+          onDone: () => {
+            slotUsagesEmitter.close()
+          },
+          onCancel: () => {
+            slotUsagesEmitter.close()
+          },
+          onError: () => {
+            slotUsagesEmitter.close()
+          },
+        })
+      : flightStream
+  return createCompositeHandle(monitoredFlightStream, {
+    slotUsagesStream: slotUsagesEmitter?.stream,
+  }) as CompositeComponentResult<TComp>
+}
+/**
+ * Creates a composite handle for server function responses.
+ * No proxy needed - the client will decode and create its own proxy.
+ */
+function createCompositeHandle(
+  flightStream: ReadableStream<Uint8Array>,
+  options?: {
+    slotUsagesStream?: ReadableStream<RscSlotUsageEvent>
+  },
+): AnyCompositeComponent {
+  // Simple single-use stream wrapper. For server function calls, the stream
+  // is consumed exactly once by the serialization adapter for transport.
+  const streamWrapper: ServerComponentStream = {
+    createReplayStream: () => flightStream,
+  }
+  // Create a stub function with the stream attached for serialization.
+  // This will never be rendered directly - it goes through serialization
+  // which extracts the stream and sends it to the client.
+  const stub = function CompositeComponentStub(): never {
+    throw new Error(
+      'CompositeComponent from server function cannot be rendered on server. ' +
+        'It should be serialized and sent to the client.',
+    )
+  }
+  ;(stub as any)[SERVER_COMPONENT_STREAM] = streamWrapper
+  // Note: RENDERABLE_RSC is not set (or implicitly false), indicating this is a composite component
+  if (options?.slotUsagesStream) {
+    ;(stub as any)[RSC_SLOT_USAGES_STREAM] = options.slotUsagesStream
+  }
+  return stub as unknown as AnyCompositeComponent
+}
+/**
+ * Base slot props type - functions that become ClientSlot placeholders
+ */
+interface SlotPropsBase {
+  [key: string]:
+    | ((...args: Array<any>) => React.ReactNode)
+    | React.ReactNode
+    | undefined
+  children?: React.ReactNode
+}
+interface SlotProxyResult<TSlotProps extends object> {
+  proxy: TSlotProps & SlotPropsBase
+}
+/**
+ * Proxy that turns property access into ClientSlot renders.
+ * Also tracks accessed slot names for devtools.
+ */
+function createSlotProxy<TSlotProps extends object>(options?: {
+  onSlotCall?: (name: string, args: Array<any>) => void
+}): SlotProxyResult<TSlotProps> {
+  const cache = new Map<string, (...args: Array<any>) => React.ReactNode>()
+  const proxy = new Proxy({} as TSlotProps & SlotPropsBase, {
+    get(_target, prop) {
+      if (prop === 'then' || typeof prop !== 'string') return undefined
+      if (prop === 'children') {
+        options?.onSlotCall?.('children', [])
+        return createElement(ClientSlot, { slot: 'children', args: [] })
+      }
+      let fn = cache.get(prop)
+      if (!fn) {
+        fn = (...args: Array<any>) => {
+          options?.onSlotCall?.(prop, args)
+          return createElement(ClientSlot, { slot: prop, args })
+        }
+        cache.set(prop, fn)
+      }
+      return fn
+    },
+  })
+  return {
+    proxy,
+  }
+}
+function createReadableStreamEmitter<T>(): {
+  stream: ReadableStream<T>
+  emit: (value: T) => void
+  close: () => void
+} {
+  let closed = false
+  const queue: Array<T> = []
+  let controller: ReadableStreamDefaultController<T> | null = null
+  const stream = new ReadableStream<T>({
+    start(ctrl) {
+      controller = ctrl
+      for (const value of queue) {
+        try {
+          ctrl.enqueue(value)
+        } catch {
+          // Ignore
+        }
+      }
+      queue.length = 0
+      if (closed) {
+        try {
+          ctrl.close()
+        } catch {
+          // Ignore
+        }
+      }
+    },
+    cancel() {
+      closed = true
+      controller = null
+      queue.length = 0
+    },
+  })
+  const emit = (value: T) => {
+    if (closed) return
+    if (!controller) {
+      queue.push(value)
+      return
+    }
+    try {
+      controller.enqueue(value)
+    } catch {
+      // Ignore
+    }
+  }
+  const close = () => {
+    if (closed) return
+    closed = true
+    if (controller) {
+      try {
+        controller.close()
+      } catch {
+        // Ignore
+      }
+      controller = null
+    }
+  }
+  return { stream, emit, close }
+}
+function wrapReadableStream<T>(
+  source: ReadableStream<T>,
+  handlers: {
+    onDone?: () => void
+    onCancel?: () => void
+    onError?: () => void
+  },
+): ReadableStream<T> {
+  const reader = source.getReader()
+  let finished = false
+  const finish = () => {
+    if (finished) return
+    finished = true
+    handlers.onDone?.()
+    try {
+      reader.releaseLock()
+    } catch {
+      // Ignore
+    }
+  }
+  return new ReadableStream<T>({
+    async pull(controller) {
+      try {
+        const { value, done } = await reader.read()
+        if (done) {
+          controller.close()
+          finish()
+          return
+        }
+        controller.enqueue(value)
+      } catch (err) {
+        try {
+          controller.error(err)
+        } catch {
+          // Ignore
+        }
+        handlers.onError?.()
+        finish()
+      }
+    },
+    async cancel(reason) {
+      handlers.onCancel?.()
+      try {
+        await reader.cancel(reason)
+      } catch {
+        // Ignore
+      }
+      finish()
+    },
+  })
+}