@khanacademy/wonder-blocks-data 5.0.1 → 6.0.0

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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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}

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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.

package/src/__docs__/exports.when-client-side.stories.mdx

@@ -0,0 +1,33 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Exports / WhenClientSide"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# WhenClientSide
+
+This enumeration is used with [`useHydratableEffect`](/docs/data-exports-usehydratableeffect--page). It defines how the hook should behave when rendering on the client.
+
+## WhenClientSide.DoNotHydrate
+
+The effect will not be hydrated and as such the effect will always be executed on initial render in the client. This is an advanced use-case that you should avoid unless you are certain of what you are doing.
+
+Without hydration support to ensure the data is available for hydration on the client, your server and client rendered pages may differ and the hydration will fail. This option is useful if something else is responsible for data capture and hydration of the action that gets executed. For example, if the action uses Apollo Client to perform the asynchronous action executed by this effect, then that may be also performing hydration responsibilities. However, be cautious; the code that calls `useHydratableEffect` will have to have access to that data on hydration as `useHydratableEffect` will return a "loading" state on initial render, which is not what you will want.
+
+## WhenClientSide.ExecuteWhenNoResult
+
+On initial render in the client, the effect is hydrated from the server-side rendered result. However, it is only executed if there was no server-side render result to hydrate (this can happen if the server-side rendered request was aborted, or if the component is rendering for the first time on the client and was never part of the server-side rendered content).
+
+## WhenClientSide.ExecuteWhenNoSuccessResult
+
+This behavior will hydrate the server-side result, but it will only execute the effect on the client if the hydrated result is not a success result.
+
+## WhenClientSide.AlwaysExecute
+
+When the effect is executed with this behavior, the server-side result will be hydrated and the effect will be executed on the initial client-side render, regardless of the hydrated result status.
+

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

@@ -0,0 +1,29 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / CachedResponse<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# CachedResponse&lt;&gt;
+
+```ts
+type CachedResponse<TData: ValidCacheData> =
+    | {|
+          +error: string,
+          +data?: void,
+      |}
+    | {|
+          +data: TData,
+          +error?: void,
+      |};
+```
+
+`CachedResponse<>` is a special union type that is used to represent the serialized result of a request, which can be used by Wonder Blocks Data to
+hydrate the response.
+
+See the section on [server-side rendering](/docs/data-server-side-rendering-and-hydration--page) for more information.