npm - @khanacademy/wonder-blocks-data - Versions diffs - 3.2.0 → 4.0.0 - Mend

@khanacademy/wonder-blocks-data 3.2.0 → 4.0.0

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

package/CHANGELOG.md +23 -0
package/dist/es/index.js +356 -332
package/dist/index.js +507 -456
package/docs.md +17 -35
package/package.json +1 -1
package/src/__tests__/__snapshots__/generated-snapshot.test.js.snap +7 -46
package/src/__tests__/generated-snapshot.test.js +56 -122
package/src/components/__tests__/data.test.js +372 -297
package/src/components/__tests__/intercept-data.test.js +6 -30
package/src/components/data.js +153 -21
package/src/components/data.md +38 -69
package/src/components/intercept-context.js +6 -2
package/src/components/intercept-data.js +40 -51
package/src/components/intercept-data.md +13 -27
package/src/components/track-data.md +9 -23
package/src/hooks/__tests__/__snapshots__/use-shared-cache.test.js.snap +17 -0
package/src/hooks/__tests__/use-server-effect.test.js +217 -0
package/src/hooks/__tests__/use-shared-cache.test.js +307 -0
package/src/hooks/use-server-effect.js +45 -0
package/src/hooks/use-shared-cache.js +106 -0
package/src/index.js +15 -19
package/src/util/__tests__/__snapshots__/scoped-in-memory-cache.test.js.snap +19 -0
package/src/util/__tests__/request-fulfillment.test.js +42 -85
package/src/util/__tests__/request-tracking.test.js +72 -191
package/src/util/__tests__/{result-from-cache-entry.test.js → result-from-cache-response.test.js} +9 -10
package/src/util/__tests__/scoped-in-memory-cache.test.js +396 -0
package/src/util/__tests__/ssr-cache.test.js +639 -0
package/src/util/request-fulfillment.js +36 -44
package/src/util/request-tracking.js +62 -75
package/src/util/{result-from-cache-entry.js → result-from-cache-response.js} +10 -13
package/src/util/scoped-in-memory-cache.js +149 -0
package/src/util/ssr-cache.js +206 -0
package/src/util/types.js +43 -108
package/src/hooks/__tests__/use-data.test.js +0 -826
package/src/hooks/use-data.js +0 -143
package/src/util/__tests__/memory-cache.test.js +0 -446
package/src/util/__tests__/request-handler.test.js +0 -121
package/src/util/__tests__/response-cache.test.js +0 -879
package/src/util/memory-cache.js +0 -187
package/src/util/request-handler.js +0 -42
package/src/util/request-handler.md +0 -51
package/src/util/response-cache.js +0 -213

package/src/components/track-data.md CHANGED Viewed

