@khanacademy/wonder-blocks-data 5.0.1 → 6.0.0

package/src/components/__tests__/data.test.js

@@ -7,19 +7,29 @@ import {render, act} from "@testing-library/react";
 import * as ReactDOMServer from "react-dom/server";
 import {Server, View} from "@khanacademy/wonder-blocks-core";
 
+import {clearSharedCache} from "../../hooks/use-shared-cache.js";
 import TrackData from "../track-data.js";
 import {RequestFulfillment} from "../../util/request-fulfillment.js";
 import {SsrCache} from "../../util/ssr-cache.js";
 import {RequestTracker} from "../../util/request-tracking.js";
 import InterceptRequests from "../intercept-requests.js";
 import Data from "../data.js";
+import {
+    // TODO(somewhatabstract, FEI-4174): Update eslint-plugin-import when they
+    // have fixed:
+    // https://github.com/import-js/eslint-plugin-import/issues/2073
+    // eslint-disable-next-line import/named
+    WhenClientSide,
+} from "../../hooks/use-hydratable-effect.js";
 
 describe("Data", () => {
     beforeEach(() => {
+        clearSharedCache();
+
         const responseCache = new SsrCache();
         jest.spyOn(SsrCache, "Default", "get").mockReturnValue(responseCache);
         jest.spyOn(RequestFulfillment, "Default", "get").mockReturnValue(
-            new RequestFulfillment(responseCache),
+            new RequestFulfillment(),
         );
         jest.spyOn(RequestTracker, "Default", "get").mockReturnValue(
             new RequestTracker(responseCache),
@@ -35,7 +45,7 @@ describe("Data", () => {
             jest.spyOn(Server, "isServerSide").mockReturnValue(false);
         });
 
-        describe("without cached data", () => {
+        describe("without hydrated data", () => {
             beforeEach(() => {
                 /**
                  * Each of these test cases will not have cached data to be
@@ -107,7 +117,7 @@ describe("Data", () => {
                 expect(fakeHandler).toHaveBeenCalledTimes(1);
             });
 
-            it("should render with an error if the request rejects to an error", async () => {
+            it("should render with an error if the handler request rejects to an error", async () => {
                 // Arrange
                 const fulfillSpy = jest.spyOn(
                     RequestFulfillment.Default,
@@ -122,20 +132,25 @@ describe("Data", () => {
                         {fakeChildrenFn}
                     </Data>,
                 );
+
                 /**
                  * We wait for the fulfillment to resolve.
                  */
-                await act(() => fulfillSpy.mock.results[0].value);
+                await act(() =>
+                    fulfillSpy.mock.results[0].value.catch(() => {
+                        /* do nothing */
+                    }),
+                );
 
                 // Assert
-                expect(fakeChildrenFn).toHaveBeenCalledTimes(2);
-                expect(fakeChildrenFn).toHaveBeenLastCalledWith({
+                expect(fakeChildrenFn).toHaveBeenNthCalledWith(2, {
                     status: "error",
-                    error: "OH NOES!",
+                    error: expect.any(Error),
                 });
+                expect(fakeChildrenFn).toHaveBeenCalledTimes(2);
             });
 
-            it("should render with data if the request resolves with data", async () => {
+            it("should render with data if the handler resolves with data", async () => {
                 // Arrange
                 const fulfillSpy = jest.spyOn(
                     RequestFulfillment.Default,
@@ -164,52 +179,68 @@ describe("Data", () => {
                 });
             });
 
-            it.each`
-                error
-                ${"CATASTROPHE!"}
-                ${new Error("CATASTROPHE!")}
-            `(
-                "should render with an error if the request rejects with $error",
-                async ({error}) => {
-                    // Arrange
-                    const fulfillSpy = jest
-                        .spyOn(RequestFulfillment.Default, "fulfill")
-                        .mockReturnValue(Promise.reject(error));
+            it("should render with aborted if the request rejects with an abort error", async () => {
+                // Arrange
+                const fulfillSpy = jest.spyOn(
+                    RequestFulfillment.Default,
+                    "fulfill",
+                );
 
-                    const fakeHandler = () => Promise.resolve("YAY!");
-                    const fakeChildrenFn = jest.fn(() => null);
-                    const consoleSpy = jest
-                        .spyOn(console, "error")
-                        .mockImplementation(() => {
-                            /* Just to shut it up */
-                        });
+                const abortError = new Error("bang bang, abort!");
+                abortError.name = "AbortError";
+                const fakeHandler = () => Promise.reject(abortError);
+                const fakeChildrenFn = jest.fn(() => null);
 
-                    // Act
-                    render(
-                        <Data handler={fakeHandler} requestId="ID">
-                            {fakeChildrenFn}
-                        </Data>,
-                    );
-                    /**
-                     * We wait for the fulfillment to reject.
-                     */
-                    await act(() =>
-                        fulfillSpy.mock.results[0].value.catch(() => {}),
-                    );
+                // Act
+                render(
+                    <Data handler={fakeHandler} requestId="ID">
+                        {fakeChildrenFn}
+                    </Data>,
+                );
+                /**
+                 * We wait for the fulfillment to resolve.
+                 */
+                await act(() => fulfillSpy.mock.results[0].value);
 
-                    // Assert
-                    expect(fakeChildrenFn).toHaveBeenCalledTimes(2);
-                    expect(fakeChildrenFn).toHaveBeenLastCalledWith({
+                // Assert
+                expect(fakeChildrenFn).toHaveBeenCalledTimes(2);
+                expect(fakeChildrenFn).toHaveBeenLastCalledWith({
+                    status: "aborted",
+                });
+            });
+
+            it("should render with an error if the RequestFulfillment rejects with an error", async () => {
+                // Arrange
+                const fulfillSpy = jest
+                    .spyOn(RequestFulfillment.Default, "fulfill")
+                    .mockResolvedValue({
                         status: "error",
-                        error: "CATASTROPHE!",
+                        error: new Error("CATASTROPHE!"),
                     });
-                    expect(consoleSpy).toHaveBeenCalledWith(
-                        expect.stringMatching(
-                            "Unexpected error occurred during data fulfillment:(?: Error:)? CATASTROPHE!",
-                        ),
-                    );
-                },
-            );
+
+                const fakeHandler = () => Promise.resolve("YAY!");
+                const fakeChildrenFn = jest.fn(() => null);
+
+                // Act
+                render(
+                    <Data handler={fakeHandler} requestId="ID">
+                        {fakeChildrenFn}
+                    </Data>,
+                );
+                /**
+                 * We wait for the fulfillment to reject.
+                 */
+                await act(() =>
+                    fulfillSpy.mock.results[0].value.catch(() => {}),
+                );
+
+                // Assert
+                expect(fakeChildrenFn).toHaveBeenCalledTimes(2);
+                expect(fakeChildrenFn).toHaveBeenLastCalledWith({
+                    status: "error",
+                    error: expect.any(Error),
+                });
+            });
 
             it("should start loading if the id changes and request not cached", async () => {
                 // Arrange
@@ -239,12 +270,13 @@ describe("Data", () => {
                 );
 
                 // Assert
-                // Render 1: Caused by handler changed
-                // Render 2: Caused by result state changing to null
-                expect(fakeChildrenFn).toHaveBeenCalledTimes(2);
+                expect(fakeChildrenFn).toHaveBeenCalledTimes(1);
                 expect(fakeChildrenFn).toHaveBeenLastCalledWith({
                     status: "loading",
                 });
+
+                // We have to do this or testing-library gets very upset.
+                await act(() => fulfillSpy.mock.results[0].value);
             });
 
             it("should ignore resolution of pending handler fulfillment when id changes", async () => {
@@ -319,7 +351,10 @@ describe("Data", () => {
 
             it("should ignore catastrophic request fulfillment when id changes", async () => {
                 // Arrange
-                const catastrophe = Promise.reject("CATASTROPHE!");
+                const catastrophe = Promise.resolve({
+                    status: "error",
+                    error: new Error("CATASTROPHE!"),
+                });
                 jest.spyOn(
                     RequestFulfillment.Default,
                     "fulfill",
@@ -347,12 +382,12 @@ describe("Data", () => {
                 // Assert
                 expect(fakeChildrenFn).not.toHaveBeenCalledWith({
                     status: "error",
-                    error: "CATASTROPHE!",
+                    error: expect.any(Error),
                 });
             });
 
             describe("with data interceptor", () => {
-                it("should request data from interceptor", () => {
+                it("should request data from interceptor", async () => {
                     // Arrange
                     const fakeHandler = jest.fn().mockResolvedValue("data");
                     const fakeChildrenFn = jest.fn(() => null);
@@ -368,13 +403,14 @@ describe("Data", () => {
                             </Data>
                         </InterceptRequests>,
                     );
+                    await act(() => interceptHandler.mock.results[0].value);
 
                     // Assert
                     expect(interceptHandler).toHaveBeenCalledTimes(1);
                     expect(fakeHandler).not.toHaveBeenCalled();
                 });
 
-                it("should invoke handler method if interceptor method returns null", () => {
+                it("should invoke handler method if interceptor method returns null", async () => {
                     // Arrange
                     const fakeHandler = jest.fn().mockResolvedValue("data");
                     const fakeChildrenFn = jest.fn(() => null);
@@ -388,50 +424,15 @@ describe("Data", () => {
                             </Data>
                         </InterceptRequests>,
                     );
+                    await act(() => fakeHandler.mock.results[0].value);
 
                     // Assert
                     expect(interceptHandler).toHaveBeenCalledTimes(1);
                     expect(fakeHandler).toHaveBeenCalledTimes(1);
                 });
             });
-        });
-
-        describe("with cache data", () => {
-            beforeEach(() => {
-                /**
-                 * Each of these test cases will start out with some cached data
-                 * retrieved.
-                 */
-                jest.spyOn(
-                    SsrCache.Default,
-                    "getEntry",
-                    // Fake once because that's how the cache would work,
-                    // deleting the hydrated value as soon as it was used.
-                ).mockReturnValueOnce({
-                    data: "YAY! DATA!",
-                });
-            });
 
-            it("should render first time with the cached data", () => {
-                // Arrange
-                const fakeHandler = () => Promise.resolve("data");
-                const fakeChildrenFn = jest.fn(() => null);
-
-                // Act
-                render(
-                    <Data handler={fakeHandler} requestId="ID">
-                        {fakeChildrenFn}
-                    </Data>,
-                );
-
-                // Assert
-                expect(fakeChildrenFn).toHaveBeenCalledWith({
-                    status: "success",
-                    data: "YAY! DATA!",
-                });
-            });
-
-            it("should retain old data while reloading if showOldDataWhileLoading is true", async () => {
+            it("should retain old data while reloading if retainResultOnChange is true", async () => {
                 // Arrange
                 const response1 = Promise.resolve("data1");
                 const response2 = Promise.resolve("data2");
@@ -443,49 +444,76 @@ describe("Data", () => {
                 const wrapper = render(
                     <Data
                         handler={fakeHandler1}
-                        requestId="ID"
-                        showOldDataWhileLoading={false}
+                        requestId="ID1"
+                        retainResultOnChange={true}
                     >
                         {fakeChildrenFn}
                     </Data>,
                 );
+                fakeChildrenFn.mockClear();
+                await act(() => response1);
                 wrapper.rerender(
                     <Data
                         handler={fakeHandler2}
-                        requestId="ID"
-                        showOldDataWhileLoading={true}
+                        requestId="ID2"
+                        retainResultOnChange={true}
                     >
                         {fakeChildrenFn}
                     </Data>,
                 );
+                await act(() => response2);
 
                 // Assert
                 expect(fakeChildrenFn).not.toHaveBeenCalledWith({
                     status: "loading",
                 });
+                expect(fakeChildrenFn).toHaveBeenCalledWith({
+                    status: "success",
+                    data: "data1",
+                });
+                expect(fakeChildrenFn).toHaveBeenLastCalledWith({
+                    status: "success",
+                    data: "data2",
+                });
             });
+        });
 
-            it("should not request data when alwaysRequestOnHydration is false and cache has a valid data result", () => {
+        describe("with hydrated data", () => {
+            beforeEach(() => {
+                /**
+                 * Each of these test cases will start out with some cached data
+                 * retrieved.
+                 */
+                jest.spyOn(
+                    SsrCache.Default,
+                    "getEntry",
+                    // Fake once because that's how the cache would work,
+                    // deleting the hydrated value as soon as it was used.
+                ).mockReturnValueOnce({
+                    data: "YAY! DATA!",
+                });
+            });
+
+            it("should render first time with the cached data", () => {
                 // Arrange
-                const fakeHandler = jest.fn().mockResolvedValue("data");
+                const fakeHandler = () => Promise.resolve("data");
                 const fakeChildrenFn = jest.fn(() => null);
 
                 // Act
                 render(
-                    <Data
-                        handler={fakeHandler}
-                        requestId="ID"
-                        alwaysRequestOnHydration={false}
-                    >
+                    <Data handler={fakeHandler} requestId="ID">
                         {fakeChildrenFn}
                     </Data>,
                 );
 
                 // Assert
-                expect(fakeHandler).not.toHaveBeenCalled();
+                expect(fakeChildrenFn).toHaveBeenCalledWith({
+                    status: "success",
+                    data: "YAY! DATA!",
+                });
             });
 
-            it("should request data if cached data value is valid but alwaysRequestOnHydration is true", () => {
+            it("should not request data when clientBehavior is WhenClientSide.ExecuteWhenNoSuccessResult and cache has a valid success result", () => {
                 // Arrange
                 const fakeHandler = jest.fn().mockResolvedValue("data");
                 const fakeChildrenFn = jest.fn(() => null);
@@ -495,43 +523,34 @@ describe("Data", () => {
                     <Data
                         handler={fakeHandler}
                         requestId="ID"
-                        alwaysRequestOnHydration={true}
+                        clientBehavior={
+                            WhenClientSide.ExecuteWhenNoSuccessResult
+                        }
                     >
                         {fakeChildrenFn}
                     </Data>,
                 );
 
                 // Assert
-                expect(fakeHandler).toHaveBeenCalledTimes(1);
-            });
-        });
-
-        describe("with cached abort", () => {
-            beforeEach(() => {
-                /**
-                 * Each of these test cases will start out with a cached abort.
-                 */
-                jest.spyOn(
-                    SsrCache.Default,
-                    "getEntry",
-                    // Fake once because that's how the cache would work,
-                    // deleting the hydrated value as soon as it was used.
-                ).mockReturnValueOnce({
-                    data: null,
-                });
+                expect(fakeHandler).not.toHaveBeenCalled();
             });
 
-            it("should request data if cached data value is null (i.e. represents an aborted request)", () => {
+            it("should request data if cached data value is valid but clientBehavior is WhenClientSide.AlwaysExecute is true", async () => {
                 // Arrange
                 const fakeHandler = jest.fn().mockResolvedValue("data");
                 const fakeChildrenFn = jest.fn(() => null);
 
                 // Act
                 render(
-                    <Data handler={fakeHandler} requestId="ID">
+                    <Data
+                        handler={fakeHandler}
+                        requestId="ID"
+                        clientBehavior={WhenClientSide.AlwaysExecute}
+                    >
                         {fakeChildrenFn}
                     </Data>,
                 );
+                await act(() => fakeHandler.mock.results[0].value);
 
                 // Assert
                 expect(fakeHandler).toHaveBeenCalledTimes(1);
@@ -553,7 +572,7 @@ describe("Data", () => {
                 });
             });
 
-            it("should always request data if there's a cached error", () => {
+            it("should always request data if there's a cached error", async () => {
                 // Arrange
                 const fakeHandler = jest.fn().mockResolvedValue("data");
                 const fakeChildrenFn = jest.fn(() => null);
@@ -564,6 +583,8 @@ describe("Data", () => {
                         {fakeChildrenFn}
                     </Data>,
                 );
+                // Have to await the promise in an act to keep TL/R happy.
+                await act(() => fakeHandler.mock.results[0].value);
 
                 // Assert
                 expect(fakeHandler).toHaveBeenCalledTimes(1);
@@ -765,7 +786,7 @@ describe("Data", () => {
                 // Assert
                 expect(fakeChildrenFn).toHaveBeenCalledWith({
                     status: "error",
-                    error: "OH NO! IT GO BOOM",
+                    error: expect.any(Error),
                 });
             });
 

package/src/components/data.js

@@ -1,11 +1,14 @@
 // @flow
 import * as React from "react";
 
-import {Server} from "@khanacademy/wonder-blocks-core";
-import {RequestFulfillment} from "../util/request-fulfillment.js";
-import {useServerEffect} from "../hooks/use-server-effect.js";
-import {useRequestInterception} from "../hooks/use-request-interception.js";
-import {resultFromCachedResponse} from "../util/result-from-cache-response.js";
+import {
+    useHydratableEffect,
+    // TODO(somewhatabstract, FEI-4174): Update eslint-plugin-import when they
+    // have fixed:
+    // https://github.com/import-js/eslint-plugin-import/issues/2073
+    // eslint-disable-next-line import/named
+    WhenClientSide,
+} from "../hooks/use-hydratable-effect.js";
 
 import type {Result, ValidCacheData} from "../util/types.js";
 
@@ -29,18 +32,16 @@ type Props<
      * old handler result may be given. This is not a supported mode of
      * operation.
      */
-    handler: () => Promise<?TData>,
+    handler: () => Promise<TData>,
 
     /**
-     * When true, the result will be hydrated when client-side. Otherwise,
-     * the request will be fulfilled for us in SSR but will be ignored during
-     * hydration. Only set this to false if you know some other mechanism
-     * will be performing hydration (such as if requests are fulfilled by
-     * Apollo Client but you consolidated all SSR requests using WB Data).
+     * How the hook should behave when rendering client-side for the first time.
      *
-     * Defaults to true.
+     * This controls how the hook hydrates and executes when client-side.
+     *
+     * Default is `OnClientRender.ExecuteWhenNoSuccessResult`.
      */
-    hydrate?: boolean,
+    clientBehavior?: WhenClientSide,
 
     /**
      * When true, the children will be rendered with the existing result
@@ -49,15 +50,7 @@ type Props<
      *
      * Defaults to false.
      */
-    showOldDataWhileLoading?: boolean,
-
-    /**
-     * When true, the handler will always be invoked after hydration.
-     * This defaults to false.
-     * NOTE: The request is invoked after hydration if the hydrated result
-     * is an error.
-     */
-    alwaysRequestOnHydration?: boolean,
+    retainResultOnChange?: boolean,
 
     /**
      * A function that will render the content of this component using the
@@ -76,97 +69,14 @@ const Data = <TData: ValidCacheData>({
     requestId,
     handler,
     children,
-    hydrate,
-    showOldDataWhileLoading,
-    alwaysRequestOnHydration,
+    retainResultOnChange = false,
+    clientBehavior = WhenClientSide.ExecuteWhenNoSuccessResult,
 }: Props<TData>): React.Node => {
-    const interceptedHandler = useRequestInterception(requestId, handler);
-
-    const hydrateResult = useServerEffect(
-        requestId,
-        interceptedHandler,
-        hydrate,
-    );
-    const [currentResult, setResult] = React.useState(hydrateResult);
-
-    // Here we make sure the request still occurs client-side as needed.
-    // This is for legacy usage that expects this. Eventually we will want
-    // to deprecate.
-    React.useEffect(() => {
-        // This is here until I can do a better documentation example for
-        // the TrackData docs.
-        // istanbul ignore next
-        if (Server.isServerSide()) {
-            return;
-        }
-
-        // We don't bother with this if we have hydration data and we're not
-        // forcing a request on hydration.
-        // We don't care if these things change after the first render,
-        // so we don't want them in the inputs array.
-        if (!alwaysRequestOnHydration && hydrateResult?.data != null) {
-            return;
-        }
-
-        // If we're not hydrating a result and we're not going to render
-        // with old data until we're loaded, we want to make sure we set our
-        // result to null so that we're in the loading state.
-        if (!showOldDataWhileLoading) {
-            // Mark ourselves as loading.
-            setResult(null);
-        }
-
-        // We aren't server-side, so let's make the request.
-        // We don't need to use our built-in request fulfillment here if we
-        // don't want, but it does mean we'll share inflight requests for the
-        // same ID and the result will be in the same format as the
-        // hydrated value.
-        let cancel = false;
-        RequestFulfillment.Default.fulfill(requestId, {
-            handler: interceptedHandler,
-        })
-            .then((result) => {
-                if (cancel) {
-                    return;
-                }
-                setResult(result);
-                return;
-            })
-            .catch((e) => {
-                if (cancel) {
-                    return;
-                }
-                /**
-                 * We should never get here as errors in fulfillment are part
-                 * of the `then`, but if we do.
-                 */
-                // eslint-disable-next-line no-console
-                console.error(
-                    `Unexpected error occurred during data fulfillment: ${e}`,
-                );
-                setResult({
-                    error: typeof e === "string" ? e : e.message,
-                });
-                return;
-            });
-
-        return () => {
-            cancel = true;
-        };
-        // If the handler changes, we don't care. The ID is what indicates
-        // the request that should be made and folks shouldn't be changing the
-        // handler without changing the ID as well.
-        // In addition, we don't want to include hydrateResult nor
-        // alwaysRequestOnHydration as them changinng after the first pass
-        // is irrelevant.
-        // Finally, we don't want to include showOldDataWhileLoading as that
-        // changing on its own is also not relevant. It only matters if the
-        // request itself changes. All of which is to say that we only
-        // run this effect for the ID changing.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [requestId]);
-
-    return children(resultFromCachedResponse(currentResult));
+    const result = useHydratableEffect(requestId, handler, {
+        retainResultOnChange,
+        clientBehavior,
+    });
+    return children(result);
 };
 
 export default Data;

package/src/components/intercept-requests.js

@@ -20,7 +20,7 @@ type Props<TData: ValidCacheData> = {|
      * so make sure to only intercept requests that you recognize from the
      * identifier.
      */
-    interceptor: (requestId: string) => ?Promise<?TData>,
+    interceptor: (requestId: string) => ?Promise<TData>,
 
     /**
      * The children to render within this component. Any requests by `Data`

package/src/hooks/__tests__/__snapshots__/use-shared-cache.test.js.snap

@@ -1,17 +1,17 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`#useSharedCache should throw if the id is  1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the id is  1`] = `[InvalidInputDataError: id must be a non-empty string]`;
 
-exports[`#useSharedCache should throw if the id is [Function anonymous] 1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the id is [Function anonymous] 1`] = `[InvalidInputDataError: id must be a non-empty string]`;
 
-exports[`#useSharedCache should throw if the id is 5 1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the id is 5 1`] = `[InvalidInputDataError: id must be a non-empty string]`;
 
-exports[`#useSharedCache should throw if the id is null 1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the id is null 1`] = `[InvalidInputDataError: id must be a non-empty string]`;
 
-exports[`#useSharedCache should throw if the scope is  1`] = `[InvalidInputError: scope must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is  1`] = `[InvalidInputDataError: scope must be a non-empty string]`;
 
-exports[`#useSharedCache should throw if the scope is [Function anonymous] 1`] = `[InvalidInputError: scope must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is [Function anonymous] 1`] = `[InvalidInputDataError: scope must be a non-empty string]`;
 
-exports[`#useSharedCache should throw if the scope is 5 1`] = `[InvalidInputError: scope must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is 5 1`] = `[InvalidInputDataError: scope must be a non-empty string]`;
 
-exports[`#useSharedCache should throw if the scope is null 1`] = `[InvalidInputError: scope must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is null 1`] = `[InvalidInputDataError: scope must be a non-empty string]`;