@khanacademy/wonder-blocks-data 7.0.1 → 8.0.2

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();
+};

package/src/util/request-api.js

@@ -0,0 +1,66 @@
+// @flow
+import {Server} from "@khanacademy/wonder-blocks-core";
+import {RequestTracker} from "./request-tracking.js";
+import {RequestFulfillment} from "./request-fulfillment.js";
+import {DataError, DataErrors} from "./data-error.js";
+
+import type {ResponseCache} from "./types.js";
+
+const SSRCheck = () => {
+    if (Server.isServerSide()) {
+        return null;
+    }
+
+    if (process.env.NODE_ENV === "production") {
+        return new DataError("No CSR tracking", DataErrors.NotAllowed);
+    } else {
+        return new DataError(
+            "Data requests are not tracked for fulfillment when when client-side",
+            DataErrors.NotAllowed,
+        );
+    }
+};
+
+/**
+ * Fetches all tracked data requests.
+ *
+ * This is for use with the `TrackData` component during server-side rendering.
+ *
+ * @throws {Error} If executed outside of server-side rendering.
+ * @returns {Promise<void>} A promise that resolves when all tracked requests
+ * have been fetched.
+ */
+export const fetchTrackedRequests = (): Promise<ResponseCache> => {
+    const ssrCheck = SSRCheck();
+    if (ssrCheck != null) {
+        return Promise.reject(ssrCheck);
+    }
+    return RequestTracker.Default.fulfillTrackedRequests();
+};
+
+/**
+ * Indicate if there are tracked requests waiting to be fetched.
+ *
+ * This is used in conjunction with `TrackData`.
+ *
+ * @throws {Error} If executed outside of server-side rendering.
+ * @returns {boolean} `true` if there are unfetched tracked requests;
+ * otherwise, `false`.
+ */
+export const hasTrackedRequestsToBeFetched = (): boolean => {
+    const ssrCheck = SSRCheck();
+    if (ssrCheck != null) {
+        throw ssrCheck;
+    }
+    return RequestTracker.Default.hasUnfulfilledRequests;
+};
+
+/**
+ * Abort all in-flight requests.
+ *
+ * This aborts all requests currently inflight via our default request
+ * fulfillment.
+ */
+export const abortInflightRequests = (): void => {
+    RequestFulfillment.Default.abortAll();
+};

package/src/util/request-fulfillment.js

@@ -5,9 +5,13 @@ import {DataError, DataErrors} from "./data-error.js";
 
 type RequestCache = {
     [id: string]: Promise<Result<any>>,
-    ...
 };
 
+type FulfillOptions<TData: ValidCacheData> = {|
+    handler: () => Promise<TData>,
+    hydrate?: boolean,
+|};
+
 let _default: RequestFulfillment;
 
 /**
@@ -31,19 +35,10 @@ export class RequestFulfillment {
      */
     fulfill: <TData: ValidCacheData>(
         id: string,
-        options: {|
-            handler: () => Promise<TData>,
-            hydrate?: boolean,
-        |},
+        options: FulfillOptions<TData>,
     ) => Promise<Result<TData>> = <TData: ValidCacheData>(
         id: string,
-        {
-            handler,
-            hydrate = true,
-        }: {|
-            handler: () => Promise<TData>,
-            hydrate?: boolean,
-        |},
+        {handler, hydrate = true}: FulfillOptions<TData>,
     ): Promise<Result<TData>> => {
         /**
          * If we have an inflight request, we'll provide that.
@@ -97,4 +92,29 @@ export class RequestFulfillment {
 
         return request;
     };
+
+    /**
+     * Abort an inflight request.
+     *
+     * NOTE: Currently, this does not perform an actual abort. It merely
+     * removes the request from being tracked.
+     */
+    abort: (id: string) => void = (id) => {
+        // TODO(somewhatabstract, FEI-4276): Add first class abort
+        // support to the handler API.
+        // For now, we will just clear the request out of the list.
+        // When abort is implemented, the `finally` in the `fulfill` method
+        // would handle the deletion.
+        delete this._requests[id];
+    };
+
+    /**
+     * Abort all inflight requests.
+     *
+     * NOTE: Currently, this does not perform actual aborts. It merely
+     * removes the requests from our tracking.
+     */
+    abortAll: () => void = (): void => {
+        Object.keys(this._requests).forEach((id) => this.abort(id));
+    };
 }

package/src/util/request-tracking.js

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

package/src/util/ssr-cache.js

@@ -26,15 +26,13 @@ export class SsrCache {
     }
 
     _hydrationCache: SerializableInMemoryCache;
