@khanacademy/wonder-blocks-data 3.0.1 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-data",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -17,6 +17,7 @@
     "@khanacademy/wonder-blocks-core": "^4.0.0"
   },
   "peerDependencies": {
+    "@khanacademy/wonder-stuff-core": "^0.1.2",
     "react": "16.14.0"
   },
   "devDependencies": {

package/src/components/__tests__/gql-router.test.js

@@ -0,0 +1,64 @@
+// @flow
+import * as React from "react";
+import {render} from "@testing-library/react";
+
+import {GqlRouterContext} from "../../util/gql-router-context.js";
+import {GqlRouter} from "../gql-router.js";
+
+describe("GqlRouter", () => {
+    it("should provide the GqlRouterContext as configured", async () => {
+        // Arrange
+        const defaultContext = {
+            foo: "bar",
+        };
+        const fetch = jest.fn();
+        const CaptureContext = ({captureFn}) => {
+            captureFn(React.useContext(GqlRouterContext));
+            return null;
+        };
+
+        // Act
+        const result = await new Promise((resolve, reject) => {
+            render(
+                <GqlRouter defaultContext={defaultContext} fetch={fetch}>
+                    <CaptureContext captureFn={resolve} />
+                </GqlRouter>,
+            );
+        });
+
+        // Assert
+        expect(result).toStrictEqual({
+            defaultContext,
+            fetch,
+        });
+    });
+
+    it("should not render React.memo-ized children if props remain the same", () => {
+        // Arrange
+        const defaultContext = {
+            foo: "bar",
+        };
+        const fetch = jest.fn();
+        let renderCount = 0;
+        const Child = React.memo(() => {
+            const context = React.useContext(GqlRouterContext);
+            renderCount++;
+            return <div>{JSON.stringify(context)}</div>;
+        });
+
+        // Act
+        const {rerender} = render(
+            <GqlRouter defaultContext={defaultContext} fetch={fetch}>
+                <Child />
+            </GqlRouter>,
+        );
+        rerender(
+            <GqlRouter defaultContext={defaultContext} fetch={fetch}>
+                <Child />
+            </GqlRouter>,
+        );
+
+        // Assert
+        expect(renderCount).toBe(1);
+    });
+});

package/src/components/gql-router.js

@@ -0,0 +1,66 @@
+// @flow
+import * as React from "react";
+
+import {GqlRouterContext} from "../util/gql-router-context.js";
+
+import type {
+    GqlContext,
+    FetchFn,
+    GqlRouterConfiguration,
+} from "../util/gql-types.js";
+
+type Props<TContext: GqlContext> = {|
+    /**
+     * The default context to be used by operations when no context is provided.
+     */
+    defaultContext: TContext,
+
+    /**
+     * The function to use when fetching requests.
+     */
+    fetch: FetchFn<any, any, any, TContext>,
+
+    /**
+     * The children to be rendered inside the router.
+     */
+    children: React.Node,
+|};
+
+/**
+ * Configure GraphQL routing for GraphQL hooks and components.
+ *
+ * These can be nested. Components and hooks relying on the GraphQL routing
+ * will use the configuration from their closest ancestral GqlRouter.
+ */
+export const GqlRouter = <TContext: GqlContext>({
+    defaultContext: thisDefaultContext,
+    fetch: thisFetch,
+    children,
+}: Props<TContext>): React.Node => {
+    // We don't care if we're nested. We always force our callers to define
+    // everything. It makes for a clearer API and requires less error checking
+    // code (assuming our flow types are correct). We also don't default fetch
+    // to anything - our callers can tell us what function to use quite easily.
+    // If code that consumes this wants more nuanced nesting, it can implement
+    // it within its own GqlRouter than then defers to this one.
+
+    // We want to always use the same object if things haven't changed to avoid
+    // over-rendering consumers of our context, let's memoize the configuration.
+    // By doing this, if a component under children that uses this context
+    // uses React.memo, we won't force it to re-render every time we render
+    // because we'll only change the context value if something has actually
+    // changed.
+    const configuration: GqlRouterConfiguration<TContext> = React.useMemo(
+        () => ({
+            fetch: thisFetch,
+            defaultContext: thisDefaultContext,
+        }),
+        [thisDefaultContext, thisFetch],
+    );
+
+    return (
+        <GqlRouterContext.Provider value={configuration}>
+            {children}
+        </GqlRouterContext.Provider>
+    );
+};

package/src/hooks/__tests__/use-gql.test.js

@@ -0,0 +1,233 @@
+// @flow
+import * as React from "react";
+import {renderHook} from "@testing-library/react-hooks";
+
+import * as GetGqlDataFromResponse from "../../util/get-gql-data-from-response.js";
+import {GqlRouterContext} from "../../util/gql-router-context.js";
+import {useGql} from "../use-gql.js";
+
+describe("#useGql", () => {
+    beforeEach(() => {
+        jest.resetAllMocks();
+    });
+
+    it("should throw if there is no GqlRouterContext available", () => {
+        // Arrange
+
+        // Act
+        const {
+            result: {error: result},
+        } = renderHook(() => useGql());
+
+        // Assert
+        expect(result).toMatchInlineSnapshot(
+            `[GqlInternalError: No GqlRouter]`,
+        );
+    });
+
+    it("should return a function", () => {
+        // Arrange
+        const gqlRouterContext = {
+            fetch: jest.fn(),
+            defaultContext: {},
+        };
+
+        // Act
+        const {
+            result: {current: result},
+        } = renderHook(() => useGql(), {
+            wrapper: ({children}) => (
+                <GqlRouterContext.Provider value={gqlRouterContext}>
+                    {children}
+                </GqlRouterContext.Provider>
+            ),
+        });
+
+        // Assert
+        expect(result).toBeInstanceOf(Function);
+    });
+
+    describe("returned gqlFetch", () => {
+        it("should fetch the operation with combined context", async () => {
+            // Arrange
+            jest.spyOn(
+                GetGqlDataFromResponse,
+                "getGqlDataFromResponse",
+            ).mockResolvedValue({
+                some: "data",
+            });
+            const fetchFake = jest
+                .fn()
+                .mockResolvedValue(("FAKE_RESPONSE": any));
+            const gqlRouterContext = {
+                fetch: fetchFake,
+                defaultContext: {
+                    a: "defaultA",
+                    b: "defaultB",
+                },
+            };
+            const {
+                result: {current: gqlFetch},
+            } = renderHook(() => useGql(), {
+                wrapper: ({children}) => (
+                    <GqlRouterContext.Provider value={gqlRouterContext}>
+                        {children}
+                    </GqlRouterContext.Provider>
+                ),
+            });
+            const gqlOp = {
+                type: "query",
+                id: "MyQuery",
+            };
+            const gqlOpContext = {
+                b: "overrideB",
+            };
+            const gqlOpVariables = {
+                var1: "val1",
+            };
+
+            // Act
+            await gqlFetch(gqlOp, {
+                context: gqlOpContext,
+                variables: gqlOpVariables,
+            });
+
+            // Assert
+            expect(fetchFake).toHaveBeenCalledWith(gqlOp, gqlOpVariables, {
+                a: "defaultA",
+                b: "overrideB",
+            });
+        });
+
+        it("should parse the response", async () => {
+            // Arrange
+            const getGqlDataFromResponseSpy = jest
+                .spyOn(GetGqlDataFromResponse, "getGqlDataFromResponse")
+                .mockResolvedValue({
+                    some: "data",
+                });
+            const gqlRouterContext = {
+                fetch: jest.fn().mockResolvedValue(("FAKE_RESPONSE": any)),
+                defaultContext: {},
+            };
+            const {
+                result: {current: gqlFetch},
+            } = renderHook(() => useGql(), {
+                wrapper: ({children}) => (
+                    <GqlRouterContext.Provider value={gqlRouterContext}>
+                        {children}
+                    </GqlRouterContext.Provider>
+                ),
+            });
+            const gqlOp = {
+                type: "query",
+                id: "MyQuery",
+            };
+
+            // Act
+            await gqlFetch(gqlOp);
+
+            // Assert
+            expect(getGqlDataFromResponseSpy).toHaveBeenCalledWith(
+                "FAKE_RESPONSE",
+            );
+        });
+
+        it("should reject if the response parse rejects", async () => {
+            // Arrange
+            jest.spyOn(
+                GetGqlDataFromResponse,
+                "getGqlDataFromResponse",
+            ).mockRejectedValue(new Error("FAKE_ERROR"));
+            const gqlRouterContext = {
+                fetch: jest.fn().mockResolvedValue(("FAKE_RESPONSE": any)),
+                defaultContext: {},
+            };
+            const {
+                result: {current: gqlFetch},
+            } = renderHook(() => useGql(), {
+                wrapper: ({children}) => (
+                    <GqlRouterContext.Provider value={gqlRouterContext}>
+                        {children}
+                    </GqlRouterContext.Provider>
+                ),
+            });
+            const gqlOp = {
+                type: "query",
+                id: "MyQuery",
+            };
+
+            // Act
+            const act = gqlFetch(gqlOp);
+
+            // Assert
+            await expect(act).rejects.toThrowErrorMatchingInlineSnapshot(
+                `"FAKE_ERROR"`,
+            );
+        });
+
+        it("should resolve to null if the fetch was aborted", async () => {
+            // Arrange
+            const abortError = new Error("Aborted");
+            abortError.name = "AbortError";
+            const gqlRouterContext = {
+                fetch: jest.fn().mockRejectedValue(abortError),
+                defaultContext: {},
+            };
+            const {
+                result: {current: gqlFetch},
+            } = renderHook(() => useGql(), {
+                wrapper: ({children}) => (
+                    <GqlRouterContext.Provider value={gqlRouterContext}>
+                        {children}
+                    </GqlRouterContext.Provider>
+                ),
+            });
+            const gqlOp = {
+                type: "query",
+                id: "MyQuery",
+            };
+
+            // Act
+            const result = await gqlFetch(gqlOp);
+
+            // Assert
+            expect(result).toBeNull();
+        });
+
+        it("should resolve to the response data", async () => {
+            // Arrange
+            jest.spyOn(
+                GetGqlDataFromResponse,
+                "getGqlDataFromResponse",
+            ).mockResolvedValue({
+                some: "data",
+            });
+            const gqlRouterContext = {
+                fetch: jest.fn().mockResolvedValue(("FAKE_RESPONSE": any)),
+                defaultContext: {},
+            };
+            const {
+                result: {current: gqlFetch},
+            } = renderHook(() => useGql(), {
+                wrapper: ({children}) => (
+                    <GqlRouterContext.Provider value={gqlRouterContext}>
+                        {children}
+                    </GqlRouterContext.Provider>
+                ),
+            });
+            const gqlOp = {
+                type: "mutation",
+                id: "MyMutation",
+            };
+
+            // Act
+            const result = await gqlFetch(gqlOp);
+
+            // Assert
+            expect(result).toEqual({
+                some: "data",
+            });
+        });
+    });
+});

package/src/hooks/use-gql.js

@@ -0,0 +1,75 @@
+// @flow
+import {useContext, useMemo} from "react";
+
+import {GqlRouterContext} from "../util/gql-router-context.js";
+import {getGqlDataFromResponse} from "../util/get-gql-data-from-response.js";
+import {GqlError, GqlErrors} from "../util/gql-error.js";
+
+import type {
+    GqlContext,
+    GqlOperation,
+    GqlFetchOptions,
+    GqlOperationType,
+} from "../util/gql-types.js";
+
+/**
+ * Hook to obtain a gqlFetch function for performing GraphQL requests.
+ *
+ * The fetch function will resolve null if the request was aborted, otherwise
+ * it will resolve the data returned by the GraphQL server.
+ */
+export const useGql = (): (<
+    TType: GqlOperationType,
+    TData,
+    TVariables: {...},
+    TContext: GqlContext,
+>(
+    operation: GqlOperation<TType, TData, TVariables>,
+    options?: GqlFetchOptions<TVariables, TContext>,
+) => Promise<?TData>) => {
+    // This hook only works if the `GqlRouter` has been used to setup context.
+    const gqlRouterContext = useContext(GqlRouterContext);
+    if (gqlRouterContext == null) {
+        throw new GqlError("No GqlRouter", GqlErrors.Internal);
+    }
+    const {fetch, defaultContext} = gqlRouterContext;
+
+    // Let's memoize the gqlFetch function we create based off our context.
+    // That way, even if the context happens to change, if its values don't
+    // we give the same function instance back to our callers instead of
+    // making a new one. That then means they can safely use the return value
+    // in hooks deps without fear of it triggering extra renders.
+    const gqlFetch = useMemo(
+        () =>
+            <
+                TType: GqlOperationType,
+                TData,
+                TVariables: {...},
+                TContext: GqlContext,
+            >(
+                operation: GqlOperation<TType, TData, TVariables>,
+                options: GqlFetchOptions<TVariables, TContext> = Object.freeze(
+                    {},
+                ),
+            ) => {
+                const {variables, context} = options;
+
+                // Invoke the fetch and extract the data.
+                return fetch(operation, variables, {
+                    ...defaultContext,
+                    ...context,
+                }).then(getGqlDataFromResponse, (error) => {
+                    // Return null if the request was aborted.
+                    // The only way to detect this reliably, it seems, is to
+                    // check the error name and see if it's "AbortError" (this
+                    // is also what Apollo does).
+                    // Even then, it's reliant on the fetch supporting aborts.
+                    if (error.name === "AbortError") {
+                        return null;
+                    }
+                });
+            },
+        [fetch, defaultContext],
+    );
+    return gqlFetch;
+};

package/src/index.js

@@ -50,14 +50,14 @@ export const removeAllFromCache = <TOptions, TData: ValidData>(
     ) => boolean,
 ): number => ResCache.Default.removeAll<TOptions, TData>(handler, predicate);
 