@@ -65,19 +65,11 @@ 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, RequestHandler, fulfillAllDataRequests} from "@khanacademy/wonder-blocks-data";
+import {Data, TrackData, fulfillAllDataRequests} from "@khanacademy/wonder-blocks-data";
-class MyPretendHandler extends RequestHandler {
-    constructor() {
-        super("MY_PRETEND_HANDLER");
-    }
-    fulfillRequest(options) {
-        return new Promise((resolve, reject) =>
-            setTimeout(() => resolve("DATA!"), 3000),
-        );
-    }
-}
+const myPretendHandler = () => new Promise((resolve, reject) =>
+    setTimeout(() => resolve("DATA!"), 3000),
+);
 class Example extends React.Component {
     constructor() {
@@ -87,7 +79,6 @@ class Example extends React.Component {
          * for the scope of this component.
          */
         this.state = {};
-        this._handler = new MyPretendHandler();
     }
     static getDerivedStateFromError(error) {
@@ -133,15 +124,16 @@ class Example extends React.Component {
         const data = this.state.data
             ? JSON.stringify(this.state.data, undefined, "  ")
             : "Data requested...";
         return (
             <React.Fragment>
                 <Strut size={Spacing.small_12} />
                 <TrackData>
-                    <Data handler={this._handler} options={{}}>
-                        {({loading, data, error}) => (
+                    <Data handler={myPretendHandler} requestId="TRACK_DATA_EXAMPLE">
+                        {(result) => (
                             <View>
-                                <BodyMonospace>{`Loading: ${loading}`}</BodyMonospace>
-                                <BodyMonospace>{`Data: ${JSON.stringify(data)}`}</BodyMonospace>
+                                <BodyMonospace>{`Loading: ${result.status === "loading"}`}</BodyMonospace>
+                                <BodyMonospace>{`Data: ${JSON.stringify(result.data)}`}</BodyMonospace>
                             </View>
                         )}
                     </Data>
@@ -162,12 +154,6 @@ class Example extends React.Component {
                         rendered tree.
                     </Body>
                     <Strut size={Spacing.small_12} />
-                    <Body>
-                        If you click to remount after the data appears, we'll
-                        rerender with the now cached data, and above should
-                        update accordingly.
-                    </Body>
-                    <Strut size={Spacing.small_12} />
                     <BodyMonospace>{data}</BodyMonospace>
                 </View>
             </React.Fragment>

package/src/hooks/__tests__/__snapshots__/use-shared-cache.test.js.snap ADDED Viewed

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+exports[`#useSharedCache should throw if the id is  1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the id is [Function anonymous] 1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the id is 5 1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the id is null 1`] = `[InvalidInputError: id must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is  1`] = `[InvalidInputError: scope must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is [Function anonymous] 1`] = `[InvalidInputError: scope must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is 5 1`] = `[InvalidInputError: scope must be a non-empty string]`;
+exports[`#useSharedCache should throw if the scope is null 1`] = `[InvalidInputError: scope must be a non-empty string]`;

package/src/hooks/__tests__/use-server-effect.test.js ADDED Viewed

@@ -0,0 +1,217 @@
+// @flow
+import {renderHook as clientRenderHook} from "@testing-library/react-hooks";
+import {renderHook as serverRenderHook} from "@testing-library/react-hooks/server";
+import {Server} from "@khanacademy/wonder-blocks-core";
+import TrackData from "../../components/track-data.js";
+import {RequestFulfillment} from "../../util/request-fulfillment.js";
+import {SsrCache} from "../../util/ssr-cache.js";
+import {RequestTracker} from "../../util/request-tracking.js";
+import {useServerEffect} from "../use-server-effect.js";
+describe("#useServerEffect", () => {
+    beforeEach(() => {
+        const responseCache = new SsrCache();
+        jest.spyOn(SsrCache, "Default", "get").mockReturnValue(responseCache);
+        jest.spyOn(RequestFulfillment, "Default", "get").mockReturnValue(
+            new RequestFulfillment(responseCache),
+        );
+        jest.spyOn(RequestTracker, "Default", "get").mockReturnValue(
+            new RequestTracker(responseCache),
+        );
+    });
+    afterEach(() => {
+        jest.resetAllMocks();
+    });
+    describe("when server-side", () => {
+        beforeEach(() => {
+            jest.spyOn(Server, "isServerSide").mockReturnValue(true);
+        });
+        it("should return null if no cached result", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            // Act
+            const {
+                result: {current: result},
+            } = serverRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(result).toBeNull();
+        });
+        it("should not directly request fulfillment", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            const fulfillRequestSpy = jest.spyOn(
+                RequestFulfillment.Default,
+                "fulfill",
+            );
+            // Act
+            serverRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(fulfillRequestSpy).not.toHaveBeenCalled();
+        });
+        it("should track the request", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            const trackDataRequestSpy = jest.spyOn(
+                RequestTracker.Default,
+                "trackDataRequest",
+            );
+            // Act
+            serverRenderHook(() => useServerEffect("ID", fakeHandler), {
+                wrapper: TrackData,
+            });
+            // Assert
+            expect(trackDataRequestSpy).toHaveBeenCalledWith(
+                "ID",
+                fakeHandler,
+                true,
+            );
+        });
+        it("should return data cached result", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            jest.spyOn(SsrCache.Default, "getEntry").mockReturnValueOnce({
+                data: "DATA",
+                error: null,
+            });
+            // Act
+            const {
+                result: {current: result},
+            } = serverRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(result).toEqual({data: "DATA", error: null});
+        });
+        it("should return error cached result", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            jest.spyOn(SsrCache.Default, "getEntry").mockReturnValueOnce({
+                data: null,
+                error: "ERROR",
+            });
+            // Act
+            const {
+                result: {current: result},
+            } = serverRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(result).toEqual({
+                data: null,
+                error: "ERROR",
+            });
+        });
+    });
+    describe("when client-side", () => {
+        beforeEach(() => {
+            jest.spyOn(Server, "isServerSide").mockReturnValue(false);
+        });
+        it("should return null if no cached result", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(result).toBeNull();
+        });
+        it("should return data cached result", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            jest.spyOn(SsrCache.Default, "getEntry").mockReturnValueOnce({
+                data: "DATA",
+                error: null,
+            });
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(result).toEqual({data: "DATA", error: null});
+        });
+        it("should return error cached result", () => {
+            // Arrange
+            const fakeHandler = jest.fn();
+            jest.spyOn(SsrCache.Default, "getEntry").mockReturnValueOnce({
+                data: null,
+                error: "ERROR",
+            });
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(result).toEqual({
+                data: null,
+                error: "ERROR",
+            });
+        });
+        it("should not track the request", () => {
+            // Arrange
+            const fakeHandler = jest.fn().mockReturnValue(
+                new Promise(() => {
+                    /*prevent act() warning*/
+                }),
+            );
+            const trackDataRequestSpy = jest.spyOn(
+                RequestTracker.Default,
+                "trackDataRequest",
+            );
+            // Act
+            clientRenderHook(() => useServerEffect("ID", fakeHandler), {
+                wrapper: TrackData,
+            });
+            // Assert
+            expect(trackDataRequestSpy).not.toHaveBeenCalled();
+        });
+        it("should not request fulfillment", () => {
+            // Arrange
+            const fakeHandler = jest.fn().mockReturnValue(
+                new Promise(() => {
+                    /*prevent act() warning*/
+                }),
+            );
+            const fulfillRequestSpy = jest.spyOn(
+                RequestFulfillment.Default,
+                "fulfill",
+            );
+            // Act
+            clientRenderHook(() => useServerEffect("ID", fakeHandler));
+            // Assert
+            expect(fulfillRequestSpy).not.toHaveBeenCalled();
+        });
+    });
+});

