@khanacademy/wonder-blocks-data 3.1.2 → 5.0.0

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

@@ -0,0 +1,307 @@
+// @flow
+import {renderHook as clientRenderHook} from "@testing-library/react-hooks";
+
+import {useSharedCache, clearSharedCache} from "../use-shared-cache.js";
+
+describe("#useSharedCache", () => {
+    beforeEach(() => {
+        clearSharedCache();
+    });
+
+    it.each`
+        id
+        ${null}
+        ${""}
+        ${5}
+        ${() => "BOO"}
+    `("should throw if the id is $id", ({id}) => {
+        // Arrange
+
+        // Act
+        const {result} = clientRenderHook(() => useSharedCache(id, "scope"));
+
+        // Assert
+        expect(result.error).toMatchSnapshot();
+    });
+
+    it.each`
+        scope
+        ${null}
+        ${""}
+        ${5}
+        ${() => "BOO"}
+    `("should throw if the scope is $scope", ({scope}) => {
+        // Arrange
+
+        // Act
+        const {result} = clientRenderHook(() => useSharedCache("id", scope));
+
+        // Assert
+        expect(result.error).toMatchSnapshot();
+    });
+
+    it("should return a tuple of two items", () => {
+        // Arrange
+
+        // Act
+        const {
+            result: {current: result},
+        } = clientRenderHook(() => useSharedCache("id", "scope"));
+
+        // Assert
+        expect(result).toBeArrayOfSize(2);
+    });
+
+    describe("tuple[0] - currentValue", () => {
+        it("should be null if nothing is cached", () => {
+            // Arrange
+
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() => useSharedCache("id", "scope"));
+
+            // Assert
+            expect(result[0]).toBeNull();
+        });
+
+        it("should match initialValue when provided as a non-function", () => {
+            // Arrange
+
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() =>
+                useSharedCache("id", "scope", "INITIAL VALUE"),
+            );
+
+            // Assert
+            expect(result[0]).toBe("INITIAL VALUE");
+        });
+
+        it("should match the return of initialValue when provided as non-function", () => {
+            // Arrange
+
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() =>
+                useSharedCache("id", "scope", () => "INITIAL VALUE"),
+            );
+
+            // Assert
+            expect(result[0]).toBe("INITIAL VALUE");
+        });
+    });
+
+    describe("tuple[1] - setValue", () => {
+        it("should be a function", () => {
+            // Arrange
+
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() => useSharedCache("id", "scope"));
+
+            // Assert
+            expect(result[1]).toBeFunction();
+        });
+
+        it("should be the same function if the id and scope remain the same", () => {
+            // Arrange
+            const wrapper = clientRenderHook(
+                ({id, scope}) => useSharedCache(id, scope),
+                {initialProps: {id: "id", scope: "scope"}},
+            );
+
+            // Act
+            wrapper.rerender({
+                id: "id",
+                scope: "scope",
+            });
+            const result1 = wrapper.result.all[wrapper.result.all.length - 2];
+            const result2 = wrapper.result.current;
+
+            // Assert
+            // $FlowIgnore[prop-missing]
+            expect(result1[1]).toBe(result2[1]);
+        });
+
+        it("should be a new function if the id changes", () => {
+            // Arrange
+            const wrapper = clientRenderHook(
+                ({id}) => useSharedCache(id, "scope"),
+                {
+                    initialProps: {id: "id"},
+                },
+            );
+
+            // Act
+            wrapper.rerender({id: "new-id"});
+            const result1 = wrapper.result.all[wrapper.result.all.length - 2];
+            const result2 = wrapper.result.current;
+
+            // Assert
+            // $FlowIgnore[prop-missing]
+            expect(result1[1]).not.toBe(result2[1]);
+        });
+
+        it("should be a new function if the scope changes", () => {
+            // Arrange
+            const wrapper = clientRenderHook(
+                ({scope}) => useSharedCache("id", scope),
+                {
+                    initialProps: {scope: "scope"},
+                },
+            );
+
+            // Act
+            wrapper.rerender({scope: "new-scope"});
+            const result1 = wrapper.result.all[wrapper.result.all.length - 2];
+            const result2 = wrapper.result.current;
+
+            // Assert
+            // $FlowIgnore[prop-missing]
+            expect(result1[1]).not.toBe(result2[1]);
+        });
+
+        it("should set the value in the cache", () => {
+            // Arrange
+            const wrapper = clientRenderHook(() =>
+                useSharedCache("id", "scope"),
+            );
+            const setValue = wrapper.result.current[1];
+
+            // Act
+            setValue("CACHED_VALUE");
+            // Rerender so the hook retrieves this new value.
+            wrapper.rerender();
+            const result = wrapper.result.current[0];
+
+            // Assert
+            expect(result).toBe("CACHED_VALUE");
+        });
+
+        it.each`
+            value
+            ${undefined}
+            ${null}
+        `("should purge the value from the cache if $value", ({value}) => {
+            // Arrange
+            const wrapper = clientRenderHook(() =>
+                useSharedCache("id", "scope"),
+            );
+            const setValue = wrapper.result.current[1];
+            setValue("CACHED_VALUE");
+
+            // Act
+            // Rerender so the result has the cached value.
+            wrapper.rerender();
+            setValue(value);
+            // Rerender so the hook retrieves this new value.
+            wrapper.rerender();
+            const result = wrapper.result.current[0];
+
+            // Assert
+            expect(result).toBeNull();
+        });
+    });
+
+    it("should share cache across all uses", () => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id", "scope"));
+        const hook2 = clientRenderHook(() => useSharedCache("id", "scope"));
+        hook1.result.current[1]("VALUE_1");
+
+        // Act
+        hook2.rerender();
+        const result = hook2.result.current[0];
+
+        // Assert
+        expect(result).toBe("VALUE_1");
+    });
+
+    it.each`
+        id
+        ${"id1"}
+        ${"id2"}
+    `("should not share cache if scope is different", ({id}) => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache(id, "scope2"));
+        hook1.result.current[1]("VALUE_1");
+
+        // Act
+        hook2.rerender();
+        const result = hook2.result.current[0];
+
+        // Assert
+        expect(result).toBeNull();
+    });
+
+    it.each`
+        scope
+        ${"scope1"}
+        ${"scope2"}
+    `("should not share cache if id is different", ({scope}) => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache("id2", scope));
+        hook1.result.current[1]("VALUE_1");
+
+        // Act
+        hook2.rerender();
+        const result = hook2.result.current[0];
+
+        // Assert
+        expect(result).toBeNull();
+    });
+});
+
+describe("#clearSharedCache", () => {
+    beforeEach(() => {
+        clearSharedCache();
+    });
+
+    it("should clear the entire cache if no scope given", () => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache("id2", "scope2"));
+        hook1.result.current[1]("VALUE_1");
+        hook2.result.current[1]("VALUE_2");
+        // Make sure both hook results include the updated value.
+        hook1.rerender();
+        hook2.rerender();
+
+        // Act
+        clearSharedCache();
+        // Make sure we refresh the hook results.
+        hook1.rerender();
+        hook2.rerender();
+
+        // Assert
+        expect(hook1.result.current[0]).toBeNull();
+        expect(hook2.result.current[0]).toBeNull();
+    });
+
+    it("should clear the given scope only", () => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache("id2", "scope2"));
+        hook1.result.current[1]("VALUE_1");
+        hook2.result.current[1]("VALUE_2");
+        // Make sure both hook results include the updated value.
+        hook1.rerender();
+        hook2.rerender();
+
+        // Act
+        clearSharedCache("scope2");
+        // Make sure we refresh the hook results.
+        hook1.rerender();
+        hook2.rerender();
+
+        // Assert
+        expect(hook1.result.current[0]).toBe("VALUE_1");
+        expect(hook2.result.current[0]).toBeNull();
+    });
+});

