@khanacademy/wonder-blocks-data 7.0.1 → 8.0.0

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

@@ -142,26 +142,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 +150,7 @@ export class SsrCache {
      *
      * It returns a count of all records removed.
      */
-    removeAll: (
+    purgeData: (
         predicate?: (
             key: string,
             cachedEntry: $ReadOnly<CachedResponse<ValidCacheData>>,

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.