@khanacademy/wonder-blocks-data 3.1.2 → 5.0.0

package/src/util/ssr-cache.js

@@ -0,0 +1,206 @@
+// @flow
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {ScopedInMemoryCache} from "./scoped-in-memory-cache.js";
+
+import type {ValidCacheData, CachedResponse, ResponseCache} from "./types.js";
+
+const DefaultScope = "default";
+
+/**
+ * The default instance is stored here.
+ * It's created below in the Default() static property.
+ */
+let _default: SsrCache;
+
+/**
+ * Implements the response cache.
+ *
+ * INTERNAL USE ONLY
+ */
+export class SsrCache {
+    static get Default(): SsrCache {
+        if (!_default) {
+            _default = new SsrCache();
+        }
+        return _default;
+    }
+
+    _hydrationCache: ScopedInMemoryCache;
+    _ssrOnlyCache: ?ScopedInMemoryCache;
+
+    constructor(
+        hydrationCache: ?ScopedInMemoryCache = null,
+        ssrOnlyCache: ?ScopedInMemoryCache = null,
+    ) {
+        this._ssrOnlyCache = Server.isServerSide()
+            ? ssrOnlyCache || new ScopedInMemoryCache()
+            : undefined;
+        this._hydrationCache = hydrationCache || new ScopedInMemoryCache();
+    }
+
+    _setCachedResponse<TData: ValidCacheData>(
+        id: string,
+        entry: CachedResponse<TData>,
+        hydrate: boolean,
+    ): CachedResponse<TData> {
+        const frozenEntry = Object.freeze(entry);
+        if (Server.isServerSide()) {
+            // We are server-side.
+            // We need to store this value.
+            if (hydrate) {
+                this._hydrationCache.set(DefaultScope, id, frozenEntry);
+            } else {
+                // Usually, when server-side, this cache will always be present.
+                // We do fake server-side in our doc example though, when it
+                // won't be.
+                this._ssrOnlyCache?.set(DefaultScope, id, frozenEntry);
+            }
+        }
+        return frozenEntry;
+    }
+
+    /**
+     * Initialize the cache from a given cache state.
+     *
+     * This can only be called if the cache is not already in use.
+     */
+    initialize: (source: ResponseCache) => void = (source) => {
+        if (this._hydrationCache.inUse) {
+            throw new Error(
+                "Cannot initialize data response cache more than once",
+            );
+        }
+        this._hydrationCache = new ScopedInMemoryCache({
+            // $FlowIgnore[incompatible-call]
+            [DefaultScope]: source,
+        });
+    };
+
+    /**
+     * Cache data for a specific response.
+     *
+     * This is a noop when client-side.
+     */
+    cacheData: <TData: ValidCacheData>(
+        id: string,
+        data: TData,
+        hydrate: boolean,
+    ) => CachedResponse<TData> = <TData: ValidCacheData>(
+        id: string,
+        data: TData,
+        hydrate: boolean,
+    ): CachedResponse<TData> => this._setCachedResponse(id, {data}, hydrate);
+
+    /**
+     * Cache an error for a specific response.
+     *
+     * This is a noop when client-side.
+     */
+    cacheError: <TData: ValidCacheData>(
+        id: string,
+        error: Error | string,
+        hydrate: boolean,
+    ) => CachedResponse<TData> = <TData: ValidCacheData>(
+        id: string,
+        error: Error | string,
+        hydrate: boolean,
+    ): CachedResponse<TData> => {
+        const errorMessage = typeof error === "string" ? error : error.message;
+        return this._setCachedResponse(id, {error: errorMessage}, hydrate);
+    };
+
+    /**
+     * Retrieve data from our cache.
+     */
+    getEntry: <TData: ValidCacheData>(
+        id: string,
+    ) => ?$ReadOnly<CachedResponse<TData>> = <TData: ValidCacheData>(
+        id: string,
+    ): ?$ReadOnly<CachedResponse<TData>> => {
+        // Get the cached entry for this value.
+
+        // We first look in the ssr cache and then the hydration cache.
+        const internalEntry =
+            this._ssrOnlyCache?.get(DefaultScope, id) ??
+            this._hydrationCache.get(DefaultScope, id);
+
+        // If we are not server-side and we hydrated something, let's clear
+        // that from the hydration cache to save memory.
+        if (this._ssrOnlyCache == null && internalEntry != null) {
+            // We now delete this from our hydration cache as we don't need it.
+            // This does mean that if another handler of the same type but
+            // without some sort of linked cache won't get the value, but
+            // that's not an expected use-case. If two different places use the
+            // same handler and options (i.e. the same request), then the
+            // handler should cater to that to ensure they share the result.
+            this._hydrationCache.purge(DefaultScope, id);
+        }
+        // Getting the typing right between the in-memory cache and this
+        // is hard. Just telling flow it's OK.
+        // $FlowIgnore[incompatible-return]
+        return internalEntry;
+    };
+
+    /**
+     * Remove from cache, the entry matching the given handler and options.
+     *
+     * This will, if present therein, remove the value from the custom cache
+     * associated with the handler and the framework in-memory cache.
+     *
+     * Returns true if something was removed from any cache; otherwise, false.
+     */
+    remove: (id: string) => boolean = (id: string): boolean => {
+        // NOTE(somewhatabstract): We could invoke removeAll with a predicate
+        // to match the key of the entry we're removing, but that's an
+        // inefficient way to remove a single item, so let's not do that.
+
+        // Delete the entry from the appropriate cache.
+        return (
+            this._hydrationCache.purge(DefaultScope, id) ||
+            (this._ssrOnlyCache?.purge(DefaultScope, id) ?? false)
+        );
+    };
+
+    /**
+     * Remove from cache, any entries matching the given handler and predicate.
+     *
+     * This will, if present therein, remove matching values from the framework
+     * in-memory cache.
+     *
+     * It returns a count of all records removed.
+     */
+    removeAll: (
+        predicate?: (
+            key: string,
+            cachedEntry: $ReadOnly<CachedResponse<ValidCacheData>>,
+        ) => boolean,
+    ) => void = (predicate) => {
+        const realPredicate = predicate
+            ? // We know what we're putting into the cache so let's assume it
+              // conforms.
+              // $FlowIgnore[incompatible-call]
+              (_, key, cachedEntry) => predicate(key, cachedEntry)
+            : undefined;
+
+        // Apply the predicate to what we have in our caches.
+        this._hydrationCache.purgeAll(realPredicate);
+        this._ssrOnlyCache?.purgeAll(realPredicate);
+    };
+
+    /**
+     * Deep clone the hydration cache.
+     *
+     * By design, this only clones the data that is to be used for hydration.
+     */
+    cloneHydratableData: () => ResponseCache = (): ResponseCache => {
+        // We return our hydration cache only.
+        const cache = this._hydrationCache.clone();
+
+        // If we're empty, we still want to return an object, so we default
+        // to an empty object.
+        // We only need the default scope out of our scoped in-memory cache.
+        // We know that it conforms to our expectations.
+        // $FlowIgnore[incompatible-return]
+        return cache[DefaultScope] ?? {};
+    };
+}

