@khanacademy/wonder-blocks-data 4.0.0 → 5.0.0

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

@@ -11,7 +11,7 @@ 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 InterceptData from "../intercept-data.js";
+import InterceptRequests from "../intercept-requests.js";
 import Data from "../data.js";
 
 describe("Data", () => {
@@ -362,14 +362,11 @@ describe("Data", () => {
 
                     // Act
                     render(
-                        <InterceptData
-                            requestId="ID"
-                            handler={interceptHandler}
-                        >
+                        <InterceptRequests interceptor={interceptHandler}>
                             <Data handler={fakeHandler} requestId="ID">
                                 {fakeChildrenFn}
                             </Data>
-                        </InterceptData>,
+                        </InterceptRequests>,
                     );
 
                     // Assert
@@ -385,14 +382,11 @@ describe("Data", () => {
 
                     // Act
                     render(
-                        <InterceptData
-                            handler={interceptHandler}
-                            requestId="ID"
-                        >
+                        <InterceptRequests interceptor={interceptHandler}>
                             <Data handler={fakeHandler} requestId="ID">
                                 {fakeChildrenFn}
                             </Data>
-                        </InterceptData>,
+                        </InterceptRequests>,
                     );
 
                     // Assert
@@ -662,14 +656,11 @@ describe("Data", () => {
 
                     // Act
                     ReactDOMServer.renderToString(
-                        <InterceptData
-                            handler={interceptedHandler}
-                            requestId="ID"
-                        >
+                        <InterceptRequests interceptor={interceptedHandler}>
                             <Data handler={fakeHandler} requestId="ID">
                                 {fakeChildrenFn}
                             </Data>
-                        </InterceptData>,
+                        </InterceptRequests>,
                     );
 
                     // Assert
@@ -692,14 +683,11 @@ describe("Data", () => {
                     // Act
                     ReactDOMServer.renderToString(
                         <TrackData>
-                            <InterceptData
-                                requestId="ID"
-                                handler={interceptedHandler}
-                            >
+                            <InterceptRequests interceptor={interceptedHandler}>
                                 <Data handler={fakeHandler} requestId="ID">
                                     {fakeChildrenFn}
                                 </Data>
-                            </InterceptData>
+                            </InterceptRequests>
                         </TrackData>,
                     );
 
@@ -817,14 +805,11 @@ describe("Data", () => {
 
                     // Act
                     ReactDOMServer.renderToString(
-                        <InterceptData
-                            handler={interceptHandler}
-                            requestId="ID"
-                        >
+                        <InterceptRequests interceptor={interceptHandler}>
                             <Data handler={fakeHandler} requestId="ID">
                                 {fakeChildrenFn}
                             </Data>
-                        </InterceptData>,
+                        </InterceptRequests>,
                     );
 
                     // Assert

package/src/components/__tests__/intercept-requests.test.js

@@ -0,0 +1,58 @@
+// @flow
+import * as React from "react";
+import {render} from "@testing-library/react";
+
+import InterceptContext from "../intercept-context.js";
+import InterceptRequests from "../intercept-requests.js";
+
+describe("InterceptRequests", () => {
+    afterEach(() => {
+        jest.resetAllMocks();
+    });
+
+    it("should update context with fulfillRequest method", () => {
+        // Arrange
+        const fakeHandler = (requestId): Promise<string> =>
+            Promise.resolve("data");
+        const props = {
+            interceptor: fakeHandler,
+        };
+        const captureContextFn = jest.fn();
+
+        // Act
+        render(
+            <InterceptRequests {...props}>
+                <InterceptContext.Consumer>
+                    {captureContextFn}
+                </InterceptContext.Consumer>
+            </InterceptRequests>,
+        );
+
+        // Assert
+        expect(captureContextFn).toHaveBeenCalledWith([fakeHandler]);
+    });
+
+    it("should override parent InterceptRequests", () => {
+        // Arrange
+        const fakeHandler1 = jest.fn();
+        const fakeHandler2 = jest.fn();
+        const captureContextFn = jest.fn();
+
+        // Act
+        render(
+            <InterceptRequests interceptor={fakeHandler1}>
+                <InterceptRequests interceptor={fakeHandler2}>
+                    <InterceptContext.Consumer>
+                        {captureContextFn}
+                    </InterceptContext.Consumer>
+                </InterceptRequests>
+            </InterceptRequests>,
+        );
+
+        // Assert
+        expect(captureContextFn).toHaveBeenCalledWith([
+            fakeHandler1,
+            fakeHandler2,
+        ]);
+    });
+});

package/src/components/data.js

@@ -3,8 +3,8 @@ import * as React from "react";
 
 import {Server} from "@khanacademy/wonder-blocks-core";
 import {RequestFulfillment} from "../util/request-fulfillment.js";
-import InterceptContext from "./intercept-context.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 type {Result, ValidCacheData} from "../util/types.js";
@@ -80,25 +80,11 @@ const Data = <TData: ValidCacheData>({
     showOldDataWhileLoading,
     alwaysRequestOnHydration,
 }: Props<TData>): React.Node => {
-    // Lookup to see if there's an interceptor for the handler.
-    // If we have one, we need to replace the handler with one that
-    // uses the interceptor.
-    const interceptorMap = React.useContext(InterceptContext);
-
-    // If we have an interceptor, we need to replace the handler with one
-    // that uses the interceptor. This helper function generates a new
-    // handler.
-    const maybeInterceptedHandler = React.useMemo(() => {
-        const interceptor = interceptorMap[requestId];
-        if (interceptor == null) {
-            return handler;
-        }
-        return () => interceptor() ?? handler();
-    }, [handler, interceptorMap, requestId]);
+    const interceptedHandler = useRequestInterception(requestId, handler);
 
     const hydrateResult = useServerEffect(
         requestId,
-        maybeInterceptedHandler,
+        interceptedHandler,
         hydrate,
     );
     const [currentResult, setResult] = React.useState(hydrateResult);
@@ -137,7 +123,7 @@ const Data = <TData: ValidCacheData>({
         // hydrated value.
         let cancel = false;
         RequestFulfillment.Default.fulfill(requestId, {
-            handler: maybeInterceptedHandler,
+            handler: interceptedHandler,
         })
             .then((result) => {
                 if (cancel) {

package/src/components/intercept-context.js

@@ -2,10 +2,9 @@
 import * as React from "react";
 import type {ValidCacheData} from "../util/types.js";
 
-type InterceptContextData = {
-    [id: string]: <TData: ValidCacheData>() => ?Promise<?TData>,
-    ...
-};
+type InterceptContextData = $ReadOnlyArray<
+    (requestId: string) => ?Promise<?ValidCacheData>,
+>;
 
 /**
  * InterceptContext defines a map from request ID to interception methods.
@@ -13,6 +12,6 @@ type InterceptContextData = {
  * INTERNAL USE ONLY
  */
 const InterceptContext: React.Context<InterceptContextData> =
-    React.createContext<InterceptContextData>({});
+    React.createContext<InterceptContextData>([]);
 
 export default InterceptContext;

package/src/components/intercept-requests.js

@@ -0,0 +1,69 @@
+// @flow
+import * as React from "react";
+
+import InterceptContext from "./intercept-context.js";
+
+import type {ValidCacheData} from "../util/types.js";
+
+type Props<TData: ValidCacheData> = {|
+    /**
+     * Called to intercept and possibly handle the request.
+     * If this returns null, the request will be handled by ancestor
+     * any ancestor interceptors, and ultimately, the original request
+     * handler, otherwise, this interceptor is handling the request.
+     *
+     * Interceptors are called in ancestor precedence, with the closest
+     * interceptor ancestor being called first, and the furthest ancestor
+     * being called last.
+     *
+     * Beware: Interceptors do not care about what data they are intercepting,
+     * so make sure to only intercept requests that you recognize from the
+     * identifier.
+     */
+    interceptor: (requestId: string) => ?Promise<?TData>,
+
+    /**
+     * The children to render within this component. Any requests by `Data`
+     * components that use same ID as this component will be intercepted.
+     * If `InterceptRequests` is used within `children`, that interception will
+     * be given a chance to intercept first.
+     */
+    children: React.Node,
+|};
+
+/**
+ * This component provides a mechanism to intercept data requests.
+ * This is for use in testing.
+ *
+ * This component is not recommended for use in production code as it
+ * can prevent predictable functioning of the Wonder Blocks Data framework.
+ * One possible side-effect is that inflight requests from the interceptor could
+ * be picked up by `Data` component requests from outside the children of this
+ * component.
+ *
+ * Interceptions within the same component tree are chained such that the
+ * interceptor closest to the intercepted request is called first, and the
+ * furthest interceptor is called last.
+ */
+const InterceptRequests = <TData: ValidCacheData>({
+    interceptor,
+    children,
+}: Props<TData>): React.Node => {
+    const interceptors = React.useContext(InterceptContext);
+
+    const updatedInterceptors = React.useMemo(
+        // We could build this in reverse order so that our hook that does
+        // the interception didn't have to use reduceRight, but I think it
+        // is easier to think about if we do this in component tree order.
+        () => [...interceptors, interceptor],
+        [interceptors, interceptor],
+    );
+
+    return (
+        <InterceptContext.Provider value={updatedInterceptors}>
+            {children}
+        </InterceptContext.Provider>
+    );
+};
+
+export default InterceptRequests;

package/src/components/{intercept-data.md → intercept-requests.md}

@@ -1,38 +1,41 @@
 When you want to generate tests that check the loading state and
 subsequent loaded state are working correctly for your uses of `Data` you can
-use the `InterceptData` component.
+use the `InterceptRequests` component. You can also use this component to
+register request interceptors for any code that uses the `useRequestInterception`
+hook.
 
-This component takes three props; children to be rendered, the handler of the
-to fulfill the request, and the id of the request that is being intercepted.
+This component takes the children to be rendered, and an interceptor function.
 
-Note that this component is expected to be used only within test cases and
-usually only as a single instance. In flight requests for a given handler
-type can be shared and as such, using `InterceptData` alongside non-intercepted
-`Data` components with the same id can have indeterminate outcomes.
+Note that this component is expected to be used only within test cases or
+stories. Be careful want request IDs are matched to avoid intercepting the
+wrong requests and remember that in-flight requests for a given request ID
+can be shared - which means a bad request ID match could share requests across
+different request IDs..
 
-The `handler` intercept function has the form:
+The `interceptor` intercept function has the form:
 
 ```js static
-() => ?Promise<?TData>;
+(requestId: string) => ?Promise<?TData>;
 ```
 
-If this method returns `null`, the default behavior occurs. This
+If this method returns `null`, then the next interceptor in the chain is
+invoked, ultimately ending with the original handler. This
 means that a request will be made for data via the handler assigned to the
-`Data` component being intercepted.
+`Data` component being intercepted if no interceptor handles the request first.
 
 ```jsx
 import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
 import {View} from "@khanacademy/wonder-blocks-core";
-import {InterceptData, Data} from "@khanacademy/wonder-blocks-data";
+import {InterceptRequests, Data} from "@khanacademy/wonder-blocks-data";
 import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Color from "@khanacademy/wonder-blocks-color";
 import Spacing from "@khanacademy/wonder-blocks-spacing";
 
 const myHandler = () => Promise.reject(new Error("You should not see this!"));
 
-const interceptHandler = () => Promise.resolve("INTERCEPTED DATA!");
+const interceptor = (requestId) => requestId === "INTERCEPT_EXAMPLE" ? Promise.resolve("INTERCEPTED DATA!") : null;
 
-<InterceptData handler={interceptHandler} requestId="INTERCEPT_EXAMPLE">
+<InterceptRequests interceptor={interceptor}>
     <View>
         <Body>This received intercepted data!</Body>
         <Data handler={myHandler} requestId="INTERCEPT_EXAMPLE">
@@ -47,5 +50,5 @@ const interceptHandler = () => Promise.resolve("INTERCEPTED DATA!");
             }}
         </Data>
     </View>
-</InterceptData>
+</InterceptRequests>
 ```

package/src/hooks/__tests__/use-request-interception.test.js

@@ -0,0 +1,255 @@
+// @flow
+import * as React from "react";
+import {renderHook} from "@testing-library/react-hooks";
+import InterceptRequests from "../../components/intercept-requests.js";
+import {useRequestInterception} from "../use-request-interception.js";
+
+describe("#useRequestInterception", () => {
+    it("should return a function", () => {
+        // Arrange
+
+        // Act
+        const {
+            result: {current: result},
+        } = renderHook(() => useRequestInterception("ID", jest.fn()));
+
+        // Assert
+        expect(result).toBeInstanceOf(Function);
+    });
+
+    it("should return the same function if the arguments and context don't change", () => {
+        // Arrange
+        const handler = jest.fn();
+
+        // Act
+        const wrapper = renderHook(() => useRequestInterception("ID", handler));
+        const result1 = wrapper.result.current;
+        wrapper.rerender();
+        const result2 = wrapper.result.current;
+
+        // Assert
+        expect(result1).toBe(result2);
+    });
+
+    it("should return a new function if the requestId changes", () => {
+        // Arrange
+        const handler = jest.fn();
+
+        // Act
+        const wrapper = renderHook(
+            ({requestId}) => useRequestInterception(requestId, handler),
+            {initialProps: {requestId: "ID"}},
+        );
+        const result1 = wrapper.result.current;
+        wrapper.rerender({requestId: "ID2"});
+        const result2 = wrapper.result.current;
+
+        // Assert
+        expect(result1).not.toBe(result2);
+    });
+
+    it("should return a new function if the handler changes", () => {
+        // Arrange
+
+        // Act
+        const wrapper = renderHook(
+            ({handler}) => useRequestInterception("ID", handler),
+            {initialProps: {handler: jest.fn()}},
+        );
+        const result1 = wrapper.result.current;
+        wrapper.rerender({handler: jest.fn()});
+        const result2 = wrapper.result.current;
+
+        // Assert
+        expect(result1).not.toBe(result2);
+    });
+
+    it("should return a new function if the context changes", () => {
+        // Arrange
+        const handler = jest.fn();
+        const interceptor1 = jest.fn();
+        const interceptor2 = jest.fn();
+        const Wrapper = ({children, interceptor}: any) => (
+            <InterceptRequests interceptor={interceptor}>
+                {children}
+            </InterceptRequests>
+        );
+
+        // Act
+        const wrapper = renderHook(
+            () => useRequestInterception("ID", handler),
+            {wrapper: Wrapper, initialProps: {interceptor: interceptor1}},
+        );
+        const result1 = wrapper.result.current;
+        wrapper.rerender({wrapper: Wrapper, interceptor: interceptor2});
+        const result2 = wrapper.result.current;
+
+        // Assert
+        expect(result1).not.toBe(result2);
+    });
+
+    describe("returned function", () => {
+        it("should invoke the original handler when there are no interceptors", () => {
+            // Arrange
+            const handler = jest.fn();
+            const requestId = "ID";
+            const {
+                result: {current: interceptedHandler},
+            } = renderHook(() => useRequestInterception(requestId, handler));
+
+            // Act
+            interceptedHandler();
+
+            // Assert
+            expect(handler).toHaveBeenCalledTimes(1);
+        });
+
+        it("should invoke interceptors nearest to furthest", () => {
+            // Arrange
+            const handler = jest.fn();
+            const interceptorFurthest = jest.fn(() => null);
+            const interceptorNearest = jest.fn(() => null);
+            const Wrapper = ({children}: any) => (
+                <InterceptRequests interceptor={interceptorFurthest}>
+                    <InterceptRequests interceptor={interceptorNearest}>
+                        {children}
+                    </InterceptRequests>
+                </InterceptRequests>
+            );
+            const {
+                result: {current: interceptedHandler},
+            } = renderHook(() => useRequestInterception("ID", handler), {
+                wrapper: Wrapper,
+            });
+
+            // Act
+            interceptedHandler();
+
+            // Assert
+            expect(interceptorNearest).toHaveBeenCalledBefore(
+                interceptorFurthest,
+            );
+        });
+
+        it("should invoke the handler last", () => {
+            // Arrange
+            const handler = jest.fn();
+            const interceptorFurthest = jest.fn(() => null);
+            const interceptorNearest = jest.fn(() => null);
+            const Wrapper = ({children}: any) => (
+                <InterceptRequests interceptor={interceptorFurthest}>
+                    <InterceptRequests interceptor={interceptorNearest}>
+                        {children}
+                    </InterceptRequests>
+                </InterceptRequests>
+            );
+            const {
+                result: {current: interceptedHandler},
+            } = renderHook(() => useRequestInterception("ID", handler), {
+                wrapper: Wrapper,
+            });
+
+            // Act
+            interceptedHandler();
+
+            // Assert
+            expect(interceptorFurthest).toHaveBeenCalledBefore(handler);
+        });
+
+        it("should invoke the original handler when there all interceptors return null", () => {
+            // Arrange
+            const handler = jest.fn();
+            const interceptor1 = jest.fn(() => null);
+            const interceptor2 = jest.fn(() => null);
+            const Wrapper = ({children}: any) => (
+                <InterceptRequests interceptor={interceptor1}>
+                    <InterceptRequests interceptor={interceptor2}>
+                        {children}
+                    </InterceptRequests>
+                </InterceptRequests>
+            );
+            const {
+                result: {current: interceptedHandler},
+            } = renderHook(() => useRequestInterception("ID", handler), {
+                wrapper: Wrapper,
+            });
+
+            // Act
+            interceptedHandler();
+
+            // Assert
+            expect(handler).toHaveBeenCalledTimes(1);
+        });
+
+        it("should return the result of the nearest interceptor that returns a non-null result", async () => {
+            // Arrange
+            const handler = jest
+                .fn()
+                .mockRejectedValue(
+                    new Error("This handler should have been intercepted"),
+                );
+            const interceptorFurthest = jest
+                .fn()
+                .mockRejectedValue(
+                    new Error("This interceptor should not get called"),
+                );
+            const interceptorNearest = jest
+                .fn()
+                .mockResolvedValue("INTERCEPTED_DATA");
+            const Wrapper = ({children}: any) => (
+                <InterceptRequests interceptor={interceptorFurthest}>
+                    <InterceptRequests interceptor={interceptorNearest}>
+                        {children}
+                    </InterceptRequests>
+                </InterceptRequests>
+            );
+            const {
+                result: {current: interceptedHandler},
+            } = renderHook(() => useRequestInterception("ID", handler), {
+                wrapper: Wrapper,
+            });
+
+            // Act
+            const result = await interceptedHandler();
+
+            // Assert
+            expect(result).toBe("INTERCEPTED_DATA");
+        });
+
+        it("should not invoke interceptors or handlers beyond a non-null interception", () => {
+            // Arrange
+            const handler = jest
+                .fn()
+                .mockRejectedValue(
+                    new Error("This handler should have been intercepted"),
+                );
+            const interceptorFurthest = jest
+                .fn()
+                .mockRejectedValue(
+                    new Error("This interceptor should not get called"),
+                );
+            const interceptorNearest = jest
+                .fn()
+                .mockResolvedValue("INTERCEPTED_DATA");
+            const Wrapper = ({children}: any) => (
+                <InterceptRequests interceptor={interceptorFurthest}>
+                    <InterceptRequests interceptor={interceptorNearest}>
+                        {children}
+                    </InterceptRequests>
+                </InterceptRequests>
+            );
+            const {
+                result: {current: interceptedHandler},
+            } = renderHook(() => useRequestInterception("ID", handler), {
+                wrapper: Wrapper,
+            });
+
+            // Act
+            interceptedHandler();
+
+            // Assert
+            expect(handler).not.toHaveBeenCalled();
+            expect(interceptorFurthest).not.toHaveBeenCalled();
+        });
+    });
+});

package/src/hooks/use-request-interception.js

@@ -0,0 +1,54 @@
+// @flow
+import * as React from "react";
+
+import InterceptContext from "../components/intercept-context.js";
+import type {ValidCacheData} from "../util/types.js";
+
+/**
+ * Allow request handling to be intercepted.
+ *
+ * Hook to take a uniquely identified request handler and return a
+ * method that will support request interception from the InterceptRequest
+ * component.
+ *
+ * If you want request interception to be supported with `useServerEffect` or
+ * any client-side effect that uses the handler, call this first to generate
+ * an intercepted handler, and then invoke `useServerEffect` (or other things)
+ * with that intercepted handler.
+ */
+export const useRequestInterception = <TData: ValidCacheData>(
+    requestId: string,
+    handler: () => Promise<?TData>,
+): (() => Promise<?TData>) => {
+    // Get the interceptors that have been registered.
+    const interceptors = React.useContext(InterceptContext);
+
+    // Now, we need to create a new handler that will check if the
+    // request is intercepted before ultimately calling the original handler
+    // if nothing intercepted it.
+    // We memoize this so that it only changes if something related to it
+    // changes.
+    const interceptedHandler = React.useMemo(
+        () => (): Promise<?TData> => {
+            // Call the interceptors from closest to furthest.
+            // If one returns a non-null result, then we keep that.
+            const interceptResponse = interceptors.reduceRight(
+                (prev, interceptor) => {
+                    if (prev != null) {
+                        return prev;
+                    }
+                    return interceptor(requestId);
+                },
+                null,
+            );
+            // If nothing intercepted this request, invoke the original handler.
+            // NOTE: We can't guarantee all interceptors return the same type
+            // as our handler, so how can flow know? Let's just suppress that.
+            // $FlowFixMe[incompatible-return]
+            return interceptResponse ?? handler();
+        },
+        [handler, interceptors, requestId],
+    );
+
+    return interceptedHandler;
+};