-/**
- * TODO(somewhatabstract): Export each cache type we implement.
- *
- * Is there a base type we export, like we do for RequestHandler?
- */
-
 export {default as RequestHandler} from "./util/request-handler.js";
 export {default as TrackData} from "./components/track-data.js";
 export {default as Data} from "./components/data.js";
 export {default as InterceptData} from "./components/intercept-data.js";
 export {useData} from "./hooks/use-data.js";
+
+// GraphQL
+export {GqlRouter} from "./components/gql-router.js";
+export {useGql} from "./hooks/use-gql.js";
+export * from "./util/gql-error.js";
+export type {GqlContext, GqlOperation} from "./util/gql-types.js";

package/src/util/__tests__/get-gql-data-from-response.test.js

@@ -0,0 +1,187 @@
+// @flow
+import {getGqlDataFromResponse} from "../get-gql-data-from-response.js";
+
+describe("#getGqlDataFromReponse", () => {
+    it("should throw if the response cannot be parsed", async () => {
+        // Arrange
+        const response: any = {
+            status: 200,
+            text: jest.fn(() => Promise.resolve("BAD JSON")),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toThrowErrorMatchingInlineSnapshot(`
+                    "Failed to parse response
+                    	caused by
+                    		SyntaxError: Unexpected token B in JSON at position 0"
+                `);
+    });
+
+    it("should include status code and body text in parse error metadata", async () => {
+        // Arrange
+        const response: any = {
+            status: 200,
+            text: jest.fn(() => Promise.resolve("BAD JSON")),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toHaveProperty("metadata", {
+            statusCode: 200,
+            bodyText: "BAD JSON",
+        });
+    });
+
+    it("should throw if the status code is not <300", async () => {
+        // Arrange
+        const response: any = {
+            status: 400,
+            text: jest.fn(() => Promise.resolve("{}")),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toThrowErrorMatchingInlineSnapshot(
+            `"Response unsuccessful"`,
+        );
+    });
+
+    it("should include status code and result in response error metadata", async () => {
+        // Arrange
+        const response: any = {
+            status: 400,
+            text: jest.fn(() =>
+                Promise.resolve(JSON.stringify({data: "DATA"})),
+            ),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toHaveProperty("metadata", {
+            statusCode: 400,
+            result: {
+                data: "DATA",
+            },
+        });
+    });
+
+    it("should throw if the response is malformed", async () => {
+        // Arrange
+        const response: any = {
+            status: 200,
+            text: jest.fn(() => Promise.resolve("{}")),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toThrowErrorMatchingInlineSnapshot(
+            `"Server response missing"`,
+        );
+    });
+
+    it("should include the status code and the result in the malformed response error", async () => {
+        // Arrange
+        const response: any = {
+            status: 200,
+            text: jest.fn(() =>
+                Promise.resolve(JSON.stringify({malformed: "response"})),
+            ),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toHaveProperty("metadata", {
+            statusCode: 200,
+            result: {
+                malformed: "response",
+            },
+        });
+    });
+
+    it("should throw if the response has GraphQL errors", async () => {
+        // Arrange
+        const response: any = {
+            status: 200,
+            text: jest.fn(() =>
+                Promise.resolve(
+                    JSON.stringify({
+                        data: {},
+                        errors: [{message: "GraphQL error"}],
+                    }),
+                ),
+            ),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toThrowErrorMatchingInlineSnapshot(
+            `"GraphQL errors"`,
+        );
+    });
+
+    it("should include the status code and result in the metadata", async () => {
+        // Arrange
+        const response: any = {
+            status: 200,
+            text: jest.fn(() =>
+                Promise.resolve(
+                    JSON.stringify({
+                        data: {},
+                        errors: [{message: "GraphQL error"}],
+                    }),
+                ),
+            ),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).rejects.toHaveProperty("metadata", {
+            statusCode: 200,
+            result: {
+                data: {},
+                errors: [{message: "GraphQL error"}],
+            },
+        });
+    });
+
+    it("should resolve to the response data", async () => {
+        // Arrange
+        const response: any = {
+            status: 200,
+            text: jest.fn(() =>
+                Promise.resolve(
+                    JSON.stringify({
+                        data: {
+                            test: "test",
+                        },
+                    }),
+                ),
+            ),
+        };
+
+        // Act
+        const result = getGqlDataFromResponse(response);
+
+        // Assert
+        await expect(result).resolves.toEqual({
+            test: "test",
+        });
+    });
+});