package/src/hooks/use-gql.js

@@ -9,7 +9,6 @@ import type {
     GqlContext,
     GqlOperation,
     GqlFetchOptions,
-    GqlOperationType,
 } from "../util/gql-types.js";
 
 /**
@@ -17,14 +16,13 @@ import type {
  *
  * The fetch function will resolve null if the request was aborted, otherwise
  * it will resolve the data returned by the GraphQL server.
+ *
+ * Context is merged with the default context provided to the GqlRouter.
+ * 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 = (): (<
-    TType: GqlOperationType,
-    TData,
-    TVariables: {...},
-    TContext: GqlContext,
->(
-    operation: GqlOperation<TType, TData, TVariables>,
+export const useGql = (): (<TData, TVariables: {...}, TContext: GqlContext>(
+    operation: GqlOperation<TData, TVariables>,
     options?: GqlFetchOptions<TVariables, TContext>,
 ) => Promise<?TData>) => {
     // This hook only works if the `GqlRouter` has been used to setup context.
@@ -41,35 +39,45 @@ export const useGql = (): (<
     // in hooks deps without fear of it triggering extra renders.
     const gqlFetch = useMemo(
         () =>
-            <
-                TType: GqlOperationType,
-                TData,
-                TVariables: {...},
-                TContext: GqlContext,
-            >(
-                operation: GqlOperation<TType, TData, TVariables>,
+            <TData, TVariables: {...}, TContext: GqlContext>(
+                operation: GqlOperation<TData, TVariables>,
                 options: GqlFetchOptions<TVariables, TContext> = Object.freeze(
                     {},
                 ),
             ) => {
-                const {variables, context} = options;
+                const {variables, context = {}} = options;
+
+                // 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, {
-                    ...defaultContext,
-                    ...context,
-                }).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;
-                });
+                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],
     );

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

@@ -0,0 +1,54 @@
+// @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.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],
+    );
+
+    return interceptedHandler;
+};

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

@@ -0,0 +1,45 @@
+// @flow
+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 type {CachedResponse, ValidCacheData} from "../util/types.js";
+
+/**
+ * Hook to perform an asynchronous action during server-side rendering.
+ *
+ * This hook registers an asynchronous action to be performed during
+ * server-side rendering. The action is performed only once, and the result
+ * is cached against the given identifier so that subsequent calls return that
+ * cached result allowing components to render more of the component.
+ *
+ * This hook requires the Wonder Blocks Data functionality for resolving
+ * pending requests, as well as support for the hydration cache to be
+ * embedded into a page so that the result can by hydrated (if that is a
+ * requirement).
+ *
+ * The asynchronous action is never invoked on the client-side.
+ */
+export const useServerEffect = <TData: ValidCacheData>(
+    requestId: string,
+    handler: () => Promise<?TData>,
+    hydrate: boolean = true,
+): ?CachedResponse<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 = 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?.(requestId, handler, hydrate);
+    }
+
+    return cachedResult;
+};

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

