@khanacademy/wonder-blocks-data 3.2.0 → 4.0.0

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);