@khanacademy/wonder-blocks-data 4.0.0 → 6.0.0

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.

package/src/__docs__/types.error-options.stories.mdx

@@ -0,0 +1,21 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / ErrorOptions"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# ErrorOptions
+
+```ts
+type ErrorOptions = {|
+    metadata?: ?Metadata,
+    cause?: ?Error,
+|};
+```
+
+These options allow for the provision of a causal error instance as well as additional metadata that may be useful to the specific error being constructed (such as [`DataError`](/docs/data-exports-dataerror--page) or [`GqlError`](/docs/data-exports-gqlerror--page)).

package/src/__docs__/types.gql-context.stories.mdx

@@ -0,0 +1,20 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / GqlContext"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlContext
+
+```ts
+type GqlContext = {|
+    [key: string]: string,
+|};
+```
+
+`GqlContext` represents the valid range of values for the `context` of a GraphQL query or mutation.

package/src/__docs__/types.gql-fetch-fn.stories.mdx

@@ -0,0 +1,24 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / GqlFetchFn<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlFetchFn&lt;&gt;
+
+```ts
+type GqlFetchFn<TData, TVariables: {...}, TContext: GqlContext> = (
+    operation: GqlOperation<TData, TVariables>,
+    variables: ?TVariables,
+    context: TContext,
+) => Promise<Response>;
+```
+
+The `GqlFetchFn<>` type describes the function that will perform a GraphQL request. A function that fits this signature is configured in Wonder Blocks Data using the [`GqlRouter`](/docs/data-exports-gqlrouter--page) component. The [`useGql`](/docs/data-exports-usegql--page) hook and derivatives are then built on top of this to abstract away complexities, such as converting the `Response` to a valid [`Result<>`](/docs/data-types-result--page) instance, as various use cases see fit.
+
+See the section on [GraphQL](/docs/data-graphql--page) for more information.

package/src/__docs__/types.gql-fetch-options.stories.mdx

@@ -0,0 +1,24 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / GqlFetchOptions<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlFetchOptions&lt;&gt;
+
+```ts
+type GqlFetchOptions<TVariables: {...}, TContext: GqlContext> = {|
+    variables?: TVariables,
+    context?: Partial<TContext>,
+|};
+```
+
+This type describes optional configuration to apply when fulfilling a GraphQL request.
+
+See the section on [GraphQL](/docs/data-graphql--page) for more information.
+

package/src/__docs__/types.gql-operation-type.stories.mdx

@@ -0,0 +1,24 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / GqlOperationType"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlOperationType
+
+```ts
+type GqlOperationType = "mutation" | "query";
+```
+
+Unlike some GraphQL clients, the Wonder Blocks Data GraphQL support avoids requiring the full GraphQL document node at runtime. This allows the client to be lighter weight and introduces the option for calling code to perform some GraphQL request optimizations at build time, such as formatting the document node as a string and therefore not requiring additional dependencies at runtime.
+
+In order to allow consumers of our GraphQL support to include some validation of the GraphQL document node at runtime (such as ensuring that mutations are not performed in unsupported scenarios), we the type of the operation is included in the operation definition.
+
+This type represents the valid values for that field.
+
+See the section on [GraphQL](/docs/data-graphql--page) for more information.

package/src/__docs__/types.gql-operation.stories.mdx

