npm - @khanacademy/wonder-blocks-data - Versions diffs - 4.0.0 → 6.0.0 - Mend

@khanacademy/wonder-blocks-data 4.0.0 → 6.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (91) hide show

package/CHANGELOG.md +31 -0
package/dist/es/index.js +793 -375
package/dist/index.js +1203 -523
package/legacy-docs.md +3 -0
package/package.json +2 -2
package/src/__docs__/_overview_.stories.mdx +18 -0
package/src/__docs__/_overview_graphql.stories.mdx +35 -0
package/src/__docs__/_overview_ssr_.stories.mdx +185 -0
package/src/__docs__/_overview_testing_.stories.mdx +123 -0
package/src/__docs__/exports.clear-shared-cache.stories.mdx +20 -0
package/src/__docs__/exports.data-error.stories.mdx +23 -0
package/src/__docs__/exports.data-errors.stories.mdx +23 -0
package/src/{components/data.md → __docs__/exports.data.stories.mdx} +15 -18
package/src/__docs__/exports.fulfill-all-data-requests.stories.mdx +24 -0
package/src/__docs__/exports.gql-error.stories.mdx +23 -0
package/src/__docs__/exports.gql-errors.stories.mdx +20 -0
package/src/__docs__/exports.gql-router.stories.mdx +29 -0
package/src/__docs__/exports.has-unfulfilled-requests.stories.mdx +20 -0
package/src/__docs__/exports.intercept-requests.stories.mdx +69 -0
package/src/__docs__/exports.intialize-cache.stories.mdx +29 -0
package/src/__docs__/exports.remove-all-from-cache.stories.mdx +24 -0
package/src/__docs__/exports.remove-from-cache.stories.mdx +25 -0
package/src/__docs__/exports.request-fulfillment.stories.mdx +36 -0
package/src/__docs__/exports.scoped-in-memory-cache.stories.mdx +92 -0
package/src/__docs__/exports.serializable-in-memory-cache.stories.mdx +112 -0
package/src/__docs__/exports.status.stories.mdx +31 -0
package/src/{components/track-data.md → __docs__/exports.track-data.stories.mdx} +15 -0
package/src/__docs__/exports.use-cached-effect.stories.mdx +41 -0
package/src/__docs__/exports.use-gql.stories.mdx +73 -0
package/src/__docs__/exports.use-hydratable-effect.stories.mdx +43 -0
package/src/__docs__/exports.use-server-effect.stories.mdx +38 -0
package/src/__docs__/exports.use-shared-cache.stories.mdx +30 -0
package/src/__docs__/exports.when-client-side.stories.mdx +33 -0
package/src/__docs__/types.cached-response.stories.mdx +29 -0
package/src/__docs__/types.error-options.stories.mdx +21 -0
package/src/__docs__/types.gql-context.stories.mdx +20 -0
package/src/__docs__/types.gql-fetch-fn.stories.mdx +24 -0
package/src/__docs__/types.gql-fetch-options.stories.mdx +24 -0
package/src/__docs__/types.gql-operation-type.stories.mdx +24 -0
package/src/__docs__/types.gql-operation.stories.mdx +67 -0
package/src/__docs__/types.response-cache.stories.mdx +33 -0
package/src/__docs__/types.result.stories.mdx +39 -0
package/src/__docs__/types.scoped-cache.stories.mdx +27 -0
package/src/__docs__/types.valid-cache-data.stories.mdx +23 -0
package/src/__tests__/__snapshots__/generated-snapshot.test.js.snap +0 -80
package/src/__tests__/generated-snapshot.test.js +7 -31
package/src/components/__tests__/data.test.js +160 -154
package/src/components/__tests__/intercept-requests.test.js +58 -0
package/src/components/data.js +22 -126
package/src/components/intercept-context.js +4 -5
package/src/components/intercept-requests.js +69 -0
package/src/hooks/__tests__/__snapshots__/use-shared-cache.test.js.snap +8 -8
package/src/hooks/__tests__/use-cached-effect.test.js +507 -0
package/src/hooks/__tests__/use-gql-router-context.test.js +133 -0
package/src/hooks/__tests__/use-gql.test.js +1 -30
package/src/hooks/__tests__/use-hydratable-effect.test.js +708 -0
package/src/hooks/__tests__/use-request-interception.test.js +255 -0
package/src/hooks/__tests__/use-server-effect.test.js +39 -11
package/src/hooks/use-cached-effect.js +225 -0
package/src/hooks/use-gql-router-context.js +50 -0
package/src/hooks/use-gql.js +22 -52
package/src/hooks/use-hydratable-effect.js +206 -0
package/src/hooks/use-request-interception.js +51 -0
package/src/hooks/use-server-effect.js +14 -7
package/src/hooks/use-shared-cache.js +13 -11
package/src/index.js +54 -2
package/src/util/__tests__/__snapshots__/serializable-in-memory-cache.test.js.snap +19 -0
package/src/util/__tests__/merge-gql-context.test.js +74 -0
package/src/util/__tests__/request-fulfillment.test.js +23 -42
package/src/util/__tests__/request-tracking.test.js +26 -7
package/src/util/__tests__/result-from-cache-response.test.js +19 -5
package/src/util/__tests__/scoped-in-memory-cache.test.js +6 -85
package/src/util/__tests__/serializable-in-memory-cache.test.js +398 -0
package/src/util/__tests__/ssr-cache.test.js +52 -52
package/src/util/abort-error.js +15 -0
package/src/util/data-error.js +58 -0
package/src/util/get-gql-data-from-response.js +3 -2
package/src/util/gql-error.js +19 -11
package/src/util/merge-gql-context.js +34 -0
package/src/util/request-fulfillment.js +49 -46
package/src/util/request-tracking.js +69 -15
package/src/util/result-from-cache-response.js +12 -16
package/src/util/scoped-in-memory-cache.js +24 -47
package/src/util/serializable-in-memory-cache.js +49 -0
package/src/util/ssr-cache.js +9 -8
package/src/util/status.js +30 -0
package/src/util/types.js +18 -1
package/docs.md +0 -122
package/src/components/__tests__/intercept-data.test.js +0 -63
package/src/components/intercept-data.js +0 -66
package/src/components/intercept-data.md +0 -51

