@khanacademy/wonder-blocks-data 3.2.0 → 4.0.0

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

@@ -5,8 +5,6 @@ import {render} from "@testing-library/react";
 import InterceptContext from "../intercept-context.js";
 import InterceptData from "../intercept-data.js";
 
-import type {IRequestHandler} from "../../util/types.js";
-
 describe("InterceptData", () => {
     afterEach(() => {
         jest.resetAllMocks();
@@ -14,15 +12,10 @@ describe("InterceptData", () => {
 
     it("should update context with fulfillRequest method", () => {
         // Arrange
-        const fakeHandler: IRequestHandler<string, string> = {
-            fulfillRequest: () => Promise.resolve("data"),
-            getKey: (o) => o,
-            type: "MY_HANDLER",
-            hydrate: true,
-        };
+        const fakeHandler = () => Promise.resolve("data");
         const props = {
             handler: fakeHandler,
-            fulfillRequest: jest.fn(),
+            requestId: "ID",
         };
         const captureContextFn = jest.fn();
 
@@ -38,36 +31,21 @@ describe("InterceptData", () => {
         // Assert
         expect(captureContextFn).toHaveBeenCalledWith(
             expect.objectContaining({
-                MY_HANDLER: {
-                    fulfillRequest: props.fulfillRequest,
-                },
+                ID: props.handler,
             }),
         );
     });
 
     it("should override parent InterceptData", () => {
         // Arrange
-        const fakeHandler: IRequestHandler<string, string> = {
-            fulfillRequest: () => Promise.resolve("data"),
-            getKey: (o) => o,
-            type: "MY_HANDLER",
-            cache: null,
-            hydrate: true,
-        };
         const fulfillRequest1Fn = jest.fn();
         const fulfillRequest2Fn = jest.fn();
         const captureContextFn = jest.fn();
 
         // Act
         render(
-            <InterceptData
-                handler={fakeHandler}
-                fulfillRequest={fulfillRequest1Fn}
-            >
-                <InterceptData
-                    handler={fakeHandler}
-                    fulfillRequest={fulfillRequest2Fn}
-                >
+            <InterceptData handler={fulfillRequest1Fn} requestId="ID">
+                <InterceptData handler={fulfillRequest2Fn} requestId="ID">
                     <InterceptContext.Consumer>
                         {captureContextFn}
                     </InterceptContext.Consumer>
@@ -78,9 +56,7 @@ describe("InterceptData", () => {
         // Assert
         expect(captureContextFn).toHaveBeenCalledWith(
             expect.objectContaining({
-                MY_HANDLER: {
-                    fulfillRequest: fulfillRequest2Fn,
-                },
+                ID: fulfillRequest2Fn,
             }),
         );
     });

package/src/components/data.js

@@ -1,36 +1,63 @@
 // @flow
 import * as React from "react";
 
-import {useData} from "../hooks/use-data.js";
+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 {resultFromCachedResponse} from "../util/result-from-cache-response.js";
 
-import type {Result, IRequestHandler, ValidData} from "../util/types.js";
+import type {Result, ValidCacheData} from "../util/types.js";
 
 type Props<
-    /**
-     * The type of options that the handler requires to define a request.
-     */
-    TOptions,
     /**
      * The type of data resolved by the handler's fulfillRequest method.
      */
-    TData,
+    TData: ValidCacheData,
 > = {|
     /**
-     * An `IRequestHandler` instance of the type this component will use to
-     * resolve its requests.
+     * A unique identifier for the request.
+     *
+     * This should not be shared by other uses of this component.
+     */
+    requestId: string,
+
+    /**
+     * This defines how the request is fulfilled.
      *
-     * The framework deduplicates handlers based on their `type` property.
-     * Handlers with the same `type` property are assumed to be the same.
+     * If this is changed without changing the ID, there are cases where the
+     * old handler result may be given. This is not a supported mode of
+     * operation.
      */
-    handler: IRequestHandler<TOptions, TData>,
+    handler: () => Promise<?TData>,
 
     /**
-     * The handler-specific options that define what requestt is to be made.
+     * 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).
      *
-     * Changing these options will only cause the data to update if the key
-     * from `handler.getKey(options)` changes.
+     * Defaults to true.
+     */
+    hydrate?: boolean,
+
+    /**
+     * When true, the children will be rendered with the existing result
+     * until the pending load is completed. Otherwise, the children will be
+     * given a loading state until the request is fulfilled.
+     *
+     * 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.
      */
-    options: TOptions,
+    alwaysRequestOnHydration?: boolean,
 
     /**
      * A function that will render the content of this component using the
@@ -45,10 +72,115 @@ type Props<
  * requirements can be placed in a React application in a manner that will
  * support server-side rendering and efficient caching.
  */
-const Data = <TOptions, TData: ValidData>(
-    props: Props<TOptions, TData>,
-): React.Node => {
-    const data = useData(props.handler, props.options);
-    return props.children(data);
+const Data = <TData: ValidCacheData>({
+    requestId,
+    handler,
+    children,
+    hydrate,
+    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 hydrateResult = useServerEffect(
+        requestId,
+        maybeInterceptedHandler,
+        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: maybeInterceptedHandler,
+        })
+            .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));
 };
+
 export default Data;

package/src/components/data.md

@@ -1,7 +1,7 @@
-The `Data` component is the frontend piece of our data architecture that
-most folks will use. It describes a data requirement in terms of a handler, and
-some options. Handlers must implement the
-`IRequestHandler` interface.
+The `Data` component is the frontend piece of our data architecture.
+It describes a data requirement in terms of a handler and an identifier.
+It also has props to govern hydrate behavior as well as loading and client-side
+request behavior.
 
 The handler is responsible for fulfilling the request when asked to do so.
 
@@ -40,49 +40,30 @@ data or an error, we re-render.
 ```jsx
 import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
 import {View} from "@khanacademy/wonder-blocks-core";
-import {Data, RequestHandler} from "@khanacademy/wonder-blocks-data";
+import {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";
 
-class MyValidHandler extends RequestHandler {
-    constructor() {
-        super("CACHE_MISS_HANDLER_VALID");
-    }
-
-    fulfillRequest(options) {
-        return new Promise((resolve, reject) =>
-            setTimeout(() => resolve("I'm DATA from a request"), 3000),
-        );
-    }
-}
-
-class MyInvalidHandler extends RequestHandler {
-    constructor() {
-        super("CACHE_MISS_HANDLER_ERROR");
-    }
+const myValidHandler = () => new Promise((resolve, reject) =>
+    setTimeout(() => resolve("I'm DATA from a request"), 3000),
+);
 
-    fulfillRequest(options) {
-        return new Promise((resolve, reject) =>
-            setTimeout(() => reject("I'm an ERROR from a request"), 3000),
-        );
-    }
-}
-
-const valid = new MyValidHandler();
-const invalid = new MyInvalidHandler();
+const myInvalidHandler = () => new Promise((resolve, reject) =>
+    setTimeout(() => reject("I'm an ERROR from a request"), 3000),
+);
 
 <View>
     <View>
         <Body>This request will succeed and give us data!</Body>
-        <Data handler={valid} options={{some: "options"}}>
-            {({loading, data}) => {
-                if (loading) {
+        <Data handler={myValidHandler} requestId="VALID">
+            {(result) => {
+                if (result.status === "loading") {
                     return "Loading...";
                 }
 
                 return (
-                    <BodyMonospace>{data}</BodyMonospace>
+                    <BodyMonospace>{result.data}</BodyMonospace>
                 );
             }}
         </Data>
@@ -90,14 +71,14 @@ const invalid = new MyInvalidHandler();
     <Strut size={Spacing.small_12} />
     <View>
         <Body>This request will go boom and give us an error!</Body>
-        <Data handler={invalid} options={{some: "options"}}>
-            {({loading, error}) => {
-                if (loading) {
+        <Data handler={myInvalidHandler} requestId="INVALID">
+            {(result) => {
+                if (result.status === "loading") {
                     return "Loading...";
                 }
 
                 return (
-                    <BodyMonospace style={{color: Color.red}}>ERROR: {error}</BodyMonospace>
+                    <BodyMonospace style={{color: Color.red}}>ERROR: {result.error}</BodyMonospace>
                 );
             }}
         </Data>
@@ -114,49 +95,37 @@ populated using the `initializeCache` method before rendering.
 ```jsx
 import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
 import {View} from "@khanacademy/wonder-blocks-core";
-import {Data, RequestHandler, initializeCache} from "@khanacademy/wonder-blocks-data";
+import {Data, initializeCache} 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";
 
-class MyHandler extends RequestHandler {
-    constructor() {
-        super("CACHE_HIT_HANDLER");
-    }
-
-    /**
-     * fulfillRequest should not get called as we already have data cached.
-     */
-    fulfillRequest(options) {
-        throw new Error(
-            "If you're seeing this error, the examples are broken and data isn't in the cache that should be.",
-        );
-    }
-}
+const myHandler = () => {
+    throw new Error(
+        "If you're seeing this error, the examples are broken and data isn't in the cache that should be.",
+    );
+};
 
-const handler = new MyHandler();
 initializeCache({
-    CACHE_HIT_HANDLER: {
-        DATA: {
-            data: "I'm DATA from the hydration cache"
-        },
-        ERROR: {
-            error: "I'm an ERROR from hydration cache"
-        }
+    DATA: {
+        data: "I'm DATA from the hydration cache"
+    },
+    ERROR: {
+        error: "I'm an ERROR from hydration cache"
     }
 });
 
 <View>
     <View>
         <Body>This cache has data!</Body>
-        <Data handler={handler} options={"DATA"}>
-            {({loading, data}) => {
-                if (loading) {
+        <Data handler={myHandler} requestId="DATA">
+            {(result) => {
+                if (result.status !== "success") {
                     return "If you see this, the example is broken!";
                 }
 
                 return (
-                    <BodyMonospace>{data}</BodyMonospace>
+                    <BodyMonospace>{result.data}</BodyMonospace>
                 );
             }}
         </Data>
@@ -164,14 +133,14 @@ initializeCache({
     <Strut size={Spacing.small_12} />
     <View>
         <Body>This cache has error!</Body>
-        <Data handler={handler} options={"ERROR"}>
-            {({loading, error}) => {
-                if (loading) {
+        <Data handler={myHandler} requestId="ERROR">
+            {(result) => {
+                if (result.status !== "error") {
                     return "If you see this, the example is broken!";
                 }
 
                 return (
-                    <BodyMonospace style={{color: Color.red}}>ERROR: {error}</BodyMonospace>
+                    <BodyMonospace style={{color: Color.red}}>ERROR: {result.error}</BodyMonospace>
                 );
             }}
         </Data>

package/src/components/intercept-context.js

@@ -1,10 +1,14 @@
 // @flow
 import * as React from "react";
+import type {ValidCacheData} from "../util/types.js";
 
-import type {InterceptContextData} from "../util/types.js";
+type InterceptContextData = {
+    [id: string]: <TData: ValidCacheData>() => ?Promise<?TData>,
+    ...
+};
 
 /**
- * InterceptContext defines a map from handler type to interception methods.
+ * InterceptContext defines a map from request ID to interception methods.
  *
  * INTERNAL USE ONLY
  */

package/src/components/intercept-data.js

@@ -3,75 +3,64 @@ import * as React from "react";
 
 import InterceptContext from "./intercept-context.js";
 
-import type {
-    ValidData,
-    IRequestHandler,
-    InterceptFulfillRequestFn,
-} from "../util/types.js";
+import type {ValidCacheData} from "../util/types.js";
 
-type Props<TOptions, TData> = {|
+type Props<TData: ValidCacheData> = {|
     /**
-     * A handler of the type to be intercepted.
+     * The ID of the request to intercept.
      */
-    handler: IRequestHandler<TOptions, TData>,
+    requestId: string,
 
     /**
-     * The children to render within this component. Any requests by `Data`
-     * components that use a handler of the same type as the handler for this
-     * component that are rendered within these children will be intercepted by
-     * this component (unless another `InterceptData` component overrides this
-     * one).
+     * Called to intercept and fulfill the request.
+     * If this returns null, the request will be fulfilled by the
+     * handler of the original request being intercepted.
      */
-    children: React.Node,
+    handler: () => ?Promise<?TData>,
 
     /**
-     * Called to fulfill a request.
-     * If this returns null, the request will be fulfilled by the
-     * handler of the original request being intercepted.
+     * The children to render within this component. Any requests by `Data`
+     * components that use same ID as this component will be intercepted.
+     * (unless another `InterceptData` component overrides this one).
      */
-    fulfillRequest: InterceptFulfillRequestFn<TOptions, TData>,
+    children: React.Node,
 |};
 
 /**
- * This component provides a mechanism to intercept the data requests for the
- * type of a given handler and provide alternative results. This is mostly
- * useful for testing.
+ * 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 of the same handler type from
- * outside the children of this component.
+ * be picked up by `Data` component requests from outside the children of this
+ * component.
  *
  * These components do not chain. If a different `InterceptData` instance is
- * rendered within this one that intercepts the same handler type, then that
+ * rendered within this one that intercepts the same id, then that
  * new instance will replace this interceptor for its children. All methods
  * will be replaced.
  */
-export default class InterceptData<
-    TOptions,
-    TData: ValidData,
-> extends React.Component<Props<TOptions, TData>> {
-    render(): React.Node {
-        return (
-            <InterceptContext.Consumer>
-                {(value) => {
-                    const handlerType = this.props.handler.type;
-                    const interceptor = {
-                        ...value[handlerType],
-                        fulfillRequest: this.props.fulfillRequest,
-                    };
-                    const newValue = {
-                        ...value,
-                        [handlerType]: interceptor,
-                    };
-                    return (
-                        <InterceptContext.Provider value={newValue}>
-                            {this.props.children}
-                        </InterceptContext.Provider>
-                    );
-                }}
-            </InterceptContext.Consumer>
-        );
-    }
-}
+const InterceptData = <TData: ValidCacheData>({
+    requestId,
+    handler,
+    children,
+}: Props<TData>): React.Node => {
+    const interceptMap = React.useContext(InterceptContext);
+
+    const updatedInterceptMap = React.useMemo(
+        () => ({
+            ...interceptMap,
+            [requestId]: handler,
+        }),
+        [interceptMap, requestId, handler],
+    );
+
+    return (
+        <InterceptContext.Provider value={updatedInterceptMap}>
+            {children}
+        </InterceptContext.Provider>
+    );
+};
+
+export default InterceptData;

package/src/components/intercept-data.md

@@ -2,18 +2,18 @@ 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.
 
-This component takes four props; children to be rendered, the handler of the
-type of data requests that are to be intercepted, and a `fulfillRequest`.
+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.
 
 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 handler type can have indeterminate outcomes.
+`Data` components with the same id can have indeterminate outcomes.
 
-The `fulfillRequest` intercept function has the form:
+The `handler` intercept function has the form:
 
 ```js static
-(options: TOptions) => ?Promise<TData>;
+() => ?Promise<?TData>;
 ```
 
 If this method returns `null`, the default behavior occurs. This
@@ -23,40 +23,26 @@ means that a request will be made for data via the handler assigned to the
 ```jsx
 import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
 import {View} from "@khanacademy/wonder-blocks-core";
-import {InterceptData, Data, RequestHandler} from "@khanacademy/wonder-blocks-data";
+import {InterceptData, 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";
 
-class MyHandler extends RequestHandler {
-    constructor() {
-        super("INTERCEPT_DATA_HANDLER1");
-    }
+const myHandler = () => Promise.reject(new Error("You should not see this!"));
 
-    fulfillRequest(options) {
-        return Promise.reject(new Error("You should not see this!"));
-    }
-}
+const interceptHandler = () => Promise.resolve("INTERCEPTED DATA!");
 
-const handler = new MyHandler();
-const fulfillRequestInterceptor = function(options) {
-    if (options === "DATA") {
-        return Promise.resolve("INTERCEPTED DATA!");
-    }
-    return null;
-};
-
-<InterceptData handler={handler} fulfillRequest={fulfillRequestInterceptor}>
+<InterceptData handler={interceptHandler} requestId="INTERCEPT_EXAMPLE">
     <View>
         <Body>This received intercepted data!</Body>
-        <Data handler={handler} options={"DATA"}>
-            {({loading, data}) => {
-                if (loading) {
+        <Data handler={myHandler} requestId="INTERCEPT_EXAMPLE">
+            {(result) => {
+                if (result.status !== "success") {
                     return "If you see this, the example is broken!";
                 }
 
                 return (
-                    <BodyMonospace>{data}</BodyMonospace>
+                    <BodyMonospace>{result.data}</BodyMonospace>
                 );
             }}
         </Data>