npm - @khanacademy/wonder-blocks-data - Versions diffs - 10.1.0 → 10.1.1 - Mend

@khanacademy/wonder-blocks-data 10.1.0 → 10.1.1

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 (180) hide show

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

@@ -1,146 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-import {Data} from "../index.js";
-<Meta
-    title="Data / Exports / Data"
-    component={Data}
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-# Data
-The `Data` component is the frontend piece of our data architecture.
-It describes a data requirement in terms of a handler and an identifier.
-It also has props to govern hydrate behavior as well as loading and client-side
-request behavior.
-The handler is responsible for fulfilling the request when asked to do so.
-#### Server-side Rendering and Hydration
-The Wonder Blocks Data framework uses an in-memory cache for supporting
-server-side rendering (SSR) and hydration.
-##### Server-side behavior
-###### Cache miss
-When the `Data` component does not get data or an error from the cache and it
-is rendering server-side, it tells our request tracking that it wants data, and
-it renders in its `loading` state. It will always render in this state if there
-is no cached response.
-###### Cache hit
-When the `Data` component gets data or an error from the cache and it is
-rendering server-side, it will render as loaded, with that data or error,
-as it would client-side. In this situation, it does not track the request it
-would have made, as it already has the data and doesn't need to.
-##### Client-side behavior
-###### Cache miss
-When the hydration cache does not contain the data, the data will be requested.
-While the request is pending, the data is rendered in the loading state.
-In this example, we use a 3 second delayed promise to simulate the request.
-We start out without any data and so the request is made. Upon receipt of that
-data or an error, we re-render.
-```jsx
-import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {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 myValidHandler = () => new Promise((resolve, reject) =>
-    setTimeout(() => resolve("I'm DATA from a request"), 3000),
-);
-const myInvalidHandler = () => new Promise((resolve, reject) =>
-    setTimeout(() => reject("I'm an ERROR from a request"), 3000),
-);
-<View>
-    <View>
-        <Body>This request will succeed and give us data!</Body>
-        <Data handler={myValidHandler} requestId="VALID">
-            {(result) => {
-                if (result.status === "loading") {
-                    return "Loading...";
-                }
-                return (
-                    <BodyMonospace>{result.data}</BodyMonospace>
-                );
-            }}
-        </Data>
-    </View>
-    <Strut size={Spacing.small_12} />
-    <View>
-        <Body>This request will go boom and give us an error!</Body>
-        <Data handler={myInvalidHandler} requestId="INVALID">
-            {(result) => {
-                if (result.status === "loading") {
-                    return "Loading...";
-                }
-                return (
-                    <BodyMonospace style={{color: Color.red}}>ERROR: {result.error}</BodyMonospace>
-                );
-            }}
-        </Data>
-    </View>
-</View>
-```
-###### Cache hit
-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 `initializeHydrationCache` method before rendering.
-```jsx
-import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
-import {View} from "@khanacademy/wonder-blocks-core";
-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";
-const myHandler = () => {
-    throw new Error(
-        "If you're seeing this error, the examples are broken and data isn't in the cache that should be.",
-    );
-};
-initializeHydrationCache({
-    DATA: {
-        data: "I'm DATA from the hydration cache"
-    },
-});
-<View>
-    <View>
-        <Body>This cache has data!</Body>
-        <Data handler={myHandler} requestId="DATA">
-            {(result) => {
-                if (result.status !== "success") {
-                    return "If you see this, the example is broken!";
-                }
-                return (
-                    <BodyMonospace>{result.data}</BodyMonospace>
-                );
-            }}
-        </Data>
-    </View>
-</View>
-```

package/src/__docs__/exports.fetch-tracked-requests.stories.mdx DELETED Viewed