package/src/__docs__/exports.intercept-requests.stories.mdx ADDED Viewed

@@ -0,0 +1,69 @@
+import {Meta} from "@storybook/addon-docs";
+import {InterceptRequests} from "../index.js";
+<Meta
+    title="Data / Exports / InterceptRequests"
+    component={InterceptRequests}
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# InterceptRequests
+When you want to generate tests that check the loading state and
+subsequent loaded state are working correctly for your uses of `Data` you can
+use the `InterceptRequests` component. You can also use this component to
+register request interceptors for any code that uses the `useRequestInterception`
+hook.
+This component takes the children to be rendered, and an interceptor function.
+Note that this component is expected to be used only within test cases or
+stories. Be careful want request IDs are matched to avoid intercepting the
+wrong requests and remember that in-flight requests for a given request ID
+can be shared - which means a bad request ID match could share requests across
+different request IDs..
+The `interceptor` intercept function has the form:
+```js static
+(requestId: string) => ?Promise<TData>;
+```
+If this method returns `null`, then the next interceptor in the chain is
+invoked, ultimately ending with the original handler. This
+means that a request will be made for data via the handler assigned to the
+`Data` component being intercepted if no interceptor handles the request first.
+```jsx
+import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {InterceptRequests, Data} 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";
+const myHandler = () => Promise.reject(new Error("You should not see this!"));
+const interceptor = (requestId) => requestId === "INTERCEPT_EXAMPLE" ? Promise.resolve("INTERCEPTED DATA!") : null;
+<InterceptRequests interceptor={interceptor}>
+    <View>
+        <Body>This received intercepted data!</Body>
+        <Data handler={myHandler} requestId="INTERCEPT_EXAMPLE">
+            {(result) => {
+                if (result.status !== "success") {
+                    return "If you see this, the example is broken!";
+                }
+                return (
+                    <BodyMonospace>{result.data}</BodyMonospace>
+                );
+            }}
+        </Data>
+    </View>
+</InterceptRequests>
+```