-    _ssrOnlyCache: ?SerializableInMemoryCache;
+    _ssrOnlyCache: SerializableInMemoryCache;
 
     constructor(
         hydrationCache: ?SerializableInMemoryCache = null,
         ssrOnlyCache: ?SerializableInMemoryCache = null,
     ) {
-        this._ssrOnlyCache = Server.isServerSide()
-            ? ssrOnlyCache || new SerializableInMemoryCache()
-            : undefined;
+        this._ssrOnlyCache = ssrOnlyCache || new SerializableInMemoryCache();
         this._hydrationCache =
             hydrationCache || new SerializableInMemoryCache();
     }
@@ -54,7 +52,7 @@ export class SsrCache {
                 // Usually, when server-side, this cache will always be present.
                 // We do fake server-side in our doc example though, when it
                 // won't be.
-                this._ssrOnlyCache?.set(DefaultScope, id, frozenEntry);
+                this._ssrOnlyCache.set(DefaultScope, id, frozenEntry);
             }
         }
         return frozenEntry;
@@ -120,14 +118,18 @@ export class SsrCache {
     ): ?$ReadOnly<CachedResponse<TData>> => {
         // Get the cached entry for this value.
 
-        // We first look in the ssr cache and then the hydration cache.
+        // We first look in the ssr cache, if we need to.
+        const ssrEntry = Server.isServerSide()
+            ? this._ssrOnlyCache.get(DefaultScope, id)
+            : null;
+
+        // Now we defer to the SSR value, and fallback to the hydration cache.
         const internalEntry =
-            this._ssrOnlyCache?.get(DefaultScope, id) ??
-            this._hydrationCache.get(DefaultScope, id);
+            ssrEntry ?? this._hydrationCache.get(DefaultScope, id);
 
         // If we are not server-side and we hydrated something, let's clear
         // that from the hydration cache to save memory.
-        if (this._ssrOnlyCache == null && internalEntry != null) {
+        if (!Server.isServerSide() && internalEntry != null) {
             // We now delete this from our hydration cache as we don't need it.
             // This does mean that if another handler of the same type but
             // without some sort of linked cache won't get the value, but
@@ -142,26 +144,6 @@ export class SsrCache {
         return internalEntry;
     };
 
-    /**
-     * Remove from cache, the entry matching the given handler and options.
-     *
-     * This will, if present therein, remove the value from the custom cache
-     * associated with the handler and the framework in-memory cache.
-     *
-     * Returns true if something was removed from any cache; otherwise, false.
-     */
-    remove: (id: string) => boolean = (id: string): boolean => {
-        // NOTE(somewhatabstract): We could invoke removeAll with a predicate
-        // to match the key of the entry we're removing, but that's an
-        // inefficient way to remove a single item, so let's not do that.
-
-        // Delete the entry from the appropriate cache.
-        return (
-            this._hydrationCache.purge(DefaultScope, id) ||
-            (this._ssrOnlyCache?.purge(DefaultScope, id) ?? false)
-        );
-    };
-
     /**
      * Remove from cache, any entries matching the given handler and predicate.
      *
@@ -170,7 +152,7 @@ export class SsrCache {
      *
      * It returns a count of all records removed.
      */
-    removeAll: (
+    purgeData: (
         predicate?: (
             key: string,
             cachedEntry: $ReadOnly<CachedResponse<ValidCacheData>>,
@@ -185,7 +167,7 @@ export class SsrCache {
 
         // Apply the predicate to what we have in our caches.
         this._hydrationCache.purgeAll(realPredicate);
-        this._ssrOnlyCache?.purgeAll(realPredicate);
+        this._ssrOnlyCache.purgeAll(realPredicate);
     };
 
     /**

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

@@ -0,0 +1,44 @@
+// @flow
+import {graphQLDocumentNodeParser} from "./graphql-document-node-parser.js";
+import type {GqlOperation} from "./gql-types.js";
+import type {DocumentNode} from "./graphql-types.js";
+
+/**
+ * Convert a GraphQL DocumentNode to a base Wonder Blocks Data GqlOperation.
+ *
+ * If you want to include the query/mutation body, extend the result of this
+ * method and use the `graphql/language/printer` like:
+ *
+ * ```js
+ * import {print} from "graphql/language/printer";
+ *
+ * const gqlOpWithBody = {
+ *     ...toGqlOperation(documentNode),
+ *     query: print(documentNode),
+ * };
+ * ```
+ *
+ * If you want to enforce inclusion of __typename properties, then you can use
+ * `apollo-utilities` first to modify the document:
+ *
+ * ```js
+ * import {print} from "graphql/language/printer";
+ * import {addTypenameToDocument} from "apollo-utilities";
+ *
+ * const documentWithTypenames = addTypenameToDocument(documentNode);
+ * const gqlOpWithBody = {
+ *     ...toGqlOperation(documentWithTypenames),
+ *     query: print(documentWithTypenames),
+ * };
+ * ```
+ */
+export const toGqlOperation = <TData, TVariables: {...}>(
+    documentNode: DocumentNode,
+): GqlOperation<TData, TVariables> => {
+    const definition = graphQLDocumentNodeParser(documentNode);
+    const wbDataOperation: GqlOperation<TData, TVariables> = {
+        id: definition.name,
+        type: definition.type,
+    };
+    return wbDataOperation;
+};

package/src/util/types.js

@@ -1,6 +1,37 @@
 // @flow
 import type {Metadata} from "@khanacademy/wonder-stuff-core";
 
+// TODO(somewhatabstract, FEI-4172): Update eslint-plugin-flowtype when
+// they've fixed https://github.com/gajus/eslint-plugin-flowtype/issues/502
+/* eslint-disable no-undef */
+/**
+ * Defines the various fetch policies that can be applied to requests.
+ */
+export enum FetchPolicy {
+    /**
+     * If the data is in the cache, return that; otherwise, fetch from the
+     * server.
+     */
+    CacheBeforeNetwork,
+
+    /**
+     * If the data is in the cache, return that; always fetch from the server
+     * regardless of cache.
+     */
+    CacheAndNetwork,
+
+    /**
+     * If the data is in the cache, return that; otherwise, do nothing.
+     */
+    CacheOnly,
+
+    /**
+     * Ignore any existing cached result; always fetch from the server.
+     */
+    NetworkOnly,
+}
+/* eslint-enable no-undef */
+
 /**
  * Define what can be cached.
  *

package/src/__docs__/exports.intialize-cache.stories.mdx

@@ -1,29 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Data / Exports / initializeCache()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# initializeCache()
-
-```ts
-initializeCache(sourceCache: ResponseCache): void;
-```
-
-| Argument | Flow&nbsp;Type | Default | Description |
-| --- | --- | --- | --- |
-| `sourceData` | `ResponseCache` | _Required_ | The source cache that will be used to initialize the response cache. |
-
-Wonder Blocks Data caches data in its response cache for hydration. This cache can be initialized with data using the `initializeCache` method.
-The `initializeCache` method can only be called when the hydration cache is empty.
-
-Usually, the data to be passed to `initializeCache` will be obtained by calling [`fulfillAllDataRequests`](/docs/data-exports-fulfillalldatarequests--page) after tracking data requests (see [`TrackData`](/docs/data-exports-trackdata--page)) during server-side rendering.
-
-Combine with [`removeFromCache`](/docs/data-exports-removefromcache--page) or [`removeAllFromCache`](/docs/data-exports-removeallfromcache--page) to support your testing needs.
-
-More details about server-side rendering with Wonder Blocks Data can be found in the [relevant overview section](/docs/data-server-side-rendering-and-hydration--page).

package/src/__docs__/exports.remove-from-cache.stories.mdx

@@ -1,25 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Data / Exports / removeFromCache()"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# removeFromCache()
-
-```ts
-removeFromCache(id: string): void;
-```
-
-| Argument | Flow&nbsp;Type | Default | Description |
-| --- | --- | --- | --- |
-| `id` | `string` | _Required_ | The id of the item to be removed. |
-
-
-Removes an entry from the cache.
-
-This can be used after [`initializeCache`](/docs/data-exports-initializecache--page) to manipulate the cache prior to hydration. This can be useful during testing.

package/src/__docs__/exports.request-fulfillment.stories.mdx

@@ -1,36 +0,0 @@
-import {Meta} from "@storybook/addon-docs";
-
-<Meta
-    title="Data / Exports / RequestFulfillment"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# RequestFulfillment
-
-The `RequestFulfillment` class encapsulates tracking of inflight asynchronous actions keyed by an identifier. Using this API, callers can request the result of the same asynchronous action multiple times without invoking the underlying action more than is necessary. Instead, any pending request will be shared by all requests for the same identifier.
-
-## Usage
-
-```ts
-    fulfill: <TData: ValidCacheData>(
-        id: string,
-        options: {|
-            handler: () => Promise<TData>,
-            hydrate?: boolean,
-        |},
-    ) => Promise<Result<TData>>;
-```
-
-There is a single function on the `RequestFulfillment` class, called `fulfill`.
-
-The `fulfill` method takes the request identifier (used to deduplicate requests) and an options object. The options object contains the following properties:
-
- * `handler`: A function that returns a promise resolving to the result of the request. This is the asynchronous work that will be tracked by the given identifier.
- * `hydrate`: A boolean indicating whether the data should be hydrated. This is used during server-side rendering to determine if the response data should be included in the hydration cache. This defaults to `true` and should only be set to `false` if you are performing server-side rendering of the request and you know that the data will not be needed for hydration to succeed.
-
-## RequestFulfillment.Default
-The `RequestFulfillment` class provides a static instance, `RequestFulfillment.Default`, which is used by the Wonder Blocks Data framework. However, a custom instance can be constructed should your specific use case need to be isolated from others.