@khanacademy/wonder-blocks-data 4.0.0 → 6.0.0

package/src/hooks/use-gql.js

@@ -1,9 +1,9 @@
 // @flow
-import {useContext, useMemo} from "react";
+import {useCallback} from "react";
 
-import {GqlRouterContext} from "../util/gql-router-context.js";
+import {mergeGqlContext} from "../util/merge-gql-context.js";
+import {useGqlRouterContext} from "./use-gql-router-context.js";
 import {getGqlDataFromResponse} from "../util/get-gql-data-from-response.js";
-import {GqlError, GqlErrors} from "../util/gql-error.js";
 
 import type {
     GqlContext,
@@ -21,65 +21,35 @@ import type {
  * Values in the partial context given to the returned fetch function will
  * only be included if they have a value other than undefined.
  */
-export const useGql = (): (<TData, TVariables: {...}, TContext: GqlContext>(
+export const useGql = <TContext: GqlContext>(
+    context: Partial<TContext> = ({}: $Shape<TContext>),
+): (<TData, TVariables: {...}>(
     operation: GqlOperation<TData, TVariables>,
     options?: GqlFetchOptions<TVariables, TContext>,
-) => Promise<?TData>) => {
+) => Promise<TData>) => {
     // This hook only works if the `GqlRouter` has been used to setup context.
-    const gqlRouterContext = useContext(GqlRouterContext);
-    if (gqlRouterContext == null) {
-        throw new GqlError("No GqlRouter", GqlErrors.Internal);
-    }
-    const {fetch, defaultContext} = gqlRouterContext;
+    const gqlRouterContext = useGqlRouterContext(context);
 
     // Let's memoize the gqlFetch function we create based off our context.
     // That way, even if the context happens to change, if its values don't
     // we give the same function instance back to our callers instead of
     // making a new one. That then means they can safely use the return value
     // in hooks deps without fear of it triggering extra renders.
-    const gqlFetch = useMemo(
-        () =>
-            <TData, TVariables: {...}, TContext: GqlContext>(
-                operation: GqlOperation<TData, TVariables>,
-                options: GqlFetchOptions<TVariables, TContext> = Object.freeze(
-                    {},
-                ),
-            ) => {
-                const {variables, context = {}} = options;
+    const gqlFetch = useCallback(
+        <TData, TVariables: {...}>(
+            operation: GqlOperation<TData, TVariables>,
+            options: GqlFetchOptions<TVariables, TContext> = Object.freeze({}),
+        ) => {
+            const {fetch, defaultContext} = gqlRouterContext;
+            const {variables, context = {}} = options;
+            const finalContext = mergeGqlContext(defaultContext, context);
 
-                // Let's merge the partial context of the fetch with the
-                // default context. We deliberately don't spread because
-                // spreading would overwrite default context values with
-                // undefined if the partial context includes a value explicitly
-                // set to undefined. Instead, we use a map/reduce of keys.
-                const mergedContext = Object.keys(context).reduce(
-                    (acc, key) => {
-                        if (context[key] !== undefined) {
-                            acc[key] = context[key];
-                        }
-                        return acc;
-                    },
-                    {...defaultContext},
-                );
-
-                // Invoke the fetch and extract the data.
-                return fetch(operation, variables, mergedContext).then(
-                    getGqlDataFromResponse,
-                    (error) => {
-                        // Return null if the request was aborted.
-                        // The only way to detect this reliably, it seems, is to
-                        // check the error name and see if it's "AbortError" (this
-                        // is also what Apollo does).
-                        // Even then, it's reliant on the fetch supporting aborts.
-                        if (error.name === "AbortError") {
-                            return null;
-                        }
-                        // Need to make sure we pass other errors along.
-                        throw error;
-                    },
-                );
-            },
-        [fetch, defaultContext],
+            // Invoke the fetch and extract the data.
+            return fetch(operation, variables, finalContext).then(
+                getGqlDataFromResponse,
+            );
+        },
+        [gqlRouterContext],
     );
     return gqlFetch;
 };

package/src/hooks/use-hydratable-effect.js

@@ -0,0 +1,206 @@
+// @flow
+import * as React from "react";
+
+import {AbortError} from "../util/abort-error.js";
+
+import {useServerEffect} from "./use-server-effect.js";
+import {useSharedCache} from "./use-shared-cache.js";
+import {useCachedEffect} from "./use-cached-effect.js";
+
+import type {Result, ValidCacheData} from "../util/types.js";
+
+/**
+ * Policies to define how a hydratable effect should behave client-side.
+ */
+export enum WhenClientSide {
+    // TODO(somewhatabstract, FEI-4172): Update eslint-plugin-flowtype when
+    // they've fixed https://github.com/gajus/eslint-plugin-flowtype/issues/502
+    /* eslint-disable no-undef */
+    /**
+     * The result from executing the effect server-side will not be hydrated.
+     * The effect will always be executed client-side.
+     *
+     * This should only be used if there is something else that is responsible
+     * for properly hydrating this component (for example, the action invokes
+     * Apollo which manages its own cache to ensure things render properly).
+     */
+    DoNotHydrate,
+
+    /**
+     * The result from executing the effect server-side will be hydrated.
+     * The effect will only execute client-side if there was no result to
+     * be hydrated (i.e. both error and success hydration results prevent the
+     * effect running client-side).
+     */
+    ExecuteWhenNoResult,
+
+    /**
+     * The result from executing the effect server-side will be hydrated.
+     * If the hydrated result is a success result, the effect will not be
+     * executed client-side.
+     * If the hydrated result was not a success result, or there was no
+     * hydrated result, the effect will not be executed.
+     */
+    ExecuteWhenNoSuccessResult,
+
+    /**
+     * The result from executing the effect server-side will be hydrated.
+     * The effect will always be executed client-side, regardless of the
+     * hydrated result status.
+     */
+    AlwaysExecute,
+    /* eslint-enable no-undef */
+}
+
+type HydratableEffectOptions<TData: ValidCacheData> = {|
+    /**
+     * How the hook should behave when rendering client-side for the first time.
+     *
+     * This controls how the hook hydrates and executes when client-side.
+     *
+     * Default is `WhenClientSide.ExecuteWhenNoSuccessResult`.
+     *
+     * Changing this value after the first call is irrelevant as it only
+     * affects the initial render behavior.
+     */
+    clientBehavior?: WhenClientSide,
+
+    /**
+     * When `true`, the effect will not be executed; otherwise, the effect will
+     * be executed.
+     *
+     * If this is set to `true` while the effect is still pending, the pending
+     * effect will be cancelled.
+     *
+     * Default is `false`.
+     */
+    skip?: boolean,
+
+    /**
+     * When `true`, the effect will not reset the result to the loading status
+     * while executing if the requestId changes, instead, returning
+     * the existing result from before the change; otherwise, the result will
+     * be set to loading status.
+     *
+     * If the status is loading when the changes are made, it will remain as
+     * loading; old pending effects are discarded on changes and as such this
+     * value has no effect in that case.
+     */
+    retainResultOnChange?: boolean,
+
+    /**
+     * Callback that is invoked if the result for the given hook has changed.
+     *
+     * When defined, the hook will invoke this callback whenever it has reason
+     * to change the result and will not otherwise affect component rendering
+     * directly.
+     *
+     * When not defined, the hook will ensure the component re-renders to pick
+     * up the latest result.
+     */
+    onResultChanged?: (result: Result<TData>) => void,
+
+    /**
+     * Scope to use with the shared cache.
+     *
+     * When specified, the given scope will be used to isolate this hook's
+     * cached results. Otherwise, a shared default scope will be used.
+     *
+     * Changing this value after the first call is not supported.
+     */
+    scope?: string,
+|};
+
+const DefaultScope = "useHydratableEffect";
+
+/**
+ * Hook to execute an async operation on server and client.
+ *
+ * This hook executes the given handler on the server and on the client,
+ * and, depending on the given options, can hydrate the server-side result.
+ *
+ * Results are cached on the client so they can be shared between equivalent
+ * invocations. Cache changes from one hook instance do not trigger renders
+ * in components that use the same requestID.
+ */
+export const useHydratableEffect = <TData: ValidCacheData>(
+    requestId: string,
+    handler: () => Promise<TData>,
+    options: HydratableEffectOptions<TData> = ({}: $Shape<
+        HydratableEffectOptions<TData>,
+    >),
+): Result<TData> => {
+    const {
+        clientBehavior = WhenClientSide.ExecuteWhenNoSuccessResult,
+        skip = false,
+        retainResultOnChange = false,
+        onResultChanged,
+        scope = DefaultScope,
+    } = options;
+
+    // Now we instruct the server to perform the operation.
+    // When client-side, this will look up any response for hydration; it does
+    // not invoke the handler.
+    const serverResult = useServerEffect(
+        requestId,
+
+        // If we're skipped (unlikely in server worlds, but maybe),
+        // just give an aborted response.
+        skip ? () => Promise.reject(new AbortError("skipped")) : handler,
+
+        // Only hydrate if our behavior isn't telling us not to.
+        clientBehavior !== WhenClientSide.DoNotHydrate,
+    );
+
+    const getDefaultCacheValue: () => ?Result<TData> = React.useCallback(() => {
+        // If we don't have a requestId, it's our first render, the one
+        // where we hydrated. So defer to our clientBehavior value.
+        switch (clientBehavior) {
+            case WhenClientSide.DoNotHydrate:
+            case WhenClientSide.AlwaysExecute:
+                // Either we weren't hydrating at all, or we don't care
+                // if we hydrated something or not, either way, we're
+                // doing a request.
+                return null;
+
+            case WhenClientSide.ExecuteWhenNoResult:
+                // We only execute if we didn't hydrate something.
+                // So, returning the hydration result as default for our
+                // cache, will then prevent the cached effect running.
+                return serverResult;
+
+            case WhenClientSide.ExecuteWhenNoSuccessResult:
+                // We only execute if we didn't hydrate a success result.
+                if (serverResult?.status === "success") {
+                    // So, returning the hydration result as default for our
+                    // cache, will then prevent the cached effect running.
+                    return serverResult;
+                }
+                return null;
+        }
+        // There is no reason for this to change after the first render.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+
+    // Instead of using state, which would be local to just this hook instance,
+    // we use a shared in-memory cache.
+    useSharedCache<Result<TData>>(
+        requestId, // The key of the cached item
+        scope, // The scope of the cached items
+        getDefaultCacheValue,
+    );
+
+    // When we're client-side, we ultimately want the result from this call.
+    const clientResult = useCachedEffect(requestId, handler, {
+        skip,
+        onResultChanged,
+        retainResultOnChange,
+        scope,
+    });
+
+    // OK, now which result do we return.
+    // Well, we return the serverResult on our very first call and then
+    // the clientResult thereafter. The great thing is that after the very
+    // first call, the serverResult is going to be `null` anyway.
+    return serverResult ?? clientResult;
+};

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

@@ -0,0 +1,51 @@
+// @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.useCallback((): 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;
+};

package/src/hooks/use-server-effect.js

@@ -3,8 +3,10 @@ import {Server} from "@khanacademy/wonder-blocks-core";
 import {useContext} from "react";
 import {TrackerContext} from "../util/request-tracking.js";
 import {SsrCache} from "../util/ssr-cache.js";
+import {resultFromCachedResponse} from "../util/result-from-cache-response.js";
+import {useRequestInterception} from "./use-request-interception.js";
 
-import type {CachedResponse, ValidCacheData} from "../util/types.js";
+import type {Result, ValidCacheData} from "../util/types.js";
 
 /**
  * Hook to perform an asynchronous action during server-side rendering.
@@ -22,24 +24,29 @@ import type {CachedResponse, ValidCacheData} from "../util/types.js";
  * The asynchronous action is never invoked on the client-side.
  */
 export const useServerEffect = <TData: ValidCacheData>(
-    id: string,
-    handler: () => Promise<?TData>,
+    requestId: string,
+    handler: () => Promise<TData>,
     hydrate: boolean = true,
-): ?CachedResponse<TData> => {
+): ?Result<TData> => {
+    // Plug in to the request interception framework for code that wants
+    // to use that.
+    const interceptedHandler = useRequestInterception(requestId, handler);
+
     // If we're server-side or hydrating, we'll have a cached entry to use.
     // So we get that and use it to initialize our state.
     // This works in both hydration and SSR because the very first call to
     // this will have cached data in those cases as it will be present on the
     // initial render - and subsequent renders on the client it will be null.
-    const cachedResult = SsrCache.Default.getEntry<TData>(id);
+    const cachedResult = SsrCache.Default.getEntry<TData>(requestId);
 
     // We only track data requests when we are server-side and we don't
     // already have a result, as given by the cachedData (which is also the
     // initial value for the result state).
     const maybeTrack = useContext(TrackerContext);
     if (cachedResult == null && Server.isServerSide()) {
-        maybeTrack?.(id, handler, hydrate);
+        maybeTrack?.(requestId, interceptedHandler, hydrate);
     }
 
-    return cachedResult;
+    // A null result means there was no result to hydrate.
+    return cachedResult == null ? null : resultFromCachedResponse(cachedResult);
 };

package/src/hooks/use-shared-cache.js

@@ -1,6 +1,6 @@
 // @flow
 import * as React from "react";
-import {KindError, Errors} from "@khanacademy/wonder-stuff-core";
+import {DataError, DataErrors} from "../util/data-error.js";
 import {ScopedInMemoryCache} from "../util/scoped-in-memory-cache.js";
 import type {ValidCacheData} from "../util/types.js";
 
@@ -57,23 +57,23 @@ export const useSharedCache = <TValue: ValidCacheData>(
 ): [?TValue, CacheValueFn<TValue>] => {
     // Verify arguments.
     if (!id || typeof id !== "string") {
-        throw new KindError(
+        throw new DataError(
             "id must be a non-empty string",
-            Errors.InvalidInput,
+            DataErrors.InvalidInput,
         );
     }
 
     if (!scope || typeof scope !== "string") {
-        throw new KindError(
+        throw new DataError(
             "scope must be a non-empty string",
-            Errors.InvalidInput,
+            DataErrors.InvalidInput,
         );
     }
 
     // Memoize our APIs.
     // This one allows callers to set or replace the cached value.
-    const cacheValue = React.useMemo(
-        () => (value: ?TValue) =>
+    const cacheValue = React.useCallback(
+        (value: ?TValue) =>
             value == null
                 ? cache.purge(scope, id)
                 : cache.set(scope, id, value),
@@ -94,11 +94,13 @@ export const useSharedCache = <TValue: ValidCacheData>(
         const value =
             typeof initialValue === "function" ? initialValue() : initialValue;
 
-        // Update the cache.
-        cacheValue(value);
+        if (value != null) {
+            // Update the cache.
+            cacheValue(value);
 
-        // Make sure we return this value as our current value.
-        currentValue = value;
+            // Make sure we return this value as our current value.
+            currentValue = value;
+        }
     }
 
     // Now we have everything, let's return it.

package/src/index.js

@@ -10,15 +10,33 @@ import type {
 } from "./util/types.js";
 
 export type {
+    ErrorOptions,
     ResponseCache,
     CachedResponse,
     Result,
     ScopedCache,
+    ValidCacheData,
 } from "./util/types.js";
 
+/**
+ * Initialize the hydration cache.
+ *
+ * @param {ResponseCache} source The cache content to use for initializing the
+ * cache.
+ * @throws {Error} If the cache is already initialized.
+ */
 export const initializeCache = (source: ResponseCache): void =>
     SsrCache.Default.initialize(source);
 
+/**
+ * Fulfill all tracked data requests.
+ *
+ * This is for use with the `TrackData` component during server-side rendering.
+ *
+ * @throws {Error} If executed outside of server-side rendering.
+ * @returns {Promise<void>} A promise that resolves when all tracked requests
+ * have been fulfilled.
+ */
 export const fulfillAllDataRequests = (): Promise<ResponseCache> => {
     if (!Server.isServerSide()) {
         return Promise.reject(
@@ -28,6 +46,15 @@ export const fulfillAllDataRequests = (): Promise<ResponseCache> => {
     return RequestTracker.Default.fulfillTrackedRequests();
 };
 
+/**
+ * Indicate if there are unfulfilled tracked requests.
+ *
+ * This is used in conjunction with `TrackData`.
+ *
+ * @throws {Error} If executed outside of server-side rendering.
+ * @returns {boolean} `true` if there are unfulfilled tracked requests;
+ * otherwise, `false`.
+ */
 export const hasUnfulfilledRequests = (): boolean => {
     if (!Server.isServerSide()) {
         throw new Error("Data requests are not tracked when client-side");
@@ -35,9 +62,21 @@ export const hasUnfulfilledRequests = (): boolean => {
     return RequestTracker.Default.hasUnfulfilledRequests;
 };
 
+/**
+ * Remove the request identified from the cached hydration responses.
+ *
+ * @param {string} id The request ID of the response to remove from the cache.
+ */
 export const removeFromCache = (id: string): boolean =>
     SsrCache.Default.remove(id);
 
+/**
+ * Remove all cached hydration responses that match the given predicate.
+ *
+ * @param {(id: string) => boolean} [predicate] The predicate to match against
+ * the cached hydration responses. If no predicate is provided, all cached
+ * hydration responses will be removed.
+ */
 export const removeAllFromCache = (
     predicate?: (
         key: string,
@@ -47,15 +86,28 @@ export const removeAllFromCache = (
 
 export {default as TrackData} from "./components/track-data.js";
 export {default as Data} from "./components/data.js";
-export {default as InterceptData} from "./components/intercept-data.js";
+export {default as InterceptRequests} from "./components/intercept-requests.js";
+export {DataError, DataErrors} from "./util/data-error.js";
 export {useServerEffect} from "./hooks/use-server-effect.js";
+export {useCachedEffect} from "./hooks/use-cached-effect.js";
 export {useSharedCache, clearSharedCache} from "./hooks/use-shared-cache.js";
+export {
+    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";
 export {ScopedInMemoryCache} from "./util/scoped-in-memory-cache.js";
+export {SerializableInMemoryCache} from "./util/serializable-in-memory-cache.js";
+export {RequestFulfillment} from "./util/request-fulfillment.js";
+export {Status} from "./util/status.js";
 
 // GraphQL
 export {GqlRouter} from "./components/gql-router.js";
 export {useGql} from "./hooks/use-gql.js";
-export * from "./util/gql-error.js";
+export {GqlError, GqlErrors} from "./util/gql-error.js";
 export type {
     GqlContext,
     GqlOperation,

package/src/util/__tests__/__snapshots__/serializable-in-memory-cache.test.js.snap

@@ -0,0 +1,19 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`SerializableInMemoryCache #set should throw if the id is  1`] = `"id must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the id is [Function anonymous] 1`] = `"id must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the id is 5 1`] = `"id must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the id is null 1`] = `"id must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the scope is  1`] = `"scope must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the scope is [Function anonymous] 1`] = `"scope must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the scope is 5 1`] = `"scope must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the scope is null 1`] = `"scope must be non-empty string"`;
+
+exports[`SerializableInMemoryCache #set should throw if the value is a function 1`] = `"value must be a non-function value"`;

package/src/util/__tests__/merge-gql-context.test.js

@@ -0,0 +1,74 @@
+// @flow
+import {mergeGqlContext} from "../merge-gql-context.js";
+
+describe("#mergeGqlContext", () => {
+    it("should combine the default context with the given overrides", () => {
+        // Arrange
+        const baseContext = {
+            foo: "bar",
+        };
+
+        // Act
+        const result = mergeGqlContext<any>(baseContext, {
+            fiz: "baz",
+        });
+
+        // Assert
+        expect(result).toStrictEqual({
+            foo: "bar",
+            fiz: "baz",
+        });
+    });
+
+    it("should overwrite values in the default context with the given overrides", () => {
+        // Arrange
+        const baseContext = {
+            foo: "bar",
+        };
+
+        // Act
+        const result = mergeGqlContext<any>(baseContext, {
+            foo: "boo",
+        });
+
+        // Assert
+        expect(result).toStrictEqual({
+            foo: "boo",
+        });
+    });
+
+    it("should not overwrite values in the default context with undefined values in the given overrides", () => {
+        // Arrange
+        const baseContext = {
+            foo: "bar",
+        };
+
+        // Act
+        const result = mergeGqlContext<any>(baseContext, {
+            foo: undefined,
+        });
+
+        // Assert
+        expect(result).toStrictEqual({
+            foo: "bar",
+        });
+    });
+
+    it("should delete values in the default context when the value is null in the given overrides", () => {
+        // Arrange
+        const baseContext = {
+            foo: "bar",
+            fiz: "baz",
+        };
+
+        // Act
+        const result = mergeGqlContext<any>(baseContext, {
+            fiz: null,
+        });
+
+        // Assert
+        expect(result).toStrictEqual({
+            foo: "bar",
+        });
+    });
+});