@@ -0,0 +1,67 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / GqlOperation<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# GqlOperation&lt;&gt;
+
+```ts
+type GqlOperation<
+    TData,
+    TVariables: {...} = Empty,
+> = {
+    type: GqlOperationType,
+    id: string,
+    [key: string]: mixed,
+    ...
+};
+```
+
+The `GqlOperation<>` type provides the Wonder Blocks Data definition of a GraphQL query or mutation. It has two required fields:
+
+ * `type`: The type of operation. It can be either `"query"` or `"mutation"`.
+ * `id`: The unique identifier of the operation.
+
+Unlike some GraphQL clients, the definition of the operation (the document node, for example) is not required by the Wonder Blocks Data implementation. If a specific use requires that information, the calling code is able to provide it.
+
+Consider the following GraphQL query (using `graphql-tag`):
+
+```ts
+const MyQuery = gql`
+    query myQuery {
+        user {
+            id
+            name
+        }
+    }
+`;
+```
+
+Rather than using the full `DocumentNode` at runtime, one could envisage a build step that converts it to a `GqlOperation<>` at compile time by parsing the `DocumentNode` to determine the operation type and extract the name of the operation. If the actual definition is needed for sending to the server in the request, this can be obtained from `graphql/language/printer`. This would then reduce the dependencies needed to perform GraphQL operations at runtime.
+
+The resulting `GqlOperation<>` would look like this:
+
+```ts
+{
+    type: "query",
+    id: "myQuery",
+}
+```
+
+Or, if say, the query definition were needed (for example, Apollo will send requests with the `query` field):
+
+```ts
+{
+    type: "query",
+    id: "myQuery",
+    query: "query myQuery { user { id name } }",
+}
+```
+
+See the section on [GraphQL](/docs/data-graphql--page) for more information.

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

@@ -0,0 +1,33 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / ResponseCache"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# ResponseCache
+
+```ts
+type ResponseCache = {
+    [key: string]: CachedResponse<any>,
+    ...
+};
+```
+
+`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).
+
+```ts
+const responseCache: ResponseCache = {
+    DATA_ID_1: {error: "It go 💥boom 😢"},
+    DATA_ID_2: {data: ["array", "of", "data"]},
+    DATA_ID_3: {data: {some: "data"}},
+};
+```
+
+In this example, the cache contains data retrieved for three different requests.
+
+Each entry in the cache is of type [`CachedResponse`](/docs/data-types-cachedresponse--page). See the section on [server-side rendering](/docs/data-server-side-rendering-and-hydration--page) for more information.

package/src/__docs__/types.result.stories.mdx

@@ -0,0 +1,39 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / Result<>"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# Result&lt;&gt;
+
+```ts
+type Result<TData: ValidCacheData> =
+    | {|
+          status: "loading",
+      |}
+    | {|
+          status: "success",
+          data: TData,
+      |}
+    | {|
+          status: "error",
+          error: Error,
+      |}
+    | {|
+          status: "aborted",
+      |};
+```
+
+The `Result<>` type is used to describe the result of an asynchronous operation. It is the primary type used by hooks and components in Wonder Blocks Data to convey the status of asynchronous tasks.
+
+There are four states represented by the `Result<>` type:
+
+ * `loading`: The operation is in pending.
+ * `success`: The operation completed successfully.
+ * `error`: The operation failed.
+ * `aborted`: The operation was aborted.

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

@@ -0,0 +1,27 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / ScopedCache"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# ScopedCache
+
+```ts
+type ScopedCache = {
+    [scope: string]: {
+        [id: string]: ValidCacheData,
+        ...
+    },
+    ...
+};
+
+```
+
+`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).
+
+See the section on [server-side rendering](/docs/data-server-side-rendering-and-hydration--page) for more information.

package/src/__docs__/types.valid-cache-data.stories.mdx

@@ -0,0 +1,23 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Data / Types / ValidCacheData"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# ValidCacheData
+
+```ts
+type ValidCacheData =
+    | string
+    | boolean
+    | number
+    | {...}
+    | Array<?ValidCacheData>;
+```
+
+This type represents the data that is allowed into the various caches provided and used by Wonder Blocks Data.

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

