@khanacademy/wonder-blocks-data 2.3.4 → 3.0.0

package/src/components/intercept-cache.js

@@ -1,79 +0,0 @@
-// @flow
-import * as React from "react";
-
-import InterceptContext from "./intercept-context.js";
-
-import type {
-    ValidData,
-    IRequestHandler,
-    InterceptCacheFn,
-} from "../util/types.js";
-
-type Props<TOptions, TData> = {|
-    /**
-     * A handler of the type to be intercepted.
-     */
-    handler: IRequestHandler<TOptions, TData>,
-
-    /**
-     * The children to render within this component. Any cache lookups by `Data`
-     * components that use a handler of the same type as the handler for this
-     * component that are rendered within these children will be intercepted by
-     * this component (unless another `InterceptData` component overrides this
-     * one).
-     */
-    children: React.Node,
-
-    /**
-     * Called to retrieve a cache entry.
-     *
-     * The method takes a key, the options for a request, and the existing
-     * cached entry if one exists.
-     *
-     * If this returns null, the default behavior occurs.
-     */
-    getEntry: InterceptCacheFn<TOptions, TData>,
-|};
-
-/**
- * This component provides a mechanism to intercept cache lookups for the
- * type of a given handler and provide alternative values. This is mostly
- * useful for testing.
- *
- * This does not modify the cache in any way. If you want to intercept
- * requests and cache based on the intercept, then use `InterceptData`.
- *
- * This component is generally not suitable for use in production code as it
- * can prevent predictable functioning of the Wonder Blocks Data framework.
- *
- * These components do not chain. If a different `InterceptCache` instance is
- * rendered within this one that intercepts the same handler type, then that
- * new instance will replace this interceptor for its children.
- */
-export default class InterceptCache<
-    TOptions,
-    TData: ValidData,
-> extends React.Component<Props<TOptions, TData>> {
-    render(): React.Node {
-        return (
-            <InterceptContext.Consumer>
-                {(value) => {
-                    const handlerType = this.props.handler.type;
-                    const interceptor = {
-                        ...value[handlerType],
-                        getEntry: this.props.getEntry,
-                    };
-                    const newValue = {
-                        ...value,
-                        [handlerType]: interceptor,
-                    };
-                    return (
-                        <InterceptContext.Provider value={newValue}>
-                            {this.props.children}
-                        </InterceptContext.Provider>
-                    );
-                }}
-            </InterceptContext.Consumer>
-        );
-    }
-}

package/src/components/intercept-cache.md

