@khanacademy/wonder-blocks-data 2.3.3 → 3.1.0

package/src/util/__tests__/result-from-cache-entry.test.js

@@ -0,0 +1,68 @@
+// @flow
+import {resultFromCacheEntry} from "../result-from-cache-entry.js";
+
+describe("#resultFromCacheEntry", () => {
+    it("should return loading status if cache entry is null", () => {
+        // Arrange
+        const cacheEntry = null;
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "loading",
+        });
+    });
+
+    it("should return success status if cache entry has data", () => {
+        // Arrange
+        const cacheEntry = {
+            data: "DATA",
+            error: null,
+        };
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "success",
+            data: "DATA",
+        });
+    });
+
+    it("should return error status if cache entry has no data and no error", () => {
+        // Arrange
+        const cacheEntry: any = {
+            data: null,
+            error: null,
+        };
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "error",
+            error: "Loaded result has invalid state where data and error are missing",
+        });
+    });
+
+    it("should return error status if cache entry has error", () => {
+        // Arrange
+        const cacheEntry: any = {
+            data: null,
+            error: "ERROR",
+        };
+
+        // Act
+        const result = resultFromCacheEntry(cacheEntry);
+
+        // Assert
+        expect(result).toStrictEqual({
+            status: "error",
+            error: "ERROR",
+        });
+    });
+});

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,60 @@
+// @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 FetchFn<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: FetchFn<any, any, any, any>,
+    defaultContext: TContext,
+|};
+
+/**
+ * Options for configuring a GQL fetch.
+ */
+export type GqlFetchOptions<TVariables: {...}, TContext: GqlContext> = {|
+    variables?: TVariables,
+    context?: Partial<TContext>,
+|};

package/src/util/memory-cache.js

@@ -25,12 +25,11 @@ function deepClone<T: {...}>(source: T | $ReadOnly<T>): $ReadOnly<T> {
  *
  * Special case cache implementation for the memory cache.
  *
- * This is only used within our framework. Handlers don't need to
- * provide this as a custom cache as the framework will default to this in the
- * absence of a custom cache. We use this for SSR too (see ./response-cache.js).
+ * This is only used within our framework for SSR (see ./response-cache.js).
  */
 export default class MemoryCache<TOptions, TData: ValidData>
-    implements ICache<TOptions, TData> {
+    implements ICache<TOptions, TData>
+{
     _cache: Cache;
 
     constructor(source: ?$ReadOnly<Cache> = null) {
@@ -52,6 +51,11 @@ export default class MemoryCache<TOptions, TData: ValidData>
         }
     }
 
+    /**
+     * Indicate if this cache is being used or now.
+     *
+     * When the cache has entries, returns `true`; otherwise, returns `false`.
+     */
     get inUse(): boolean {
         return Object.keys(this._cache).length > 0;
     }
@@ -67,9 +71,7 @@ export default class MemoryCache<TOptions, TData: ValidData>
     ): void => {
         const requestType = handler.type;
 
-        const frozenEntry = Object.isFrozen(entry)
-            ? entry
-            : Object.freeze(entry);
+        const frozenEntry = Object.freeze(entry);
 
         // Ensure we have a cache location for this handler type.
         this._cache[requestType] = this._cache[requestType] || {};
@@ -156,16 +158,19 @@ export default class MemoryCache<TOptions, TData: ValidData>
             return 0;
         }
 
-        // Apply the predicate to what we have cached.
         let removedCount = 0;
-        for (const [key, entry] of Object.entries(handlerCache)) {
-            if (
-                typeof predicate !== "function" ||
-                predicate(key, (entry: any))
-            ) {
-                removedCount++;
-                delete handlerCache[key];
+        if (typeof predicate === "function") {
+            // Apply the predicate to what we have cached.
+            for (const [key, entry] of Object.entries(handlerCache)) {
+                if (predicate(key, (entry: any))) {
+                    removedCount++;
+                    delete handlerCache[key];
+                }
             }
+        } else {
+            // We're removing everything so delete the entire subcache.
+            removedCount = Object.keys(handlerCache).length;
+            delete this._cache[requestType];
         }
         return removedCount;
     };

package/src/util/request-fulfillment.js

@@ -76,6 +76,8 @@ export class RequestFulfillment {
                     delete handlerRequests[key];
                     /**
                      * Let's cache the data!
+                     *
+                     * NOTE: This only caches when we're server side.
                      */
                     return cacheData<TOptions, TData>(handler, options, data);
                 })
@@ -83,6 +85,8 @@ export class RequestFulfillment {
                     delete handlerRequests[key];
                     /**
                      * Let's cache the error!
+                     *
+                     * NOTE: This only caches when we're server side.
                      */
                     return cacheError<TOptions, TData>(handler, options, error);
                 });

