@khanacademy/wonder-blocks-data 3.1.3 → 5.0.1

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

@@ -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 {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, 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.
      */
-    options: TOptions,
+    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.
+     */
+    alwaysRequestOnHydration?: boolean,
 
     /**
      * A function that will render the content of this component using the
@@ -45,10 +72,101 @@ 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 => {
+    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));
 };
+
 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,14 +1,17 @@
 // @flow
 import * as React from "react";
+import type {ValidCacheData} from "../util/types.js";
 
-import type {InterceptContextData} from "../util/types.js";
+type InterceptContextData = $ReadOnlyArray<
+    (requestId: string) => ?Promise<?ValidCacheData>,
+>;
 
 /**
- * InterceptContext defines a map from handler type to interception methods.
+ * InterceptContext defines a map from request ID to interception methods.
  *
  * 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-requests.md

@@ -0,0 +1,54 @@
+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 `InterceptRequests` component. You can also use this component to
+register request interceptors for any code that uses the `useRequestInterception`
+hook.
+
+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 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 `interceptor` intercept function has the form:
+
+```js static
+(requestId: string) => ?Promise<?TData>;
+```
+
+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 if no interceptor handles the request first.
+
+```jsx
+import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
+import {View} from "@khanacademy/wonder-blocks-core";
+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 interceptor = (requestId) => requestId === "INTERCEPT_EXAMPLE" ? Promise.resolve("INTERCEPTED DATA!") : null;
+
+<InterceptRequests interceptor={interceptor}>
+    <View>
+        <Body>This received intercepted data!</Body>
+        <Data handler={myHandler} requestId="INTERCEPT_EXAMPLE">
+            {(result) => {
+                if (result.status !== "success") {
+                    return "If you see this, the example is broken!";
+                }
+
+                return (
+                    <BodyMonospace>{result.data}</BodyMonospace>
+                );
+            }}
+        </Data>
+    </View>
+</InterceptRequests>
+```

package/src/components/track-data.md

@@ -65,19 +65,11 @@ import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Spacing from "@khanacademy/wonder-blocks-spacing";
 import Button from "@khanacademy/wonder-blocks-button";
 import {Server, View} from "@khanacademy/wonder-blocks-core";
-import {Data, TrackData, RequestHandler, fulfillAllDataRequests} from "@khanacademy/wonder-blocks-data";
+import {Data, TrackData, fulfillAllDataRequests} from "@khanacademy/wonder-blocks-data";
 
-class MyPretendHandler extends RequestHandler {
-    constructor() {
-        super("MY_PRETEND_HANDLER");
-    }
-
-    fulfillRequest(options) {
-        return new Promise((resolve, reject) =>
-            setTimeout(() => resolve("DATA!"), 3000),
-        );
-    }
-}
+const myPretendHandler = () => new Promise((resolve, reject) =>
+    setTimeout(() => resolve("DATA!"), 3000),
+);
 
 class Example extends React.Component {
     constructor() {
@@ -87,7 +79,6 @@ class Example extends React.Component {
          * for the scope of this component.
          */
         this.state = {};
-        this._handler = new MyPretendHandler();
     }
 
     static getDerivedStateFromError(error) {
@@ -133,15 +124,16 @@ class Example extends React.Component {
         const data = this.state.data
             ? JSON.stringify(this.state.data, undefined, "  ")
             : "Data requested...";
+
         return (
             <React.Fragment>
                 <Strut size={Spacing.small_12} />
                 <TrackData>
-                    <Data handler={this._handler} options={{}}>
-                        {({loading, data, error}) => (
+                    <Data handler={myPretendHandler} requestId="TRACK_DATA_EXAMPLE">
+                        {(result) => (
                             <View>
-                                <BodyMonospace>{`Loading: ${loading}`}</BodyMonospace>
-                                <BodyMonospace>{`Data: ${JSON.stringify(data)}`}</BodyMonospace>
+                                <BodyMonospace>{`Loading: ${result.status === "loading"}`}</BodyMonospace>
+                                <BodyMonospace>{`Data: ${JSON.stringify(result.data)}`}</BodyMonospace>
                             </View>
                         )}
                     </Data>
@@ -162,12 +154,6 @@ class Example extends React.Component {
                         rendered tree.
                     </Body>
                     <Strut size={Spacing.small_12} />
-                    <Body>
-                        If you click to remount after the data appears, we'll
-                        rerender with the now cached data, and above should
-                        update accordingly.
-                    </Body>
-                    <Strut size={Spacing.small_12} />
                     <BodyMonospace>{data}</BodyMonospace>
                 </View>
             </React.Fragment>

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

@@ -0,0 +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 [Function anonymous] 1`] = `[InvalidInputError: 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 null 1`] = `[InvalidInputError: 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 [Function anonymous] 1`] = `[InvalidInputError: 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 null 1`] = `[InvalidInputError: scope must be a non-empty string]`;

package/src/hooks/__tests__/use-gql.test.js

@@ -80,6 +80,7 @@ describe("#useGql", () => {
                 id: "MyQuery",
             };
             const gqlOpContext = {
+                a: undefined, // This should not get included.
                 b: "overrideB",
             };
             const gqlOpVariables = {