@khanacademy/wonder-blocks-data 3.0.0 → 3.1.2

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

@@ -50,14 +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 {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",
+        });
+    });
+});

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

@@ -0,0 +1,69 @@
+// @flow
+import {GqlError, GqlErrors} from "./gql-error.js";
+
+/**
+ * Validate a GQL operation response and extract the data.
+ */
+export const getGqlDataFromResponse = async <TData>(
+    response: Response,
+): Promise<TData> => {
+    // Get the response as text, that way we can use the text in error
+    // messaging, should our parsing fail.
+    const bodyText = await response.text();
+    let result;
+    try {
+        result = JSON.parse(bodyText);
+    } catch (e) {
+        throw new GqlError("Failed to parse response", GqlErrors.Parse, {
+            metadata: {
+                statusCode: response.status,
+                bodyText,
+            },
+            cause: e,
+        });
+    }
+
+    // Check for a bad status code.
+    if (response.status >= 300) {
+        throw new GqlError("Response unsuccessful", GqlErrors.Network, {
+            metadata: {
+                statusCode: response.status,
+                result,
+            },
+        });
+    }
+
+    // Check that we have a valid result payload.
+    if (
+        // Flow shouldn't be warning about this.
+        // $FlowIgnore[method-unbinding]
+        !Object.prototype.hasOwnProperty.call(result, "data") &&
+        // Flow shouldn't be warning about this.
+        // $FlowIgnore[method-unbinding]
+        !Object.prototype.hasOwnProperty.call(result, "errors")
+    ) {
+        throw new GqlError("Server response missing", GqlErrors.BadResponse, {
+            metadata: {
+                statusCode: response.status,
+                result,
+            },
+        });
+    }
+
+    // If the response payload has errors, throw an error.
+    if (
+        result.errors != null &&
+        Array.isArray(result.errors) &&
+        result.errors.length > 0
+    ) {
+        throw new GqlError("GraphQL errors", GqlErrors.ErrorResult, {
+            metadata: {
+                statusCode: response.status,
+                result,
+            },
+        });
+    }
+
+    // We got here, so return the data.
+    return result.data;
+};

package/src/util/gql-error.js

@@ -0,0 +1,36 @@
+// @flow
+import {KindError, Errors} from "@khanacademy/wonder-stuff-core";
+import type {Metadata} from "@khanacademy/wonder-stuff-core";
+
+type GqlErrorOptions = {|
+    metadata?: ?Metadata,
+    cause?: ?Error,
+|};
+
+/**
+ * Error kinds for GqlError.
+ */
+export const GqlErrors = Object.freeze({
+    ...Errors,
+    Network: "Network",
+    Parse: "Parse",
+    BadResponse: "BadResponse",
+    ErrorResult: "ErrorResult",
+});
+
+/**
+ * An error from the GQL API.
+ */
+export class GqlError extends KindError {
+    constructor(
+        message: string,
+        kind: $Values<typeof GqlErrors>,
+        {metadata, cause}: GqlErrorOptions = ({}: $Shape<GqlErrorOptions>),
+    ) {
+        super(message, kind, {
+            metadata,
+            cause,
+            prefix: "Gql",
+        });
+    }
+}

package/src/util/gql-router-context.js

@@ -0,0 +1,6 @@
+// @flow
+import * as React from "react";
+import type {GqlRouterConfiguration} from "./gql-types.js";
+
+export const GqlRouterContext: React.Context<?GqlRouterConfiguration<any>> =
+    React.createContext<?GqlRouterConfiguration<any>>(null);

package/src/util/gql-types.js

@@ -0,0 +1,65 @@
+// @flow
+/**
+ * Operation types.
+ */
+export type GqlOperationType = "mutation" | "query";
+
+/**
+ * A GraphQL operation.
+ */
+export type GqlOperation<
+    TType: GqlOperationType,
+    // TData is not used to define a field on this type, but it is used
+    // to ensure that calls using this operation will properly return the
+    // correct data type.
+    // eslint-disable-next-line no-unused-vars
+    TData,
+    // TVariables is not used to define a field on this type, but it is used
+    // to ensure that calls using this operation will properly consume the
+    // correct variables type.
+    // eslint-disable-next-line no-unused-vars
+    TVariables: {...} = Empty,
+> = {
+    type: TType,
+    id: string,
+    // We allow other things here to be passed along to the fetch function.
+    // For example, we might want to pass the full query/mutation definition
+    // as a string here to allow that to be sent to an Apollo server that
+    // expects it. This is a courtesy to calling code; these additional
+    // values are ignored by WB Data, and passed through as-is.
+    ...
+};
+
+export type GqlContext = {|
+    [key: string]: string,
+|};
+
+/**
+ * Functions that make fetches of GQL operations.
+ */
+export type GqlFetchFn<
+    TType,
+    TData,
+    TVariables: {...},
+    TContext: GqlContext,
+> = (
+    operation: GqlOperation<TType, TData, TVariables>,
+    variables: ?TVariables,
+    context: TContext,
+) => Promise<Response>;
+
+/**
+ * The configuration stored in the GqlRouterContext context.
+ */
+export type GqlRouterConfiguration<TContext: GqlContext> = {|
+    fetch: GqlFetchFn<any, any, any, any>,
+    defaultContext: TContext,
+|};
+
+/**
+ * Options for configuring a GQL fetch.
+ */
+export type GqlFetchOptions<TVariables: {...}, TContext: GqlContext> = {|
+    variables?: TVariables,
+    context?: Partial<TContext>,
+|};