package/src/util/request-handler.js

@@ -1,5 +1,5 @@
 // @flow
-import type {ValidData, CacheEntry, IRequestHandler, ICache} from "./types.js";
+import type {ValidData, IRequestHandler} from "./types.js";
 
 /**
  * Base implementation for creating a request handler.
@@ -8,18 +8,13 @@ import type {ValidData, CacheEntry, IRequestHandler, ICache} from "./types.js";
  * use with the Wonder Blocks Data framework.
  */
 export default class RequestHandler<TOptions, TData: ValidData>
-    implements IRequestHandler<TOptions, TData> {
+    implements IRequestHandler<TOptions, TData>
+{
     _type: string;
-    _cache: ?ICache<TOptions, TData>;
     _hydrate: boolean;
 
-    constructor(
-        type: string,
-        cache?: ICache<TOptions, TData>,
-        hydrate?: boolean = true,
-    ) {
+    constructor(type: string, hydrate?: boolean = true) {
         this._type = type;
-        this._cache = cache || null;
         this._hydrate = !!hydrate;
     }
 
@@ -27,29 +22,10 @@ export default class RequestHandler<TOptions, TData: ValidData>
         return this._type;
     }
 
-    get cache(): ?ICache<TOptions, TData> {
-        return this._cache;
-    }
-
     get hydrate(): boolean {
         return this._hydrate;
     }
 
-    shouldRefreshCache(
-        options: TOptions,
-        cachedEntry: ?$ReadOnly<CacheEntry<TData>>,
-    ): boolean {
-        /**
-         * By default, the cache needs a refresh if the current entry is an
-         * error.
-         *
-         * This means that an error will cause a re-request on render.
-         * Useful if the server rendered an error, as it means the client
-         * will update after rehydration.
-         */
-        return cachedEntry == null || cachedEntry.error != null;
-    }
-
     getKey(options: TOptions): string {
         try {
             return options === undefined

package/src/util/request-handler.md

@@ -14,12 +14,6 @@ interface IRequestHandler<TOptions, TData> {
      */
     get type(): string;
 
-    /**
-     * A custom cache to use with data that this handler requests.
-     * This only affects client-side caching of data.
-     */
-    get cache(): ?ICache<TOptions, TData>;
-
     /**
      * When true, server-side results are cached and hydrated in the client.
      * When false, the server-side cache is not used and results are not
@@ -29,17 +23,6 @@ interface IRequestHandler<TOptions, TData> {
      */
     get hydrate(): boolean;
 
-    /**
-     * Determine if the cached data should be refreshed.
-     *
-     * If this returns true, the framework will use the currently cached value
-     * but also request a new value.
-     */
-    shouldRefreshCache(
-        options: TOptions,
-        cachedEntry: ?$ReadOnly<CacheEntry<TData>>,
-    ): boolean;
-
     /**
      * Get the key to use for a given request. This should be idempotent for a
      * given options set if you want caching to work across requests.
@@ -52,13 +35,6 @@ The constructor requires a `type` to identify your handler. This should be uniqu
 among the handlers that are used across your application, otherwise, requests
 may be fulfilled by the wrong handler.
 
-There is also an optional constructor argument, `cache`, which can be used to
-provide a custom cache for use with data the handler fulfills. Custom caches
-must implement the `ICache<TOptions, TData>` interface. If this is omitted, the
-core Wonder Blocks Data in-memory cache will be used. If you want to avoid
-caching in memory, see `NoCache`, which is a caching strategy that eliminates
-the use of caching entirely.
-
 The `fulfillRequest` method of this class is not implemented and will throw if
 called. Subclasses will need to implement this method.
 
@@ -73,11 +49,3 @@ SSR process is tracking the data for hydration. An example of setting this to
 false might be when you are using Apollo Client. In that scenario, you may use
 Apollo Cache to store and hydrate the data, while using Wonder Blocks Data to
 track and fulfill any query requests made via Apollo Client.
-
-Finally, the `shouldRefreshCache` method is provided for cases where a handler
-may want control over cache freshness. By default, this will return `true` for
-error results or a missing value. However, in some cases, handlers may want to
-make sure cached entries are not stale, and so may return `true` from the
-`shouldRefreshCache` method to instruct the framework to make a new request.
-The existing cached value will still be used, but an updated value will be
-requested.

package/src/util/request-tracking.js

@@ -25,9 +25,8 @@ type RequestCache = {
  *
  * INTERNAL USE ONLY
  */
-export const TrackerContext: React.Context<?TrackerFn> = new React.createContext<?TrackerFn>(
-    null,
-);
+export const TrackerContext: React.Context<?TrackerFn> =
+    new React.createContext<?TrackerFn>(null);
 
 /**
  * The default instance is stored here.