@khanacademy/wonder-blocks-data 8.0.5 → 9.1.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @khanacademy/wonder-blocks-data
 
+## 9.1.1
+
+### Patch Changes
+
+-   eb59ce34: Update to latest Wonder Stuff Core
+
+## 9.1.0
+
+### Minor Changes
+
+-   944c3071: Make sure objects and arrays in variables are sorted and readable in generated request identifiers
+
+## 9.0.0
+
+### Major Changes
+
+-   778f8e43: `SharedCache` export added for interacting with the shared in-memory cache. `purgeSharedCache` method has been removed.
+-   778f8e43: Rename `ScopedCache` type to `RawScopedCache`
+
 ## 8.0.5
 
 ### Patch Changes

package/dist/es/index.js

@@ -390,13 +390,7 @@ const abortInflightRequests = () => {
 };
 
 const cache$1 = new ScopedInMemoryCache();
-const purgeSharedCache = (scope = "") => {
-  if (scope && typeof scope === "string") {
-    cache$1.purgeScope(scope);
-  } else {
-    cache$1.purgeAll();
-  }
-};
+const SharedCache = cache$1;
 const useSharedCache = (id, scope, initialValue) => {
   if (!id || typeof id !== "string") {
     throw new DataError("id must be a non-empty string", DataErrors.InvalidInput);
@@ -422,7 +416,7 @@ const useSharedCache = (id, scope, initialValue) => {
 };
 
 const purgeCaches = () => {
-  purgeSharedCache();
+  SharedCache.purgeAll();
   purgeHydrationCache();
 };
 
@@ -689,14 +683,27 @@ const InterceptRequests = ({
   }, children);
 };
 
-const toString = valid => {
+const toString = value => {
   var _JSON$stringify;
 
-  if (typeof valid === "string") {
-    return valid;
+  if (typeof value === "string") {
+    return value;
+  }
+
+  return (_JSON$stringify = JSON.stringify(value)) != null ? _JSON$stringify : "";
+};
+
+const toStringifiedVariables = (acc, key, value) => {
+  if (typeof value === "object" && value !== null) {
+    return Object.entries(value).reduce((innerAcc, [i, v]) => {
+      const subKey = `${key}.${i}`;
+      return toStringifiedVariables(innerAcc, subKey, v);
+    }, acc);
+  } else {
+    acc[key] = toString(value);
   }
 
-  return (_JSON$stringify = JSON.stringify(valid)) != null ? _JSON$stringify : "";
+  return acc;
 };
 
 const getGqlRequestId = (operation, variables, context) => {
@@ -708,8 +715,8 @@ const getGqlRequestId = (operation, variables, context) => {
 
   if (variables != null) {
     const stringifiedVariables = Object.keys(variables).reduce((acc, key) => {
-      acc[key] = toString(variables[key]);
-      return acc;
+      const value = variables[key];
+      return toStringifiedVariables(acc, key, value);
     }, {});
     const sortableVariables = new URLSearchParams(stringifiedVariables);
     sortableVariables.sort();
@@ -934,4 +941,4 @@ const useGql = (context = {}) => {
   return gqlFetch;
 };
 
-export { Data, DataError, DataErrors, FetchPolicy, GqlError, GqlErrors, GqlRouter, InterceptRequests, ScopedInMemoryCache, SerializableInMemoryCache, Status, TrackData, WhenClientSide, abortInflightRequests, fetchTrackedRequests, getGqlDataFromResponse, getGqlRequestId, graphQLDocumentNodeParser, hasTrackedRequestsToBeFetched, initializeHydrationCache, purgeCaches, purgeHydrationCache, purgeSharedCache, toGqlOperation, useCachedEffect, useGql, useHydratableEffect, useServerEffect, useSharedCache };
+export { Data, DataError, DataErrors, FetchPolicy, GqlError, GqlErrors, GqlRouter, InterceptRequests, ScopedInMemoryCache, SerializableInMemoryCache, SharedCache, Status, TrackData, WhenClientSide, abortInflightRequests, fetchTrackedRequests, getGqlDataFromResponse, getGqlRequestId, graphQLDocumentNodeParser, hasTrackedRequestsToBeFetched, initializeHydrationCache, purgeCaches, purgeHydrationCache, toGqlOperation, useCachedEffect, useGql, useHydratableEffect, useServerEffect, useSharedCache };

package/dist/index.js

@@ -242,7 +242,7 @@ class GqlError extends _khanacademy_wonder_stuff_core__WEBPACK_IMPORTED_MODULE_0
 /***/ (function(module, __webpack_exports__, __webpack_require__) {
 
 "use strict";
-/* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return purgeSharedCache; });
+/* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return SharedCache; });
 /* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "b", function() { return useSharedCache; });
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0__ = __webpack_require__(1);
 /* harmony import */ var react__WEBPACK_IMPORTED_MODULE_0___default = /*#__PURE__*/__webpack_require__.n(react__WEBPACK_IMPORTED_MODULE_0__);
@@ -259,18 +259,13 @@ class GqlError extends _khanacademy_wonder_stuff_core__WEBPACK_IMPORTED_MODULE_0
  */
 const cache = new _util_scoped_in_memory_cache_js__WEBPACK_IMPORTED_MODULE_2__[/* ScopedInMemoryCache */ "a"]();
 /**
- * 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.
  */
 
-const purgeSharedCache = (scope = "") => {
-  // 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();
-  }
-};
+const SharedCache = cache;
 /**
  * Hook to retrieve data from and store data in an in-memory cache.
  *
@@ -279,9 +274,6 @@ const purgeSharedCache = (scope = "") => {
  * 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
@@ -1737,7 +1729,7 @@ const abortInflightRequests = () => {
  */
 
 const purgeCaches = () => {
-  Object(_hooks_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_0__[/* purgeSharedCache */ "a"])();
+  _hooks_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_0__[/* SharedCache */ "a"].purgeAll();
   Object(_hydration_cache_api_js__WEBPACK_IMPORTED_MODULE_1__[/* purgeHydrationCache */ "b"])();
 };
 
@@ -1851,14 +1843,32 @@ const InterceptRequests = ({
 
 "use strict";
 /* harmony export (binding) */ __webpack_require__.d(__webpack_exports__, "a", function() { return getGqlRequestId; });
-const toString = valid => {
+const toString = value => {
   var _JSON$stringify;
 
-  if (typeof valid === "string") {
-    return valid;
+  if (typeof value === "string") {
+    return value;
+  }
+
+  return (_JSON$stringify = JSON.stringify(value)) != null ? _JSON$stringify : "";
+};
+
+const toStringifiedVariables = (acc, key, value) => {
+  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 (_JSON$stringify = JSON.stringify(valid)) != null ? _JSON$stringify : "";
+  return acc;
 };
 /**
  * Get an identifier for a given request.
@@ -1879,9 +1889,36 @@ const getGqlRequestId = (operation, variables, context) => {
 
   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);
     }, {}); // We use the same mechanism as context to sort and arrange the
     // variables.
 
@@ -2174,7 +2211,7 @@ __webpack_require__.r(__webpack_exports__);
 /* harmony import */ var _hooks_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_10__ = __webpack_require__(5);
 /* harmony reexport (safe) */ __webpack_require__.d(__webpack_exports__, "useSharedCache", function() { return _hooks_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_10__["b"]; });
 
-/* harmony reexport (safe) */ __webpack_require__.d(__webpack_exports__, "purgeSharedCache", function() { return _hooks_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_10__["a"]; });
+/* harmony reexport (safe) */ __webpack_require__.d(__webpack_exports__, "SharedCache", function() { return _hooks_use_shared_cache_js__WEBPACK_IMPORTED_MODULE_10__["a"]; });
 
 /* harmony import */ var _hooks_use_hydratable_effect_js__WEBPACK_IMPORTED_MODULE_11__ = __webpack_require__(12);
 /* harmony reexport (safe) */ __webpack_require__.d(__webpack_exports__, "useHydratableEffect", function() { return _hooks_use_hydratable_effect_js__WEBPACK_IMPORTED_MODULE_11__["b"]; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-data",
-  "version": "8.0.5",
+  "version": "9.1.1",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -17,7 +17,7 @@
     "@khanacademy/wonder-blocks-core": "^4.3.2"
   },
   "peerDependencies": {
-    "@khanacademy/wonder-stuff-core": "^0.1.2",
+    "@khanacademy/wonder-stuff-core": "^1.0.1",
     "flow-enums-runtime": "^0.0.6",
     "react": "16.14.0"
   },
@@ -26,4 +26,4 @@
   },
   "author": "",
   "license": "MIT"
-}
+}

package/src/__docs__/_overview_ssr_.stories.mdx

@@ -86,7 +86,7 @@ import {
     TrackData,
     hasTrackedRequestsToBeFetched,
     fetchTrackedRequests,
-    purgeSharedCache,
+    SharedCache,
 } from "@khanacademy/wonder-blocks-data";
 
 // Don't forget to import your app!
@@ -113,7 +113,7 @@ async function renderApp(): Promise<string> {
          * shared cache used by the `useSharedCache` hook as this is transient
          * cache that does not itself get directly hydrated.
          */
-        purgeSharedCache();
+        SharedCache.purgeAll();
 
         // Render the tracked component.
         renderedComponent = renderToString(trackedElement);

package/src/__docs__/exports.purge-caches.stories.mdx

@@ -20,4 +20,4 @@ The `purgeCaches` method will purge the following caches managed by Wonder Block
 - Shared in-memory cache as used by  [`useSharedCache`](/docs/data-exports-usesharedcache--page) and other hooks
 - Hydration cache as used during server-side rendering
 
-This is equivalent to calling both `purgeSharedCache()` and `purgeHydrationCache()`, and is especially useful when writing tests or setting up a test environment.
+This is equivalent to calling both `SharedCache.purgeAll()` and `purgeHydrationCache()`, and is especially useful when writing tests or setting up a test environment.

package/src/__docs__/exports.scoped-in-memory-cache.stories.mdx

@@ -11,12 +11,12 @@ import {Meta} from "@storybook/addon-docs";
 
 # ScopedInMemoryCache
 
-This class implements an in-memory cache that can contain different scopes of cached data. This allows for quick removal of entire classes of data as identified by their scopes without having to iterate each cached item to find them.
+This class implements an in-memory cache that can contain different scopes of cached data. This allows for quick removal of entire classes of data as identified by their scopes without having to iterate each cached item to find them. It implements the [`ScopedCache`](/docs/data-types-scopedcache--page) interface.
 
 ## constructor()
 
 ```ts
-new ScopedInMemoryCache(initialCache?: ScopedCache)
+new ScopedInMemoryCache(initialCache?: RawScopedCache)
 ```
 
 Creates a new instance. An initial state for the cache can be provided.
@@ -34,7 +34,7 @@ Is `true` if the cache contains any data; otherwise, `false`.
 ## set()
 
 ```ts
-set<TValue: ValidCacheData>(
+set(
     scope: string,
     id: string,
     value: TValue,

package/src/__docs__/exports.serializable-in-memory-cache.stories.mdx

@@ -16,7 +16,7 @@ This class is a specialization of [`ScopedInMemoryCache`](/docs/data-exports-sco
 ## constructor()
 
 ```ts
-new SerializableInMemoryCache(initialCache?: ScopedCache)
+new SerializableInMemoryCache(initialCache?: RawScopedCache)
 ```
 
 Creates a new instance. The `initialCache`, if provided, will be cloned and used as the initial state of the cache.
@@ -67,7 +67,7 @@ Gets a value from the cache. If a value with the given identifier (`id`) is not
 ## clone()
 
 ```ts
-clone(): ScopedCache;
+clone(): RawScopedCache;
 ```
 
 Returns a clone of the current cache.

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

@@ -0,0 +1,16 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / SharedCache"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# SharedCache
+
+The `SharedCache` export can be used to view and modify the in-memory cache used by [`useSharedCache`](/docs/data-exports-usesharedcache--page) hook and the hooks and components that relate to it.
+
+The `SharedCache` export implements the [`ScopedCache` interface type](/docs/data-types-scopedcache--page).

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

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__/graphql-document-node-parser.test.js

@@ -18,7 +18,7 @@ describe("#graphQLDocumentNodeParser", () => {
 
         it("should throw if the document lacks the kind property", () => {
             // Arrange
-            const documentNode = ({}: any);
+            const documentNode: any = {};
 
             // Act
             const underTest = () => graphQLDocumentNodeParser(documentNode);
@@ -283,7 +283,7 @@ describe("#graphQLDocumentNodeParser", () => {
 
             // Assert
             expect(underTest).toThrowErrorMatchingInlineSnapshot(
-                `"We do not support subscriptions. {\\"kind\\":\\"Document\\",\\"definitions\\":[{\\"kind\\":\\"OperationDefinition\\",\\"operation\\":\\"subscription\\",\\"variableDefinitions\\":[],\\"name\\":{\\"kind\\":\\"Name\\",\\"value\\":\\"subscription\\"}}]} had 1 subscriptions"`,
+                `"We do not support subscriptions. {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"subscription","variableDefinitions":[],"name":{"kind":"Name","value":"subscription"}}]} had 1 subscriptions"`,
             );
         });
 
@@ -318,7 +318,7 @@ describe("#graphQLDocumentNodeParser", () => {
 
             // Assert
             expect(underTest).toThrowErrorMatchingInlineSnapshot(
-                `"We only support one query or mutation per component. {\\"kind\\":\\"Document\\",\\"definitions\\":[{\\"kind\\":\\"OperationDefinition\\",\\"operation\\":\\"query\\",\\"variableDefinitions\\":[],\\"name\\":{\\"kind\\":\\"Name\\",\\"value\\":\\"query\\"}},{\\"kind\\":\\"OperationDefinition\\",\\"operation\\":\\"query\\",\\"variableDefinitions\\":[],\\"name\\":{\\"kind\\":\\"Name\\",\\"value\\":\\"query\\"}}]} had 2 queries and 0 mutations. "`,
+                `"We only support one query or mutation per component. {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"query","variableDefinitions":[],"name":{"kind":"Name","value":"query"}},{"kind":"OperationDefinition","operation":"query","variableDefinitions":[],"name":{"kind":"Name","value":"query"}}]} had 2 queries and 0 mutations. "`,
             );
         });
 
@@ -353,7 +353,7 @@ describe("#graphQLDocumentNodeParser", () => {
 
             // Assert
             expect(underTest).toThrowErrorMatchingInlineSnapshot(
-                `"We only support one query or mutation per component. {\\"kind\\":\\"Document\\",\\"definitions\\":[{\\"kind\\":\\"OperationDefinition\\",\\"operation\\":\\"mutation\\",\\"variableDefinitions\\":[],\\"name\\":{\\"kind\\":\\"Name\\",\\"value\\":\\"mutation\\"}},{\\"kind\\":\\"OperationDefinition\\",\\"operation\\":\\"mutation\\",\\"variableDefinitions\\":[],\\"name\\":{\\"kind\\":\\"Name\\",\\"value\\":\\"mutation\\"}}]} had 0 queries and 2 mutations. "`,
+                `"We only support one query or mutation per component. {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"mutation","variableDefinitions":[],"name":{"kind":"Name","value":"mutation"}},{"kind":"OperationDefinition","operation":"mutation","variableDefinitions":[],"name":{"kind":"Name","value":"mutation"}}]} had 0 queries and 2 mutations. "`,
             );
         });
 
@@ -388,7 +388,7 @@ describe("#graphQLDocumentNodeParser", () => {
 
             // Assert
             expect(underTest).toThrowErrorMatchingInlineSnapshot(
-                `"We only support one query or mutation per component. {\\"kind\\":\\"Document\\",\\"definitions\\":[{\\"kind\\":\\"OperationDefinition\\",\\"operation\\":\\"query\\",\\"variableDefinitions\\":[],\\"name\\":{\\"kind\\":\\"Name\\",\\"value\\":\\"query\\"}},{\\"kind\\":\\"OperationDefinition\\",\\"operation\\":\\"mutation\\",\\"variableDefinitions\\":[],\\"name\\":{\\"kind\\":\\"Name\\",\\"value\\":\\"mutation\\"}}]} had 1 queries and 1 mutations. "`,
+                `"We only support one query or mutation per component. {"kind":"Document","definitions":[{"kind":"OperationDefinition","operation":"query","variableDefinitions":[],"name":{"kind":"Name","value":"query"}},{"kind":"OperationDefinition","operation":"mutation","variableDefinitions":[],"name":{"kind":"Name","value":"mutation"}}]} had 1 queries and 1 mutations. "`,
             );
         });
     });

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.