package/src/util/types.js

@@ -1,135 +1,70 @@
 // @flow
-export type ValidData = string | boolean | number | {...};
-
-export type Status = "loading" | "success" | "error";
+/**
+ * Define what can be cached.
+ *
+ * We disallow functions and undefined as undefined represents a cache miss
+ * and functions are not allowed.
+ */
+export type ValidCacheData =
+    | string
+    | boolean
+    | number
+    | {...}
+    | Array<?ValidCacheData>;
 
-export type Result<TData: ValidData> =
+/**
+ * The normalized result of a request.
+ */
+export type Result<TData: ValidCacheData> =
     | {|
           status: "loading",
       |}
     | {|
           status: "success",
-          data?: TData,
+          data: TData,
       |}
     | {|
           status: "error",
           error: string,
+      |}
+    | {|
+          status: "aborted",
       |};
 
-export type CacheEntry<TData: ValidData> =
+/**
+ * A cache entry for a fulfilled request response.
+ */
+export type CachedResponse<TData: ValidCacheData> =
     | {|
           +error: string,
-          +data?: ?void,
+          +data?: void,
       |}
     | {|
           +data: TData,
-          +error?: ?void,
+          +error?: void,
       |};
 
-type HandlerSubcache = {
-    [key: string]: CacheEntry<any>,
-    ...
-};
-
-export type InterceptFulfillRequestFn<TOptions, TData: ValidData> = (
-    options: TOptions,
-) => ?Promise<TData>;
-
-export type Interceptor = {|
-    fulfillRequest: InterceptFulfillRequestFn<any, any>,
-|};
-
-export type InterceptContextData = {
-    [key: string]: Interceptor,
-    ...
-};
-
-export type Cache = {
-    [key: string]: HandlerSubcache,
+/**
+ * A cache of fulfilled request responses.
+ */
+export type ResponseCache = {
+    [key: string]: CachedResponse<any>,
     ...
 };
 
-export 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;
-}
-
 /**
- * A handler for data requests.
+ * A cache with scoped sections.
  */
-export interface IRequestHandler<TOptions, TData: ValidData> {
+export type ScopedCache = {
     /**
-     * Fulfill a given request.
-     *
-     * @param {TOptions} options Options tha the request may need.
-     * @return {Promise<TData>} A promise of the requested data.
+     * The cache is scoped to allow easier clearing of different types of usage.
      */
-    fulfillRequest(options: TOptions): Promise<TData>;
-
-    /**
-     * The handler type; this is used to uniquely identify this handler from
-     * any other handler.
-     */
-    get type(): string;
-
-    /**
-     * When true, server-side results are cached and hydrated in the client.
-     * When false, the server-side cache is not used and results are not
-     * hydrated.
-     * This should only be set to false if something is ensuring that the
-     * hydrated client result will match the server result.
-     *
-     * For example, if Apollo is used to handle GraphQL requests in SSR mode,
-     * it has its own cache that is used to hydrate the client. Setting this
-     * to false makes sure we don't store the data twice, which would
-     * unnecessarily bloat the data sent back to the client.
-     */
-    get hydrate(): boolean;
-
-    /**
-     * Get the key to use for a given request. This should be idempotent for a
-     * given options set if you want caching to work across requests.
-     */
-    getKey(options: TOptions): string;
-}
-
-export type ResponseCache = $ReadOnly<Cache>;
+    [scope: string]: {
+        /**
+         * Each value in the cache is then identified within a given scope.
+         */
+        [id: string]: ValidCacheData,
+        ...
+    },
+    ...
+};

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

