@khanacademy/wonder-blocks-data 8.0.4 → 9.1.0

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

@@ -19,12 +19,12 @@ function useSharedCache<TValue: ValidCacheData>(
 ): [?TValue, CacheValueFn<TValue>];
 ```
 
-The `useSharedCache` hook provides access to a shared in-memory cache. This cache is not part of the cache hydrated by Wonder Blocks Data, so [`purgeSharedCache`](/docs/data-exports-purgesharedcache--page) must be called between server-side render cycles.
+The `useSharedCache` hook provides access to a shared in-memory cache. This cache is not part of the cache hydrated by Wonder Blocks Data, so [`SharedCache.purgeAll()`](/docs/data-exports-sharedcache--page) must be called between server-side render cycles.
 
 The hook returns a tuple of the currently cached value, or `null` if none is cached, and a function that can be used to set the cached value.
 
 The shared cache is passive and as such does not notify of changes to its contents.
 
-Each cached item is identified by an id and a scope. The scope is used to group items. Whole scopes can be cleared by specifying the specific scope when calling [`purgeSharedCache`](/docs/data-exports-purgesharedcache--page).
+Each cached item is identified by an id and a scope. The scope is used to group items. Whole scopes can be cleared by specifying the specific scope when calling [`SharedCache.purgeScope()`](/docs/data-exports-sharedcache--page).
 
 An optional argument, `initialValue` can be given. This can be either the value to be cached itself or a function that returns the value to be cached  (functions themselves are not valid cachable values). This allows for expensive initialization to only occur when it is necessary.

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-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__/get-gql-request-id.test.js

@@ -71,4 +71,37 @@ describe("#getGqlRequestId", () => {
             `variable1=value1&variable2=42&variable3=&variable4=null&variable5=true`,
         );
     });
+
+    it("should sort nested variable properties", () => {
+        // Arrange
+        const operation = {
+            type: "query",
+            id: "myQuery",
+        };
+        const variables = {
+            variable4: null,
+            variable2: 42,
+            variable1: "value1",
+            variable5: true,
+            variable3: undefined,
+            variable6: {
+                nested2: "nested2",
+                nested1: "nested1",
+            },
+            variable7: [1, 2, 3],
+        };
+
+        // Act
+        const requestId = getGqlRequestId(operation, variables, {
+            module: "MODULE",
+            curriculum: "CURRICULUM",
+            targetLocale: "LOCALE",
+        });
+        const result = new Set(requestId.split("|"));
+
+        // Assert
+        expect(result).toContain(
+            `variable1=value1&variable2=42&variable3=&variable4=null&variable5=true&variable6.nested1=nested1&variable6.nested2=nested2&variable7.0=1&variable7.1=2&variable7.2=3`,
+        );
+    });
 });

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/get-gql-request-id.js

@@ -1,11 +1,28 @@
 // @flow
 import type {GqlOperation, GqlContext} from "./gql-types.js";
 
-const toString = (valid: mixed): string => {
-    if (typeof valid === "string") {
-        return valid;
+const toString = (value: mixed): string => {
+    if (typeof value === "string") {
+        return value;
     }
-    return JSON.stringify(valid) ?? "";
+    return JSON.stringify(value) ?? "";
+};
+
+const toStringifiedVariables = (acc: any, key: string, value: mixed): any => {
+    if (typeof value === "object" && value !== null) {
+        // If we have an object or array, we build sub-variables so that
+        // the ID is easily human-readable rather than having lots of
+        // extra %-encodings. This means that an object or array variable
+        // turns into x variables, where x is the field or element count of
+        // variable. See below for example.
+        return Object.entries(value).reduce((innerAcc, [i, v]) => {
+            const subKey = `${key}.${i}`;
+            return toStringifiedVariables(innerAcc, subKey, v);
+        }, acc);
+    } else {
+        acc[key] = toString(value);
+    }
+    return acc;
 };
 
 /**
@@ -32,10 +49,37 @@ export const getGqlRequestId = <TData, TVariables: {...}>(
     // Finally, if we have variables, we add those too.
     if (variables != null) {
         // We need to turn each variable into a string.
+        // We also need to ensure we sort any sub-object keys.
+        // `toStringifiedVariables` helps us with this by hoisting nested
+        // data to individual variables for the purposes of ID generation.
+        //
+        // For example, consider variables:
+        //    {x: [1,2,3], y: {a: 1, b: 2, c: 3}, z: 123}
+        //
+        // Each variable, x, y and z, would be stringified into
+        // stringifiedVariables as follows:
+        //  x becomes {"x.0": "1", "x.1": "2", "x.2": "3"}
+        //  y becomes {"y.a": "1", "y.b": "2", "y.c": "3"}
+        //  z becomes {"z": "123"}
+        //
+        // This then leads to stringifiedVariables being:
+        //  {
+        //    "x.0": "1",
+        //    "x.1": "2",
+        //    "x.2": "3",
+        //    "y.a": "1",
+        //    "y.b": "2",
+        //    "y.c": "3",
+        //    "z": "123",
+        //  }
+        //
+        // Thus allowing our use of URLSearchParams to both sort and easily
+        // encode the variables into an idempotent identifier for those
+        // variable values that is also human-readable.
         const stringifiedVariables = Object.keys(variables).reduce(
             (acc, key) => {
-                acc[key] = toString(variables[key]);
-                return acc;
+                const value = variables[key];
+                return toStringifiedVariables(acc, key, value);
             },
             {},
         );

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

@@ -84,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.
      */
@@ -112,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.