@khanacademy/wonder-blocks-data 4.0.0 → 6.0.0

package/docs.md

@@ -1,122 +0,0 @@
-## fulfillAllDataRequests
-
-When performing server-side rendering (SSR), the data requests that are being
-made via the `Data` component can be tracked by rendering the React tree
-inside the `TrackData` component. After this has occurred, the tracked requests
-can be fulfilled using `fulfillAllDataRequests`.
-
-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 `initializeCache`
-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.
-
-### Usage
-
-```js static
-fulfillAllDataRequests(): Promise<ResponseCache>;
-```
-
-## initializeCache
-
-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` after tracking data requests
-(see [TrackData](#trackdata)) during server-side rendering.
-
-Combine with `removeFromCache` or `removeAllFromCache` to support your testing
-needs.
-
-### Usage
-
-```js static
-initializeCache(sourceCache: ResponseCache): void;
-```
-
-#### Function arguments
-
-| Argument | Flow&nbsp;Type | Default | Description |
-| --- | --- | --- | --- |
-| `sourceData` | `ResponseCache` | _Required_ | The source cache that will be used to initialize the response cache. |
-
-## removeFromCache
-
-Removes an entry from the cache. The given handler and options identify the entry to be removed.
-
-If an item is removed, this returns `true`; otherwise, `false`.
-
-This can be used after `initializeCache` to manipulate the cache prior to hydration.
-This can be useful during testing.
-
-### Usage
-
-```js static
-removeFromCache(id: string): boolean;
-```
-
-#### Function arguments
-
-| Argument | Flow&nbsp;Type | Default | Description |
-| --- | --- | --- | --- |
-| `id` | `string` | _Required_ | The id of the item to be removed. |
-
-## removeAllFromCache
-
-Removes all entries that match a given predicate from the cache. If no predicate is given, all cached entries for the given handler are removed.
-
-This returns the count of entries removed.
-
-This can be used after `initializeCache` to manipulate the cache prior to hydration.
-This can be useful during testing (especially to clear the cache so that it can be initialized again).
-If the predicate is not given, all items are removed.
-
-### Usage
-
-```js static
-removeAllFromCache(predicate?: (key: string, entry: $ReadOnly<CachedResponse<TData>>) => boolean): number;
-```
-
-#### Function arguments
-
-| 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. |
-
-## Types
-
-### ResponseCache
-
-```js static
-type CachedResponse =
-    | {|
-        data: any,
-      |}
-    | {|
-        error: string,
-      |};
-
-type ResponseCache = {
-    [id: string]: CachedResponse,
-    ...,
-};
-```
-
-An example is of the response cache is shown below.
-
-```js static
-const 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.

package/src/components/__tests__/intercept-data.test.js

@@ -1,63 +0,0 @@
-// @flow
-import * as React from "react";
-import {render} from "@testing-library/react";
-
-import InterceptContext from "../intercept-context.js";
-import InterceptData from "../intercept-data.js";
-
-describe("InterceptData", () => {
-    afterEach(() => {
-        jest.resetAllMocks();
-    });
-
-    it("should update context with fulfillRequest method", () => {
-        // Arrange
-        const fakeHandler = () => Promise.resolve("data");
-        const props = {
-            handler: fakeHandler,
-            requestId: "ID",
-        };
-        const captureContextFn = jest.fn();
-
-        // Act
-        render(
-            <InterceptData {...props}>
-                <InterceptContext.Consumer>
-                    {captureContextFn}
-                </InterceptContext.Consumer>
-            </InterceptData>,
-        );
-
-        // Assert
-        expect(captureContextFn).toHaveBeenCalledWith(
-            expect.objectContaining({
-                ID: props.handler,
-            }),
-        );
-    });
-
-    it("should override parent InterceptData", () => {
-        // Arrange
-        const fulfillRequest1Fn = jest.fn();
-        const fulfillRequest2Fn = jest.fn();
-        const captureContextFn = jest.fn();
-
-        // Act
-        render(
-            <InterceptData handler={fulfillRequest1Fn} requestId="ID">
-                <InterceptData handler={fulfillRequest2Fn} requestId="ID">
-                    <InterceptContext.Consumer>
-                        {captureContextFn}
-                    </InterceptContext.Consumer>
-                </InterceptData>
-            </InterceptData>,
-        );
-
-        // Assert
-        expect(captureContextFn).toHaveBeenCalledWith(
-            expect.objectContaining({
-                ID: fulfillRequest2Fn,
-            }),
-        );
-    });
-});

package/src/components/intercept-data.js

@@ -1,66 +0,0 @@
-// @flow
-import * as React from "react";
-
-import InterceptContext from "./intercept-context.js";
-
-import type {ValidCacheData} from "../util/types.js";
-
-type Props<TData: ValidCacheData> = {|
-    /**
-     * The ID of the request to intercept.
-     */
-    requestId: string,
-
-    /**
-     * Called to intercept and fulfill the request.
-     * If this returns null, the request will be fulfilled by the
-     * handler of the original request being intercepted.
-     */
-    handler: () => ?Promise<?TData>,
-
-    /**
-     * The children to render within this component. Any requests by `Data`
-     * components that use same ID as this component will be intercepted.
-     * (unless another `InterceptData` component overrides this one).
-     */
-    children: React.Node,
-|};
-
-/**
- * This component provides a mechanism to intercept data requests.
- * This is for use in testing.
- *
- * This component is not recommended for use in production code as it
- * can prevent predictable functioning of the Wonder Blocks Data framework.
- * One possible side-effect is that inflight requests from the interceptor could
- * be picked up by `Data` component requests from outside the children of this
- * component.
- *
- * These components do not chain. If a different `InterceptData` instance is
- * rendered within this one that intercepts the same id, then that
- * new instance will replace this interceptor for its children. All methods
- * will be replaced.
- */
-const InterceptData = <TData: ValidCacheData>({
-    requestId,
-    handler,
-    children,
-}: Props<TData>): React.Node => {
-    const interceptMap = React.useContext(InterceptContext);
-
-    const updatedInterceptMap = React.useMemo(
-        () => ({
-            ...interceptMap,
-            [requestId]: handler,
-        }),
-        [interceptMap, requestId, handler],
-    );
-
-    return (
-        <InterceptContext.Provider value={updatedInterceptMap}>
-            {children}
-        </InterceptContext.Provider>
-    );
-};
-
-export default InterceptData;

package/src/components/intercept-data.md

@@ -1,51 +0,0 @@
-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 `InterceptData` component.
-
-This component takes three props; children to be rendered, the handler of the
-to fulfill the request, and the id of the request that is being intercepted.
-
-Note that this component is expected to be used only within test cases and
-usually only as a single instance. In flight requests for a given handler
-type can be shared and as such, using `InterceptData` alongside non-intercepted
-`Data` components with the same id can have indeterminate outcomes.
-
-The `handler` intercept function has the form:
-
-```js static
-() => ?Promise<?TData>;
-```
-
-If this method returns `null`, the default behavior occurs. This
-means that a request will be made for data via the handler assigned to the
-`Data` component being intercepted.
-
-```jsx
-import {Body, BodyMonospace} from "@khanacademy/wonder-blocks-typography";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {InterceptData, 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 interceptHandler = () => Promise.resolve("INTERCEPTED DATA!");
-
-<InterceptData handler={interceptHandler} requestId="INTERCEPT_EXAMPLE">
-    <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>
-</InterceptData>
-```