@@ -1,103 +0,0 @@
-Although it is possible to use the `initializeCache` method to setup test cases
-when working with the `Data` component, that can be a little cumbersome since
-it can only be called once and it requires knowledge of the cache structure.
-
-Instead of jumping through those hoops, you can use the `InterceptCache`
-component and provide an override method that will get called when looking up
-cached values. This component takes three props:
-
-- children to be rendered
-- the handler for data caches that are to be intercepted
-- a function for processing the intercept
-
-The intercept function has the form:
-
-```js static
-(options: TOptions, cacheEntry: ?$ReadOnly<CacheEntry<TData>>) => ?$ReadOnly<CacheEntry<TData>>
-```
-
-`options` are the options that would configure a data request that leads to the
-cached result.
-`cacheEntry` is the existing entry in the data cache.
-
-If the method returns `null`, the default behavior occurs. This means that if
-`cacheEntry` has a value, that will be used; otherwise, a request will be
-made for data via the relevant 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 {InterceptCache, Data, RequestHandler} 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";
-
-class MyHandler extends RequestHandler {
-    constructor() {
-        super("INTERCEPT_CACHE_HANDLER");
-    }
-
-    /**
-     * fulfillRequest should not get called as we already have data cached.
-     */
-    fulfillRequest(options) {
-        throw new Error(
-            "If you're seeing this error, the examples are broken.",
-        );
-    }
-
-    shouldRefreshCache(options, cachedEntry) {
-        /**
-         * For our purposes, the cache never needs a refresh.
-         */
-        return false;
-    }
-}
-
-const handler = new MyHandler();
-const getEntryIntercept = function(options) {
-    if (options === "ERROR") {
-        return {error: "I'm an ERROR from the cache interceptor"};
-    }
-
-    return {data: "I'm DATA from the cache interceptor"};
-};
-
-<InterceptCache handler={handler} getEntry={getEntryIntercept}>
-    <View>
-        <Body>This intercepted cache has data!</Body>
-        <Data handler={handler} options={"DATA"}>
-            {({loading, data}) => {
-                if (loading) {
-                    return "If you see this, the example is broken!";
-                }
-
-                return (
-                    <BodyMonospace>{data}</BodyMonospace>
-                );
-            }}
-        </Data>
-    </View>
-    <Strut size={Spacing.small_12} />
-    <View>
-        <Body>This intercepted cache has error!</Body>
-        <Data handler={handler} options={"ERROR"}>
-            {({loading, error}) => {
-                if (loading) {
-                    return "If you see this, the example is broken!";
-                }
-
-                return (
-                    <BodyMonospace style={{color: Color.red}}>ERROR: {error}</BodyMonospace>
-                );
-            }}
-        </Data>
-    </View>
-</InterceptCache>
-```
-
-This component can also be useful if you want to avoid a data request because
-a parent component already has the data you need. Using this component, you
-can map already cached data of one request (or a portion thereof) to another
-without affecting the cache itself.

package/src/components/internal-data.js

@@ -1,219 +0,0 @@
-// @flow
-import * as React from "react";
-import {Server} from "@khanacademy/wonder-blocks-core";
-
-import {RequestFulfillment} from "../util/request-fulfillment.js";
-import {TrackerContext} from "../util/request-tracking.js";
-
-import type {
-    ValidData,
-    CacheEntry,
-    Result,
-    IRequestHandler,
-} from "../util/types.js";
-
-type Props<TOptions, TData> = {|
-    handler: IRequestHandler<TOptions, TData>,
-    options: TOptions,
-    getEntry: (
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => ?$ReadOnly<CacheEntry<TData>>,
-    children: (result: Result<TData>) => React.Node,
-|};
-
-type State<TData> = {|
-    loading: boolean,
-    data: ?TData,
-    error: ?string,
-|};
-
-/**
- * This component is responsible for actually handling the data request.
- * It is wrapped by Data in order to support intercepts and be exported for use.
- *
- * INTERNAL USE ONLY
- */
-export default class InternalData<
-    TOptions,
-    TData: ValidData,
-> extends React.Component<Props<TOptions, TData>, State<TData>> {
-    _mounted: boolean;
-
-    constructor(props: Props<TOptions, TData>) {
-        super(props);
-
-        this.state = this._buildStateAndfulfillNeeds(props);
-    }
-
-    componentDidMount() {
-        this._mounted = true;
-    }
-
-    shouldComponentUpdate(
-        nextProps: $ReadOnly<Props<TOptions, TData>>,
-        nextState: $ReadOnly<State<TData>>,
-    ): boolean {
-        /**
-         * We only bother updating if our state changed.
-         *
-         * And we only update the state if props changed
-         * or we got new data/error.
-         */
-        if (!this._propsMatch(nextProps)) {
-            const newState = this._buildStateAndfulfillNeeds(nextProps);
-            this.setState(newState);
-        }
-
-        return (
-            this.state.loading !== nextState.loading ||
-            this.state.data !== nextState.data ||
-            this.state.error !== nextState.error
-        );
-    }
-
-    componentWillUnmount() {
-        this._mounted = false;
-    }
-
-    _propsMatch(otherProps: $Shape<Props<TOptions, TData>>): boolean {
-        const {handler, options} = this.props;
-        const {handler: prevHandler, options: prevOptions} = otherProps;
-        return (
-            handler === prevHandler &&
-            handler.getKey(options) === prevHandler.getKey(prevOptions)
-        );
-    }
-
-    _buildStateAndfulfillNeeds(
-        propsAtFulfillment: $ReadOnly<Props<TOptions, TData>>,
-    ): State<TData> {
-        const {getEntry, handler, options} = propsAtFulfillment;
-        const cachedData = getEntry(handler, options);
-        if (
-            !Server.isServerSide() &&
-            (cachedData == null ||
-                handler.shouldRefreshCache(options, cachedData))
-        ) {
-            /**
-             * We're not on the server, the cache missed, or our handler says
-             * we should refresh the cache.
-             *
-             * Therefore, we need to request data.
-             *
-             * We have to do this here from the constructor so that this
-             * data request is tracked when performing server-side rendering.
-             */
-            RequestFulfillment.Default.fulfill(handler, options)
-                .then((cacheEntry) => {
-                    /**
-                     * We get here, we should have updated the cache.
-                     * However, we need to update the component, but we
-                     * should only do that if the props are the same as they
-                     * were when this was called.
-                     */
-                    if (this._mounted && this._propsMatch(propsAtFulfillment)) {
-                        this.setState({
-                            loading: false,
-                            data: cacheEntry.data,
-                            error: cacheEntry.error,
-                        });
-                    }
-                    return null;
-                })
-                .catch((e) => {
-                    /**
-                     * We should never get here, but if we do.
-                     */
-                    // eslint-disable-next-line no-console
-                    console.error(
-                        `Unexpected error occurred during data fulfillment: ${e}`,
-                    );
-                    if (this._mounted && this._propsMatch(propsAtFulfillment)) {
-                        this.setState({
-                            loading: false,
-                            data: null,
-                            error: typeof e === "string" ? e : e.message,
-                        });
-                    }
-                    return null;
-                });
-        }
-
-        /**
-         * This is the default response for the server and for the initial
-         * client-side render if we have cachedData.
-         *
-         * This ensures we don't make promises we don't want when doing
-         * server-side rendering. Instead, we either have data from the cache
-         * or we don't.
-         */
-        return {
-            loading: cachedData == null,
-            data: cachedData && cachedData.data,
-            error: cachedData && cachedData.error,
-        };
-    }
-
-    _resultFromState(): Result<TData> {
-        const {loading, data, error} = this.state;
-
-        if (loading) {
-            return {
-                loading: true,
-            };
-        }
-
-        if (data != null) {
-            return {
-                loading: false,
-                data,
-            };
-        }
-
-        if (error == null) {
-            // We should never get here ever.
-            throw new Error(
-                "Loaded result has invalid state where data and error are missing",
-            );
-        }
-
-        return {
-            loading: false,
-            error,
-        };
-    }
-
-    _renderContent(result: Result<TData>): React.Node {
-        const {children} = this.props;
-        return children(result);
-    }
-
-    _renderWithTrackingContext(result: Result<TData>): React.Node {
-        return (
-            <TrackerContext.Consumer>
-                {(track) => {
-                    /**
-                     * If data tracking wasn't enabled, don't do it.
-                     */
-                    if (track != null) {
-                        track(this.props.handler, this.props.options);
-                    }
-                    return this._renderContent(result);
-                }}
-            </TrackerContext.Consumer>
-        );
-    }
-
-    render(): React.Node {
-        const result = this._resultFromState();
-        // We only track data requests when we are server-side and we don't
-        // already have a result. The existence of a result is indicated by the
-        // loading flag being false.
-        if (result.loading && Server.isServerSide()) {
-            return this._renderWithTrackingContext(result);
-        }
-
-        return this._renderContent(result);
-    }
-}

package/src/util/__tests__/no-cache.test.js

@@ -1,112 +0,0 @@
-// @flow
-import NoCache from "../no-cache.js";
-
-import type {IRequestHandler} from "../types.js";
-
-describe("NoCache", () => {
-    describe("#store", () => {
-        it("should not throw", () => {
-            // Arrange
-            const cache = new NoCache();
-            const fakeHandler: IRequestHandler<string, string> = {
-                getKey: () => "MY_KEY",
-                type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
-                fulfillRequest: jest.fn(),
-                cache: null,
-                hydrate: true,
-            };
-
-            // Act
-            const underTest = () =>
-                cache.store<string, string>(fakeHandler, "options", {
-                    data: "data",
-                });
-
-            // Assert
-            expect(underTest).not.toThrow();
-        });
-    });
-
-    describe("#retrieve", () => {
-        it("should return null", () => {
-            // Arrange
-            const cache = new NoCache();
-            const fakeHandler: IRequestHandler<string, string> = {
-                getKey: () => "MY_KEY",
-                type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
-                fulfillRequest: jest.fn(),
-                cache: null,
-                hydrate: true,
-            };
-
-            // Act
-            const result = cache.retrieve(fakeHandler, "options");
-
-            // Assert
-            expect(result).toBeNull();
-        });
-    });
-
-    describe("#remove", () => {
-        it("should return false", () => {
-            // Arrange
-            const cache = new NoCache();
-            const fakeHandler: IRequestHandler<string, string> = {
-                getKey: () => "MY_KEY",
-                type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
-                fulfillRequest: jest.fn(),
-                cache: null,
-                hydrate: true,
-            };
-
-            // Act
-            const result = cache.remove(fakeHandler, "options");
-
-            // Assert
-            expect(result).toBeFalsy();
-        });
-    });
-
-    describe("#removeAll", () => {
-        it("should return 0 without predicate", () => {
-            // Arrange
-            const cache = new NoCache();
-            const fakeHandler: IRequestHandler<string, string> = {
-                getKey: () => "MY_KEY",
-                type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
-                fulfillRequest: jest.fn(),
-                cache: null,
-                hydrate: true,
-            };
-
-            // Act
-            const result = cache.removeAll(fakeHandler);
-
-            // Assert
-            expect(result).toBe(0);
-        });
-
-        it("should return 0 with predicate", () => {
-            // Arrange
-            const cache = new NoCache();
-            const fakeHandler: IRequestHandler<string, string> = {
-                getKey: () => "MY_KEY",
-                type: "MY_HANDLER",
-                shouldRefreshCache: () => false,
-                fulfillRequest: jest.fn(),
-                cache: null,
-                hydrate: true,
-            };
-
-            // Act
-            const result = cache.removeAll(fakeHandler, () => true);
-
-            // Assert
-            expect(result).toBe(0);
-        });
-    });
-});

package/src/util/no-cache.js

@@ -1,67 +0,0 @@
-// @flow
-import type {ValidData, ICache, CacheEntry, IRequestHandler} from "./types.js";
-
-let defaultInstance: ?ICache<any, any> = null;
-/**
- * This is a cache implementation to use when no caching is wanted.
- *
- * Use this with your request handler if you want to support server-side
- * rendering of your data requests, but want to ensure data is never cached
- * on the client-side.
- *
- * This is better than having `shouldRefreshCache` always return `true` in the
- * handler as this ensures that cache space and memory are never used for the
- * requested data after hydration has finished.
- */
-export default class NoCache<TOptions, TData: ValidData>
-    implements ICache<TOptions, TData>
-{
-    static get Default(): ICache<TOptions, TData> {
-        if (defaultInstance == null) {
-            defaultInstance = new NoCache<TOptions, TData>();
-        }
-        return defaultInstance;
-    }
-
-    store: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        entry: CacheEntry<TData>,
-    ) => void = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        entry: CacheEntry<TData>,
-    ): void => {
-        /* empty */
-    };
-
-    retrieve: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => ?CacheEntry<TData> = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): ?CacheEntry<TData> => null;
-
-    remove: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ) => boolean = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): boolean => false;
-
-    removeAll: <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ) => number = <TOptions, TData: ValidData>(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ): number => 0;
-}

package/src/util/no-cache.md

@@ -1,66 +0,0 @@
-
-`NoCache` is a cache implementation to use when no caching is wanted.
-
-Use this with your request handler if you want to support server-side
-rendering of your data requests, but want to ensure data is never cached
-on the client-side.
-
-This is better than having `shouldRefreshCache` always return `true` in the
-handler as this ensures that cache space and memory are never used for the
-requested data after hydration has finished.
-
-The `ICache` interface is included below for reference in case you would like
-to implement your own caching strategy.
-
-```js static
-interface ICache<TOptions, TData: ValidData> {
-    /**
-     * Stores a value in the cache for the given handler and options.
-     */
-    store(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-        entry: CacheEntry<TData>,
-    ): void;
-
-    /**
-     * Retrieves a value from the cache for the given handler and options.
-     */
-    retrieve(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): ?$ReadOnly<CacheEntry<TData>>;
-
-    /**
-     * Remove the cached entry for the given handler and options.
-     *
-     * If the item exists in the cache, the cached entry is deleted and true
-     * is returned. Otherwise, this returns false.
-     */
-    remove(
-        handler: IRequestHandler<TOptions, TData>,
-        options: TOptions,
-    ): boolean;
-
-    /**
-     * Remove all cached entries for the given handler that, optionally, match
-     * a given predicate.
-     *
-     * Returns the number of entries that were cleared from the cache.
-     */
-    removeAll(
-        handler: IRequestHandler<TOptions, TData>,
-        predicate?: (
-            key: string,
-            cachedEntry: $ReadOnly<CacheEntry<TData>>,
-        ) => boolean,
-    ): number;
-```
-
-Use `NoCache` with your request handler if you want to support server-side
-rendering of your data requests, but also want to ensure data is never cached
-on the client-side.
-
-This is better than having `shouldRefreshCache` always return `true` in the
-handler as this ensures that cache space and memory are never used for the
-requested data after hydration has finished.