@@ -1,87 +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";
-
-import type {IRequestHandler} from "../../util/types.js";
-
-describe("InterceptData", () => {
-    afterEach(() => {
-        jest.resetAllMocks();
-    });
-
-    it("should update context with fulfillRequest method", () => {
-        // Arrange
-        const fakeHandler: IRequestHandler<string, string> = {
-            fulfillRequest: () => Promise.resolve("data"),
-            getKey: (o) => o,
-            type: "MY_HANDLER",
-            hydrate: true,
-        };
-        const props = {
-            handler: fakeHandler,
-            fulfillRequest: jest.fn(),
-        };
-        const captureContextFn = jest.fn();
-
-        // Act
-        render(
-            <InterceptData {...props}>
-                <InterceptContext.Consumer>
-                    {captureContextFn}
-                </InterceptContext.Consumer>
-            </InterceptData>,
-        );
-
-        // Assert
-        expect(captureContextFn).toHaveBeenCalledWith(
-            expect.objectContaining({
-                MY_HANDLER: {
-                    fulfillRequest: props.fulfillRequest,
-                },
-            }),
-        );
-    });
-
-    it("should override parent InterceptData", () => {
-        // Arrange
-        const fakeHandler: IRequestHandler<string, string> = {
-            fulfillRequest: () => Promise.resolve("data"),
-            getKey: (o) => o,
-            type: "MY_HANDLER",
-            cache: null,
-            hydrate: true,
-        };
-        const fulfillRequest1Fn = jest.fn();
-        const fulfillRequest2Fn = jest.fn();
-        const captureContextFn = jest.fn();
-
-        // Act
-        render(
-            <InterceptData
-                handler={fakeHandler}
-                fulfillRequest={fulfillRequest1Fn}
-            >
-                <InterceptData
-                    handler={fakeHandler}
-                    fulfillRequest={fulfillRequest2Fn}
-                >
-                    <InterceptContext.Consumer>
-                        {captureContextFn}
-                    </InterceptContext.Consumer>
-                </InterceptData>
-            </InterceptData>,
-        );
-
-        // Assert
-        expect(captureContextFn).toHaveBeenCalledWith(
-            expect.objectContaining({
-                MY_HANDLER: {
-                    fulfillRequest: fulfillRequest2Fn,
-                },
-            }),
-        );
-    });
-});

package/src/components/intercept-data.js

@@ -1,77 +0,0 @@
-// @flow
-import * as React from "react";
-
-import InterceptContext from "./intercept-context.js";
-
-import type {
-    ValidData,
-    IRequestHandler,
-    InterceptFulfillRequestFn,
-} 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 requests 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 fulfill a request.
-     * If this returns null, the request will be fulfilled by the
-     * handler of the original request being intercepted.
-     */
-    fulfillRequest: InterceptFulfillRequestFn<TOptions, TData>,
-|};
-
-/**
- * This component provides a mechanism to intercept the data requests for the
- * type of a given handler and provide alternative results. This is mostly
- * useful for 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 of the same handler type 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 handler type, then that
- * new instance will replace this interceptor for its children. All methods
- * will be replaced.
- */
-export default class InterceptData<
-    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],
-                        fulfillRequest: this.props.fulfillRequest,
-                    };
-                    const newValue = {
-                        ...value,
-                        [handlerType]: interceptor,
-                    };
-                    return (
-                        <InterceptContext.Provider value={newValue}>
-                            {this.props.children}
-                        </InterceptContext.Provider>
-                    );
-                }}
-            </InterceptContext.Consumer>
-        );
-    }
-}

package/src/components/intercept-data.md

@@ -1,65 +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 four props; children to be rendered, the handler of the
-type of data requests that are to be intercepted, and a `fulfillRequest`.
-
-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 handler type can have indeterminate outcomes.
-
-The `fulfillRequest` intercept function has the form:
-
-```js static
-(options: TOptions) => ?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, 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_DATA_HANDLER1");
-    }
-
-    fulfillRequest(options) {
-        return Promise.reject(new Error("You should not see this!"));
-    }
-}
-
-const handler = new MyHandler();
-const fulfillRequestInterceptor = function(options) {
-    if (options === "DATA") {
-        return Promise.resolve("INTERCEPTED DATA!");
-    }
-    return null;
-};
-
-<InterceptData handler={handler} fulfillRequest={fulfillRequestInterceptor}>
-    <View>
-        <Body>This received intercepted 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>
-</InterceptData>
-```