@@ -0,0 +1,106 @@
+// @flow
+import * as React from "react";
+import {KindError, Errors} from "@khanacademy/wonder-stuff-core";
+import {ScopedInMemoryCache} from "../util/scoped-in-memory-cache.js";
+import type {ValidCacheData} from "../util/types.js";
+
+/**
+ * A function for inserting a value into the cache or clearing it.
+ */
+type CacheValueFn<TValue: ValidCacheData> = (value: ?TValue) => void;
+
+/**
+ * This is the cache.
+ * It's incredibly complex.
+ * Very in-memory. So cache. Such complex. Wow.
+ */
+const cache = new ScopedInMemoryCache();
+
+/**
+ * Clear the in-memory cache or a single scope within it.
+ */
+export const clearSharedCache = (scope: string = "") => {
+    // If we have a valid scope (empty string is falsy), then clear that scope.
+    if (scope && typeof scope === "string") {
+        cache.purgeScope(scope);
+    } else {
+        // Just reset the object. This should be sufficient.
+        cache.purgeAll();
+    }
+};
+
+/**
+ * Hook to retrieve data from and store data in an in-memory cache.
+ *
+ * @returns {[?ReadOnlyCacheValue, CacheValueFn]}
+ * Returns an array containing the current cache entry (or undefined), a
+ * function to set the cache entry (passing null or undefined to this function
+ * will delete the entry).
+ *
+ * To clear a single scope within the cache or the entire cache,
+ * the `clearScopedCache` export is available.
+ *
+ * NOTE: Unlike useState or useReducer, we don't automatically update folks
+ * if the value they reference changes. We might add it later (if we need to),
+ * but the likelihood here is that things won't be changing in this cache in a
+ * way where we would need that. If we do (and likely only in specific
+ * circumstances), we should consider adding a simple boolean useState that can
+ * be toggled to cause a rerender whenever the referenced cached data changes
+ * so that callers can re-render on cache changes. However, we should make
+ * sure this toggling is optional - or we could use a callback argument, to
+ * achieve this on an as-needed basis.
+ */
+export const useSharedCache = <TValue: ValidCacheData>(
+    id: string,
+    scope: string,
+    initialValue?: ?TValue | (() => ?TValue),
+): [?TValue, CacheValueFn<TValue>] => {
+    // Verify arguments.
+    if (!id || typeof id !== "string") {
+        throw new KindError(
+            "id must be a non-empty string",
+            Errors.InvalidInput,
+        );
+    }
+
+    if (!scope || typeof scope !== "string") {
+        throw new KindError(
+            "scope must be a non-empty string",
+            Errors.InvalidInput,
+        );
+    }
+
+    // Memoize our APIs.
+    // This one allows callers to set or replace the cached value.
+    const cacheValue = React.useMemo(
+        () => (value: ?TValue) =>
+            value == null
+                ? cache.purge(scope, id)
+                : cache.set(scope, id, value),
+        [id, scope],
+    );
+
+    // We don't memo-ize the current value, just in case the cache was updated
+    // since our last run through. Also, our cache does not know what type it
+    // stores, so we have to cast it to the type we're exporting. This is a
+    // dev time courtesy, rather than a runtime thing.
+    // $FlowIgnore[incompatible-type]
+    let currentValue: ?TValue = cache.get(scope, id);
+
+    // If we have an initial value, we need to add it to the cache
+    // and use it as our current value.
+    if (currentValue == null && initialValue !== undefined) {
+        // Get the initial value.
+        const value =
+            typeof initialValue === "function" ? initialValue() : initialValue;
+
+        // Update the cache.
+        cacheValue(value);
+
+        // Make sure we return this value as our current value.
+        currentValue = value;
+    }
+
+    // Now we have everything, let's return it.
+    return [currentValue, cacheValue];
+};

