@khanacademy/wonder-blocks-data 7.0.1 → 8.0.0

package/src/util/__tests__/request-api.test.js

@@ -0,0 +1,188 @@
+// @flow
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {RequestFulfillment} from "../request-fulfillment.js";
+import {RequestTracker} from "../request-tracking.js";
+
+import {
+    abortInflightRequests,
+    fetchTrackedRequests,
+    hasTrackedRequestsToBeFetched,
+} from "../request-api.js";
+
+describe("#fetchTrackedRequests", () => {
+    describe("when server-side", () => {
+        beforeEach(() => {
+            jest.spyOn(Server, "isServerSide").mockReturnValue(true);
+        });
+
+        it("should call RequestTracker.Default.fulfillTrackedRequests", () => {
+            // Arrange
+            const fulfillTrackedRequestsSpy = jest.spyOn(
+                RequestTracker.Default,
+                "fulfillTrackedRequests",
+            );
+
+            // Act
+            fetchTrackedRequests();
+
+            // Assert
+            expect(fulfillTrackedRequestsSpy).toHaveBeenCalled();
+        });
+
+        it("should return the response cache", async () => {
+            // Arrange
+            const responseCache = {};
+            jest.spyOn(
+                RequestTracker.Default,
+                "fulfillTrackedRequests",
+            ).mockResolvedValue(responseCache);
+
+            // Act
+            const result = await fetchTrackedRequests();
+
+            // Assert
+            expect(result).toBe(responseCache);
+        });
+    });
+
+    describe("when client-side", () => {
+        const NODE_ENV = process.env.NODE_ENV;
+        beforeEach(() => {
+            jest.spyOn(Server, "isServerSide").mockReturnValue(false);
+        });
+
+        afterEach(() => {
+            if (NODE_ENV === undefined) {
+                delete process.env.NODE_ENV;
+            } else {
+                process.env.NODE_ENV = NODE_ENV;
+            }
+        });
+
+        describe("in production", () => {
+            it("should reject with error", async () => {
+                // Arrange
+                process.env.NODE_ENV = "production";
+
+                // Act
+                const result = fetchTrackedRequests();
+
+                // Assert
+                await expect(result).rejects.toThrowErrorMatchingInlineSnapshot(
+                    `"No CSR tracking"`,
+                );
+            });
+        });
+
+        describe("not in production", () => {
+            it("should reject with error", async () => {
+                // Arrange
+                process.env.NODE_ENV = "test";
+
+                // Act
+                const result = fetchTrackedRequests();
+
+                // Assert
+                await expect(result).rejects.toThrowErrorMatchingInlineSnapshot(
+                    `"Data requests are not tracked for fulfillment when when client-side"`,
+                );
+            });
+        });
+    });
+});
+
+describe("#hasTrackedRequestsToBeFetched", () => {
+    describe("when server-side", () => {
+        beforeEach(() => {
+            jest.spyOn(Server, "isServerSide").mockReturnValue(true);
+        });
+
+        it("should call RequestTracker.Default.hasUnfulfilledRequests", () => {
+            // Arrange
+            const hasUnfulfilledRequestsSpy = jest.spyOn(
+                RequestTracker.Default,
+                "hasUnfulfilledRequests",
+                "get",
+            );
+
+            // Act
+            hasTrackedRequestsToBeFetched();
+
+            // Assert
+            expect(hasUnfulfilledRequestsSpy).toHaveBeenCalled();
+        });
+
+        it("should return the boolean value from RequestTracker.Default.hasUnfulfilledRequests", () => {
+            // Arrange
+            jest.spyOn(
+                RequestTracker.Default,
+                "hasUnfulfilledRequests",
+                "get",
+            ).mockReturnValue(true);
+
+            // Act
+            const result = hasTrackedRequestsToBeFetched();
+
+            // Assert
+            expect(result).toBeTrue();
+        });
+    });
+
+    describe("when client-side", () => {
+        const NODE_ENV = process.env.NODE_ENV;
+        beforeEach(() => {
+            jest.spyOn(Server, "isServerSide").mockReturnValue(false);
+        });
+
+        afterEach(() => {
+            if (NODE_ENV === undefined) {
+                delete process.env.NODE_ENV;
+            } else {
+                process.env.NODE_ENV = NODE_ENV;
+            }
+        });
+
+        describe("in production", () => {
+            it("should reject with error", () => {
+                // Arrange
+                process.env.NODE_ENV = "production";
+
+                // Act
+                const underTest = () => hasTrackedRequestsToBeFetched();
+
+                // Assert
+                expect(underTest).toThrowErrorMatchingInlineSnapshot(
+                    `"No CSR tracking"`,
+                );
+            });
+        });
+
+        describe("not in production", () => {
+            it("should reject with error", () => {
+                // Arrange
+                process.env.NODE_ENV = "test";
+
+                // Act
+                const underTest = () => hasTrackedRequestsToBeFetched();
+
+                // Assert
+                expect(underTest).toThrowErrorMatchingInlineSnapshot(
+                    `"Data requests are not tracked for fulfillment when when client-side"`,
+                );
+            });
+        });
+    });
+});
+
+describe("#abortInflightRequests", () => {
+    it("should call RequestFulfillment.Default.abortAll", () => {
+        // Arrange
+        const abortAllSpy = jest.spyOn(RequestFulfillment.Default, "abortAll");
+
+        // Act
+        abortInflightRequests();
+
+        // Assert
+        expect(abortAllSpy).toHaveBeenCalled();
+    });
+});

