@khanacademy/wonder-blocks-data 2.3.2 → 3.0.1

package/src/hooks/use-data.js

@@ -0,0 +1,143 @@
+// @flow
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {useState, useEffect, useContext, useRef} from "react";
+import {RequestFulfillment} from "../util/request-fulfillment.js";
+import InterceptContext from "../components/intercept-context.js";
+import {TrackerContext} from "../util/request-tracking.js";
+import {resultFromCacheEntry} from "../util/result-from-cache-entry.js";
+import {ResponseCache} from "../util/response-cache.js";
+
+import type {
+    Result,
+    IRequestHandler,
+    ValidData,
+    CacheEntry,
+} from "../util/types.js";
+
+export const useData = <TOptions, TData: ValidData>(
+    handler: IRequestHandler<TOptions, TData>,
+    options: TOptions,
+): Result<TData> => {
+    // 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 = ResponseCache.Default.getEntry<TOptions, TData>(
+        handler,
+        options,
+    );
+    const [result, setResult] = useState<?CacheEntry<TData>>(cachedResult);
+
+    // 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 = useContext(InterceptContext);
+    const interceptor = interceptorMap[handler.type];
+
+    // If we have an interceptor, we need to replace the handler with one that
+    // uses the interceptor. This helper function generates a new handler.
+    // We need this before we track the request as we want the interceptor
+    // to also work for tracked requests to simplify testing the server-side
+    // request fulfillment.
+    const getMaybeInterceptedHandler = () => {
+        if (interceptor == null) {
+            return handler;
+        }
+
+        const fulfillRequestFn = (options) =>
+            interceptor.fulfillRequest(options) ??
+            handler.fulfillRequest(options);
+        return {
+            fulfillRequest: fulfillRequestFn,
+            getKey: (options) => handler.getKey(options),
+            type: handler.type,
+            hydrate: handler.hydrate,
+        };
+    };
+
+    // 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 (result == null && Server.isServerSide()) {
+        maybeTrack?.(getMaybeInterceptedHandler(), options);
+    }
+
+    // We need to update our request when the handler changes or the key
+    // to the options change, so we keep track of those.
+    // However, even if we are hydrating from cache, we still need to make the
+    // request at least once, so we do not initialize these references.
+    const handlerRef = useRef();
+    const keyRef = useRef();
+    const interceptorRef = useRef();
+
+    // This effect will ensure that we fulfill the request as desired.
+    useEffect(() => {
+        // If we are server-side, then just skip the effect. We track requests
+        // during SSR and fulfill them outside of the React render cycle.
+        // NOTE: This shouldn't happen since effects would not run on the server
+        // but let's be defensive - I think it makes the code clearer.
+        /* istanbul ignore next */
+        if (Server.isServerSide()) {
+            return;
+        }
+
+        // Update our refs to the current handler and key.
+        handlerRef.current = handler;
+        keyRef.current = handler.getKey(options);
+        interceptorRef.current = interceptor;
+
+        // If we're not hydrating a result, we want to make sure we set our
+        // result to null so that we're in the loading state.
+        if (cachedResult == null) {
+            // Mark ourselves as loading.
+            setResult(null);
+        }
+
+        // We aren't server-side, so let's make the request.
+        // The request handler is in control of whether that request actually
+        // happens or not.
+        let cancel = false;
+        RequestFulfillment.Default.fulfill(
+            getMaybeInterceptedHandler(),
+            options,
+        )
+            .then((updateEntry) => {
+                if (cancel) {
+                    return;
+                }
+                setResult(updateEntry);
+                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({
+                    data: null,
+                    error: typeof e === "string" ? e : e.message,
+                });
+                return;
+            });
+
+        return () => {
+            cancel = true;
+        };
+        // - handler.getKey is a proxy for options
+        // - We don't want to trigger on cachedResult changing, we're
+        //   just using that as a flag for render state if the other things
+        //   trigger this effect.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [handler, handler.getKey(options), interceptor]);
+
+    return resultFromCacheEntry(result);
+};

package/src/index.js

@@ -15,7 +15,6 @@ export type {
     CacheEntry,
     Result,
     IRequestHandler,
-    ICache,
     ResponseCache,
 } from "./util/types.js";
 
@@ -61,5 +60,4 @@ export {default as RequestHandler} from "./util/request-handler.js";
 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 InterceptCache} from "./components/intercept-cache.js";
-export {default as NoCache} from "./util/no-cache.js";
+export {useData} from "./hooks/use-data.js";

package/src/util/__tests__/memory-cache.test.js

