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

@khanacademy/wonder-blocks-data 10.0.5 → 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 (181) hide show

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

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

@@ -1,31 +0,0 @@
-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/__docs__/exports.track-data.stories.mdx DELETED Viewed

@@ -1,209 +0,0 @@
-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.
-#### Client-side behavior
-If used outside of server-side mode (as set using `Server.setServerSide`), this
-component will throw, as demonstrated below.
-```jsx
-import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
-import {Server, View} from "@khanacademy/wonder-blocks-core";
-import {TrackData} from "@khanacademy/wonder-blocks-data";
-class ErrorBoundary extends React.Component {
-    constructor(props) {
-        super(props);
-        this.state = {};
-    }
-    static getDerivedStateFromError(error) {
-        return {error: error.message};
-    }
-    render() {
-        if (typeof jest !== "undefined") {
-            /**
-             * The snapshot test just sees the error getting thrown, not the
-             * awesome error boundary, so we have to hack around it to keep
-             * this live example, but not get test failures.
-             */
-            return "Sorry, no snapshot for you";
-        }
-        if (this.state.error) {
-            return (
-                <View>
-                    {this.state.error}
-                </View>
-            );
-        }
-        return this.props.children;
-    }
-}
-<ErrorBoundary>
-    <View>
-        <TrackData>
-            <Body>This only renders if we're in server-side mode and the page hot reloaded</Body>
-        </TrackData>
-    </View>
-</ErrorBoundary>
-```
-#### Server-side behavior
-When used server-side, this component tracks any data requests made through
-the `Data` component during a render cycle. This data can then be obtained
-using the `fetchTrackedRequests` method. The data can then be used in an
-additional render cycle to render with that data.
-```jsx
-import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
-import {Strut} from "@khanacademy/wonder-blocks-layout";
-import Spacing from "@khanacademy/wonder-blocks-spacing";
-import Button from "@khanacademy/wonder-blocks-button";
-import {Server, View} from "@khanacademy/wonder-blocks-core";
-import {Data, TrackData, fetchTrackedRequests} from "@khanacademy/wonder-blocks-data";
-const myPretendHandler = () => new Promise((resolve, reject) =>
-    setTimeout(() => resolve("DATA!"), 3000),
-);
-class Example extends React.Component {
-    constructor() {
-        super();
-        /**
-         * For this demonstration, we need to hack the return of isServerSide solely
-         * for the scope of this component.
-         */
-        this.state = {};
-    }
-    static getDerivedStateFromError(error) {
-        return {error};
-    }
-    componentDidMount() {
-        this._mounted = true;
-    }
-    componentWillUnmount() {
-        this._mounted = false;
-    }
-    setClientMode() {
-        window.location.reload();
-    }
-    setServerMode() {
-        Server.setServerSide();
-        this.setState({refresh: Date.now(), error: null});
-    };
-    _renderErrorOrContent() {
-        if (typeof jest !== "undefined") {
-            /**
-             * The snapshot test just sees the error getting thrown, not the
-             * awesome error boundary, so we have to hack around it to keep
-             * this live example, but not get test failures.
-             */
-            return "Sorry, no snapshot for you";
-        }
-        if (this.state.error) {
-            return (
-                <React.Fragment>
-                    <Strut size={Spacing.small_12} />
-                    <Body>We can't show you anything useful in client-side mode</Body>
-                </React.Fragment>
-            );
-        }
-        const data = this.state.data
-            ? JSON.stringify(this.state.data, undefined, "  ")
-            : "Data requested...";
-        return (
-            <React.Fragment>
-                <Strut size={Spacing.small_12} />
-                <TrackData>
-                    <Data handler={myPretendHandler} requestId="TRACK_DATA_EXAMPLE">
-                        {(result) => (
-                            <View>
-                                <BodyMonospace>{`Loading: ${result.status === "loading"}`}</BodyMonospace>
-                                <BodyMonospace>{`Data: ${JSON.stringify(result.data)}`}</BodyMonospace>
-                            </View>
-                        )}
-                    </Data>
-                </TrackData>
-                <Strut size={Spacing.small_12} />
-                <View>
-                    <Body>
-                        The above components requested data, but we're server-side,
-                        so all that happened is we tracked the request.
-                        In this example, we've also called `fetchTrackedRequests`
-                        to fetch that tracked data.
-                    </Body>
-                    <Strut size={Spacing.small_12} />
-                    <Body>
-                        In about 3 seconds, it will appear below. Notice that
-                        when it does, the above still doesn't update. That's
-                        because during SSR, the data is not updated in the
-                        rendered tree.
-                    </Body>
-                    <Strut size={Spacing.small_12} />
-                    <BodyMonospace>{data}</BodyMonospace>
-                </View>
-            </React.Fragment>
-        );
-    }
-    render() {
-        try {
-            return (
-                <View key={this.state.refresh}>
-                    {Server.isServerSide()
-                        ? (
-                            <React.Fragment>
-                                <Button kind={"secondary"} onClick={() => this.setClientMode()}>Back to Client-side Mode (reloads page)</Button>
-                                <Strut size={Spacing.small_12} />
-                                <Button kind={"secondary"} onClick={() => this.setServerMode()}>Re-mount</Button>
-                            </React.Fragment>
-                        ) : (
-                            <Button kind={"primary"} onClick={() => this.setServerMode()}>Enable Server-side Mode</Button>
-                        )
-                    }
-                    {this._renderErrorOrContent()}
-                </View>
-            );
-        } finally {
-            if (!this.state.data && Server.isServerSide()) {
-                setTimeout(() => fetchTrackedRequests().then((data) => {
-                    if (this._mounted) {
-                        this.setState({data});
-                    }
-                }), 0);
-            }
-        }
-    }
-}
-<Example />
-```

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

@@ -1,44 +0,0 @@
-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>, () => void];
-```
-This hook invokes the given handler and caches the result using the [`useSharedCache`](/docs/data-exports-usesharedcache--page) hook. The `requestId` is used to both identify inflight requests that can be shared, and to identify the cached value to use.
-The hook returns an array containing the current state of the request, and a function that can be used to `refetch` that request on demand. Calling `refetch` while an inflight request is in progress for the given `requestId` will be a no-op.
-The behavior of the hook can be modified with the options.
-```ts
-type CachedEffectOptions<TData: ValidCacheData> = {|
-    skip?: boolean,
-    retainResultOnChange?: boolean,
-    onResultChanged?: (result: Result<TData>) => void,
-    scope?: string,
-    fetchPolicy?: FetchPolicy,
-|};
-```
-| 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. |
-| `fetchPolicy` | [`FetchPolicy`](/docs/data-types-fetchpolicy--page) | Fetch policy to use when fetching the data. Defaults to `FetchPolicy.CacheBeforeNetwork`. |