@khanacademy/wonder-blocks-data 2.3.4 → 3.1.1

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-data.js

@@ -0,0 +1,143 @@
+// @flow
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {useState, useEffect, useContext, useRef} from "react";
+import {RequestFulfillment} from "../util/request-fulfillment.js";
+import InterceptContext from "../components/intercept-context.js";
+import {TrackerContext} from "../util/request-tracking.js";
+import {resultFromCacheEntry} from "../util/result-from-cache-entry.js";
+import {ResponseCache} from "../util/response-cache.js";
+
+import type {
+    Result,
+    IRequestHandler,
+    ValidData,
+    CacheEntry,
+} from "../util/types.js";
+
+export const useData = <TOptions, TData: ValidData>(
+    handler: IRequestHandler<TOptions, TData>,
+    options: TOptions,
+): Result<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 = ResponseCache.Default.getEntry<TOptions, TData>(
+        handler,
+        options,
+    );
+    const [result, setResult] = useState<?CacheEntry<TData>>(cachedResult);
+
+    // Lookup to see if there's an interceptor for the handler.
+    // If we have one, we need to replace the handler with one that
+    // uses the interceptor.
+    const interceptorMap = useContext(InterceptContext);
+    const interceptor = interceptorMap[handler.type];
+
+    // If we have an interceptor, we need to replace the handler with one that
+    // uses the interceptor. This helper function generates a new handler.
+    // We need this before we track the request as we want the interceptor
+    // to also work for tracked requests to simplify testing the server-side
+    // request fulfillment.
+    const getMaybeInterceptedHandler = () => {
+        if (interceptor == null) {
+            return handler;
+        }
+
+        const fulfillRequestFn = (options) =>
+            interceptor.fulfillRequest(options) ??
+            handler.fulfillRequest(options);
+        return {
+            fulfillRequest: fulfillRequestFn,
+            getKey: (options) => handler.getKey(options),
+            type: handler.type,
+            hydrate: handler.hydrate,
+        };
+    };
+
+    // 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 (result == null && Server.isServerSide()) {
+        maybeTrack?.(getMaybeInterceptedHandler(), options);
+    }
+
+    // We need to update our request when the handler changes or the key
+    // to the options change, so we keep track of those.
+    // However, even if we are hydrating from cache, we still need to make the
+    // request at least once, so we do not initialize these references.
+    const handlerRef = useRef();
+    const keyRef = useRef();
+    const interceptorRef = useRef();
+
+    // This effect will ensure that we fulfill the request as desired.
+    useEffect(() => {
+        // If we are server-side, then just skip the effect. We track requests
+        // during SSR and fulfill them outside of the React render cycle.
+        // NOTE: This shouldn't happen since effects would not run on the server
+        // but let's be defensive - I think it makes the code clearer.
+        /* istanbul ignore next */
+        if (Server.isServerSide()) {
+            return;
+        }
+
+        // Update our refs to the current handler and key.
+        handlerRef.current = handler;
+        keyRef.current = handler.getKey(options);
+        interceptorRef.current = interceptor;
+
+        // If we're not hydrating a result, we want to make sure we set our
+        // result to null so that we're in the loading state.
+        if (cachedResult == null) {
+            // Mark ourselves as loading.
+            setResult(null);
+        }
+
+        // We aren't server-side, so let's make the request.
+        // The request handler is in control of whether that request actually
+        // happens or not.
+        let cancel = false;
+        RequestFulfillment.Default.fulfill(
+            getMaybeInterceptedHandler(),
+            options,
+        )
+            .then((updateEntry) => {
+                if (cancel) {
+                    return;
+                }
+                setResult(updateEntry);
+                return;
+            })
+            .catch((e) => {
+                if (cancel) {
+                    return;
+                }
+                /**
+                 * We should never get here as errors in fulfillment are part
+                 * of the `then`, but if we do.
+                 */
+                // eslint-disable-next-line no-console
+                console.error(
+                    `Unexpected error occurred during data fulfillment: ${e}`,
+                );
+                setResult({
+                    data: null,
+                    error: typeof e === "string" ? e : e.message,
+                });
+                return;
+            });
+
+        return () => {
+            cancel = true;
+        };
+        // - handler.getKey is a proxy for options
+        // - We don't want to trigger on cachedResult changing, we're
+        //   just using that as a flag for render state if the other things
+        //   trigger this effect.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [handler, handler.getKey(options), interceptor]);
+
+    return resultFromCacheEntry(result);
+};

package/src/hooks/use-gql.js

@@ -0,0 +1,77 @@
+// @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;
+                    }
+                    // Need to make sure we pass other errors along.
+                    throw error;
+                });
+            },
+        [fetch, defaultContext],
+    );
+    return gqlFetch;
+};

package/src/index.js

@@ -15,7 +15,6 @@ export type {
     CacheEntry,
     Result,
     IRequestHandler,
-    ICache,
     ResponseCache,
 } from "./util/types.js";
 
@@ -51,15 +50,20 @@ 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 {default as InterceptCache} from "./components/intercept-cache.js";
-export {default as NoCache} from "./util/no-cache.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,
+    GqlOperationType,
+    GqlFetchOptions,
+    GqlFetchFn,
+} 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",
+        });
+    });
+});