@@ -47,9 +47,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -71,9 +69,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -95,9 +91,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -119,9 +113,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -142,9 +134,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -165,9 +155,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -186,9 +174,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -207,9 +193,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -230,9 +214,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -253,9 +235,7 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
@@ -269,6 +249,23 @@ describe("MemoryCache", () => {
     });
 
     describe("#removeAll", () => {
+        it("should return 0 if the handler subcache is absent", () => {
+            // Arrange
+            const cache = new MemoryCache();
+            const fakeHandler: IRequestHandler<string, string> = {
+                getKey: () => "MY_KEY",
+                type: "MY_HANDLER",
+                fulfillRequest: jest.fn(),
+                hydrate: true,
+            };
+
+            // Act
+            const result = cache.removeAll(fakeHandler);
+
+            // Assert
+            expect(result).toBe(0);
+        });
+
         it("should remove matching entries from handler subcache", () => {
             const cache = new MemoryCache({
                 MY_HANDLER: {
@@ -283,32 +280,84 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
+                hydrate: true,
+            };
+
+            // Act
+            cache.removeAll(fakeHandler, (k, d) => d.data === "2");
+            const result = cache.cloneData();
+
+            // Assert
+            expect(result).toStrictEqual({
+                MY_HANDLER: {
+                    MY_KEY2: {data: "1"},
+                },
+                OTHER_HANDLER: {
+                    MY_KEY: {data: "1"},
+                },
+            });
+        });
+
+        it("should return the number of items that matched the predicate and were removed", () => {
+            const cache = new MemoryCache({
+                MY_HANDLER: {
+                    MY_KEY: {data: "a"},
+                    MY_KEY2: {data: "b"},
+                    MY_KEY3: {data: "a"},
+                },
+                OTHER_HANDLER: {
+                    MY_KEY: {data: "b"},
+                },
+            });
+            const fakeHandler: IRequestHandler<string, string> = {
+                getKey: () => "MY_KEY",
+                type: "MY_HANDLER",
+                fulfillRequest: jest.fn(),
                 hydrate: true,
             };
 
             // Act
             const result = cache.removeAll(
                 fakeHandler,
-                (k, d) => d.data === "2",
+                (k, d) => d.data === "a",
             );
-            const after = cache.cloneData();
 
             // Assert
             expect(result).toBe(2);
-            expect(after).toStrictEqual({
+        });
+
+        it("should remove the entire handler subcache if no predicate", () => {
+            const cache = new MemoryCache({
                 MY_HANDLER: {
-                    MY_KEY2: {data: "1"},
+                    MY_KEY: {data: "data!"},
+                    MY_KEY2: {data: "data!"},
+                    MY_KEY3: {data: "data!"},
                 },
                 OTHER_HANDLER: {
-                    MY_KEY: {data: "1"},
+                    MY_KEY: {data: "data!"},
+                },
+            });
+            const fakeHandler: IRequestHandler<string, string> = {
+                getKey: () => "MY_KEY",
+                type: "MY_HANDLER",
+                fulfillRequest: jest.fn(),
+                hydrate: true,
+            };
+
+            // Act
+            cache.removeAll(fakeHandler);
+            const result = cache.cloneData();
+
+            // Assert
+            expect(result).toStrictEqual({
+                OTHER_HANDLER: {
+                    MY_KEY: {data: "data!"},
                 },
             });
         });
 
-        it("should remove all entries from handler subcache if no predicate", () => {
+        it("should return the number of items that were in the handler subcache if there was no predicate", () => {
             const cache = new MemoryCache({
                 MY_HANDLER: {
                     MY_KEY: {data: "data!"},
@@ -322,26 +371,76 @@ describe("MemoryCache", () => {
             const fakeHandler: IRequestHandler<string, string> = {
                 getKey: () => "MY_KEY",
                 type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
                 fulfillRequest: jest.fn(),
-                cache: null,
                 hydrate: true,
             };
 
             // Act
             const result = cache.removeAll(fakeHandler);
-            const after = cache.cloneData();
 
             // Assert
             expect(result).toBe(3);
-            expect(after).toStrictEqual({
-                MY_HANDLER: {},
-                OTHER_HANDLER: {
+        });
+    });
+
+    describe("#cloneData", () => {
+        it("should return a copy of the cache data", () => {});
+
+        it("should throw if there is an error during cloning", () => {
+            // Arrange
+            const cache = new MemoryCache({
+                MY_HANDLER: {
                     MY_KEY: {data: "data!"},
                 },
             });
+            jest.spyOn(JSON, "stringify").mockImplementation(() => {
+                throw new Error("BANG!");
+            });
+
+            // Act
+            const act = () => cache.cloneData();
+
+            // Assert
+            expect(act).toThrowErrorMatchingInlineSnapshot(
+                `"An error occurred while trying to clone the cache: Error: BANG!"`,
+            );
         });
     });
 
-    describe("#cloneData", () => {});
+    describe("@inUse", () => {
+        it("should return true if the cache contains data", () => {
+            // Arrange
+            const cache = new MemoryCache({
+                MY_HANDLER: {
+                    MY_KEY: {data: "data!"},
+                },
+            });
+
+            // Act
+            const result = cache.inUse;
+
+            // Assert
+            expect(result).toBeTruthy();
+        });
+
+        it("should return false if the cache is empty", () => {
+            // Arrange
+            const cache = new MemoryCache({
+                MY_HANDLER: {
+                    MY_KEY: {data: "data!"},
+                },
+            });
+            cache.removeAll(
+                ({
+                    type: "MY_HANDLER",
+                }: any),
+            );
+
+            // Act
+            const result = cache.inUse;
+
+            // Assert
+            expect(result).toBeFalsy();
+        });
+    });
 });

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

@@ -17,32 +17,30 @@ describe("RequestFulfillment", () => {
     });
 
     describe("#fulfill", () => {
-        it("should cache errors caused directly by handlers", async () => {
+        it("should attempt to cache errors caused directly by handlers", async () => {
             // Arrange
             const responseCache = new ResponseCache();
             const requestFulfillment = new RequestFulfillment(responseCache);
+            const error = new Error("OH NO!");
             const fakeBadHandler: IRequestHandler<any, any> = {
                 fulfillRequest: () => {
-                    throw new Error("OH NO!");
+                    throw error;
                 },
                 getKey: jest.fn().mockReturnValue("MY_KEY"),
-                shouldRefreshCache: () => false,
                 type: "MY_TYPE",
-                cache: null,
                 hydrate: true,
             };
+            const cacheErrorSpy = jest.spyOn(responseCache, "cacheError");
 
             // Act
             await requestFulfillment.fulfill(fakeBadHandler, "OPTIONS");
 
             // Assert
-            expect(responseCache.cloneHydratableData()).toStrictEqual({
-                MY_TYPE: {
-                    MY_KEY: {
-                        error: "OH NO!",
-                    },
-                },
-            });
+            expect(cacheErrorSpy).toHaveBeenCalledWith(
+                fakeBadHandler,
+                "OPTIONS",
+                error,
+            );
         });
 
         it("should cache errors occurring in promises", async () => {
@@ -53,23 +51,20 @@ describe("RequestFulfillment", () => {
                 fulfillRequest: () =>
                     new Promise((resolve, reject) => reject("OH NO!")),
                 getKey: (o) => o,
-                shouldRefreshCache: () => false,
                 type: "BAD_REQUEST",
-                cache: null,
                 hydrate: true,
             };
+            const cacheErrorSpy = jest.spyOn(responseCache, "cacheError");
 
             // Act
             await requestFulfillment.fulfill(fakeBadRequestHandler, "OPTIONS");
 
             // Assert
-            expect(responseCache.cloneHydratableData()).toStrictEqual({
-                BAD_REQUEST: {
-                    OPTIONS: {
-                        error: "OH NO!",
-                    },
-                },
-            });
+            expect(cacheErrorSpy).toHaveBeenCalledWith(
+                fakeBadRequestHandler,
+                "OPTIONS",
+                "OH NO!",
+            );
         });
 
         it("should cache data from requests", async () => {
@@ -79,24 +74,20 @@ describe("RequestFulfillment", () => {
             const fakeRequestHandler: IRequestHandler<string, any> = {
                 fulfillRequest: () => Promise.resolve("DATA!"),
                 getKey: (o) => o,
-                shouldRefreshCache: () => false,
                 type: "VALID_REQUEST",
-                cache: null,
                 hydrate: true,
             };
+            const cacheDataSpy = jest.spyOn(responseCache, "cacheData");
 
             // Act
             await requestFulfillment.fulfill(fakeRequestHandler, "OPTIONS");
-            const result = responseCache.cloneHydratableData();
 
             // Assert
-            expect(result).toStrictEqual({
-                VALID_REQUEST: {
-                    OPTIONS: {
-                        data: "DATA!",
-                    },
-                },
-            });
+            expect(cacheDataSpy).toHaveBeenCalledWith(
+                fakeRequestHandler,
+                "OPTIONS",
+                "DATA!",
+            );
         });
 
         it("should return a promise of the result", async () => {
@@ -106,9 +97,7 @@ describe("RequestFulfillment", () => {
             const fakeRequestHandler: IRequestHandler<string, any> = {
                 fulfillRequest: () => Promise.resolve("DATA!"),
                 getKey: (o) => o,
-                shouldRefreshCache: () => false,
                 type: "VALID_REQUEST",
-                cache: null,
                 hydrate: true,
             };
 
@@ -131,9 +120,7 @@ describe("RequestFulfillment", () => {
             const fakeRequestHandler: IRequestHandler<string, any> = {
                 fulfillRequest: () => Promise.resolve("DATA!"),
                 getKey: (o) => o,
-                shouldRefreshCache: () => false,
                 type: "VALID_REQUEST",
-                cache: null,
                 hydrate: true,
             };
 
@@ -158,9 +145,7 @@ describe("RequestFulfillment", () => {
             const fakeRequestHandler: IRequestHandler<string, any> = {
                 fulfillRequest: () => Promise.resolve("DATA!"),
                 getKey: (o) => o,
-                shouldRefreshCache: () => false,
                 type: "VALID_REQUEST",
-                cache: null,
                 hydrate: false,
             };