package/src/hooks/__tests__/use-shared-cache.test.js ADDED Viewed

@@ -0,0 +1,307 @@
+// @flow
+import {renderHook as clientRenderHook} from "@testing-library/react-hooks";
+import {useSharedCache, clearSharedCache} from "../use-shared-cache.js";
+describe("#useSharedCache", () => {
+    beforeEach(() => {
+        clearSharedCache();
+    });
+    it.each`
+        id
+        ${null}
+        ${""}
+        ${5}
+        ${() => "BOO"}
+    `("should throw if the id is $id", ({id}) => {
+        // Arrange
+        // Act
+        const {result} = clientRenderHook(() => useSharedCache(id, "scope"));
+        // Assert
+        expect(result.error).toMatchSnapshot();
+    });
+    it.each`
+        scope
+        ${null}
+        ${""}
+        ${5}
+        ${() => "BOO"}
+    `("should throw if the scope is $scope", ({scope}) => {
+        // Arrange
+        // Act
+        const {result} = clientRenderHook(() => useSharedCache("id", scope));
+        // Assert
+        expect(result.error).toMatchSnapshot();
+    });
+    it("should return a tuple of two items", () => {
+        // Arrange
+        // Act
+        const {
+            result: {current: result},
+        } = clientRenderHook(() => useSharedCache("id", "scope"));
+        // Assert
+        expect(result).toBeArrayOfSize(2);
+    });
+    describe("tuple[0] - currentValue", () => {
+        it("should be null if nothing is cached", () => {
+            // Arrange
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() => useSharedCache("id", "scope"));
+            // Assert
+            expect(result[0]).toBeNull();
+        });
+        it("should match initialValue when provided as a non-function", () => {
+            // Arrange
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() =>
+                useSharedCache("id", "scope", "INITIAL VALUE"),
+            );
+            // Assert
+            expect(result[0]).toBe("INITIAL VALUE");
+        });
+        it("should match the return of initialValue when provided as non-function", () => {
+            // Arrange
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() =>
+                useSharedCache("id", "scope", () => "INITIAL VALUE"),
+            );
+            // Assert
+            expect(result[0]).toBe("INITIAL VALUE");
+        });
+    });
+    describe("tuple[1] - setValue", () => {
+        it("should be a function", () => {
+            // Arrange
+            // Act
+            const {
+                result: {current: result},
+            } = clientRenderHook(() => useSharedCache("id", "scope"));
+            // Assert
+            expect(result[1]).toBeFunction();
+        });
+        it("should be the same function if the id and scope remain the same", () => {
+            // Arrange
+            const wrapper = clientRenderHook(
+                ({id, scope}) => useSharedCache(id, scope),
+                {initialProps: {id: "id", scope: "scope"}},
+            );
+            // Act
+            wrapper.rerender({
+                id: "id",
+                scope: "scope",
+            });
+            const result1 = wrapper.result.all[wrapper.result.all.length - 2];
+            const result2 = wrapper.result.current;
+            // Assert
+            // $FlowIgnore[prop-missing]
+            expect(result1[1]).toBe(result2[1]);
+        });
+        it("should be a new function if the id changes", () => {
+            // Arrange
+            const wrapper = clientRenderHook(
+                ({id}) => useSharedCache(id, "scope"),
+                {
+                    initialProps: {id: "id"},
+                },
+            );
+            // Act
+            wrapper.rerender({id: "new-id"});
+            const result1 = wrapper.result.all[wrapper.result.all.length - 2];
+            const result2 = wrapper.result.current;
+            // Assert
+            // $FlowIgnore[prop-missing]
+            expect(result1[1]).not.toBe(result2[1]);
+        });
+        it("should be a new function if the scope changes", () => {
+            // Arrange
+            const wrapper = clientRenderHook(
+                ({scope}) => useSharedCache("id", scope),
+                {
+                    initialProps: {scope: "scope"},
+                },
+            );
+            // Act
+            wrapper.rerender({scope: "new-scope"});
+            const result1 = wrapper.result.all[wrapper.result.all.length - 2];
+            const result2 = wrapper.result.current;
+            // Assert
+            // $FlowIgnore[prop-missing]
+            expect(result1[1]).not.toBe(result2[1]);
+        });
+        it("should set the value in the cache", () => {
+            // Arrange
+            const wrapper = clientRenderHook(() =>
+                useSharedCache("id", "scope"),
+            );
+            const setValue = wrapper.result.current[1];
+            // Act
+            setValue("CACHED_VALUE");
+            // Rerender so the hook retrieves this new value.
+            wrapper.rerender();
+            const result = wrapper.result.current[0];
+            // Assert
+            expect(result).toBe("CACHED_VALUE");
+        });
+        it.each`
+            value
+            ${undefined}
+            ${null}
+        `("should purge the value from the cache if $value", ({value}) => {
+            // Arrange
+            const wrapper = clientRenderHook(() =>
+                useSharedCache("id", "scope"),
+            );
+            const setValue = wrapper.result.current[1];
+            setValue("CACHED_VALUE");
+            // Act
+            // Rerender so the result has the cached value.
+            wrapper.rerender();
+            setValue(value);
+            // Rerender so the hook retrieves this new value.
+            wrapper.rerender();
+            const result = wrapper.result.current[0];
+            // Assert
+            expect(result).toBeNull();
+        });
+    });
+    it("should share cache across all uses", () => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id", "scope"));
+        const hook2 = clientRenderHook(() => useSharedCache("id", "scope"));
+        hook1.result.current[1]("VALUE_1");
+        // Act
+        hook2.rerender();
+        const result = hook2.result.current[0];
+        // Assert
+        expect(result).toBe("VALUE_1");
+    });
+    it.each`
+        id
+        ${"id1"}
+        ${"id2"}
+    `("should not share cache if scope is different", ({id}) => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache(id, "scope2"));
+        hook1.result.current[1]("VALUE_1");
+        // Act
+        hook2.rerender();
+        const result = hook2.result.current[0];
+        // Assert
+        expect(result).toBeNull();
+    });
+    it.each`
+        scope
+        ${"scope1"}
+        ${"scope2"}
+    `("should not share cache if id is different", ({scope}) => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache("id2", scope));
+        hook1.result.current[1]("VALUE_1");
+        // Act
+        hook2.rerender();
+        const result = hook2.result.current[0];
+        // Assert
+        expect(result).toBeNull();
+    });
+});
+describe("#clearSharedCache", () => {
+    beforeEach(() => {
+        clearSharedCache();
+    });
+    it("should clear the entire cache if no scope given", () => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache("id2", "scope2"));
+        hook1.result.current[1]("VALUE_1");
+        hook2.result.current[1]("VALUE_2");
+        // Make sure both hook results include the updated value.
+        hook1.rerender();
+        hook2.rerender();
+        // Act
+        clearSharedCache();
+        // Make sure we refresh the hook results.
+        hook1.rerender();
+        hook2.rerender();
+        // Assert
+        expect(hook1.result.current[0]).toBeNull();
+        expect(hook2.result.current[0]).toBeNull();
+    });
+    it("should clear the given scope only", () => {
+        // Arrange
+        const hook1 = clientRenderHook(() => useSharedCache("id1", "scope1"));
+        const hook2 = clientRenderHook(() => useSharedCache("id2", "scope2"));
+        hook1.result.current[1]("VALUE_1");
+        hook2.result.current[1]("VALUE_2");
+        // Make sure both hook results include the updated value.
+        hook1.rerender();
+        hook2.rerender();
+        // Act
+        clearSharedCache("scope2");
+        // Make sure we refresh the hook results.
+        hook1.rerender();
+        hook2.rerender();
+        // Assert
+        expect(hook1.result.current[0]).toBe("VALUE_1");
+        expect(hook2.result.current[0]).toBeNull();
+    });
+});