@@ -1,24 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-<Meta
-    title="Data / Exports / fetchTrackedRequests()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-# fetchTrackedRequests()
-```ts
-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 `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 [`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 DELETED Viewed

@@ -1,24 +0,0 @@
-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.gql-error.stories.mdx DELETED Viewed

@@ -1,23 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-<Meta
-    title="Data / Exports / GqlError"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-# GqlError
-```ts
-new GqlError(
-    message: string,
-    kind: $Values<typeof GqlErrors>,
-    options?: ErrorOptions,
-);
-```
-The `GqlError` class is a derivation of the Wonder Blocks Core `KindError` (which is itself a derivation of `Error`). It is used by the Wonder Blocks Data GraphQL framework to encapsulate errors that can occur within the GraphQL API. The different kinds of errors supported are defined by the [`GqlErrors`](/docs/data-exports-gqlerrors--page) export.

package/src/__docs__/exports.gql-errors.stories.mdx DELETED Viewed

@@ -1,20 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-<Meta
-    title="Data / Exports / GqlErrors"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-# GqlErrors
-This export defines the error taxonomy used by Wonder Blocks Data to describe the GraphQL-related errors that can occur with GraphQL requests. These are for use with [`GqlError`](/docs/data-exports-gqlerror--page).
-| Kind | Description |
-| ---- | ----------- |
-| `GqlErrors.Unknown` | The type of error is unknown. |
-| `GqlErrors.BadResponse` | Response does not have the correct structure for a GraphQL response. |
-| `GqlErrors.ErrorResult` | A valid GraphQL result with errors field in the payload. |

package/src/__docs__/exports.gql-router.stories.mdx DELETED Viewed

@@ -1,29 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-import {GqlRouter} from "../index.js";
-<Meta
-    title="Data / Exports / GqlRouter"
-    component={GqlRouter}
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-# GqlRouter
-The `GqlRouter` component is used to define the default context and fetch function for performing GraphQL requests using the Wonder Blocks Data API.
-The [`useGql`](/docs/data-exports-usegql--page) (and therefore any hooks or components that use it) requires at least one `GqlRouter` in the component hierarchy above it or it will throw an error.
-The `defaultContext` is specific to the needs of your specific implementation, as is the `fetch` function. Currently, a default for the fetch function is not provided by Wonder Blocks Data and should be written to the specification of the server that will fulfill your GraphQL responses. The `fetch` function must conform to the [`GqlFetchFn<>`](/docs/data-types-gqlfetchfn--page) type.
-```tsx
-<GqlRouter defaultContext={{a: "1", b: "2"}} fetch={gqlFetchFn}>
-    <div>
-        The code that will ultimately use Wonder Blocks Data-based GraphQL
-        operations goes here.
-    </div>
-</GqlRouter>
-```

package/src/__docs__/exports.has-tracked-requests-to-be-fetched.stories.mdx DELETED Viewed

@@ -1,20 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-<Meta
-    title="Data / Exports / hasTrackedRequestsToBeFetched()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-# hasTrackedRequestsToBeFetched()
-```ts
-hasTrackedRequestsToBeFetched(): boolean;
-```
-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.intercept-requests.stories.mdx DELETED Viewed

@@ -1,69 +0,0 @@
-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-hydration-cache.stories.mdx DELETED Viewed

@@ -1,29 +0,0 @@
-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 DELETED Viewed

@@ -1,23 +0,0 @@
-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 `SharedCache.purgeAll()` and `purgeHydrationCache()`, and is especially useful when writing tests or setting up a test environment.

package/src/__docs__/exports.purge-hydration-cache.stories.mdx DELETED Viewed

@@ -1,24 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-<Meta
-    title="Data / Exports / purgeHydrationCache()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-# purgeHydrationCache()
-```ts
-purgeHydrationCache(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 [`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.scoped-in-memory-cache.stories.mdx DELETED Viewed

@@ -1,92 +0,0 @@
-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. It implements the [`ScopedCache`](/docs/data-types-scopedcache--page) interface.
-## constructor()
-```ts
-new ScopedInMemoryCache(initialCache?: RawScopedCache)
-```
-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(
-    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 DELETED Viewed

@@ -1,112 +0,0 @@
-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?: RawScopedCache)
-```
-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(): RawScopedCache;
-```
-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.shared-cache.stories.mdx DELETED Viewed

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