@khanacademy/wonder-blocks-data 3.1.1 → 4.0.0

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-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>(
+    id: 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>(id);
+
+    // 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);
+    }
+
+    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,22 @@ 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 {useServerEffect} from "./hooks/use-server-effect.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";

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

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

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

@@ -1,9 +1,7 @@
 // @flow
-import {ResponseCache} from "../response-cache.js";
+import {SsrCache} from "../ssr-cache.js";
 import {RequestFulfillment} from "../request-fulfillment.js";
 
-import type {IRequestHandler} from "../types.js";
-
 describe("RequestFulfillment", () => {
     it("should provide static default instance", () => {
         // Arrange
@@ -19,93 +17,66 @@ describe("RequestFulfillment", () => {
     describe("#fulfill", () => {
         it("should attempt to cache errors caused directly by handlers", async () => {
             // Arrange
-            const responseCache = new ResponseCache();
+            const responseCache = new SsrCache();
             const requestFulfillment = new RequestFulfillment(responseCache);
             const error = new Error("OH NO!");
-            const fakeBadHandler: IRequestHandler<any, any> = {
-                fulfillRequest: () => {
-                    throw error;
-                },
-                getKey: jest.fn().mockReturnValue("MY_KEY"),
-                type: "MY_TYPE",
-                hydrate: true,
+            const fakeBadHandler = () => {
+                throw error;
             };
             const cacheErrorSpy = jest.spyOn(responseCache, "cacheError");
 
             // Act
-            await requestFulfillment.fulfill(fakeBadHandler, "OPTIONS");
+            await requestFulfillment.fulfill("ID", {
+                handler: fakeBadHandler,
+            });
 
             // Assert
-            expect(cacheErrorSpy).toHaveBeenCalledWith(
-                fakeBadHandler,
-                "OPTIONS",
-                error,
-            );
+            expect(cacheErrorSpy).toHaveBeenCalledWith("ID", error, true);
         });
 
         it("should cache errors occurring in promises", async () => {
             // Arrange
-            const responseCache = new ResponseCache();
+            const responseCache = new SsrCache();
             const requestFulfillment = new RequestFulfillment(responseCache);
-            const fakeBadRequestHandler: IRequestHandler<string, any> = {
-                fulfillRequest: () =>
-                    new Promise((resolve, reject) => reject("OH NO!")),
-                getKey: (o) => o,
-                type: "BAD_REQUEST",
-                hydrate: true,
-            };
+            const fakeBadRequestHandler = () =>
+                new Promise((resolve, reject) => reject("OH NO!"));
             const cacheErrorSpy = jest.spyOn(responseCache, "cacheError");
 
             // Act
-            await requestFulfillment.fulfill(fakeBadRequestHandler, "OPTIONS");
+            await requestFulfillment.fulfill("ID", {
+                handler: fakeBadRequestHandler,
+            });
 
             // Assert
-            expect(cacheErrorSpy).toHaveBeenCalledWith(
-                fakeBadRequestHandler,
-                "OPTIONS",
-                "OH NO!",
-            );
+            expect(cacheErrorSpy).toHaveBeenCalledWith("ID", "OH NO!", true);
         });
 
         it("should cache data from requests", async () => {
             // Arrange
-            const responseCache = new ResponseCache();
+            const responseCache = new SsrCache();
             const requestFulfillment = new RequestFulfillment(responseCache);
-            const fakeRequestHandler: IRequestHandler<string, any> = {
-                fulfillRequest: () => Promise.resolve("DATA!"),
-                getKey: (o) => o,
-                type: "VALID_REQUEST",
-                hydrate: true,
-            };
+            const fakeRequestHandler = () => Promise.resolve("DATA!");
             const cacheDataSpy = jest.spyOn(responseCache, "cacheData");
 
             // Act
-            await requestFulfillment.fulfill(fakeRequestHandler, "OPTIONS");
+            await requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
 
             // Assert
-            expect(cacheDataSpy).toHaveBeenCalledWith(
-                fakeRequestHandler,
-                "OPTIONS",
-                "DATA!",
-            );
+            expect(cacheDataSpy).toHaveBeenCalledWith("ID", "DATA!", true);
         });
 
         it("should return a promise of the result", async () => {
             // Arrange
-            const responseCache = new ResponseCache();
+            const responseCache = new SsrCache();
             const requestFulfillment = new RequestFulfillment(responseCache);
-            const fakeRequestHandler: IRequestHandler<string, any> = {
-                fulfillRequest: () => Promise.resolve("DATA!"),
-                getKey: (o) => o,
-                type: "VALID_REQUEST",
-                hydrate: true,
-            };
+            const fakeRequestHandler = () => Promise.resolve("DATA!");
 
             // Act
-            const result = await requestFulfillment.fulfill(
-                fakeRequestHandler,
-                "OPTIONS",
-            );
+            const result = await requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
 
             // Assert
             expect(result).toStrictEqual({
@@ -115,24 +86,17 @@ describe("RequestFulfillment", () => {
 
         it("should reuse inflight requests", () => {
             // Arrange
-            const responseCache = new ResponseCache();
+            const responseCache = new SsrCache();
             const requestFulfillment = new RequestFulfillment(responseCache);
-            const fakeRequestHandler: IRequestHandler<string, any> = {
-                fulfillRequest: () => Promise.resolve("DATA!"),
-                getKey: (o) => o,
-                type: "VALID_REQUEST",
-                hydrate: true,
-            };
+            const fakeRequestHandler = () => Promise.resolve("DATA!");
 
             // Act
-            const promise = requestFulfillment.fulfill(
-                fakeRequestHandler,
-                "OPTIONS",
-            );
-            const result = requestFulfillment.fulfill(
-                fakeRequestHandler,
-                "OPTIONS",
-            );
+            const promise = requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
+            const result = requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
 
             // Assert
             expect(result).toBe(promise);
@@ -140,25 +104,18 @@ describe("RequestFulfillment", () => {
 
         it("should remove inflight requests upon completion", async () => {
             // Arrange
-            const responseCache = new ResponseCache();
+            const responseCache = new SsrCache();
             const requestFulfillment = new RequestFulfillment(responseCache);
-            const fakeRequestHandler: IRequestHandler<string, any> = {
-                fulfillRequest: () => Promise.resolve("DATA!"),
-                getKey: (o) => o,
-                type: "VALID_REQUEST",
-                hydrate: false,
-            };
+            const fakeRequestHandler = () => Promise.resolve("DATA!");
 
             // Act
-            const promise = requestFulfillment.fulfill(
-                fakeRequestHandler,
-                "OPTIONS",
-            );
+            const promise = requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
             await promise;
-            const result = requestFulfillment.fulfill(
-                fakeRequestHandler,
-                "OPTIONS",
-            );
+            const result = requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
 
             // Assert
             expect(result).not.toBe(promise);