@khanacademy/wonder-blocks-data 7.0.1 → 8.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-data",
-  "version": "7.0.1",
+  "version": "8.0.0",
   "design": "v1",
   "publishConfig": {
     "access": "public"

package/src/__docs__/_overview_ssr_.stories.mdx

@@ -56,11 +56,11 @@ renderToString(trackedElement);
 
 After each render, we want to see if there are any tracked requests needing to be fulfilled. If there are, we will want to fulfill them and render again; if there are not, we are ready to finish the page rendering and move on.
 
-To determine which path to take, we can use [`hasUnfullfilledRequests`](/docs/data-exports-hasunfulfilledrequests--page), and then based off that result, either fulfill the requests, or finish rendering our page.
+To determine which path to take, we can use [`hasTrackedRequestsToBeFetched`](/docs/data-exports-hastrackedrequeststobefetched--page), and then based off that result, either fulfill the requests, or finish rendering our page.
 
 ```ts
-if (hasUnfulfilledRequests()) {
-    await fulfillAllDataRequests();
+if (hasTrackedRequestsToBeFetched()) {
+    await fetchTrackedRequests();
 
     // Render again.
     // ...
@@ -72,7 +72,7 @@ if (hasUnfulfilledRequests()) {
 
 Internally, Wonder Blocks Data caches the responses of fulfilled requests and does not track them again. Each cycle of the rendering should occur with the same knowledge you expect the client-side to have when it performs the render, so although we want to retain our hydration cache response, we need to make sure any transient caches are cleared.
 
-Once the rendered component no longer requires any further data, the cached responses can be obtained to include in the rendered page for the client to hydrate. The hydration cache is promised by `fulfillAllDataRequests()`, regardless of whether it actually had any pending requests or not.
+Once the rendered component no longer requires any further data, the cached responses can be obtained to include in the rendered page for the client to hydrate. The hydration cache is promised by `fetchTrackedRequests()`, regardless of whether it actually had any pending requests or not.
 
 ### Putting it all together
 
@@ -84,9 +84,9 @@ A function for server-side rendering with Wonder Blocks Data could look somethin
 import {Server} from "@khanacademy/wonder-blocks-core";
 import {
     TrackData,
-    hasUnfulfilledRequests,
-    fulfillAllDataRequests,
-    clearSharedCache,
+    hasTrackedRequestsToBeFetched,
+    fetchTrackedRequests,
+    purgeSharedCache,
 } from "@khanacademy/wonder-blocks-data";
 
 // Don't forget to import your app!
@@ -113,14 +113,14 @@ async function renderApp(): Promise<string> {
          * shared cache used by the `useSharedCache` hook as this is transient
          * cache that does not itself get directly hydrated.
          */
-        clearSharedCache();
+        purgeSharedCache();
 
         // Render the tracked component.
         renderedComponent = renderToString(trackedElement);
 
-        if (hasUnfulfilledRequests()) {
+        if (hasTrackedRequestsToBeFetched()) {
             // Fulfill any pending requests.
-            await fulfillAllDataRequests();
+            await fetchTrackedRequests();
 
             // We can't leave the loop yet as we want to render the element
             // again with the newly fulfilled data.
@@ -130,7 +130,7 @@ async function renderApp(): Promise<string> {
 
         // We rendered with all the data fulfilled, so we can grab the
         // hydration cache contents and exit the loop now.
-        hydrationCache = await fulfillAllDataRequests();
+        hydrationCache = await fetchTrackedRequests();
     } while (hydrationCache == null);
 
     // Finally, render the page with our hydration cache and rendered
@@ -164,12 +164,12 @@ In the previous section, this was displayed as the `hydrate.js` script. Here is
 
 ```tsx
 import {hydrate} from "react-dom";
-import {initializeCache} from "@khanacademy/wonder-blocks-data";
+import {initializeHydrationCache} from "@khanacademy/wonder-blocks-data";
 
 // Don't forget to import your app!
 import App from "./App.js";
 
-initializeCache(window._WONDER_BLOCKS_DATA_);
+initializeHydrationCache(window._WONDER_BLOCKS_DATA_);
 
 React.hydrate(
     // This should match whatever was passed to the server-side rendering

package/src/__docs__/exports.abort-inflight-requests.stories.mdx

@@ -0,0 +1,20 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / abortInflightRequests()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# abortInflightRequests()
+
+```ts
+abortInflightRequests(): void;
+```
+
+Aborts all inflight requests that were started via [`useCachedEffect`](/docs/data-exports-usecachedeffect--page), [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page), or [`fetchTrackedRequests()`](/docs/data-exports-fetchtrackedrequests--page).
+
+NOTE: Full abort signalling is not currently implemented. The effect of this call is to remove any inflight requests from our inflight request tracking such that a new matching request will cause a new fetch to occur rather than sharing any existing one.

package/src/__docs__/exports.data.stories.mdx

@@ -105,12 +105,12 @@ const myInvalidHandler = () => new Promise((resolve, reject) =>
 
 If the hydration cache already contains data or an error for our request, then
 the `Data` component will render it immediately. The hydration cache is
-populated using the `initializeCache` method before rendering.
+populated using the `initializeHydrationCache` method before rendering.
 
 ```jsx
 import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
 import {View} from "@khanacademy/wonder-blocks-core";
-import {Data, initializeCache} from "@khanacademy/wonder-blocks-data";
+import {Data, initializeHydrationCache} from "@khanacademy/wonder-blocks-data";
 import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Color from "@khanacademy/wonder-blocks-color";
 import Spacing from "@khanacademy/wonder-blocks-spacing";
@@ -121,7 +121,7 @@ const myHandler = () => {
     );
 };
 
-initializeCache({
+initializeHydrationCache({
     DATA: {
         data: "I'm DATA from the hydration cache"
     },

package/src/__docs__/{exports.fulfill-all-data-requests.stories.mdx → exports.fetch-tracked-requests.stories.mdx}

@@ -1,7 +1,7 @@
 import {Meta} from "@storybook/addon-docs";
 
 <Meta
-    title="Data / Exports / fulfillAllDataRequests()"
+    title="Data / Exports / fetchTrackedRequests()"
     parameters={{
         chromatic: {
             disableSnapshot: true,
@@ -9,16 +9,16 @@ import {Meta} from "@storybook/addon-docs";
     }}
 />
 
-# fulfillAllDataRequests()
+# fetchTrackedRequests()
 
 ```ts
-fulfillAllDataRequests(): Promise<ResponseCache>;
+fetchTrackedRequests(): Promise<ResponseCache>;
 ```
 
-When performing server-side rendering (SSR), the data requests that are being made via the [`Data`](/docs/data-exports-data--page) component can be tracked by rendering the React tree inside the [`TrackData`](/docs/data-exports-trackdata--page) component. After this has occurred, the tracked requests can be fulfilled using `fulfillAllDataRequests`.
+When performing server-side rendering (SSR), the data requests that are being made via the [`Data`](/docs/data-exports-data--page) component can be tracked by rendering the React tree inside the [`TrackData`](/docs/data-exports-trackdata--page) component. After this has occurred, the tracked requests can be fulfilled using `fetchTrackedRequests`.
 
 This method returns a promise that resolves to a copy of the data that was cached by fulfilling the tracked requests. In the process, it clears the record of tracked requests so that new requests can be tracked and fulfilled if so required.
 
-The returned copy of the data cache can be used with the [`initializeCache`](/docs/data-exports-initializecache--page) method to prepare the data cache before a subsequent render. This is useful on the server to then SSR a more complete result, and again on the client, to rehydrate that result.
+The returned copy of the data cache can be used with the [`initializeHydrationCache`](/docs/data-exports-initializehydrationcache--page) method to prepare the data cache before a subsequent render. This is useful on the server to then SSR a more complete result, and again on the client, to rehydrate that result.
 
 More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--page).

package/src/__docs__/exports.get-gql-request-id.stories.mdx

@@ -0,0 +1,24 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / getGqlRequestId()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# getGqlRequestId()
+
+```ts
+function getGqlRequestId<TData, TVariables: {...}>(
+    operation: GqlOperation<TData, TVariables>,
+    variables: ?TVariables,
+    context: GqlContext,
+): string;
+```
+
+The `getGqlRequestId` function generates an identifier based on the operation, variables, and context of a specific GraphQL request. This identifier is guaranteed to be the same for all requests that share the same operation, variables, and context, even if variables and context values are in different orders.
+
+The identifier returned by this function can then be used with our [`useCachedEffect`](/docs/data-exports-usecachedeffect--page), [`useServerEffect`](/docs/data-exports-useservereffect--page), and [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page) hooks as the `requestId` parameter, allowing them to be combined with the fetch operation from the [`useGql`](/docs/data-exports-usegql--page) hook.

package/src/__docs__/{exports.has-unfulfilled-requests.stories.mdx → exports.has-tracked-requests-to-be-fetched.stories.mdx}

@@ -1,7 +1,7 @@
 import {Meta} from "@storybook/addon-docs";
 
 <Meta
-    title="Data / Exports / hasUnfulfilledRequests()"
+    title="Data / Exports / hasTrackedRequestsToBeFetched()"
     parameters={{
         chromatic: {
             disableSnapshot: true,
@@ -9,12 +9,12 @@ import {Meta} from "@storybook/addon-docs";
     }}
 />
 
-# hasUnfulfilledRequests()
+# hasTrackedRequestsToBeFetched()
 
 ```ts
-hasUnfulfilledRequests(): boolean;
+hasTrackedRequestsToBeFetched(): boolean;
 ```
 
-When performing server-side rendering (SSR), any requests that have been tracked will cause this method to return `true`. Once [`fulfillAllDataRequests`](/docs/data-exports-fulfillalldatarequests--page) has been called and the promise is settled, this method will return `false` to indicate that there are no more pending requests.
+When performing server-side rendering (SSR), any requests that have been tracked will cause this method to return `true`. Once [`fetchTrackedRequests`](/docs/data-exports-fetchtrackedrequests--page) has been called and the promise is settled, this method will return `false` to indicate that there are no more pending requests.
 
 More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--page).

package/src/__docs__/exports.intialize-hydration-cache.stories.mdx

@@ -0,0 +1,29 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / initializeHydrationCache()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# initializeHydrationCache()
+
+```ts
+initializeHydrationCache(sourceCache: ResponseCache): void;
+```
+
+| Argument | Flow&nbsp;Type | Default | Description |
+| --- | --- | --- | --- |
+| `sourceData` | `ResponseCache` | _Required_ | The source cache that will be used to initialize the response cache. |
+
+Wonder Blocks Data caches data in its response cache for hydration. This cache can be initialized with data using the `initializeHydrationCache` method.
+The `initializeHydrationCache` method can only be called when the hydration cache is empty.
+
+Usually, the data to be passed to `v` will be obtained by calling [`fetchTrackedRequests`](/docs/data-exports-fetchtrackedrequests--page) after tracking data requests (see [`TrackData`](/docs/data-exports-trackdata--page)) during server-side rendering.
+
+Combine with [`purgeHydrationCache`](/docs/data-exports-purgehydrationcache--page) to support your testing needs.
+
+More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--page).

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

@@ -0,0 +1,23 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / purgeCaches()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# purgeCaches()
+
+```ts
+purgeCaches(scope?: string): void;
+```
+
+The `purgeCaches` method will purge the following caches managed by Wonder Blocks Data:
+
+- 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.

package/src/__docs__/{exports.remove-all-from-cache.stories.mdx → exports.purge-hydration-cache.stories.mdx}

@@ -1,7 +1,7 @@
 import {Meta} from "@storybook/addon-docs";
 
 <Meta
-    title="Data / Exports / removeAllFromCache()"
+    title="Data / Exports / purgeHydrationCache()"
     parameters={{
         chromatic: {
             disableSnapshot: true,
@@ -9,10 +9,10 @@ import {Meta} from "@storybook/addon-docs";
     }}
 />
 
-# removeAllFromCache()
+# purgeHydrationCache()
 
 ```ts
-removeAllFromCache(predicate?: (key: string, cacheEntry: $ReadOnly<CachedResponse<ValidCacheData>>) => boolean): void;
+purgeHydrationCache(predicate?: (key: string, cacheEntry: $ReadOnly<CachedResponse<ValidCacheData>>) => boolean): void;
 ```
 
 | Argument | Flow&nbsp;Type | Default | Description |
@@ -21,4 +21,4 @@ removeAllFromCache(predicate?: (key: string, cacheEntry: $ReadOnly<CachedRespons
 
 Removes all entries that match a given predicate from the cache. If no predicate is given, all cached entries.
 
-This can be used after [`initializeCache`](/docs/data-exports-initializecache--page)  to manipulate the cache prior to hydration wich can be useful during testing (especially to clear the cache so that it can be initialized again).
+This can be used after [`initializeHydrationCache`](/docs/data-exports-initializehydrationcache--page)  to manipulate the cache prior to hydration wich can be useful during testing (especially to clear the cache so that it can be initialized again).

package/src/__docs__/{exports.clear-shared-cache.stories.mdx → exports.purge-shared-cache.stories.mdx}

@@ -1,7 +1,7 @@
 import {Meta} from "@storybook/addon-docs";
 
 <Meta
-    title="Data / Exports / clearSharedCache()"
+    title="Data / Exports / purgeSharedCache()"
     parameters={{
         chromatic: {
             disableSnapshot: true,
@@ -9,12 +9,12 @@ import {Meta} from "@storybook/addon-docs";
     }}
 />
 
-# clearSharedCache()
+# purgeSharedCache()
 
 ```ts
-clearSharedCache(scope?: string): void;
+purgeSharedCache(scope?: string): void;
 ```
 
-The `clearSharedCache` method can be used to clear the shared in-memory cache used by the [`useSharedCache`](/docs/data-exports-clearsharedcache--page) hook. Either a single scope or all scopes can be cleared.
+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.

package/src/__docs__/exports.track-data.stories.mdx

@@ -71,7 +71,7 @@ class ErrorBoundary extends React.Component {
 
 When used server-side, this component tracks any data requests made through
 the `Data` component during a render cycle. This data can then be obtained
-using the `fulfillAllDataRequests` method. The data can then be used in an
+using the `fetchTrackedRequests` method. The data can then be used in an
 additional render cycle to render with that data.
 
 ```jsx
@@ -80,7 +80,7 @@ import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Spacing from "@khanacademy/wonder-blocks-spacing";
 import Button from "@khanacademy/wonder-blocks-button";
 import {Server, View} from "@khanacademy/wonder-blocks-core";
-import {Data, TrackData, fulfillAllDataRequests} from "@khanacademy/wonder-blocks-data";
+import {Data, TrackData, fetchTrackedRequests} from "@khanacademy/wonder-blocks-data";
 
 const myPretendHandler = () => new Promise((resolve, reject) =>
     setTimeout(() => resolve("DATA!"), 3000),
@@ -158,7 +158,7 @@ class Example extends React.Component {
                     <Body>
                         The above components requested data, but we're server-side,
                         so all that happened is we tracked the request.
-                        In this example, we've also called `fulfillAllDataRequests`
+                        In this example, we've also called `fetchTrackedRequests`
                         to fetch that tracked data.
                     </Body>
                     <Strut size={Spacing.small_12} />
@@ -195,7 +195,7 @@ class Example extends React.Component {
             );
         } finally {
             if (!this.state.data && Server.isServerSide()) {
-                setTimeout(() => fulfillAllDataRequests().then((data) => {
+                setTimeout(() => fetchTrackedRequests().then((data) => {
                     if (this._mounted) {
                         this.setState({data});
                     }

package/src/__docs__/exports.use-cached-effect.stories.mdx

@@ -16,13 +16,14 @@ function useCachedEffect<TData: ValidCacheData>(
     requestId: string,
     handler: () => Promise<TData>,
     options?: CachedEffectOptions<TData>,
-): Result<TData>;
+): [Result<TData>, () => void];
 ```
 
-This hook is a wrapper around `useEffect`. Internally it uses the [`useSharedCache`](/docs/data-exports-usesharedcache--page) hook to store the result of the effect and, if that result is available, returns it without rerunning the effect. The precise behavior of the
-hook can be modified using the options.
+This hook invokes the given handler and caches the result using the [`useSharedCache`](/docs/data-exports-usesharedcache--page) hook. The `requestId` is used to both identify inflight requests that can be shared, and to identify the cached value to use.
 
-There is currently no way to reinvoke the effect without changing the `requestId`.
+The hook returns an array containing the current state of the request, and a function that can be used to `refetch` that request on demand. Calling `refetch` while an inflight request is in progress for the given `requestId` will be a no-op.
+
+The behavior of the hook can be modified with the options.
 
 ```ts
 type CachedEffectOptions<TData: ValidCacheData> = {|
@@ -30,6 +31,7 @@ type CachedEffectOptions<TData: ValidCacheData> = {|
     retainResultOnChange?: boolean,
     onResultChanged?: (result: Result<TData>) => void,
     scope?: string,
+    fetchPolicy?: FetchPolicy,
 |};
 ```
 
@@ -39,3 +41,4 @@ type CachedEffectOptions<TData: ValidCacheData> = {|
 | `retainResultOnChange` | `false` | When `true`, the effect will not reset the result to the loading status while executing if the requestId changes, instead, returning the existing result from before the change; otherwise, the result will be set to loading status.  If the status is loading when the changes are made, it will remain as loading; old pending effects are discarded on changes and as such this value has no effect in that case.|
 | `onResultChanged` | `undefined` | Callback that is invoked if the result for the given hook has changed. When defined, the hook will invoke this callback whenever it has reason to change the result and will not otherwise affect component rendering directly. When not defined, the hook will ensure the component re-renders to pick up the latest result. |
 | `scope` | `"useCachedEffect"` | Scope to use with the shared cache. When specified, the given scope will be used to isolate this hook's cached results. Otherwise, the default scope will be used. Changing this value after the first call is not supported. |
+| `fetchPolicy` | [`FetchPolicy`](/docs/data-types-fetchpolicy--page) | Fetch policy to use when fetching the data. Defaults to `FetchPolicy.CacheBeforeNetwork`. |

package/src/__docs__/exports.use-gql.stories.mdx

@@ -30,39 +30,7 @@ The return value of `useGql` is a fetch function that can be used to invoke a Gr
 
 The result of calling the function returned by `useGql` is a promise of the data that the request will return. This is compatible with the [`useServerEffect`](/docs/data-exports-useservereffect--page), [`useCachedEffect`](/docs/data-exports-usecachedeffect--page),  and [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page) hooks, allowing a variety of scenarios to be easily constructed.
 
-Below is an example request identifier generation function that could be used to generate request identifiers (we hope to include a base implementation for this purpose in a future release of Wonder Blocks Data):
-
-```ts
-const getGqlRequestId = <TData, TVariables: {...}>(
-    operation: GqlOperation<TData, TVariables>,
-    variables: ?TVariables,
-    context: GqlContext,
-): string => {
-    // We add all the bits for this into an array and then join them with
-    // a chosen separator.
-    const parts = [];
-    parts.push(operation.id);
-    if (context != null) {
-        // Turn the context into a string of the form,
-        //     "key1=;key2=value"
-        const sortedContext = Object.keys(context || {})
-            .sort()
-            .map((key) => `${key}=${JSON.stringify(context?.[key]) || ""}`)
-            .join(";");
-        parts.push(sortedContext);
-    }
-    if (variables != null) {
-        // Turn the variables into a string of the form,
-        //     "key1=;key2=value"
-        const sortedVariables = Object.keys(variables || {})
-            .sort()
-            .map((key) => `${key}=${JSON.stringify(variables?.[key]) || ""}`)
-            .join(";");
-        parts.push(sortedVariables);
-    }
-    return parts.join("|");
-};
-```
+Use [`getGqlRequestId`](/docs/data-exports-getgqlrequestid--page) to get a request ID that can be used with these hooks.
 
 ## Context Merging
 

package/src/__docs__/exports.use-server-effect.stories.mdx

@@ -39,7 +39,7 @@ First, this hook checks the server-side rendering cache for the request identifi
 
 If there is no cached value, it will return a "loading" state. In addition, if the current rendering component has a [`TrackData`](/docs/data-exports-trackdata--page) ancestor, `useServerEffect` will register the request for fulfillment.
 
-This then allows that pending request to be fulfilled with [`fulfillAllDataRequests`](/docs/data-exports-fulfillalldatarequests--page), the response to be placed into the cache, and the render to be reexecuted, at which point, this hook will be able to provide that result instead of "loading.
+This then allows that pending request to be fulfilled with [`fetchTrackedRequests`](/docs/data-exports-fetchtrackddatarequests--page), the response to be placed into the cache, and the render to be reexecuted, at which point, this hook will be able to provide that result instead of "loading.
 
 More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--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 [`clearSharedCache`](/docs/data-exports-clearsharedcache--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 [`purgeSharedCache`](/docs/data-exports-purgesharedcache--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 [`clearSharedCache`](/docs/data-exports-clearsharedcache--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 [`purgeSharedCache`](/docs/data-exports-purgesharedcache--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.fetch-policy.stories.mdx

@@ -0,0 +1,44 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / FetchPolicy"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# FetchPolicy
+
+```ts
+export enum FetchPolicy {
+    /**
+     * If the data is in the cache, return that; otherwise, fetch from the server.
+     */
+    CacheBeforeNetwork,
+
+    /**
+     * If the data is in the cache, return that; always fetch from the server
+     * regardless of cache.
+     */
+    CacheAndNetwork,
+
+    /**
+     * If the data is in the cache, return that; otherwise, do nothing.
+     */
+    CacheOnly,
+
+    /**
+     * Ignore any existing cached result; fetch from the server.
+     */
+    NetworkOnly,
+}
+```
+
+The `FetchPolicy` type is used with our request framework to define how a request should be fulfilled with respect to the cache and the network.
+
+ * `CacheBeforeNetwork`: If the data is in the cache, return that; otherwise, fetch from the server.
+ * `CacheAndNetwork`:  If the data is in the cache, return that; always fetch from the server regardless of cache.
+ * `CacheOnly`: If the data is in the cache, return that; otherwise, do nothing.
+ * `NetworkOnly`: Ignore any existing cached result; always fetch from the server.

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

@@ -18,7 +18,7 @@ type ResponseCache = {
 };
 ```
 
-`ResponseCache` describes the serialized cache that is used to hydrate responses. An example of a valid `ResponseCache` instance is shown below. Generally, you would not generate this object directly, but rather use the returned data from [`fulfillAllDataRequests`](/docs/data-exports-fulfillalldatarequests--page).
+`ResponseCache` describes the serialized cache that is used to hydrate responses. An example of a valid `ResponseCache` instance is shown below. Generally, you would not generate this object directly, but rather use the returned data from [`fetchTrackedRequests`](/docs/data-exports-fetchtrackedrequests--page).
 
 ```ts
 const responseCache: ResponseCache = {

package/src/__tests__/generated-snapshot.test.js

@@ -12,10 +12,10 @@ import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
 import {View, Server} from "@khanacademy/wonder-blocks-core";
 import {
     Data,
-    initializeCache,
+    initializeHydrationCache,
     InterceptRequests,
     TrackData,
-    fulfillAllDataRequests,
+    fetchTrackedRequests,
 } from "@khanacademy/wonder-blocks-data";
 import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Color from "@khanacademy/wonder-blocks-color";
@@ -82,7 +82,7 @@ describe("wonder-blocks-data", () => {
             );
         };
 
-        initializeCache({
+        initializeHydrationCache({
             DATA: {
                 data: "I'm DATA from the hydration cache",
             },
@@ -277,7 +277,7 @@ describe("wonder-blocks-data", () => {
                                 The above components requested data, but we're
                                 server-side, so all that happened is we tracked
                                 the request. In this example, we've also called
-                                `fulfillAllDataRequests` to fetch that tracked
+                                `fetchTrackedRequests` to fetch that tracked
                                 data.
                             </Body>
                             <Strut size={Spacing.small_12} />
@@ -329,7 +329,7 @@ describe("wonder-blocks-data", () => {
                     if (!this.state.data && Server.isServerSide()) {
                         setTimeout(
                             () =>
-                                fulfillAllDataRequests().then((data) => {
+                                fetchTrackedRequests().then((data) => {
                                     if (this._mounted) {
                                         this.setState({
                                             data,

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 {clearSharedCache} from "../../hooks/use-shared-cache.js";
+import {purgeSharedCache} 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(() => {
-        clearSharedCache();
+        purgeSharedCache();
 
         const responseCache = new SsrCache();
         jest.spyOn(SsrCache, "Default", "get").mockReturnValue(responseCache);
@@ -36,10 +36,6 @@ describe("Data", () => {
         );
     });
 
-    afterEach(() => {
-        jest.resetAllMocks();
-    });
-
     describe("CSR: isServerSide false", () => {
         beforeEach(() => {
             jest.spyOn(Server, "isServerSide").mockReturnValue(false);