package/src/util/__tests__/request-fulfillment.test.js

@@ -102,4 +102,46 @@ describe("RequestFulfillment", () => {
             expect(result).not.toBe(promise);
         });
     });
+
+    describe("#abort", () => {
+        it("should delete the given request from the inflight requests", () => {
+            // Arrange
+            const requestFulfillment = new RequestFulfillment();
+            const fakeRequestHandler = () => Promise.resolve("DATA!");
+            const promise = requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
+
+            // Act
+            requestFulfillment.abort("ID");
+            const result = requestFulfillment.fulfill("ID", {
+                handler: fakeRequestHandler,
+            });
+
+            // Assert
+            expect(result).not.toBe(promise);
+        });
+    });
+
+    describe("#abortAll", () => {
+        it("should abort all inflight requests", () => {
+            // Arrange
+            const requestFulfillment = new RequestFulfillment();
+            const abortSpy = jest.spyOn(requestFulfillment, "abort");
+            const fakeRequestHandler = () => Promise.resolve("DATA!");
+            requestFulfillment.fulfill("ID1", {
+                handler: fakeRequestHandler,
+            });
+            requestFulfillment.fulfill("ID2", {
+                handler: fakeRequestHandler,
+            });
+
+            // Act
+            requestFulfillment.abortAll();
+
+            // Assert
+            expect(abortSpy).toHaveBeenCalledWith("ID1");
+            expect(abortSpy).toHaveBeenCalledWith("ID2");
+        });
+    });
 });

package/src/util/__tests__/ssr-cache.test.js

@@ -393,56 +393,6 @@ describe("../ssr-cache.js", () => {
         });
     });
 