package/src/index.js

@@ -1,25 +1,23 @@
 // @flow
 import {Server} from "@khanacademy/wonder-blocks-core";
-import {ResponseCache as ResCache} from "./util/response-cache.js";
+import {SsrCache} from "./util/ssr-cache.js";
 import {RequestTracker} from "./util/request-tracking.js";
 
 import type {
-    ValidData,
-    CacheEntry,
-    IRequestHandler,
+    ValidCacheData,
+    CachedResponse,
     ResponseCache,
 } from "./util/types.js";
 
 export type {
-    Cache,
-    CacheEntry,
-    Result,
-    IRequestHandler,
     ResponseCache,
+    CachedResponse,
+    Result,
+    ScopedCache,
 } from "./util/types.js";
 
 export const initializeCache = (source: ResponseCache): void =>
-    ResCache.Default.initialize(source);
+    SsrCache.Default.initialize(source);
 
 export const fulfillAllDataRequests = (): Promise<ResponseCache> => {
     if (!Server.isServerSide()) {
@@ -37,24 +35,23 @@ export const hasUnfulfilledRequests = (): boolean => {
     return RequestTracker.Default.hasUnfulfilledRequests;
 };
 
-export const removeFromCache = <TOptions, TData: ValidData>(
-    handler: IRequestHandler<TOptions, TData>,
-    options: TOptions,
-): boolean => ResCache.Default.remove<TOptions, TData>(handler, options);
+export const removeFromCache = (id: string): boolean =>
+    SsrCache.Default.remove(id);
 
-export const removeAllFromCache = <TOptions, TData: ValidData>(
-    handler: IRequestHandler<TOptions, TData>,
+export const removeAllFromCache = (
     predicate?: (
         key: string,
-        cacheEntry: ?$ReadOnly<CacheEntry<TData>>,
+        cacheEntry: ?$ReadOnly<CachedResponse<ValidCacheData>>,
     ) => boolean,
-): number => ResCache.Default.removeAll<TOptions, TData>(handler, predicate);
+): void => SsrCache.Default.removeAll(predicate);
 
-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 {useData} from "./hooks/use-data.js";
+export {default as InterceptRequests} from "./components/intercept-requests.js";
+export {useServerEffect} from "./hooks/use-server-effect.js";
+export {useRequestInterception} from "./hooks/use-request-interception.js";
+export {useSharedCache, clearSharedCache} from "./hooks/use-shared-cache.js";
+export {ScopedInMemoryCache} from "./util/scoped-in-memory-cache.js";
 
 // GraphQL
 export {GqlRouter} from "./components/gql-router.js";