docs: add detailed JSDoc comments for RSC functions and utilities to improve code clarity and maintainability

Author: AbanoubGhadban

node_package/src/RSCPayloadGenerator.ts

@@ -13,12 +13,20 @@ const mapRailsContextToRSCPayloadStreams = new Map<RailsContext, RSCPayloadStrea
 
 const rscPayloadCallbacks = new Map<RailsContext, Array<RSCPayloadCallback>>();
 
-// The RSC payload callbacks must be executed synchronously to maintain proper hydration timing.
-// This ensures that the RSC payload initialization script is injected into the HTML page
-// before the corresponding component's HTML markup appears. This timing is critical because:
-// 1. Client-side components only hydrate after their HTML is present in the page
-// 2. The RSC payload must be available before hydration begins to prevent unnecessary refetching
-// 3. Using setTimeout(callback, 0) would break this synchronization and could lead to hydration issues
+/**
+ * Registers a callback to be executed when RSC payloads are generated.
+ *
+ * This function:
+ * 1. Stores the callback function by railsContext
+ * 2. Immediately executes the callback for any existing streams
+ *
+ * This synchronous execution is critical for preventing hydration race conditions.
+ * It ensures payload array initialization happens before component HTML appears
+ * in the response stream.
+ *
+ * @param railsContext - Context for the current request
+ * @param callback - Function to call when an RSC payload is generated
+ */
 export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCPayloadCallback) => {
   const callbacks = rscPayloadCallbacks.get(railsContext) || [];
   callbacks.push(callback);
@@ -29,6 +37,22 @@ export const onRSCPayloadGenerated = (railsContext: RailsContext, callback: RSCP
   existingStreams.forEach((streamInfo) => callback(streamInfo));
 };
 
+/**
+ * Generates and tracks RSC payloads for server components.
+ *
+ * getRSCPayloadStream:
+ * 1. Calls the global generateRSCPayload function
+ * 2. Tracks streams by railsContext for later injection
+ * 3. Notifies callbacks immediately to enable early payload embedding
+ *
+ * The immediate callback notification is critical for preventing hydration race conditions,
+ * as it ensures the payload array is initialized in the HTML stream before component rendering.
+ *
+ * @param componentName - Name of the server component
+ * @param props - Props for the server component
+ * @param railsContext - Context for the current request
+ * @returns A stream of the RSC payload
+ */
 export const getRSCPayloadStream = async (
   componentName: string,
   props: unknown,

node_package/src/RSCProvider.tsx

@@ -10,6 +10,25 @@ type RSCContextType = {
 
 const RSCContext = React.createContext<RSCContextType | undefined>(undefined);
 
+/**
+ * Creates a provider context for React Server Components.
+ *
+ * RSCProvider is a foundational component that:
+ * 1. Provides caching for server components to prevent redundant requests
+ * 2. Manages the fetching of server components through getComponent
+ * 3. Offers environment-agnostic access to server components
+ *
+ * This factory function accepts an environment-specific getServerComponent implementation,
+ * allowing it to work correctly in both client and server environments.
+ *
+ * @param railsContext - Context for the current request
+ * @param getServerComponent - Environment-specific function for fetching server components
+ * @returns A provider component that wraps children with RSC context
+ *
+ * @important This is an internal function. End users should not use this directly.
+ * Instead, use wrapServerComponentRenderer from 'react-on-rails/wrapServerComponentRenderer/client'
+ * for client-side rendering or 'react-on-rails/wrapServerComponentRenderer/server' for server-side rendering.
+ */
 export const createRSCProvider = ({
   railsContext,
   getServerComponent,
@@ -53,6 +72,25 @@ export const createRSCProvider = ({
   };
 };
 
+/**
+ * Hook to access the RSC context within client components.
+ *
+ * This hook provides access to:
+ * - getCachedComponent: For retrieving already rendered server components
+ * - getComponent: For fetching and rendering server components
+ *
+ * It must be used within a component wrapped by RSCProvider (typically done
+ * automatically by wrapServerComponentRenderer).
+ *
+ * @returns The RSC context containing methods for working with server components
+ * @throws Error if used outside of an RSCProvider
+ *
+ * @example
+ * ```tsx
+ * const { getComponent } = useRSC();
+ * const serverComponent = React.use(getComponent('MyServerComponent', props));
+ * ```
+ */
 export const useRSC = () => {
   const context = React.useContext(RSCContext);
   if (!context) {

node_package/src/RSCRoute.ts

@@ -1,6 +1,28 @@
 import * as React from 'react';
 import { useRSC } from './RSCProvider.tsx';
 
+/**
+ * Renders a React Server Component inside a React Client Component.
+ *
+ * RSCRoute provides a bridge between client and server components, allowing server components
+ * to be directly rendered inside client components. This component:
+ *
+ * 1. During initial SSR - Uses the RSC payload to render the server component and embeds the payload in the page
+ * 2. During hydration - Uses the embedded RSC payload already in the page
+ * 3. During client navigation - Fetches the RSC payload via HTTP
+ *
+ * @example
+ * ```tsx
+ * <RSCRoute componentName="MyServerComponent" componentProps={{ user }} />
+ * ```
+ *
+ * @important Only use for server components whose props change rarely. Frequent prop changes
+ * will cause network requests for each change, impacting performance.
+ *
+ * @important This component expects that the component tree that contains it is wrapped using
+ * wrapServerComponentRenderer from 'react-on-rails/wrapServerComponentRenderer/client' for client-side
+ * rendering or 'react-on-rails/wrapServerComponentRenderer/server' for server-side rendering.
+ */
 export type RSCRouteProps = {
   componentName: string;
   componentProps: unknown;

node_package/src/getReactServerComponent.client.ts

@@ -26,6 +26,20 @@ const createFromFetch = async (fetchPromise: Promise<Response>) => {
   return createFromReadableStream<React.ReactNode>(transformedStream);
 };
 
+/**
+ * Fetches an RSC payload via HTTP request.
+ *
+ * This function:
+ * 1. Serializes the component props
+ * 2. Makes an HTTP request to the RSC payload generation endpoint
+ * 3. Processes the response stream into React elements
+ *
+ * This is used for client-side navigation or when rendering components
+ * that weren't part of the initial server render.
+ *
+ * @param props - Object containing component name, props, and railsContext
+ * @returns A Promise resolving to the rendered React element
+ */
 const fetchRSC = ({ componentName, componentProps, railsContext }: ClientGetReactServerComponentProps) => {
   const propsString = JSON.stringify(componentProps);
   const { rscPayloadGenerationUrl } = railsContext;
@@ -65,12 +79,48 @@ const createRSCStreamFromArray = (payloads: string[]) => {
   return stream;
 };
 
+/**
+ * Creates React elements from preloaded RSC payloads in the page.
+ *
+ * This function:
+ * 1. Creates a ReadableStream from the array of payload chunks
+ * 2. Transforms the stream to handle console logs and other processing
+ * 3. Uses React's createFromReadableStream to process the payload
+ *
+ * This is used during hydration to avoid making HTTP requests when
+ * the payload is already embedded in the page.
+ *
+ * @param payloads - Array of RSC payload chunks from the global array
+ * @returns A Promise resolving to the rendered React element
+ */
 const createFromPreloadedPayloads = (payloads: string[]) => {
   const stream = createRSCStreamFromArray(payloads);
   const transformedStream = transformRSCStreamAndReplayConsoleLogs(stream);
   return createFromReadableStream<React.ReactNode>(transformedStream);
 };
 
+/**
+ * Fetches and renders a server component on the client side.
+ *
+ * This function:
+ * 1. Checks for embedded RSC payloads in window.REACT_ON_RAILS_RSC_PAYLOADS
+ * 2. If found, uses the embedded payload to avoid an HTTP request
+ * 3. If not found (during client navigation or dynamic rendering), fetches via HTTP
+ * 4. Processes the RSC payload into React elements
+ *
+ * The embedded payload approach ensures optimal performance during initial page load,
+ * while the HTTP fallback enables dynamic rendering after navigation.
+ *
+ * @param componentName - Name of the server component to render
+ * @param componentProps - Props to pass to the server component
+ * @param railsContext - Context for the current request
+ * @returns A Promise resolving to the rendered React element
+ *
+ * @important This is an internal function. End users should not use this directly.
+ * Instead, use the useRSC hook which provides getComponent and getCachedComponent functions
+ * for fetching or retrieving cached server components. For rendering server components,
+ * consider using RSCRoute component which handles the rendering logic automatically.
+ */
 const getReactServerComponent = ({
   componentName,
   componentProps,

node_package/src/getReactServerComponent.server.ts

@@ -17,6 +17,21 @@ const createFromReactOnRailsNodeStream = (
   return createFromNodeStream(transformedStream, ssrManifest);
 };
 
+/**
+ * Creates an SSR manifest for React's server components runtime.
+ *
+ * This function:
+ * 1. Loads the server and client component manifests
+ * 2. Creates a mapping between client and server module IDs
+ * 3. Builds a moduleMap structure required by React's SSR runtime
+ *
+ * The manifest allows React to correctly associate server components
+ * with their client counterparts during hydration.
+ *
+ * @param reactServerManifestFileName - Path to the server manifest file
+ * @param reactClientManifestFileName - Path to the client manifest file
+ * @returns A Promise resolving to the SSR manifest object
+ */
 const createSSRManifest = async (
   reactServerManifestFileName: string,
   reactClientManifestFileName: string,
@@ -52,6 +67,29 @@ const createSSRManifest = async (
   return ssrManifest;
 };
 
+/**
+ * Fetches and renders a server component on the server side.
+ *
+ * This function:
+ * 1. Validates the railsContext for required properties
+ * 2. Creates an SSR manifest mapping server and client modules
+ * 3. Gets the RSC payload stream via getRSCPayloadStream
+ * 4. Processes the stream with React's SSR runtime
+ *
+ * During SSR, this function ensures that the RSC payload is both:
+ * - Used to render the server component
+ * - Tracked so it can be embedded in the HTML response
+ *
+ * @param componentName - Name of the server component to render
+ * @param componentProps - Props to pass to the server component
+ * @param railsContext - Context for the current request
+ * @returns A Promise resolving to the rendered React element
+ *
+ * @important This is an internal function. End users should not use this directly.
+ * Instead, use the useRSC hook which provides getComponent and getCachedComponent functions
+ * for fetching or retrieving cached server components. For rendering server components,
+ * consider using RSCRoute component which handles the rendering logic automatically.
+ */
 const getReactServerComponent = async ({
   componentName,
   componentProps,

node_package/src/injectRSCPayload.ts

@@ -30,6 +30,24 @@ function writeChunk(chunk: string, transform: Transform, cacheKey: string) {
   writeScript(`(${cacheKeyJSArray(cacheKey)}).push(${chunk})`, transform);
 }
 
+/**
+ * Embeds RSC payloads into the HTML stream for optimal hydration.
+ *
+ * This function:
+ * 1. Creates a result stream for the combined HTML + RSC payloads
+ * 2. Listens for RSC payload generation via onRSCPayloadGenerated
+ * 3. Initializes global arrays for each payload BEFORE component HTML
+ * 4. Writes each payload chunk as a script tag that pushes to the array
+ * 5. Passes HTML through to the result stream
+ *
+ * The timing of array initialization is critical - it must occur before the
+ * component's HTML to ensure the array exists when client hydration begins.
+ * This prevents unnecessary HTTP requests during hydration.
+ *
+ * @param pipeableHtmlStream - HTML stream from React's renderToPipeableStream
+ * @param railsContext - Context for the current request
+ * @returns A combined stream with embedded RSC payloads
+ */
 export default function injectRSCPayload(
   pipeableHtmlStream: NodeJS.ReadableStream | PipeableStream,
   railsContext: RailsContext,

node_package/src/registerServerComponent/server.rsc.ts

@@ -2,12 +2,12 @@ import ReactOnRails from '../ReactOnRails.client.ts';
 import { ReactComponent, RenderFunction } from '../types/index.ts';
 
 /**
- * Registers React Server Components (RSC) with React on Rails for the RSC bundle.
+ * Registers React Server Components in the RSC bundle.
  *
- * This function handles the registration of components in the RSC bundle context,
- * where components are registered directly into the ComponentRegistry without any
- * additional wrapping. This is different from the server bundle registration,
- * which wraps components with RSCServerRoot.
+ * Unlike the client and server implementations, the RSC bundle registration
+ * directly registers components without any wrapping. This is because the
+ * RSC bundle is responsible for generating the actual RSC payload of server
+ * components, not for rendering or hydrating client components.
  *
  * @param components - Object mapping component names to their implementations
  *

node_package/src/registerServerComponent/server.tsx

@@ -5,15 +5,12 @@ import { ReactComponent, RenderFunction } from '../types/index.ts';
 import wrapServerComponentRenderer from '../wrapServerComponentRenderer/server.tsx';
 
 /**
- * Registers React Server Components (RSC) with React on Rails for the server bundle.
+ * Registers React Server Components for use in server bundles.
  *
- * This function wraps each component with RSCServerRoot, which handles the server-side
- * rendering of React Server Components using pre-generated RSC payloads.
- *
- * The RSCServerRoot component:
- * - Uses pre-generated RSC payloads from the RSC bundle
- * - Builds the rendering tree of the server component
- * - Handles the integration with React's streaming SSR
+ * This function:
+ * 1. Takes server component implementations
+ * 2. Wraps each component with RSCRoute using WrapServerComponentRenderer
+ * 3. Registers the wrapped components with ReactOnRails
  *
  * @param components - Object mapping component names to their implementations
  *

node_package/src/transformRSCNodeStream.ts

@@ -1,5 +1,19 @@
 import { Transform } from 'stream';
 
+/**
+ * Transforms an RSC Node.js stream for server-side processing.
+ *
+ * This utility:
+ * 1. Takes a Node.js ReadableStream of RSC payload chunks
+ * 2. Applies necessary transformations for server-side consumption
+ * 3. Returns a modified stream that works with React's SSR runtime
+ *
+ * This is essential for proper handling of RSC payloads in Node.js
+ * environment during server-side rendering.
+ *
+ * @param stream - The Node.js RSC payload stream
+ * @returns A transformed stream compatible with React's SSR runtime
+ */
 export default function transformRSCStream(stream: NodeJS.ReadableStream): NodeJS.ReadableStream {
   const decoder = new TextDecoder();
   let lastIncompleteChunk = '';

node_package/src/transformRSCStreamAndReplayConsoleLogs.ts

@@ -1,5 +1,19 @@
 import { RSCPayloadChunk } from './types/index.ts';
 
+/**
+ * Transforms an RSC stream and replays console logs on the client.
+ *
+ * This utility:
+ * 1. Takes a ReadableStream of RSC payload chunks
+ * 2. Processes each chunk to extract and replay embedded console logs
+ * 3. Passes through the actual RSC payload data
+ *
+ * This improves debugging by making server-side console logs appear in
+ * the client console, maintaining a seamless development experience.
+ *
+ * @param stream - The RSC payload stream to transform
+ * @returns A transformed stream with console logs extracted and replayed
+ */
 export default function transformRSCStreamAndReplayConsoleLogs(stream: ReadableStream<Uint8Array | string>) {
   return new ReadableStream({
     async start(controller) {