@khanacademy/wonder-blocks-data 4.0.0 → 6.0.0

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 InterceptContext from "./intercept-context.js";
-import {useServerEffect} from "../hooks/use-server-effect.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,111 +69,14 @@ const Data = <TData: ValidCacheData>({
     requestId,
     handler,
     children,
-    hydrate,
-    showOldDataWhileLoading,
-    alwaysRequestOnHydration,
+    retainResultOnChange = false,
+    clientBehavior = WhenClientSide.ExecuteWhenNoSuccessResult,
 }: 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));
+    const result = useHydratableEffect(requestId, handler, {
+        retainResultOnChange,
+        clientBehavior,
+    });
+    return children(result);
 };
 
 export default Data;

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/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]`;