feat: add required APIs for react streaming

packages/holocron/__tests__/__snapshots__/index.spec.js.snap

@@ -1,7 +1,44 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+// eslint-disable-next-line jest/no-large-snapshots -- this one is ok to be a bit large
 exports[`public API should not have anything removed 1`] = `
 {
+ "ModuleContext": {
+ "$$typeof": Symbol(react.context),
+ "Consumer": {
+ "$$typeof": Symbol(react.context),
+ "_context": [Circular],
+ },
+ "Provider": {
+ "$$typeof": Symbol(react.provider),
+ "_context": [Circular],
+ },
+ "_currentRenderer": null,
+ "_currentRenderer2": null,
+ "_currentValue": undefined,
+ "_currentValue2": undefined,
+ "_defaultValue": null,
+ "_globalName": null,
+ "_threadCount": 0,
+ },
+ "ReactStreamingContext": {
+ "$$typeof": Symbol(react.context),
+ "Consumer": {
+ "$$typeof": Symbol(react.context),
+ "_context": [Circular],
+ },
+ "Provider": {
+ "$$typeof": Symbol(react.provider),
+ "_context": [Circular],
+ },
+ "_currentRenderer": null,
+ "_currentRenderer2": null,
+ "_currentValue": {},
+ "_currentValue2": {},
+ "_defaultValue": null,
+ "_globalName": null,
+ "_threadCount": 0,
+ },
  "RenderModule": [Function],
  "clearModulesUsingExternals": [Function],
  "composeModules": [Function],
@@ -26,5 +63,6 @@ exports[`public API should not have anything removed 1`] = `
  "registerModule": [Function],
  "setModuleMap": [Function],
  "setRequiredExternalsRegistry": [Function],
+ "useAsyncModuleData": [Function],
 }
 `;

packages/holocron/__tests__/reactStreaming.spec.jsx

@@ -0,0 +1,97 @@
+import React from 'react';
+// eslint-disable-next-line import/no-extraneous-dependencies -- monorepo, this is at the root
+import { renderHook } from '@testing-library/react';
+import { useAsyncModuleData, ReactStreamingContext, ModuleContext } from '../src/reactStreaming';
+
+describe('reactStreaming', () => {
+ it('exports ReactStreamingContext', () => {
+ expect(ReactStreamingContext).toBeDefined();
+ });
+
+ it('exports ModuleContext', () => {
+ expect(ModuleContext).toBeDefined();
+ });
+
+ describe('useAsyncModuleData', () => {
+ // eslint-disable-next-line react/display-name, react/prop-types -- test component
+ const Providers = ({ moduleName, promise, key }) => ({ children }) => (
+ // eslint-disable-next-line react/jsx-no-constructed-context-values -- test component
+ <ReactStreamingContext.Provider value={{ [moduleName]: { [key]: promise } }}>
+ {/* eslint-disable-next-line react/jsx-no-constructed-context-values -- test component */}
+ <ModuleContext.Provider value={{ moduleName }}>
+ {children}
+ </ModuleContext.Provider>
+ </ReactStreamingContext.Provider>
+ );
+ it('should throw a promise if the data is not yet resolved', () => {
+ const key = 'test';
+ const moduleName = 'testModule';
+ const streamedPromise = new Promise(() => {});
+ const { result } = renderHook(() => {
+ try {
+ return useAsyncModuleData(key);
+ } catch (promise) {
+ return promise;
+ }
+ }, {
+ wrapper: Providers({ moduleName, promise: streamedPromise, key }),
+ });
+ expect(result.current).toBe(streamedPromise);
+ });
+
+ it('should return data once the promise is resolved', () => {
+ const key = 'test';
+ const moduleName = 'testModule';
+ let resolve;
+ const streamedPromise = new Promise((res) => { resolve = res; });
+ const { result, rerender } = renderHook(() => {
+ try {
+ return useAsyncModuleData(key);
+ } catch (promise) {
+ return promise;
+ }
+ }, {
+ wrapper: Providers({ moduleName, promise: streamedPromise, key }),
+ });
+ resolve();
+ streamedPromise.data = 'testData';
+ rerender();
+ expect(result.current).toBe('testData');
+ });
+
+ it('should throw an error if the promise is rejected', () => {
+ const key = 'test';
+ const moduleName = 'testModule';
+ let reject;
+ const streamedPromise = new Promise((_, rej) => { reject = rej; });
+ const { result, rerender } = renderHook(() => {
+ try {
+ return useAsyncModuleData(key);
+ } catch (error) {
+ return error;
+ }
+ }, {
+ wrapper: Providers({ moduleName, promise: streamedPromise, key }),
+ });
+ reject();
+ streamedPromise.error = 'testError';
+ rerender();
+ expect(result.current).toBe('testError');
+ });
+ it('should return undefined if there is no promise', () => {
+ const key = 'test';
+ const moduleName = 'testModule';
+ const streamedPromise = undefined;
+ const { result } = renderHook(() => {
+ try {
+ return useAsyncModuleData(key);
+ } catch (promise) {
+ return promise;
+ }
+ }, {
+ wrapper: Providers({ moduleName, promise: streamedPromise, key }),
+ });
+ expect(result.current).toBe(undefined);
+ });
+ });
+});

packages/holocron/src/index.js

@@ -42,6 +42,11 @@ import {
  getRequiredExternalsRegistry,
  setRequiredExternalsRegistry,
 } from './externalRegistry';
+import {
+ ReactStreamingContext,
+ ModuleContext,
+ useAsyncModuleData,
+} from './reactStreaming';
 
 // Public API
 export {
@@ -69,4 +74,8 @@ export {
  setRequiredExternalsRegistry,
  clearModulesUsingExternals,
  getModulesUsingExternals,
+ // Streaming
+ ReactStreamingContext,
+ ModuleContext,
+ useAsyncModuleData,
 };

packages/holocron/src/reactStreaming.js

@@ -0,0 +1,39 @@
+import { createContext, useContext } from 'react';
+
+const ReactStreamingContext = createContext({});
+
+const ModuleContext = createContext();
+
+const useAsyncModuleData = (key) => {
+ const { moduleName } = useContext(ModuleContext);
+ const streamContext = useContext(ReactStreamingContext);
+ const streamedPromise = streamContext[moduleName]?.[key];
+ if (
+ streamedPromise
+ && streamedPromise instanceof Promise
+ && !streamedPromise.data
+ && !streamedPromise.error
+ ) {
+ streamedPromise
+ .then((data) => {
+ streamedPromise.data = data;
+ })
+ .catch((error) => {
+ streamedPromise.error = error;
+ });
+
+ throw streamedPromise;
+ }
+ if (streamedPromise?.error) {
+ // The suspense boundary will re-throw this error to be caught by the nearest error boundary
+ // https://react.dev/reference/react/Suspense#providing-a-fallback-for-server-errors-and-client-only-content
+ throw streamedPromise.error;
+ }
+
+ if (streamedPromise?.data) {
+ return streamedPromise.data;
+ }
+ return undefined;
+};
+
+export { ReactStreamingContext, ModuleContext, useAsyncModuleData };