@khanacademy/wonder-blocks-data 8.0.3 → 9.0.0

package/src/__docs__/types.raw-scoped-cache.stories.mdx

@@ -0,0 +1,27 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / RawScopedCache"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# RawScopedCache
+
+```ts
+type RawScopedCache = {
+    [scope: string]: {
+        [id: string]: ValidCacheData,
+        ...
+    },
+    ...
+};
+
+```
+
+`RawScopedCache` describes a cache that has distinct scoped sections in its raw object form. This is the representation of the caches used internally by Wonder Blocks Data to support the scoping of requests when using hooks such as [`useSharedCache`](/docs/data-exports-use-shared-cache--page), [`useCachedEffect`](/docs/data-exports-use-cached-effect--page), and [`useHydratableEffect`](/docs/data-exports-use-hydratable-effect--page).
+
+See the section on [server-side rendering](/docs/data-server-side-rendering-and-hydration--page) for more information.

package/src/__docs__/types.scoped-cache.stories.mdx

@@ -12,16 +12,103 @@ import {Meta} from "@storybook/addon-docs";
 # ScopedCache
 
 ```ts
-type ScopedCache = {
-    [scope: string]: {
-        [id: string]: ValidCacheData,
-        ...
-    },
-    ...
-};
+interface ScopedCache {
+    set(scope: string, id: string, value: ValidCacheData): void;
 
+    /**
+     * Retrieve a value from the cache.
+     */
+    get(scope: string, id: string): ?ValidCacheData;
+
+    /**
+     * Purge an item from the cache.
+     */
+    purge(scope: string, id: string): void;
+
+    /**
+     * Purge a scope of items that match the given predicate.
+     *
+     * If the predicate is omitted, then all items in the scope are purged.
+     */
+    purgeScope(
+        scope: string,
+        predicate?: (id: string, value: ValidCacheData) => boolean,
+    ): void;
+
+    /**
+     * Purge all items from the cache that match the given predicate.
+     *
+     * If the predicate is omitted, then all items in the cache are purged.
+     */
+    purgeAll(
+        predicate?: (
+            scope: string,
+            id: string,
+            value: ValidCacheData,
+        ) => boolean,
+    ): void;
+}
+```
+
+This interface defines how to interact with a scoped cache, such as [`ScopedInMemoryCache`](/docs/data-exports-scopedinmemorycache--page).
+
+## set()
+
+```ts
+set(
+    scope: string,
+    id: string,
+    value: TValue,
+): void;
+```
+
+Sets a value in the cache within a given scope.
+
+### Throws
+
+| Error Type | Error Name | Reason |
+| ------ | ------ | ------ |
+| [`DataError`](/docs/data-exports-dataerror--page) | `InvalidInputDataError` | `id` and `scope` must be non-empty strings |
+| [`DataError`](/docs/data-exports-dataerror--page) | `InvalidInputDataError` | `value` must be a non-function value |
+
+## get()
+
+```ts
+get(scope: string, id: string): ?ValidCacheData;
+```
+
+Gets a value from the cache. If a value with the given identifier (`id`) is not found within the given scope (`scope`) of the cache, `null` is returned.
+
+## purge()
+
+```ts
+purge(scope: string, id: string): void;
+```
+
+Purges the value from the cache. If a value with the given identifier (`id`) is not found within the given scope (`scope`) of the cache, nothing happens.
+
+## purgeScope()
+
+```ts
+purgeScope(
+    scope: string,
+    predicate?: (id: string, value: ValidCacheData) => boolean,
+): void;
+```
+
+Purges items within a given scope (`scope`) of the cache from that scope. If a predicate is provided, only items for which the predicate returns `true` will be purged; otherwise, the entire scope will be purged.
+
+## purgeAll()
+
+```ts
+purgeAll(
+    predicate?: (
+        scope: string,
+        id: string,
+        value: ValidCacheData,
+    ) => boolean,
+): void;
 ```
 