package/src/hooks/use-server-effect.js ADDED Viewed

@@ -0,0 +1,45 @@
+// @flow
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {useContext} from "react";
+import {TrackerContext} from "../util/request-tracking.js";
+import {SsrCache} from "../util/ssr-cache.js";
+import type {CachedResponse, ValidCacheData} from "../util/types.js";
+/**
+ * Hook to perform an asynchronous action during server-side rendering.
+ *
+ * This hook registers an asynchronous action to be performed during
+ * server-side rendering. The action is performed only once, and the result
+ * is cached against the given identifier so that subsequent calls return that
+ * cached result allowing components to render more of the component.
+ *
+ * This hook requires the Wonder Blocks Data functionality for resolving
+ * pending requests, as well as support for the hydration cache to be
+ * embedded into a page so that the result can by hydrated (if that is a
+ * requirement).
+ *
+ * The asynchronous action is never invoked on the client-side.
+ */
+export const useServerEffect = <TData: ValidCacheData>(
+    id: string,
+    handler: () => Promise<?TData>,
+    hydrate: boolean = true,
+): ?CachedResponse<TData> => {
+    // If we're server-side or hydrating, we'll have a cached entry to use.
+    // So we get that and use it to initialize our state.
+    // This works in both hydration and SSR because the very first call to
+    // this will have cached data in those cases as it will be present on the
+    // initial render - and subsequent renders on the client it will be null.
+    const cachedResult = SsrCache.Default.getEntry<TData>(id);
+    // We only track data requests when we are server-side and we don't
+    // already have a result, as given by the cachedData (which is also the
+    // initial value for the result state).
+    const maybeTrack = useContext(TrackerContext);
+    if (cachedResult == null && Server.isServerSide()) {
+        maybeTrack?.(id, handler, hydrate);
+    }
+    return cachedResult;
+};