package/src/__docs__/exports.intialize-cache.stories.mdx ADDED Viewed

@@ -0,0 +1,29 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / initializeCache()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# initializeCache()
+```ts
+initializeCache(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 `initializeCache` method.
+The `initializeCache` method can only be called when the hydration cache is empty.
+Usually, the data to be passed to `initializeCache` will be obtained by calling [`fulfillAllDataRequests`](/docs/data-exports-fulfillalldatarequests--page) after tracking data requests (see [`TrackData`](/docs/data-exports-trackdata--page)) during server-side rendering.
+Combine with [`removeFromCache`](/docs/data-exports-removefromcache--page) or [`removeAllFromCache`](/docs/data-exports-removeallfromcache--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.remove-all-from-cache.stories.mdx ADDED Viewed

@@ -0,0 +1,24 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / removeAllFromCache()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# removeAllFromCache()
+```ts
+removeAllFromCache(predicate?: (key: string, cacheEntry: $ReadOnly<CachedResponse<ValidCacheData>>) => boolean): void;
+```
+| Argument | Flow&nbsp;Type | Default | Description |
+| --- | --- | --- | --- |
+| `predicate` | `(key: string, entry: $ReadOnly<CachedResponse<TData>>) => boolean)` | _Optional_ | A predicate to identify which entries to remove. If absent, all data is removed; if present, any entries for which the predicate returns `true` will be returned. |
+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).

package/src/__docs__/exports.remove-from-cache.stories.mdx ADDED Viewed

@@ -0,0 +1,25 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / removeFromCache()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# removeFromCache()
+```ts
+removeFromCache(id: string): void;
+```
+| Argument | Flow&nbsp;Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | _Required_ | The id of the item to be removed. |
+Removes an entry from the cache.
+This can be used after [`initializeCache`](/docs/data-exports-initializecache--page) to manipulate the cache prior to hydration. This can be useful during testing.

package/src/__docs__/exports.request-fulfillment.stories.mdx ADDED Viewed

@@ -0,0 +1,36 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / RequestFulfillment"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# RequestFulfillment
+The `RequestFulfillment` class encapsulates tracking of inflight asynchronous actions keyed by an identifier. Using this API, callers can request the result of the same asynchronous action multiple times without invoking the underlying action more than is necessary. Instead, any pending request will be shared by all requests for the same identifier.
+## Usage
+```ts
+    fulfill: <TData: ValidCacheData>(
+        id: string,
+        options: {|
+            handler: () => Promise<TData>,
+            hydrate?: boolean,
+        |},
+    ) => Promise<Result<TData>>;
+```
+There is a single function on the `RequestFulfillment` class, called `fulfill`.
+The `fulfill` method takes the request identifier (used to deduplicate requests) and an options object. The options object contains the following properties:
+ * `handler`: A function that returns a promise resolving to the result of the request. This is the asynchronous work that will be tracked by the given identifier.
+ * `hydrate`: A boolean indicating whether the data should be hydrated. This is used during server-side rendering to determine if the response data should be included in the hydration cache. This defaults to `true` and should only be set to `false` if you are performing server-side rendering of the request and you know that the data will not be needed for hydration to succeed.
+## RequestFulfillment.Default
+The `RequestFulfillment` class provides a static instance, `RequestFulfillment.Default`, which is used by the Wonder Blocks Data framework. However, a custom instance can be constructed should your specific use case need to be isolated from others.

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

@@ -0,0 +1,92 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / ScopedInMemoryCache"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# 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.
+## constructor()
+```ts
+new ScopedInMemoryCache(initialCache?: ScopedCache)
+```
+Creates a new instance. An initial state for the cache can be provided.
+## inUse
+```ts
+    if (cache.inUse) {
+        // Cache is in use
+    }
+```
+Is `true` if the cache contains any data; otherwise, `false`.
+## set()
+```ts
+set<TValue: ValidCacheData>(
+    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;
+```
+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.

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

@@ -0,0 +1,112 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / SerializableInMemoryCache"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# SerializableInMemoryCache
+This class is a specialization of [`ScopedInMemoryCache`](/docs/data-exports-scopedinmemorycache--page). This specialization requires that values added can be serialized to and from strings.
+## constructor()
+```ts
+new SerializableInMemoryCache(initialCache?: ScopedCache)
+```
+Creates a new instance. The `initialCache`, if provided, will be cloned and used as the initial state of the cache.
+### Throws
+| Error Type | Error Name | Reason |
+| ------ | ------ | ------ |
+| [`DataError`](/docs/data-exports-dataerror--page) | `InvalidInputDataError` | Could not clone the initial cache. |
+## inUse
+```ts
+    if (cache.inUse) {
+        // Cache is in use
+    }
+```
+Is `true` if the cache contains any data; otherwise, `false`.
+## set()
+```ts
+set<TValue: ValidCacheData>(
+    scope: string,
+    id: string,
+    value: TValue,
+): void;
+```
+Sets a value in the cache within a given scope. The value is cloned and the clone is frozen before being added to the cache.
+### 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.
+## clone()
+```ts
+clone(): ScopedCache;
+```
+Returns a clone of the current cache.
+### Throws
+| Error Type | Error Name | Reason |
+| ------ | ------ | ------ |
+| [`DataError`](/docs/data-exports-dataerror--page) | `InternalDataError` | Could not clone the cache. |
+## 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;
+```
+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.

package/src/__docs__/exports.status.stories.mdx ADDED Viewed

@@ -0,0 +1,31 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / Status"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# Status
+Provides a helper API for creating [`Result<TData>`](/docs/data-types-result--page) instances with specific statuses.
+## loading()
+`Status.loading()` creates a result with the `"loading"` status.
+## aborted()
+`Status.aborted()` creates a result with the `"aborted"` status.
+## success()
+`Status.success()` creates a result with the `"success"` status and the given data.
+## error()
+`Status.error()` creates a result with the `"error"` status and the given error.

package/src/{components/track-data.md → __docs__/exports.track-data.stories.mdx} RENAMED Viewed

@@ -1,3 +1,18 @@
+import {Meta} from "@storybook/addon-docs";
+import {TrackData} from "../index.js";
+<Meta
+    title="Data / Exports / TrackData"
+    component={TrackData}
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# TrackData
 The `TrackData` component is a server-side only component. It should be used as
 a parent to the components whose data requests you want to fulfill during
 server-side rendering.

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

@@ -0,0 +1,41 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / useCachedEffect()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# useCachedEffect()
+```ts
+function useCachedEffect<TData: ValidCacheData>(
+    requestId: string,
+    handler: () => Promise<TData>,
+    options?: CachedEffectOptions<TData>,
+): Result<TData>;
+```
+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.
+There is currently no way to reinvoke the effect without changing the `requestId`.
+```ts
+type CachedEffectOptions<TData: ValidCacheData> = {|
+    skip?: boolean,
+    retainResultOnChange?: boolean,
+    onResultChanged?: (result: Result<TData>) => void,
+    scope?: string,
+|};
+```
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `skip` | `false` | When `true`, the effect will not be executed; otherwise, the effect will be executed.  If this is set to `true` while the effect is still pending, the pending effect will be cancelled. |
+| `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. |

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

@@ -0,0 +1,73 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / useGql()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# useGql()
+```ts
+type FetchFn = <TData, TVariables: {...}>(
+    operation: GqlOperation<TData, TVariables>,
+    options?: GqlFetchOptions<TVariables, TContext>,
+) => Promise<TData>;
+function useGql<TContext: GqlContext>(
+    context: Partial<TContext> = ({}: $Shape<TContext>),
+): FetchFn;
+```
+The `useGql` hook requires that the calling component has been rendered with a [`GqlRouter`](/docs/data-exports-gqlrouter--page) as an ancestor component since it relies on the default context and fetch operation that is specified therein.
+The `useGql` hook can take a partial context value which will be combined with the default context to create the context used for a specific request.
+The return value of `useGql` is a fetch function that can be used to invoke a GraphQL request. It takes as arguments the [`GqlOperation`](/docs/data-types-gqloperation--page) operation to be performed and some options (which, by their nature, are optional). These options can be used to provide variables for the operation as well as additional customization of the context.
+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("|");
+};
+```
+## Context Merging
+Context overrides are combined such that any values that are explicitly or implicitly `undefined` on the partial context will be ignored. Any values that are explicitly `null` on the partial context will be removed from the merged context. The order of precedence is as follows:
+ 1. Values from the fetch partial context, then,
+ 2. Values from the `useGql` partial context, then,
+ 3. Values from the default context.

package/src/__docs__/exports.use-hydratable-effect.stories.mdx ADDED Viewed

@@ -0,0 +1,43 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / useHydratableEffect()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# useHydratableEffect()
+```ts
+function useHydratableEffect<TData: ValidCacheData>(
+    requestId: string,
+    handler: () => Promise<TData>,
+    options?: HydratableEffectOptions<TData>,
+): Result<TData>;
+```
+This hook combines [`useServerEffect`](/docs/data-exports-useservereffect--page) and [`useCachedEffect`](/docs/data-exports-usecachedeffect--page) to form an effect that can execute on the server and hydrate on the client.
+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).
+```ts
+type HydratableEffectOptions<TData: ValidCacheData> = {|
+    clientBehavior?: WhenClientSide,
+    skip?: boolean,
+    retainResultOnChange?: boolean,
+    onResultChanged?: (result: Result<TData>) => void,
+    scope?: string,
+|};
+```
+| Option | Default | Description |
+| ------ | ------- | ----------- |
+| `clientBehavior` | [`WhenClientSide.ExecuteWhenNoSuccessResult`](/docs/data-exports-whenclientside--page#whenclientsideexecutewhennosuccessresult) | How the hook should behave when rendering client-side for the first time. This controls the hydration and execution of the effect on the client. Changing this value after the initial render is inert. For more information on other behaviors, see [`WhenClientSide`](/docs/data-exports-whenclientside--page). |
+| `skip` | `false` | When `true`, the effect will not be executed; otherwise, the effect will be executed.  If this is set to `true` while the effect is still pending, the pending effect will be cancelled. |
+| `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. |

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

@@ -0,0 +1,38 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / useServerEffect()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# useServerEffect()
+```ts
+function useServerEffect<TData: ValidCacheData>(
+    requestId: string,
+    handler: () => Promise<TData>,
+    hydrate: boolean = true,
+): ?Result<TData>;
+```
+The `useServerEffect` hook is an integral part of server-side rendering. It has different behavior depending on whether it is running on the server (and in what context) or the client.
+## Server-side behavior
+First, this hook checks the server-side rendering cache for the request identifier; if it finds a cached value, it will return that.
+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.
+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).
+## Client-side behavior
+On initial render in the client, this hook will look for a corresponding value in the Wonder Blocks Data hydration cache. If there is one, it will delete it from the hydration cache and return that value.
+Otherwise, it will return `null`.

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

@@ -0,0 +1,30 @@
+import {Meta} from "@storybook/addon-docs";
+<Meta
+    title="Data / Exports / useSharedCache()"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+# useSharedCache()
+```ts
+function useSharedCache<TValue: ValidCacheData>(
+    id: string,
+    scope: string,
+    initialValue?: ?TValue | (() => ?TValue),
+): [?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 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).
+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.