@khanacademy/wonder-blocks-data 5.0.1 → 6.0.0

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

@@ -18,8 +18,8 @@ import type {ValidCacheData} from "../util/types.js";
  */
 export const useRequestInterception = <TData: ValidCacheData>(
     requestId: string,
-    handler: () => Promise<?TData>,
-): (() => Promise<?TData>) => {
+    handler: () => Promise<TData>,
+): (() => Promise<TData>) => {
     // Get the interceptors that have been registered.
     const interceptors = React.useContext(InterceptContext);
 
@@ -28,27 +28,24 @@ export const useRequestInterception = <TData: ValidCacheData>(
     // 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],
-    );
+    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.
@@ -23,9 +25,13 @@ import type {CachedResponse, ValidCacheData} from "../util/types.js";
  */
 export const useServerEffect = <TData: ValidCacheData>(
     requestId: string,
-    handler: () => Promise<?TData>,
+    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
@@ -38,8 +44,9 @@ export const useServerEffect = <TData: ValidCacheData>(
     // initial value for the result state).
     const maybeTrack = useContext(TrackerContext);
     if (cachedResult == null && Server.isServerSide()) {
-        maybeTrack?.(requestId, 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,
@@ -48,16 +87,27 @@ export const removeAllFromCache = (
 export {default as TrackData} from "./components/track-data.js";
 export {default as Data} from "./components/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 {useRequestInterception} from "./hooks/use-request-interception.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 {resultFromCachedResponse} from "./util/result-from-cache-response.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",
+        });
+    });
+});

package/src/util/__tests__/request-fulfillment.test.js

@@ -1,6 +1,6 @@
 // @flow
-import {SsrCache} from "../ssr-cache.js";
 import {RequestFulfillment} from "../request-fulfillment.js";
+import {DataError} from "../data-error.js";
 
 describe("RequestFulfillment", () => {
     it("should provide static default instance", () => {
@@ -15,62 +15,44 @@ describe("RequestFulfillment", () => {
     });
 
     describe("#fulfill", () => {
-        it("should attempt to cache errors caused directly by handlers", async () => {
+        it("should resolve to an error result", async () => {
             // Arrange
-            const responseCache = new SsrCache();
-            const requestFulfillment = new RequestFulfillment(responseCache);
-            const error = new Error("OH NO!");
-            const fakeBadHandler = () => {
-                throw error;
-            };
-            const cacheErrorSpy = jest.spyOn(responseCache, "cacheError");
+            const requestFulfillment = new RequestFulfillment();
+            const fakeBadRequestHandler = () => Promise.reject("OH NO!");
 
             // Act
-            await requestFulfillment.fulfill("ID", {
-                handler: fakeBadHandler,
+            const result = await requestFulfillment.fulfill("ID", {
+                handler: fakeBadRequestHandler,
             });
 
             // Assert
-            expect(cacheErrorSpy).toHaveBeenCalledWith("ID", error, true);
+            expect(result).toStrictEqual({
+                status: "error",
+                error: expect.any(DataError),
+            });
         });
 
-        it("should cache errors occurring in promises", async () => {
+        it("should resolve to an aborted result", async () => {
             // Arrange
-            const responseCache = new SsrCache();
-            const requestFulfillment = new RequestFulfillment(responseCache);
-            const fakeBadRequestHandler = () =>
-                new Promise((resolve, reject) => reject("OH NO!"));
-            const cacheErrorSpy = jest.spyOn(responseCache, "cacheError");
+            const requestFulfillment = new RequestFulfillment();
+            const abortError = new Error("abort abort abort, awoooga");
+            abortError.name = "AbortError";
+            const fakeBadRequestHandler = () => Promise.reject(abortError);
 
             // Act
-            await requestFulfillment.fulfill("ID", {
+            const result = await requestFulfillment.fulfill("ID", {
                 handler: fakeBadRequestHandler,
             });
 
             // Assert
-            expect(cacheErrorSpy).toHaveBeenCalledWith("ID", "OH NO!", true);
-        });
-
-        it("should cache data from requests", async () => {
-            // Arrange
-            const responseCache = new SsrCache();
-            const requestFulfillment = new RequestFulfillment(responseCache);
-            const fakeRequestHandler = () => Promise.resolve("DATA!");
-            const cacheDataSpy = jest.spyOn(responseCache, "cacheData");
-
-            // Act
-            await requestFulfillment.fulfill("ID", {
-                handler: fakeRequestHandler,
+            expect(result).toStrictEqual({
+                status: "aborted",
             });
-
-            // Assert
-            expect(cacheDataSpy).toHaveBeenCalledWith("ID", "DATA!", true);
         });
 
-        it("should return a promise of the result", async () => {
+        it("should resolve to a data result", async () => {
             // Arrange
-            const responseCache = new SsrCache();
-            const requestFulfillment = new RequestFulfillment(responseCache);
+            const requestFulfillment = new RequestFulfillment();
             const fakeRequestHandler = () => Promise.resolve("DATA!");
 
             // Act
@@ -80,14 +62,14 @@ describe("RequestFulfillment", () => {
 
             // Assert
             expect(result).toStrictEqual({
+                status: "success",
                 data: "DATA!",
             });
         });
 
         it("should reuse inflight requests", () => {
             // Arrange
-            const responseCache = new SsrCache();
-            const requestFulfillment = new RequestFulfillment(responseCache);
+            const requestFulfillment = new RequestFulfillment();
             const fakeRequestHandler = () => Promise.resolve("DATA!");
 
             // Act
@@ -104,8 +86,7 @@ describe("RequestFulfillment", () => {
 
         it("should remove inflight requests upon completion", async () => {
             // Arrange
-            const responseCache = new SsrCache();
-            const requestFulfillment = new RequestFulfillment(responseCache);
+            const requestFulfillment = new RequestFulfillment();
             const fakeRequestHandler = () => Promise.resolve("DATA!");
 
             // Act