Enhance type safety in RSCClientRoot and RSCPayloadContainer by using RSCPayloadChunk type, and improve documentation for chunk handling and transfer resilience.

Author: AbanoubGhadban

node_package/src/RSCClientRoot.ts

@@ -1,7 +1,5 @@
 'use client';
 
-/* eslint-disable no-underscore-dangle */
-
 import * as React from 'react';
 import * as ReactDOMClient from 'react-dom/client';
 import { createFromReadableStream } from 'react-on-rails-rsc/client';
@@ -17,7 +15,7 @@ if (typeof use !== 'function') {
 
 declare global {
   interface Window {
-    REACT_ON_RAILS_RSC_PAYLOAD: unknown[];
+    REACT_ON_RAILS_RSC_PAYLOAD: RSCPayloadChunk[];
   }
 }
 
@@ -50,14 +48,29 @@ const createRSCStreamFromPage = () => {
       if (typeof window === 'undefined') {
         return;
       }
-      const handleChunk = (chunk: unknown) => {
-        controller.enqueue(chunk as RSCPayloadChunk);
+      const handleChunk = (chunk: RSCPayloadChunk) => {
+        controller.enqueue(chunk);
       };
+
+      // The RSC payload transfer mechanism works in two possible scenarios:
+      // 1. RSCClientRoot executes first:
+      //    - Initializes REACT_ON_RAILS_RSC_PAYLOAD as an empty array
+      //    - Overrides the push function to handle incoming chunks
+      //    - When server scripts run later, they use the overridden push function
+      // 2. Server scripts execute first:
+      //    - Initialize REACT_ON_RAILS_RSC_PAYLOAD as an empty array
+      //    - Buffer RSC payload chunks in the array
+      //    - When RSCClientRoot runs, it reads buffered chunks and overrides push
+      //
+      // Key points:
+      // - The array is never reassigned, ensuring data consistency
+      // - The push function override ensures all chunks are properly handled
+      // - Execution order is irrelevant - both scenarios work correctly
       if (!window.REACT_ON_RAILS_RSC_PAYLOAD) {
         window.REACT_ON_RAILS_RSC_PAYLOAD = [];
       }
       window.REACT_ON_RAILS_RSC_PAYLOAD.forEach(handleChunk);
-      window.REACT_ON_RAILS_RSC_PAYLOAD.push = (...chunks: unknown[]) => {
+      window.REACT_ON_RAILS_RSC_PAYLOAD.push = (...chunks) => {
         chunks.forEach(handleChunk);
         return chunks.length;
       };

node_package/src/RSCPayloadContainer.ts

@@ -18,6 +18,25 @@ function escapeScript(script: string) {
   return script.replace(/<!--/g, '<\\!--').replace(/<\/(script)/gi, '</\\$1');
 }
 
+/**
+ * RSCPayloadContainer is a React component that handles the server-to-client transfer
+ * of React Server Component (RSC) payloads. It works in conjunction with RSCClientRoot
+ * to ensure reliable delivery of RSC chunks.
+ *
+ * How it works:
+ * 1. Receives a NodeJS.ReadableStream containing RSC payload chunks from the server
+ * 2. Creates a series of promises to handle each chunk asynchronously
+ * 3. For each chunk:
+ *    - Creates a script tag that pushes the chunk to window.REACT_ON_RAILS_RSC_PAYLOAD
+ *    - Uses React.use() to handle the async chunk loading
+ *    - Recursively renders the next chunk using Suspense
+ *
+ * The component ensures that:
+ * - Chunks are processed in order
+ * - Server-side console logs are preserved
+ * - The transfer is resilient to network conditions
+ * - The client receives all chunks reliably
+ */
 const RSCPayloadContainer = ({
   chunkIndex,
   getChunkPromise,
@@ -27,6 +46,9 @@ const RSCPayloadContainer = ({
 
   const scriptElement = React.createElement('script', {
     dangerouslySetInnerHTML: {
+      // Ensure the array is never reassigned.
+      // Even at the RSCClientRoot component, the array is assigned
+      // only if it's not already assigned by this script.
       __html: escapeScript(`(self.REACT_ON_RAILS_RSC_PAYLOAD||=[]).push(${chunk.chunk})`),
     },
     key: `script-${chunkIndex}`,

node_package/src/RSCServerRoot.ts

@@ -79,14 +79,14 @@ const RSCServerRoot: RenderFunction = async (
       'serverClientManifestFileName and reactServerClientManifestFileName are required. ' +
         'Please ensure that React Server Component webpack configurations are properly set ' +
         'as stated in the React Server Component tutorial. ' +
-        'Ensure to use "stream_react_component" instead of "react_component" to SSR a server component.',
+        'Make sure to use "stream_react_component" instead of "react_component" to SSR a server component.',
     );
   }
 
   if (typeof generateRSCPayload !== 'function') {
     throw new Error(
       'generateRSCPayload is not defined. Please ensure that you are using at least version 4.0.0 of ' +
-        'React on Rails Pro and the node renderer, and that ReactOnRailsPro.configuration.enable_rsc_support ' +
+        'React on Rails Pro and the Node renderer, and that ReactOnRailsPro.configuration.enable_rsc_support ' +
         'is set to true.',
     );
   }