Add component registry timeout configuration

- Introduce a new configuration option `component_registry_timeout` to control the maximum time to wait for client-side component registration
- Update `CallbackRegistry` to handle timeout events and reject pending callbacks
- Add validation for the timeout configuration in the Rails configuration
- Modify client-side startup and page lifecycle to support the new timeout mechanism
- Enhance error handling for unregistered components and stores

Author: AbanoubGhadban

lib/react_on_rails/configuration.rb

@@ -10,6 +10,7 @@ def self.configure
 
   DEFAULT_GENERATED_ASSETS_DIR = File.join(%w[public webpack], Rails.env).freeze
   DEFAULT_REACT_CLIENT_MANIFEST_FILE = "react-client-manifest.json"
+  DEFAULT_COMPONENT_REGISTRY_TIMEOUT = 5000
 
   def self.configuration
     @configuration ||= Configuration.new(
@@ -44,7 +45,11 @@ def self.configuration
       make_generated_server_bundle_the_entrypoint: false,
       defer_generated_component_packs: true,
       # forces the loading of React components
-      force_load: false
+      force_load: false,
+      # Maximum time in milliseconds to wait for client-side component registration after page load.
+      # If exceeded, an error will be thrown for server-side rendered components not registered on the client.
+      # Set to 0 to disable the timeout and wait indefinitely for component registration.
+      component_registry_timeout: DEFAULT_COMPONENT_REGISTRY_TIMEOUT
     )
   end
 
@@ -60,7 +65,7 @@ class Configuration
                   :same_bundle_for_client_and_server, :rendering_props_extension,
                   :make_generated_server_bundle_the_entrypoint,
                   :defer_generated_component_packs, :force_load, :rsc_bundle_js_file,
-                  :react_client_manifest_file
+                  :react_client_manifest_file, :component_registry_timeout
 
     # rubocop:disable Metrics/AbcSize
     def initialize(node_modules_location: nil, server_bundle_js_file: nil, prerender: nil,
@@ -76,7 +81,7 @@ def initialize(node_modules_location: nil, server_bundle_js_file: nil, prerender
                    i18n_dir: nil, i18n_yml_dir: nil, i18n_output_format: nil, i18n_yml_safe_load_options: nil,
                    random_dom_id: nil, server_render_method: nil, rendering_props_extension: nil,
                    components_subdirectory: nil, auto_load_bundle: nil, force_load: nil,
-                   rsc_bundle_js_file: nil, react_client_manifest_file: nil)
+                   rsc_bundle_js_file: nil, react_client_manifest_file: nil, component_registry_timeout: nil)
       self.node_modules_location = node_modules_location.present? ? node_modules_location : Rails.root
       self.generated_assets_dirs = generated_assets_dirs
       self.generated_assets_dir = generated_assets_dir