-`ScopedCache` describes a cache that has distinct scoped sections. This is the representation of the caches used internally by Wonder Blocks Data to support the scoping of requests when using hooks such as [`useSharedCache`](/docs/data-exports-use-shared-cache--page), [`useCachedEffect`](/docs/data-exports-use-cached-effect--page), and [`useHydratableEffect`](/docs/data-exports-use-hydratable-effect--page).
+Purges all items from the cache. If a predicate is provided, only items for which the predicate returns `true` will be purged; otherwise, the entire cache will be purged.
 
-See the section on [server-side rendering](/docs/data-server-side-rendering-and-hydration--page) for more information.

package/src/components/__tests__/data.test.js

@@ -7,7 +7,7 @@ import {render, act} from "@testing-library/react";
 import * as ReactDOMServer from "react-dom/server";
 import {Server, View} from "@khanacademy/wonder-blocks-core";
 
-import {purgeSharedCache} from "../../hooks/use-shared-cache.js";
+import {SharedCache} from "../../hooks/use-shared-cache.js";
 import TrackData from "../track-data.js";
 import {RequestFulfillment} from "../../util/request-fulfillment.js";
 import {SsrCache} from "../../util/ssr-cache.js";
@@ -24,7 +24,7 @@ import {
 
 describe("Data", () => {
     beforeEach(() => {
-        purgeSharedCache();
+        SharedCache.purgeAll();
 
         const responseCache = new SsrCache();
         jest.spyOn(SsrCache, "Default", "get").mockReturnValue(responseCache);

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

@@ -1,11 +1,11 @@
 // @flow
 import {renderHook as clientRenderHook} from "@testing-library/react-hooks";
 
-import {useSharedCache, purgeSharedCache} from "../use-shared-cache.js";
+import {useSharedCache, SharedCache} from "../use-shared-cache.js";
 
 describe("#useSharedCache", () => {
     beforeEach(() => {
-        purgeSharedCache();
+        SharedCache.purgeAll();
     });
 
     it.each`
@@ -257,51 +257,3 @@ describe("#useSharedCache", () => {
         expect(result).toBeNull();
     });
 });
-
-describe("#purgeSharedCache", () => {
-    beforeEach(() => {
-        purgeSharedCache();
-    });
-
-    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
-        purgeSharedCache();
-        // 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
-        purgeSharedCache("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-cached-effect.js

@@ -232,10 +232,6 @@ export const useCachedEffect = <TData: ValidCacheData>(
         fetchPolicy,
     ]);
 
-    // We need to trigger a re-render when the request ID changes as that
-    // indicates its a different request.
-    const requestIdRef = React.useRef(requestId);
-
     // Calculate if we want to fetch the result or not.
     // If this is true, we will do a new fetch, cancelling the previous fetch
     // if there is one inflight.
@@ -252,12 +248,8 @@ export const useCachedEffect = <TData: ValidCacheData>(
                 return false;
 
             case FetchPolicy.CacheBeforeNetwork:
-                // If we don't have a cached value or this is a new requestId,
-                // then we need to fetch.
-                return (
-                    mostRecentResult == null ||
-                    requestId !== requestIdRef.current
-                );
+                // If we don't have a cached value then we need to fetch.
+                return mostRecentResult == null;
 
             case FetchPolicy.CacheAndNetwork:
             case FetchPolicy.NetworkOnly:
@@ -265,10 +257,7 @@ export const useCachedEffect = <TData: ValidCacheData>(
                 // result, then we need to fetch one.
                 return networkResultRef.current == null;
         }
-    }, [requestId, mostRecentResult, fetchPolicy, hardSkip]);
-
-    // Let's make sure our ref is set to the most recent requestId.
-    requestIdRef.current = requestId;
+    }, [mostRecentResult, fetchPolicy, hardSkip]);
 
     React.useEffect(() => {
         if (!shouldFetch) {

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

@@ -16,9 +16,6 @@ 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.
@@ -52,7 +49,6 @@ export enum WhenClientSide {
      * hydrated result status.
      */
     AlwaysExecute,
-    /* eslint-enable no-undef */
 }
 
 type HydratableEffectOptions<TData: ValidCacheData> = {|

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

@@ -2,7 +2,7 @@
 import * as React from "react";
 import {DataError, DataErrors} from "../util/data-error.js";
 import {ScopedInMemoryCache} from "../util/scoped-in-memory-cache.js";
-import type {ValidCacheData} from "../util/types.js";
+import type {ValidCacheData, ScopedCache} from "../util/types.js";
 
 /**
  * A function for inserting a value into the cache or clearing it.
@@ -17,17 +17,12 @@ type CacheValueFn<TValue: ValidCacheData> = (value: ?TValue) => void;
 const cache = new ScopedInMemoryCache();
 
 /**
- * Purge the in-memory cache or a single scope within it.
+ * Access to the shared in-memory cache.
+ *
+ * This is the cache used by `useSharedCache` and related hooks and
+ * components.
  */
-export const purgeSharedCache = (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();
-    }
-};
+export const SharedCache: ScopedCache = cache;
 
 /**
  * Hook to retrieve data from and store data in an in-memory cache.
@@ -37,9 +32,6 @@ export const purgeSharedCache = (scope: string = "") => {
  * 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

package/src/index.js

@@ -9,8 +9,9 @@ export type {
     ResponseCache,
     CachedResponse,
     Result,
-    ScopedCache,
+    RawScopedCache,
     ValidCacheData,
+    ScopedCache,
 } from "./util/types.js";
 
 export * from "./util/hydration-cache-api.js";
@@ -22,7 +23,7 @@ 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 {useCachedEffect} from "./hooks/use-cached-effect.js";
-export {useSharedCache, purgeSharedCache} from "./hooks/use-shared-cache.js";
+export {useSharedCache, SharedCache} from "./hooks/use-shared-cache.js";
 export {
     useHydratableEffect,
     // TODO(somewhatabstract, FEI-4174): Update eslint-plugin-import when they
@@ -39,6 +40,7 @@ export {Status} from "./util/status.js";
 // GraphQL
 ////////////////////////////////////////////////////////////////////////////////
 export {getGqlRequestId} from "./util/get-gql-request-id.js";
+export {getGqlDataFromResponse} from "./util/get-gql-data-from-response.js";
 export {graphQLDocumentNodeParser} from "./util/graphql-document-node-parser.js";
 export {toGqlOperation} from "./util/to-gql-operation.js";
 export {GqlRouter} from "./components/gql-router.js";

package/src/util/__tests__/purge-caches.test.js

@@ -1,5 +1,5 @@
 // @flow
-import * as UseSharedCache from "../../hooks/use-shared-cache.js";
+import {SharedCache} from "../../hooks/use-shared-cache.js";
 import * as HydrationCacheApi from "../hydration-cache-api.js";
 
 import {purgeCaches} from "../purge-caches.js";
@@ -7,7 +7,7 @@ import {purgeCaches} from "../purge-caches.js";
 describe("#purgeCaches", () => {
     it("should purge the shared cache", () => {
         // Arrange
-        const spy = jest.spyOn(UseSharedCache, "purgeSharedCache");
+        const spy = jest.spyOn(SharedCache, "purgeAll");
 
         // Act
         purgeCaches();

package/src/util/purge-caches.js

@@ -1,5 +1,5 @@
 // @flow
-import {purgeSharedCache} from "../hooks/use-shared-cache.js";
+import {SharedCache} from "../hooks/use-shared-cache.js";
 import {purgeHydrationCache} from "./hydration-cache-api.js";
 
 /**
@@ -10,6 +10,6 @@ import {purgeHydrationCache} from "./hydration-cache-api.js";
  * which caches may have been used during a given test run.
  */
 export const purgeCaches = () => {
-    purgeSharedCache();
+    SharedCache.purgeAll();
     purgeHydrationCache();
 };

package/src/util/scoped-in-memory-cache.js

@@ -1,14 +1,14 @@
 // @flow
 import {DataError, DataErrors} from "./data-error.js";
-import type {ScopedCache, ValidCacheData} from "./types.js";
+import type {ScopedCache, RawScopedCache, ValidCacheData} from "./types.js";
 
 /**
  * Describe an in-memory cache.
  */
-export class ScopedInMemoryCache {
-    _cache: ScopedCache;
+export class ScopedInMemoryCache implements ScopedCache {
+    _cache: RawScopedCache;
 
-    constructor(initialCache: ScopedCache = {}) {
+    constructor(initialCache: RawScopedCache = {}) {
         this._cache = initialCache;
     }
 
@@ -24,11 +24,7 @@ export class ScopedInMemoryCache {
     /**
      * Set a value in the cache.
      */
-    set<TValue: ValidCacheData>(
-        scope: string,
-        id: string,
-        value: TValue,
-    ): void {
+    set(scope: string, id: string, value: ValidCacheData): void {
         if (!id || typeof id !== "string") {
             throw new DataError(
                 "id must be non-empty string",

package/src/util/serializable-in-memory-cache.js

@@ -2,13 +2,13 @@
 import {clone} from "@khanacademy/wonder-stuff-core";
 import {DataError, DataErrors} from "./data-error.js";
 import {ScopedInMemoryCache} from "./scoped-in-memory-cache.js";
-import type {ValidCacheData, ScopedCache} from "./types.js";
+import type {ValidCacheData, RawScopedCache} from "./types.js";
 
 /**
  * Describe a serializable in-memory cache.
  */
 export class SerializableInMemoryCache extends ScopedInMemoryCache {
-    constructor(initialCache: ScopedCache = {}) {
+    constructor(initialCache: RawScopedCache = {}) {
         try {
             super(clone(initialCache));
         } catch (e) {
@@ -22,18 +22,14 @@ export class SerializableInMemoryCache extends ScopedInMemoryCache {
     /**
      * Set a value in the cache.
      */
-    set<TValue: ValidCacheData>(
-        scope: string,
-        id: string,
-        value: TValue,
-    ): void {
+    set(scope: string, id: string, value: ValidCacheData): void {
         super.set(scope, id, Object.freeze(clone(value)));
     }
 
     /**
      * Clone the cache.
      */
-    clone(): ScopedCache {
+    clone(): RawScopedCache {
         try {
             return clone(this._cache);
         } catch (e) {

package/src/util/types.js

@@ -1,9 +1,6 @@
 // @flow
 import type {Metadata} from "@khanacademy/wonder-stuff-core";
 
-// 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 */
 /**
  * Defines the various fetch policies that can be applied to requests.
  */
@@ -30,7 +27,6 @@ export enum FetchPolicy {
      */
     NetworkOnly,
 }
-/* eslint-enable no-undef */
 
 /**
  * Define what can be cached.
@@ -88,7 +84,7 @@ export type ResponseCache = {
 /**
  * A cache with scoped sections.
  */
-export type ScopedCache = {
+export type RawScopedCache = {
     /**
      * The cache is scoped to allow easier clearing of different types of usage.
      */
@@ -116,3 +112,40 @@ export type ErrorOptions = {|
      */
     cause?: ?Error,
 |};
+
+export interface ScopedCache {
+    set(scope: string, id: string, value: ValidCacheData): void;
+
+    /**
+     * Retrieve a value from the cache.
+     */
+    get(scope: string, id: string): ?ValidCacheData;
+
+    /**
+     * Purge an item from the cache.
+     */
+    purge(scope: string, id: string): void;
+
+    /**
+     * Purge a scope of items that match the given predicate.
+     *
+     * If the predicate is omitted, then all items in the scope are purged.
+     */
+    purgeScope(
+        scope: string,
+        predicate?: (id: string, value: ValidCacheData) => boolean,
+    ): void;
+
+    /**
+     * Purge all items from the cache that match the given predicate.
+     *
+     * If the predicate is omitted, then all items in the cache are purged.
+     */
+    purgeAll(
+        predicate?: (
+            scope: string,
+            id: string,
+            value: ValidCacheData,
+        ) => boolean,
+    ): void;
+}

package/src/__docs__/exports.purge-shared-cache.stories.mdx

@@ -1,20 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Data / Exports / purgeSharedCache()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# purgeSharedCache()
-
-```ts
-purgeSharedCache(scope?: string): void;
-```
-
-The `purgeSharedCache` method can be used to clear the shared in-memory cache used by the [`useSharedCache`](/docs/data-exports-usesharedcache--page) hook. Either a single scope or all scopes can be cleared.
-
-Common uses for calling this method are during [server-side rendering](/docs/data-server-side-rendering-and-hydration--page) to ensure each render cycle remains isolated, or during testing in a `beforeEach` to cover for where previous test cases may have changed the shared cache.