-    describe("#remove", () => {
-        it("should return false if nothing was removed", () => {
-            // Arrange
-            const hydrationCache = new SerializableInMemoryCache();
-            const ssrOnlycache = new SerializableInMemoryCache();
-            jest.spyOn(hydrationCache, "purge").mockReturnValue(false);
-            jest.spyOn(ssrOnlycache, "purge").mockReturnValue(false);
-            const cache = new SsrCache(hydrationCache, ssrOnlycache);
-
-            // Act
-            const result = cache.remove("A");
-
-            // Assert
-            expect(result).toBeFalsy();
-        });
-
-        it("should return true if something was removed from hydration cache", () => {
-            // Arrange
-            const hydrationCache = new SerializableInMemoryCache();
-            jest.spyOn(hydrationCache, "purge").mockReturnValue(true);
-            const cache = new SsrCache(hydrationCache);
-
-            // Act
-            const result = cache.remove("A");
-
-            // Assert
-            expect(result).toBeTruthy();
-        });
-
-        describe("when server-side", () => {
-            beforeEach(() => {
-                jest.spyOn(Server, "isServerSide").mockReturnValue(true);
-            });
-
-            it("should return true if something was removed from ssr-only cache", () => {
-                // Arrange
-                const hydrationCache = new SerializableInMemoryCache();
-                const ssrOnlyCache = new SerializableInMemoryCache();
-                jest.spyOn(ssrOnlyCache, "purge").mockReturnValue(true);
-                const cache = new SsrCache(hydrationCache, ssrOnlyCache);
-
-                // Act
-                const result = cache.remove("A");
-
-                // Assert
-                expect(result).toBeTruthy();
-            });
-        });
-    });
-
     describe("#cloneHydratableData", () => {
         it("should clone the hydration cache", () => {
             // Arrange
@@ -467,7 +417,7 @@ describe("../ssr-cache.js", () => {
         });
     });
 
-    describe("#removeAll", () => {
+    describe("#purgeData", () => {
         describe("when client-side", () => {
             beforeEach(() => {
                 jest.spyOn(Server, "isServerSide").mockReturnValue(false);
@@ -480,7 +430,7 @@ describe("../ssr-cache.js", () => {
                 const cache = new SsrCache(hydrationCache);
 
                 // Act
-                cache.removeAll();
+                cache.purgeData();
 
                 // Assert
                 expect(purgeAllSpy).toHaveBeenCalledWith(undefined);
@@ -496,7 +446,7 @@ describe("../ssr-cache.js", () => {
                 );
 
                 // Act
-                cache.removeAll(() => true);
+                cache.purgeData(() => true);
 
                 // Assert
                 expect(purgeAllSpy).toHaveBeenCalledWith(expect.any(Function));
@@ -518,7 +468,7 @@ describe("../ssr-cache.js", () => {
                 const predicate = jest.fn().mockReturnValue(false);
 
                 // Act
-                cache.removeAll(predicate);
+                cache.purgeData(predicate);
 
                 // Assert
                 expect(predicate).toHaveBeenCalledWith("KEY1", {data: "DATA"});
@@ -543,7 +493,7 @@ describe("../ssr-cache.js", () => {
                 );
 
                 // Act
-                cache.removeAll();
+                cache.purgeData();
 
                 // Assert
                 expect(hydrationPurgeAllSpy).toHaveBeenCalledWith(undefined);
@@ -559,7 +509,7 @@ describe("../ssr-cache.js", () => {
                 );
 
                 // Act
-                cache.removeAll();
+                cache.purgeData();
 
                 // Assert
                 expect(ssrPurgeAllSpy).toHaveBeenCalledWith(undefined);
@@ -575,7 +525,7 @@ describe("../ssr-cache.js", () => {
                 );
 
                 // Act
-                cache.removeAll(() => true);
+                cache.purgeData(() => true);
 
                 // Assert
                 expect(purgeAllSpy).toHaveBeenCalledWith(expect.any(Function));
@@ -591,7 +541,7 @@ describe("../ssr-cache.js", () => {
                 );
 
                 // Act
-                cache.removeAll(() => true);
+                cache.purgeData(() => true);
 
                 // Assert
                 expect(purgeAllSpy).toHaveBeenCalledWith(expect.any(Function));
@@ -608,7 +558,7 @@ describe("../ssr-cache.js", () => {
                 const predicate = jest.fn().mockReturnValue(false);
 
                 // Act
-                cache.removeAll(predicate);
+                cache.purgeData(predicate);
 
                 // Assert
                 expect(predicate).toHaveBeenCalledWith("KEY1", {data: "DATA"});
@@ -629,7 +579,7 @@ describe("../ssr-cache.js", () => {
                 const predicate = jest.fn().mockReturnValue(false);
 
                 // Act
-                cache.removeAll(predicate);
+                cache.purgeData(predicate);
 
                 // Assert
                 expect(predicate).toHaveBeenCalledWith("KEY1", {data: "DATA"});

package/src/util/__tests__/to-gql-operation.test.js

@@ -0,0 +1,42 @@
+// @flow
+import {toGqlOperation} from "../to-gql-operation.js";
+import * as GDNP from "../graphql-document-node-parser.js";
+
+jest.mock("../graphql-document-node-parser.js");
+
+describe("#toGqlOperation", () => {
+    it("should parse the document node", () => {
+        // Arrange
+        const documentNode: any = {};
+        const parserSpy = jest
+            .spyOn(GDNP, "graphQLDocumentNodeParser")
+            .mockReturnValue({
+                name: "operationName",
+                type: "query",
+            });
+
+        // Act
+        toGqlOperation(documentNode);
+
+        // Assert
+        expect(parserSpy).toHaveBeenCalledWith(documentNode);
+    });
+
+    it("should return the Wonder Blocks Data representation of the given document node", () => {
+        // Arrange
+        const documentNode: any = {};
+        jest.spyOn(GDNP, "graphQLDocumentNodeParser").mockReturnValue({
+            name: "operationName",
+            type: "mutation",
+        });
+
+        // Act
+        const result = toGqlOperation(documentNode);
+
+        // Assert
+        expect(result).toStrictEqual({
+            id: "operationName",
+            type: "mutation",
+        });
+    });
+});

package/src/util/data-error.js

@@ -26,6 +26,12 @@ export const DataErrors = Object.freeze({
      */
     Network: "Network",
 
+    /**
+     * There was a problem due to the state of the system not matching the
+     * requested operation or input.
+     */
+    NotAllowed: "NotAllowed",
+
     /**
      * Response could not be parsed.
      */

package/src/util/get-gql-request-id.js

@@ -0,0 +1,50 @@
+// @flow
+import type {GqlOperation, GqlContext} from "./gql-types.js";
+
+const toString = (valid: mixed): string => {
+    if (typeof valid === "string") {
+        return valid;
+    }
+    return JSON.stringify(valid) ?? "";
+};
+
+/**
+ * Get an identifier for a given request.
+ */
+export const getGqlRequestId = <TData, TVariables: {...}>(
+    operation: GqlOperation<TData, TVariables>,
+    variables: ?TVariables,
+    context: GqlContext,
+): string => {
+    // We add all the bits for this into an array and then join them with
+    // a chosen separator.
+    const parts = [];
+
+    // First, we push the context values.
+    const sortableContext = new URLSearchParams(context);
+    // $FlowIgnore[prop-missing] Flow has incomplete support for URLSearchParams
+    sortableContext.sort();
+    parts.push(sortableContext.toString());
+
+    // Now we add the operation identifier.
+    parts.push(operation.id);
+
+    // Finally, if we have variables, we add those too.
+    if (variables != null) {
+        // We need to turn each variable into a string.
+        const stringifiedVariables = Object.keys(variables).reduce(
+            (acc, key) => {
+                acc[key] = toString(variables[key]);
+                return acc;
+            },
+            {},
+        );
+        // We use the same mechanism as context to sort and arrange the
+        // variables.
+        const sortableVariables = new URLSearchParams(stringifiedVariables);
+        // $FlowIgnore[prop-missing] Flow has incomplete support for URLSearchParams
+        sortableVariables.sort();
+        parts.push(sortableVariables.toString());
+    }
+    return parts.join("|");
+};

package/src/util/graphql-document-node-parser.js

@@ -0,0 +1,133 @@
+// @flow
+import type {
+    DocumentNode,
+    DefinitionNode,
+    VariableDefinitionNode,
+    OperationDefinitionNode,
+} from "./graphql-types.js";
+import {DataError, DataErrors} from "./data-error.js";
+
+export const DocumentTypes = Object.freeze({
+    query: "query",
+    mutation: "mutation",
+});
+
+export type DocumentType = $Values<typeof DocumentTypes>;
+
+export interface IDocumentDefinition {
+    type: DocumentType;
+    name: string;
+    variables: $ReadOnlyArray<VariableDefinitionNode>;
+}
+
+const cache = new Map<DocumentNode, IDocumentDefinition>();
+
+/**
+ * Parse a GraphQL document node to determine some info about it.
+ *
+ * This is based on:
+ * https://github.com/apollographql/react-apollo/blob/3bc993b2ea91704bd6a2667f42d1940656c071ff/src/parser.ts
+ */
+export function graphQLDocumentNodeParser(
+    document: DocumentNode,
+): IDocumentDefinition {
+    const cached = cache.get(document);
+    if (cached) {
+        return cached;
+    }
+
+    /**
+     * Saftey check for proper usage.
+     */
+    if (!document?.kind) {
+        if (process.env.NODE_ENV === "production") {
+            throw new DataError("Bad DocumentNode", DataErrors.InvalidInput);
+        } else {
+            throw new DataError(
+                `Argument of ${JSON.stringify(
+                    document,
+                )} passed to parser was not a valid GraphQL ` +
+                    `DocumentNode. You may need to use 'graphql-tag' or another method ` +
+                    `to convert your operation into a document`,
+                DataErrors.InvalidInput,
+            );
+        }
+    }
+
+    const fragments = document.definitions.filter(
+        (x: DefinitionNode) => x.kind === "FragmentDefinition",
+    );
+
+    const queries = document.definitions.filter(
+        (x: DefinitionNode) =>
+            // $FlowIgnore[prop-missing]
+            x.kind === "OperationDefinition" && x.operation === "query",
+    );
+
+    const mutations = document.definitions.filter(
+        (x: DefinitionNode) =>
+            // $FlowIgnore[prop-missing]
+            x.kind === "OperationDefinition" && x.operation === "mutation",
+    );
+
+    const subscriptions = document.definitions.filter(
+        (x: DefinitionNode) =>
+            // $FlowIgnore[prop-missing]
+            x.kind === "OperationDefinition" && x.operation === "subscription",
+    );
+
+    if (fragments.length && !queries.length && !mutations.length) {
+        if (process.env.NODE_ENV === "production") {
+            throw new DataError("Fragment only", DataErrors.InvalidInput);
+        } else {
+            throw new DataError(
+                `Passing only a fragment to 'graphql' is not supported. ` +
+                    `You must include a query or mutation as well`,
+                DataErrors.InvalidInput,
+            );
+        }
+    }
+
+    if (subscriptions.length) {
+        if (process.env.NODE_ENV === "production") {
+            throw new DataError("No subscriptions", DataErrors.InvalidInput);
+        } else {
+            throw new DataError(
+                `We do not support subscriptions. ` +
+                    `${JSON.stringify(document)} had ${
+                        subscriptions.length
+                    } subscriptions`,
+                DataErrors.InvalidInput,
+            );
+        }
+    }
+
+    if (queries.length + mutations.length > 1) {
+        if (process.env.NODE_ENV === "production") {
+            throw new DataError("Too many ops", DataErrors.InvalidInput);
+        } else {
+            throw new DataError(
+                `We only support one query or mutation per component. ` +
+                    `${JSON.stringify(document)} had ${
+                        queries.length
+                    } queries and ` +
+                    `${mutations.length} mutations. `,
+                DataErrors.InvalidInput,
+            );
+        }
+    }
+
+    const type = queries.length ? DocumentTypes.query : DocumentTypes.mutation;
+    const definitions = queries.length ? queries : mutations;
+
+    const definition: OperationDefinitionNode = (definitions[0]: any);
+    const variables = definition.variableDefinitions || [];
+
+    // fallback to using data if no name
+    const name =
+        definition.name?.kind === "Name" ? definition.name.value : "data";
+
+    const payload: IDocumentDefinition = {name, type, variables};
+    cache.set(document, payload);
+    return payload;
+}

package/src/util/graphql-types.js

@@ -0,0 +1,30 @@
+// @flow
+// NOTE(somewhatabstract):
+// These types are bare minimum to support document parsing. They're derived
+// from graphql@14.5.8, the last version that provided flow types.
+// Doing this avoids us having to take a dependency on that library just for
+// these types.
+export interface DefinitionNode {
+    +kind: string;
+}
+
+export type VariableDefinitionNode = {
+    +kind: "VariableDefinition",
+    ...
+};
+
+export interface OperationDefinitionNode extends DefinitionNode {
+    +kind: "OperationDefinition";
+    +operation: string;
+    +variableDefinitions: $ReadOnlyArray<VariableDefinitionNode>;
+    +name?: {|
+        +kind: mixed,
+        +value: string,
+    |};
+}
+
+export type DocumentNode = {
+    +kind: "Document",
+    +definitions: $ReadOnlyArray<DefinitionNode>,
+    ...
+};

package/src/util/hydration-cache-api.js

@@ -0,0 +1,28 @@
+// @flow
+import {SsrCache} from "./ssr-cache.js";
+
+import type {ValidCacheData, CachedResponse, ResponseCache} from "./types.js";
+
+/**
+ * Initialize the hydration cache.
+ *
+ * @param {ResponseCache} source The cache content to use for initializing the
+ * cache.
+ * @throws {Error} If the cache is already initialized.
+ */
+export const initializeHydrationCache = (source: ResponseCache): void =>
+    SsrCache.Default.initialize(source);
+
+/**
+ * Purge cached hydration responses that match the given predicate.
+ *
+ * @param {(id: string) => boolean} [predicate] The predicate to match against
+ * the cached hydration responses. If no predicate is provided, all cached
+ * hydration responses will be purged.
+ */
+export const purgeHydrationCache = (
+    predicate?: (
+        key: string,
+        cacheEntry: ?$ReadOnly<CachedResponse<ValidCacheData>>,
+    ) => boolean,
+): void => SsrCache.Default.purgeData(predicate);

package/src/util/purge-caches.js

@@ -0,0 +1,15 @@
+// @flow
+import {purgeSharedCache} from "../hooks/use-shared-cache.js";
+import {purgeHydrationCache} from "./hydration-cache-api.js";
+
+/**
+ * Purge all caches managed by Wonder Blocks Data.
+ *
+ * This is a convenience method that purges the shared cache and the hydration
+ * cache. It is useful for testing purposes to avoid having to reason about
+ * which caches may have been used during a given test run.
+ */
+export const purgeCaches = () => {
+    purgeSharedCache();
+    purgeHydrationCache();
+};