@@ -100,6 +105,7 @@ def initialize(node_modules_location: nil, server_bundle_js_file: nil, prerender
       self.raise_on_prerender_error = raise_on_prerender_error
       self.skip_display_none = skip_display_none
       self.rendering_props_extension = rendering_props_extension
+      self.component_registry_timeout = component_registry_timeout
 
       # Server rendering:
       self.server_bundle_js_file = server_bundle_js_file
@@ -132,10 +138,19 @@ def setup_config_values
       error_if_using_packer_and_generated_assets_dir_not_match_public_output_path
       # check_deprecated_settings
       adjust_precompile_task
+      check_component_registry_timeout
     end
 
     private
 
+    def check_component_registry_timeout
+      self.component_registry_timeout = DEFAULT_COMPONENT_REGISTRY_TIMEOUT if component_registry_timeout.nil?
+
+      return if component_registry_timeout.is_a?(Integer) && component_registry_timeout >= 0
+
+      raise ReactOnRails::Error, "component_registry_timeout must be a positive integer"
+    end
+
     def check_autobundling_requirements
       raise_missing_components_subdirectory if auto_load_bundle && !components_subdirectory.present?
       return unless components_subdirectory.present?

lib/react_on_rails/helper.rb

@@ -309,6 +309,7 @@ def rails_context(server_side: true)
       # ALERT: Keep in sync with node_package/src/types/index.ts for the properties of RailsContext
       @rails_context ||= begin
         result = {
+          componentRegistryTimeout: ReactOnRails.configuration.component_registry_timeout,
           railsEnv: Rails.env,
           inMailer: in_mailer?,
           # Locale settings

node_package/src/CallbackRegistry.ts

@@ -1,21 +1,65 @@
 import { ItemRegistrationCallback } from "./types";
+import { onPageLoaded, onPageUnloaded } from "./pageLifecycle";
+import { getContextAndRailsContext } from "./context";
 
 export default class CallbackRegistry<T> {
+  private readonly registryType: string;
   private registeredItems = new Map<string, T>();
-  private callbacks = new Map<string, Array<ItemRegistrationCallback<T>>>();
+  private callbacks = new Map<string, Array<{
+    resolve: ItemRegistrationCallback<T>;
+    reject: (error: Error) => void;
+  }>>();
+
+  private timoutEventsInitialized = false;
+  private timedout = false;
+
+  constructor(registryType: string) {
+    this.registryType = registryType;
+    this.initializeTimeoutEvents();
+  }
+
+  private initializeTimeoutEvents() {
+    if (!this.timoutEventsInitialized) {
+      this.timoutEventsInitialized = true;
+    }
+
+    let timeoutId: NodeJS.Timeout;
+    const triggerTimeout = () => {
+      this.timedout = true;
+      this.callbacks.forEach((itemCallbacks, itemName) => {
+        itemCallbacks.forEach((callback) => {
+          callback.reject(this.createNotFoundError(itemName));
+        });
+      });
+    };
+
+    onPageLoaded(() => {
+      const registryTimeout = getContextAndRailsContext().railsContext?.componentRegistryTimeout;
+      if (!registryTimeout) return;
+
+      timeoutId = setTimeout(triggerTimeout, registryTimeout);
+    });
+
+    onPageUnloaded(() => {
+      this.callbacks.clear();
+      this.timedout = false;
+      clearTimeout(timeoutId);
+    });
+  }
 
   set(name: string, item: T): void {
     this.registeredItems.set(name, item);
 
     const callbacks = this.callbacks.get(name) || [];
-    callbacks.forEach(callback => {
-      setTimeout(() => callback(item), 0);
-    });
+    callbacks.forEach(callback => callback.resolve(item));
     this.callbacks.delete(name);
   }
 
-  get(name: string): T | undefined {
-    return this.registeredItems.get(name);
+  get(name: string): T {
+    const item = this.registeredItems.get(name);
+    if (item !== undefined) return item;
+
+    throw this.createNotFoundError(name);
   }
 
   has(name: string): boolean {
@@ -30,21 +74,28 @@ export default class CallbackRegistry<T> {
     return this.registeredItems;
   }
 
-  onItemRegistered(name: string, callback: ItemRegistrationCallback<T>): void {
-    const existingItem = this.registeredItems.get(name);
-    if (existingItem) {
-      setTimeout(() => callback(existingItem), 0);
-      return;
-    }
+  getOrWaitForItem(name: string): Promise<T> {
+    return new Promise((resolve, reject) => {
+      try {
+        resolve(this.get(name));
+      } catch(error) {
+        if (this.timedout) {
+          throw error;
+        }
 
-    const itemCallbacks = this.callbacks.get(name) || [];
-    itemCallbacks.push(callback);
-    this.callbacks.set(name, itemCallbacks);
+        const itemCallbacks = this.callbacks.get(name) || [];
+        itemCallbacks.push({ resolve, reject });
+        this.callbacks.set(name, itemCallbacks);
+      }
+    });
   }
 
-  getOrWaitForItem(name: string): Promise<T> {
-    return new Promise((resolve) => {
-      this.onItemRegistered(name, resolve);
-    });
+  private createNotFoundError(itemName: string): Error {
+    const keys = Array.from(this.registeredItems.keys()).join(', ');
+    return new Error(
+      `Could not find ${this.registryType} registered with name ${itemName}. ` +
+      `Registered ${this.registryType} names include [ ${keys} ]. ` +
+      `Maybe you forgot to register the ${this.registryType}?`
+    );
   }
 }

node_package/src/ComponentRegistry.ts

@@ -2,26 +2,13 @@ import {
   type RegisteredComponent,
   type ReactComponentOrRenderFunction,
   type RenderFunction,
-  type ItemRegistrationCallback,
 } from './types';
 import isRenderFunction from './isRenderFunction';
 import CallbackRegistry from './CallbackRegistry';
 
-const componentRegistry = new CallbackRegistry<RegisteredComponent>();
+const componentRegistry = new CallbackRegistry<RegisteredComponent>('component');
 
 export default {
-  /**
-   * Register a callback to be called when a specific component is registered
-   * @param componentName Name of the component to watch for
-   * @param callback Function called with the component details when registered
-   */
-  onComponentRegistered(
-    componentName: string,
-    callback: ItemRegistrationCallback<RegisteredComponent>,
-  ): void {
-    componentRegistry.onItemRegistered(componentName, callback);
-  },
-
   /**
    * @param components { component1: component1, component2: component2, etc. }
    */
@@ -53,12 +40,7 @@ export default {
    * @returns { name, component, isRenderFunction, isRenderer }
    */
   get(name: string): RegisteredComponent {
-    const component = componentRegistry.get(name);
-    if (component !== undefined) return component;
-
-    const keys = Array.from(componentRegistry.getAll().keys()).join(', ');
-    throw new Error(`Could not find component registered with name ${name}. \
-Registered component names include [ ${keys} ]. Maybe you forgot to register the component?`);
+    return componentRegistry.get(name);
   },
 
   getOrWaitForComponent(name: string): Promise<RegisteredComponent> {

node_package/src/StoreRegistry.ts

@@ -1,8 +1,8 @@
 import CallbackRegistry from './CallbackRegistry';
-import type { Store, StoreGenerator, ItemRegistrationCallback } from './types';
+import type { Store, StoreGenerator } from './types';
 
-const storeGeneratorRegistry = new CallbackRegistry<StoreGenerator>();
-const hydratedStoreRegistry = new CallbackRegistry<Store>();
+const storeGeneratorRegistry = new CallbackRegistry<StoreGenerator>('store generator');
+const hydratedStoreRegistry = new CallbackRegistry<Store>('hydrated store');
 
 export default {
   /**
@@ -33,28 +33,24 @@ export default {
    * @returns Redux Store, possibly hydrated
    */
   getStore(name: string, throwIfMissing = true): Store | undefined {
-    const store = hydratedStoreRegistry.get(name);
-    if (store) return store;
-
-    const storeKeys = Array.from(hydratedStoreRegistry.getAll().keys()).join(', ');
-
-    if (storeKeys.length === 0) {
-      const msg =
+    try {
+      return hydratedStoreRegistry.get(name);
+    } catch (error) {
+      if (hydratedStoreRegistry.getAll().size === 0) {
+        const msg =
 `There are no stores hydrated and you are requesting the store ${name}.
 This can happen if you are server rendering and either:
 1. You do not call redux_store near the top of your controller action's view (not the layout)
    and before any call to react_component.
 2. You do not render redux_store_hydration_data anywhere on your page.`;
-      throw new Error(msg);
-    }
+        throw new Error(msg);
+      }
 
-    if (throwIfMissing) {
-      console.log('storeKeys', storeKeys);
-      throw new Error(`Could not find hydrated store with name '${name}'. ` +
-        `Hydrated store names include [${storeKeys}].`);
+      if (throwIfMissing) {
+        throw error;
+      }
+      return undefined;
     }
-
-    return undefined;
   },
 
   /**
@@ -63,12 +59,7 @@ This can happen if you are server rendering and either:
    * @returns storeCreator with given name
    */
   getStoreGenerator(name: string): StoreGenerator {
-    const generator = storeGeneratorRegistry.get(name);
-    if (generator) return generator;
-
-    const storeKeys = Array.from(storeGeneratorRegistry.getAll().keys()).join(', ');
-    throw new Error(`Could not find store registered with name '${name}'. Registered store ` +
-      `names include [ ${storeKeys} ]. Maybe you forgot to register the store?`);
+    return storeGeneratorRegistry.get(name);
   },
 
   /**
@@ -103,15 +94,6 @@ This can happen if you are server rendering and either:
     return hydratedStoreRegistry.getAll();
   },
 
-  /**
-   * Register a callback to be called when a specific store is hydrated
-   * @param storeName Name of the store to watch for
-   * @param callback Function called with the store when hydrated
-   */
-  onStoreHydrated(storeName: string, callback: ItemRegistrationCallback<Store>): void {
-    hydratedStoreRegistry.onItemRegistered(storeName, callback);
-  },
-
   /**
    * Used by components to get the hydrated store, waiting for it to be hydrated if necessary.
    * @param name Name of the store to wait for
@@ -121,15 +103,6 @@ This can happen if you are server rendering and either:
     return hydratedStoreRegistry.getOrWaitForItem(name);
   },
 
-  /**
-   * Register a callback to be called when a specific store generator is registered
-   * @param storeName Name of the store generator to watch for
-   * @param callback Function called with the store generator when registered
-   */
-  onStoreGeneratorRegistered(storeName: string, callback: ItemRegistrationCallback<StoreGenerator>): void {
-    storeGeneratorRegistry.onItemRegistered(storeName, callback);
-  },
-
   /**
    * Used by components to get the store generator, waiting for it to be registered if necessary.
    * @param name Name of the store generator to wait for

node_package/src/clientStartup.ts

@@ -41,6 +41,6 @@ export async function clientStartup(context: Context): Promise<void> {
   hydrateForceLoadedStores();
 
   // Other components and stores are rendered and hydrated when the page is fully loaded
-  onPageLoaded(renderOrHydrateAllComponents);
+  onPageLoaded(reactOnRailsPageLoaded);
   onPageUnloaded(reactOnRailsPageUnloaded);
 }

node_package/src/pageLifecycle.ts

@@ -63,6 +63,8 @@ function setupTurbolinksEventListeners(): void {
 
 let isEventListenerInitialized = false;
 function initializePageEventListeners(): void {
+  if (typeof window === 'undefined') return;
+
   if (isEventListenerInitialized) {
     return;
   }