@@ -195,86 +195,6 @@ exports[`wonder-blocks-data example 2 1`] = `
       I'm DATA from the hydration cache
     </span>
   </div>
-  <div
-    aria-hidden="true"
-    className=""
-    style={
-      Object {
-        "MsFlexBasis": 12,
-        "MsFlexPreferredSize": 12,
-        "WebkitFlexBasis": 12,
-        "alignItems": "stretch",
-        "borderStyle": "solid",
-        "borderWidth": 0,
-        "boxSizing": "border-box",
-        "display": "flex",
-        "flexBasis": 12,
-        "flexDirection": "column",
-        "flexShrink": 0,
-        "margin": 0,
-        "minHeight": 0,
-        "minWidth": 0,
-        "padding": 0,
-        "position": "relative",
-        "width": 12,
-        "zIndex": 0,
-      }
-    }
-  />
-  <div
-    className=""
-    style={
-      Object {
-        "alignItems": "stretch",
-        "borderStyle": "solid",
-        "borderWidth": 0,
-        "boxSizing": "border-box",
-        "display": "flex",
-        "flexDirection": "column",
-        "margin": 0,
-        "minHeight": 0,
-        "minWidth": 0,
-        "padding": 0,
-        "position": "relative",
-        "zIndex": 0,
-      }
-    }
-  >
-    <span
-      className=""
-      style={
-        Object {
-          "MozOsxFontSmoothing": "grayscale",
-          "WebkitFontSmoothing": "antialiased",
-          "display": "block",
-          "fontFamily": "Lato, \\"Noto Sans\\", sans-serif",
-          "fontSize": 16,
-          "fontWeight": 400,
-          "lineHeight": "22px",
-        }
-      }
-    >
-      This cache has error!
-    </span>
-    <span
-      className=""
-      style={
-        Object {
-          "MozOsxFontSmoothing": "grayscale",
-          "WebkitFontSmoothing": "antialiased",
-          "color": "#d92916",
-          "display": "block",
-          "fontFamily": "Inconsolata, monospace",
-          "fontSize": 17,
-          "fontWeight": 400,
-          "lineHeight": "22px",
-        }
-      }
-    >
-      ERROR: 
-      I'm an ERROR from hydration cache
-    </span>
-  </div>
 </div>
 `;
 

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

@@ -13,7 +13,7 @@ import {View, Server} from "@khanacademy/wonder-blocks-core";
 import {
     Data,
     initializeCache,
-    InterceptData,
+    InterceptRequests,
     TrackData,
     fulfillAllDataRequests,
 } from "@khanacademy/wonder-blocks-data";
@@ -86,9 +86,6 @@ describe("wonder-blocks-data", () => {
             DATA: {
                 data: "I'm DATA from the hydration cache",
             },
-            ERROR: {
-                error: "I'm an ERROR from hydration cache",
-            },
         });
         const example = (
             <View>
@@ -104,27 +101,6 @@ describe("wonder-blocks-data", () => {
                         }}
                     </Data>
                 </View>
-                <Strut size={Spacing.small_12} />
-                <View>
-                    <Body>This cache has error!</Body>
-                    <Data handler={myHandler} requestId="ERROR">
-                        {(result) => {
-                            if (result.status !== "error") {
-                                return "If you see this, the example is broken!";
-                            }
-
-                            return (
-                                <BodyMonospace
-                                    style={{
-                                        color: Color.red,
-                                    }}
-                                >
-                                    ERROR: {result.error}
-                                </BodyMonospace>
-                            );
-                        }}
-                    </Data>
-                </View>
             </View>
         );
         const tree = renderer.create(example).toJSON();
@@ -135,13 +111,13 @@ describe("wonder-blocks-data", () => {
         const myHandler = () =>
             Promise.reject(new Error("You should not see this!"));
 
-        const interceptHandler = () => Promise.resolve("INTERCEPTED DATA!");
+        const interceptor = (requestId) =>
+            requestId === "INTERCEPT_EXAMPLE"
+                ? Promise.resolve("INTERCEPTED DATA!")
+                : null;
 
         const example = (
-            <InterceptData
-                handler={interceptHandler}
-                requestId="INTERCEPT_EXAMPLE"
-            >
+            <InterceptRequests interceptor={interceptor}>
                 <View>
                     <Body>This received intercepted data!</Body>
                     <Data handler={myHandler} requestId="INTERCEPT_EXAMPLE">
@@ -154,7 +130,7 @@ describe("wonder-blocks-data", () => {
                         }}
                     </Data>
                 </View>
-            </InterceptData>
+            </InterceptRequests>
         );
         const tree = renderer.create(example).toJSON();
         expect(tree).toMatchSnapshot();