@khanacademy/wonder-blocks-data 5.0.0 → 6.0.1

package/dist/es/index.js

@@ -1,117 +1,216 @@
-import { Server } from '@khanacademy/wonder-blocks-core';
-import { KindError, Errors, clone } from '@khanacademy/wonder-stuff-core';
-import * as React from 'react';
-import { useContext, useMemo } from 'react';
+import { Server, useForceUpdate } from '@khanacademy/wonder-blocks-core';
+import { KindError, clone } from '@khanacademy/wonder-stuff-core';
 import _extends from '@babel/runtime/helpers/extends';
+import * as React from 'react';
+import { useContext, useRef, useMemo, useCallback } from 'react';
+
+/**
+ * Error kinds for DataError.
+ */
+const DataErrors = Object.freeze({
+  /**
+   * The kind of error is not known.
+   */
+  Unknown: "Unknown",
+
+  /**
+   * The error is internal to the executing code.
+   */
+  Internal: "Internal",
+
+  /**
+   * There was a problem with the provided input.
+   */
+  InvalidInput: "InvalidInput",
+
+  /**
+   * A network error occurred.
+   */
+  Network: "Network",
+
+  /**
+   * Response could not be parsed.
+   */
+  Parse: "Parse",
+
+  /**
+   * An error that occurred during SSR and was hydrated from cache
+   */
+  Hydrated: "Hydrated"
+});
+/**
+ * An error from the Wonder Blocks Data API.
+ *
+ * Errors of this type will have names of the format:
+ *     `${kind}DataError`
+ */
+
+class DataError extends KindError {
+  constructor(message, kind, {
+    metadata,
+    cause
+  } = {}) {
+    super(message, kind, {
+      metadata,
+      cause,
+      name: "Data"
+    });
+  }
+
+}
 
 /**
  * Describe an in-memory cache.
  */
 class ScopedInMemoryCache {
-  constructor(initialCache = Object.freeze({})) {
-    this.set = (scope, id, value) => {
-      var _this$_cache$scope;
+  constructor(initialCache = {}) {
+    this._cache = initialCache;
+  }
+  /**
+   * Indicate if this cache is being used or not.
+   *
+   * When the cache has entries, returns `true`; otherwise, returns `false`.
+   */
 
-      if (!id || typeof id !== "string") {
-        throw new KindError("id must be non-empty string", Errors.InvalidInput);
-      }
 
-      if (!scope || typeof scope !== "string") {
-        throw new KindError("scope must be non-empty string", Errors.InvalidInput);
-      }
+  get inUse() {
+    return Object.keys(this._cache).length > 0;
+  }
+  /**
+   * Set a value in the cache.
+   */
 
-      if (typeof value === "function") {
-        throw new KindError("value must be a non-function value", Errors.InvalidInput);
-      }
 
-      this._cache[scope] = (_this$_cache$scope = this._cache[scope]) != null ? _this$_cache$scope : {};
-      this._cache[scope][id] = Object.freeze(clone(value));
-    };
+  set(scope, id, value) {
+    var _this$_cache$scope;
 
-    this.get = (scope, id) => {
-      var _this$_cache$scope$id, _this$_cache$scope2;
+    if (!id || typeof id !== "string") {
+      throw new DataError("id must be non-empty string", DataErrors.InvalidInput);
+    }
 
-      return (_this$_cache$scope$id = (_this$_cache$scope2 = this._cache[scope]) == null ? void 0 : _this$_cache$scope2[id]) != null ? _this$_cache$scope$id : null;
-    };
+    if (!scope || typeof scope !== "string") {
+      throw new DataError("scope must be non-empty string", DataErrors.InvalidInput);
+    }
 
-    this.purge = (scope, id) => {
-      var _this$_cache$scope3;
+    if (typeof value === "function") {
+      throw new DataError("value must be a non-function value", DataErrors.InvalidInput);
+    }
 
-      if (!((_this$_cache$scope3 = this._cache[scope]) != null && _this$_cache$scope3[id])) {
-        return;
-      }
+    this._cache[scope] = (_this$_cache$scope = this._cache[scope]) != null ? _this$_cache$scope : {};
+    this._cache[scope][id] = value;
+  }
+  /**
+   * Retrieve a value from the cache.
+   */
 
-      delete this._cache[scope][id];
 
-      if (Object.keys(this._cache[scope]).length === 0) {
-        delete this._cache[scope];
-      }
-    };
+  get(scope, id) {
+    var _this$_cache$scope$id, _this$_cache$scope2;
 
-    this.purgeScope = (scope, predicate) => {
-      if (!this._cache[scope]) {
-        return;
-      }
+    return (_this$_cache$scope$id = (_this$_cache$scope2 = this._cache[scope]) == null ? void 0 : _this$_cache$scope2[id]) != null ? _this$_cache$scope$id : null;
+  }
+  /**
+   * Purge an item from the cache.
+   */
 
-      if (predicate == null) {
-        delete this._cache[scope];
-        return;
-      }
 
-      for (const key of Object.keys(this._cache[scope])) {
-        if (predicate(key, this._cache[scope][key])) {
-          delete this._cache[scope][key];
-        }
-      }
+  purge(scope, id) {
+    var _this$_cache$scope3;
 
-      if (Object.keys(this._cache[scope]).length === 0) {
-        delete this._cache[scope];
-      }
-    };
+    if (!((_this$_cache$scope3 = this._cache[scope]) != null && _this$_cache$scope3[id])) {
+      return;
+    }
 
-    this.purgeAll = predicate => {
-      if (predicate == null) {
-        this._cache = {};
-        return;
-      }
+    delete this._cache[scope][id];
 
-      for (const scope of Object.keys(this._cache)) {
-        this.purgeScope(scope, (id, value) => predicate(scope, id, value));
-      }
-    };
+    if (Object.keys(this._cache[scope]).length === 0) {
+      delete this._cache[scope];
+    }
+  }
+  /**
+   * Purge a scope of items that match the given predicate.
+   *
+   * If the predicate is omitted, then all items in the scope are purged.
+   */
 
-    this.clone = () => {
-      try {
-        return clone(this._cache);
-      } catch (e) {
-        throw new Error(`An error occurred while trying to clone the cache: ${e}`);
+
+  purgeScope(scope, predicate) {
+    if (!this._cache[scope]) {
+      return;
+    }
+
+    if (predicate == null) {
+      delete this._cache[scope];
+      return;
+    }
+
+    for (const key of Object.keys(this._cache[scope])) {
+      if (predicate(key, this._cache[scope][key])) {
+        delete this._cache[scope][key];
       }
-    };
+    }
 
-    try {
-      this._cache = clone(initialCache);
-    } catch (e) {
-      throw new KindError(`An error occurred trying to initialize from a response cache snapshot: ${e}`, Errors.InvalidInput);
+    if (Object.keys(this._cache[scope]).length === 0) {
+      delete this._cache[scope];
     }
   }
   /**
-   * Indicate if this cache is being used or not.
+   * Purge all items from the cache that match the given predicate.
    *
-   * When the cache has entries, returns `true`; otherwise, returns `false`.
+   * If the predicate is omitted, then all items in the cache are purged.
    */
 
 
-  get inUse() {
-    return Object.keys(this._cache).length > 0;
+  purgeAll(predicate) {
+    if (predicate == null) {
+      this._cache = {};
+      return;
+    }
+
+    for (const scope of Object.keys(this._cache)) {
+      this.purgeScope(scope, (id, value) => predicate(scope, id, value));
+    }
+  }
+
+}
+
+/**
+ * Describe a serializable in-memory cache.
+ */
+class SerializableInMemoryCache extends ScopedInMemoryCache {
+  constructor(initialCache = {}) {
+    try {
+      super(clone(initialCache));
+    } catch (e) {
+      throw new DataError(`An error occurred trying to initialize from a response cache snapshot: ${e}`, DataErrors.InvalidInput);
+    }
   }
   /**
    * Set a value in the cache.
    */
 
 
+  set(scope, id, value) {
+    super.set(scope, id, Object.freeze(clone(value)));
+  }
+  /**
+   * Clone the cache.
+   */
+
+
+  clone() {
+    try {
+      return clone(this._cache);
+    } catch (e) {
+      throw new DataError("An error occurred while trying to clone the cache", DataErrors.Internal, {
+        cause: e
+      });
+    }
+  }
+
 }
 
-const DefaultScope = "default";
+const DefaultScope$2 = "default";
 /**
  * The default instance is stored here.
  * It's created below in the Default() static property.
@@ -140,9 +239,9 @@ class SsrCache {
         throw new Error("Cannot initialize data response cache more than once");
       }
 
-      this._hydrationCache = new ScopedInMemoryCache({
+      this._hydrationCache = new SerializableInMemoryCache({
         // $FlowIgnore[incompatible-call]
-        [DefaultScope]: source
+        [DefaultScope$2]: source
       });
     };
 
@@ -162,7 +261,7 @@ class SsrCache {
 
       // Get the cached entry for this value.
       // We first look in the ssr cache and then the hydration cache.
-      const internalEntry = (_this$_ssrOnlyCache$g = (_this$_ssrOnlyCache = this._ssrOnlyCache) == null ? void 0 : _this$_ssrOnlyCache.get(DefaultScope, id)) != null ? _this$_ssrOnlyCache$g : this._hydrationCache.get(DefaultScope, id); // If we are not server-side and we hydrated something, let's clear
+      const internalEntry = (_this$_ssrOnlyCache$g = (_this$_ssrOnlyCache = this._ssrOnlyCache) == null ? void 0 : _this$_ssrOnlyCache.get(DefaultScope$2, id)) != null ? _this$_ssrOnlyCache$g : this._hydrationCache.get(DefaultScope$2, 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) {
@@ -172,7 +271,7 @@ class SsrCache {
         // that's not an expected use-case. If two different places use the
         // same handler and options (i.e. the same request), then the
         // handler should cater to that to ensure they share the result.
-        this._hydrationCache.purge(DefaultScope, id);
+        this._hydrationCache.purge(DefaultScope$2, id);
       } // Getting the typing right between the in-memory cache and this
       // is hard. Just telling flow it's OK.
       // $FlowIgnore[incompatible-return]
@@ -188,7 +287,7 @@ class SsrCache {
       // 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$p = (_this$_ssrOnlyCache2 = this._ssrOnlyCache) == null ? void 0 : _this$_ssrOnlyCache2.purge(DefaultScope, id)) != null ? _this$_ssrOnlyCache$p : false);
+      return this._hydrationCache.purge(DefaultScope$2, id) || ((_this$_ssrOnlyCache$p = (_this$_ssrOnlyCache2 = this._ssrOnlyCache) == null ? void 0 : _this$_ssrOnlyCache2.purge(DefaultScope$2, id)) != null ? _this$_ssrOnlyCache$p : false);
     };
 
     this.removeAll = predicate => {
@@ -215,11 +314,11 @@ class SsrCache {
       // $FlowIgnore[incompatible-return]
 
 
-      return (_cache$DefaultScope = cache[DefaultScope]) != null ? _cache$DefaultScope : {};
+      return (_cache$DefaultScope = cache[DefaultScope$2]) != null ? _cache$DefaultScope : {};
     };
 
-    this._ssrOnlyCache = Server.isServerSide() ? ssrOnlyCache || new ScopedInMemoryCache() : undefined;
-    this._hydrationCache = hydrationCache || new ScopedInMemoryCache();
+    this._ssrOnlyCache = Server.isServerSide() ? ssrOnlyCache || new SerializableInMemoryCache() : undefined;
+    this._hydrationCache = hydrationCache || new SerializableInMemoryCache();
   }
 
   _setCachedResponse(id, entry, hydrate) {
@@ -229,14 +328,14 @@ class SsrCache {
       // We are server-side.
       // We need to store this value.
       if (hydrate) {
-        this._hydrationCache.set(DefaultScope, id, frozenEntry);
+        this._hydrationCache.set(DefaultScope$2, id, frozenEntry);
       } else {
         var _this$_ssrOnlyCache4;
 
         // 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$_ssrOnlyCache4 = this._ssrOnlyCache) == null ? void 0 : _this$_ssrOnlyCache4.set(DefaultScope, id, frozenEntry);
+        (_this$_ssrOnlyCache4 = this._ssrOnlyCache) == null ? void 0 : _this$_ssrOnlyCache4.set(DefaultScope$2, id, frozenEntry);
       }
     }
 
@@ -252,17 +351,13 @@ class SsrCache {
 }
 
 let _default$1;
+/**
+ * This fulfills a request, making sure that in-flight requests are shared.
+ */
 
-class RequestFulfillment {
-  static get Default() {
-    if (!_default$1) {
-      _default$1 = new RequestFulfillment();
-    }
-
-    return _default$1;
-  }
 
-  constructor(responseCache = undefined) {
+class RequestFulfillment {
+  constructor() {
     this._requests = {};
 
     this.fulfill = (id, {
@@ -282,57 +377,48 @@ class RequestFulfillment {
        */
 
 
-      const {
-        cacheData,
-        cacheError
-      } = this._responseCache;
+      const request = handler().then(data => ({
+        status: "success",
+        data
+      })).catch(error => {
+        const actualError = typeof error === "string" ? new DataError("Request failed", DataErrors.Unknown, {
+          metadata: {
+            unexpectedError: error
+          }
+        }) : error; // Return aborted result 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 handler supporting aborts.
+        // TODO(somewhatabstract, FEI-4276): Add first class abort
+        // support to the handler API.
+
+        if (actualError.name === "AbortError") {
+          return {
+            status: "aborted"
+          };
+        }
 
-      try {
-        const request = handler().then(data => {
-          delete this._requests[id];
+        return {
+          status: "error",
+          error: actualError
+        };
+      }).finally(() => {
+        delete this._requests[id];
+      }); // Store the request in our cache.
 
-          if (data == null) {
-            // Request aborted. We won't cache this.
-            return null;
-          }
-          /**
-           * Let's cache the data!
-           *
-           * NOTE: This only caches when we're server side.
-           */
-
-
-          return cacheData(id, data, _hydrate);
-        }).catch(error => {
-          delete this._requests[id];
-          /**
-           * Let's cache the error!
-           *
-           * NOTE: This only caches when we're server side.
-           */
-
-          return cacheError(id, error, _hydrate);
-        });
-        this._requests[id] = request;
-        return request;
-      } catch (e) {
-        /**
-         * In this case, we don't cache an inflight request, because there
-         * really isn't one.
-         */
-        return Promise.resolve(cacheError(id, e, _hydrate));
-      }
+      this._requests[id] = request;
+      return request;
     };
-
-    this._responseCache = responseCache || SsrCache.Default;
   }
-  /**
-   * Get a promise of a request for a given handler and options.
-   *
-   * This will return an inflight request if one exists, otherwise it will
-   * make a new request. Inflight requests are deleted once they resolve.
-   */
 
+  static get Default() {
+    if (!_default$1) {
+      _default$1 = new RequestFulfillment();
+    }
+
+    return _default$1;
+  }
 
 }
 
@@ -389,11 +475,54 @@ class RequestTracker {
 
     this.fulfillTrackedRequests = () => {
       const promises = [];
+      const {
+        cacheData,
+        cacheError
+      } = this._responseCache;
 
       for (const requestKey of Object.keys(this._trackedRequests)) {
-        const promise = this._requestFulfillment.fulfill(requestKey, this._trackedRequests[requestKey]);
-
-        promises.push(promise);
+        const options = this._trackedRequests[requestKey];
+
+        try {
+          promises.push(this._requestFulfillment.fulfill(requestKey, _extends({}, options)).then(result => {
+            switch (result.status) {
+              case "success":
+                /**
+                 * Let's cache the data!
+                 *
+                 * NOTE: This only caches when we're
+                 * server side.
+                 */
+                cacheData(requestKey, result.data, options.hydrate);
+                break;
+
+              case "error":
+                /**
+                 * Let's cache the error!
+                 *
+                 * NOTE: This only caches when we're
+                 * server side.
+                 */
+                cacheError(requestKey, result.error, options.hydrate);
+                break;
+            } // For status === "loading":
+            // Could never get here unless we wrote
+            // the code wrong. Rather than bloat
+            // code with useless error, just ignore.
+            // For status === "aborted":
+            // We won't cache this.
+            // We don't hydrate aborted requests,
+            // so the client would just see them
+            // as unfulfilled data.
+
+
+            return;
+          }));
+        } catch (e) {
+          // This captures if there are problems in the code that
+          // begins the requests.
+          promises.push(Promise.resolve(cacheError(requestKey, e, options.hydrate)));
+        }
       }
       /**
        * Clear out our tracked info.
@@ -401,16 +530,15 @@ class RequestTracker {
        * We call this now for a simpler API.
        *
        * If we reset the tracked calls after all promises resolve, any
-       * requst tracking done while promises are in flight would be lost.
+       * request tracking done while promises are in flight would be lost.
        *
        * If we don't reset at all, then we have to expose the `reset` call
        * for consumers to use, or they'll only ever be able to accumulate
        * more and more tracked requests, having to fulfill them all every
        * time.
        *
-       * Calling it here means we can have multiple "track -> request" cycles
-       * in a row and in an easy to reason about manner.
-       *
+       * Calling it here means we can have multiple "track -> request"
+       * cycles in a row and in an easy to reason about manner.
        */
 
 
@@ -423,7 +551,7 @@ class RequestTracker {
     };
 
     this._responseCache = responseCache || SsrCache.Default;
-    this._requestFulfillment = new RequestFulfillment(responseCache);
+    this._requestFulfillment = new RequestFulfillment();
   }
   /**
    * Track a request.
@@ -473,37 +601,70 @@ class TrackData extends React.Component {
 }
 
 /**
- * Hook to perform an asynchronous action during server-side rendering.
- *
- * This hook registers an asynchronous action to be performed during
- * server-side rendering. The action is performed only once, and the result
- * is cached against the given identifier so that subsequent calls return that
- * cached result allowing components to render more of the component.
+ * Simple implementation to represent aborting.
  *
- * This hook requires the Wonder Blocks Data functionality for resolving
- * pending requests, as well as support for the hydration cache to be
- * embedded into a page so that the result can by hydrated (if that is a
- * requirement).
- *
- * The asynchronous action is never invoked on the client-side.
+ * Other frameworks may provide this too, so we won't be sharing this with
+ * the outside world. It's just a utility for test and internal use whenever
+ * we need to represent the concept of aborted things.
  */
-const useServerEffect = (requestId, handler, hydrate = true) => {
-  // If we're server-side or hydrating, we'll have a cached entry to use.
-  // So we get that and use it to initialize our state.
-  // This works in both hydration and SSR because the very first call to
-  // this will have cached data in those cases as it will be present on the
-  // initial render - and subsequent renders on the client it will be null.
-  const cachedResult = SsrCache.Default.getEntry(requestId); // We only track data requests when we are server-side and we don't
-  // already have a result, as given by the cachedData (which is also the
-  // initial value for the result state).
+class AbortError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AbortError";
+  }
 
-  const maybeTrack = useContext(TrackerContext);
+}
 
-  if (cachedResult == null && Server.isServerSide()) {
-    maybeTrack == null ? void 0 : maybeTrack(requestId, handler, hydrate);
+const loadingStatus = Object.freeze({
+  status: "loading"
+});
+const abortedStatus = Object.freeze({
+  status: "aborted"
+});
+/**
+ * Create Result<TData> instances with specific statuses.
+ */
+
+const Status = Object.freeze({
+  loading: () => loadingStatus,
+  aborted: () => abortedStatus,
+  success: data => ({
+    status: "success",
+    data
+  }),
+  error: error => ({
+    status: "error",
+    error
+  })
+});
+
+/**
+ * Turns a cache entry into a stateful result.
+ */
+const resultFromCachedResponse = cacheEntry => {
+  // No cache entry means no result to be hydrated.
+  if (cacheEntry == null) {
+    return null;
   }
 
-  return cachedResult;
+  const {
+    data,
+    error
+  } = cacheEntry;
+
+  if (error != null) {
+    // Let's hydrate the error. We don't persist everything about the
+    // original error on the server, hence why we only superficially
+    // hydrate it to a GqlHydratedError.
+    return Status.error(new DataError(error, DataErrors.Hydrated));
+  }
+
+  if (data != null) {
+    return Status.success(data);
+  } // We shouldn't get here since we don't actually cache null data.
+
+
+  return Status.aborted();
 };
 
 /**
@@ -533,7 +694,7 @@ const useRequestInterception = (requestId, handler) => {
   // We memoize this so that it only changes if something related to it
   // changes.
 
-  const interceptedHandler = React.useMemo(() => () => {
+  const interceptedHandler = React.useCallback(() => {
     // Call the interceptors from closest to furthest.
     // If one returns a non-null result, then we keep that.
     const interceptResponse = interceptors.reduceRight((prev, interceptor) => {
@@ -553,158 +714,41 @@ const useRequestInterception = (requestId, handler) => {
 };
 
 /**
- * Turns a cache entry into a stateful result.
- */
-const resultFromCachedResponse = cacheEntry => {
-  // No cache entry means we didn't load one yet.
-  if (cacheEntry == null) {
-    return {
-      status: "loading"
-    };
-  }
-
-  const {
-    data,
-    error
-  } = cacheEntry;
-
-  if (error != null) {
-    return {
-      status: "error",
-      error
-    };
-  }
-
-  if (data != null) {
-    return {
-      status: "success",
-      data
-    };
-  }
-
-  return {
-    status: "aborted"
-  };
-};
-
-/**
- * This component is the main component of Wonder Blocks Data. With this, data
- * requirements can be placed in a React application in a manner that will
- * support server-side rendering and efficient caching.
+ * Hook to perform an asynchronous action during server-side rendering.
+ *
+ * This hook registers an asynchronous action to be performed during
+ * server-side rendering. The action is performed only once, and the result
+ * is cached against the given identifier so that subsequent calls return that
+ * cached result allowing components to render more of the component.
+ *
+ * This hook requires the Wonder Blocks Data functionality for resolving
+ * pending requests, as well as support for the hydration cache to be
+ * embedded into a page so that the result can by hydrated (if that is a
+ * requirement).
+ *
+ * The asynchronous action is never invoked on the client-side.
  */
-const Data = ({
-  requestId,
-  handler,
-  children,
-  hydrate,
-  showOldDataWhileLoading,
-  alwaysRequestOnHydration
-}) => {
-  const interceptedHandler = useRequestInterception(requestId, handler);
-  const hydrateResult = useServerEffect(requestId, interceptedHandler, hydrate);
-  const [currentResult, setResult] = React.useState(hydrateResult); // Here we make sure the request still occurs client-side as needed.
-  // This is for legacy usage that expects this. Eventually we will want
-  // to deprecate.
-
-  React.useEffect(() => {
-    // This is here until I can do a better documentation example for
-    // the TrackData docs.
-    // istanbul ignore next
-    if (Server.isServerSide()) {
-      return;
-    } // We don't bother with this if we have hydration data and we're not
-    // forcing a request on hydration.
-    // We don't care if these things change after the first render,
-    // so we don't want them in the inputs array.
-
-
-    if (!alwaysRequestOnHydration && (hydrateResult == null ? void 0 : hydrateResult.data) != null) {
-      return;
-    } // If we're not hydrating a result and we're not going to render
-    // with old data until we're loaded, we want to make sure we set our
-    // result to null so that we're in the loading state.
-
-
-    if (!showOldDataWhileLoading) {
-      // Mark ourselves as loading.
-      setResult(null);
-    } // We aren't server-side, so let's make the request.
-    // We don't need to use our built-in request fulfillment here if we
-    // don't want, but it does mean we'll share inflight requests for the
-    // same ID and the result will be in the same format as the
-    // hydrated value.
+const useServerEffect = (requestId, handler, hydrate = true) => {
+  // Plug in to the request interception framework for code that wants
+  // to use that.
+  const interceptedHandler = useRequestInterception(requestId, handler); // If we're server-side or hydrating, we'll have a cached entry to use.
+  // So we get that and use it to initialize our state.
+  // This works in both hydration and SSR because the very first call to
+  // this will have cached data in those cases as it will be present on the
+  // initial render - and subsequent renders on the client it will be null.
 
+  const cachedResult = SsrCache.Default.getEntry(requestId); // We only track data requests when we are server-side and we don't
+  // already have a result, as given by the cachedData (which is also the
+  // initial value for the result state).
 
-    let cancel = false;
-    RequestFulfillment.Default.fulfill(requestId, {
-      handler: interceptedHandler
-    }).then(result => {
-      if (cancel) {
-        return;
-      }
+  const maybeTrack = useContext(TrackerContext);
 
-      setResult(result);
-      return;
-    }).catch(e => {
-      if (cancel) {
-        return;
-      }
-      /**
-       * We should never get here as errors in fulfillment are part
-       * of the `then`, but if we do.
-       */
-      // eslint-disable-next-line no-console
+  if (cachedResult == null && Server.isServerSide()) {
+    maybeTrack == null ? void 0 : maybeTrack(requestId, interceptedHandler, hydrate);
+  } // A null result means there was no result to hydrate.
 
 
-      console.error(`Unexpected error occurred during data fulfillment: ${e}`);
-      setResult({
-        error: typeof e === "string" ? e : e.message
-      });
-      return;
-    });
-    return () => {
-      cancel = true;
-    }; // If the handler changes, we don't care. The ID is what indicates
-    // the request that should be made and folks shouldn't be changing the
-    // handler without changing the ID as well.
-    // In addition, we don't want to include hydrateResult nor
-    // alwaysRequestOnHydration as them changinng after the first pass
-    // is irrelevant.
-    // Finally, we don't want to include showOldDataWhileLoading as that
-    // changing on its own is also not relevant. It only matters if the
-    // request itself changes. All of which is to say that we only
-    // run this effect for the ID changing.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [requestId]);
-  return children(resultFromCachedResponse(currentResult));
-};
-
-/**
- * This component provides a mechanism to intercept data requests.
- * This is for use in testing.
- *
- * This component is not recommended for use in production code as it
- * can prevent predictable functioning of the Wonder Blocks Data framework.
- * One possible side-effect is that inflight requests from the interceptor could
- * be picked up by `Data` component requests from outside the children of this
- * component.
- *
- * Interceptions within the same component tree are chained such that the
- * interceptor closest to the intercepted request is called first, and the
- * furthest interceptor is called last.
- */
-const InterceptRequests = ({
-  interceptor,
-  children
-}) => {
-  const interceptors = React.useContext(InterceptContext);
-  const updatedInterceptors = React.useMemo( // We could build this in reverse order so that our hook that does
-  // the interception didn't have to use reduceRight, but I think it
-  // is easier to think about if we do this in component tree order.
-  () => [].concat(interceptors, [interceptor]), [interceptors, interceptor]);
-  return /*#__PURE__*/React.createElement(InterceptContext.Provider, {
-    value: updatedInterceptors
-  }, children);
+  return cachedResult == null ? null : resultFromCachedResponse(cachedResult);
 };
 
 /**
@@ -751,16 +795,16 @@ const clearSharedCache = (scope = "") => {
 const useSharedCache = (id, scope, initialValue) => {
   // Verify arguments.
   if (!id || typeof id !== "string") {
-    throw new KindError("id must be a non-empty string", Errors.InvalidInput);
+    throw new DataError("id must be a non-empty string", DataErrors.InvalidInput);
   }
 
   if (!scope || typeof scope !== "string") {
-    throw new KindError("scope must be a non-empty string", Errors.InvalidInput);
+    throw new DataError("scope must be a non-empty string", DataErrors.InvalidInput);
   } // Memoize our APIs.
   // This one allows callers to set or replace the cached value.
 
 
-  const cacheValue = React.useMemo(() => value => value == null ? cache.purge(scope, id) : cache.set(scope, id, value), [id, scope]); // We don't memo-ize the current value, just in case the cache was updated
+  const cacheValue = React.useCallback(value => value == null ? cache.purge(scope, id) : cache.set(scope, id, value), [id, scope]); // We don't memo-ize the current value, just in case the cache was updated
   // since our last run through. Also, our cache does not know what type it
   // stores, so we have to cast it to the type we're exporting. This is a
   // dev time courtesy, rather than a runtime thing.
@@ -771,17 +815,290 @@ const useSharedCache = (id, scope, initialValue) => {
 
   if (currentValue == null && initialValue !== undefined) {
     // Get the initial value.
-    const value = typeof initialValue === "function" ? initialValue() : initialValue; // Update the cache.
+    const value = typeof initialValue === "function" ? initialValue() : initialValue;
 
-    cacheValue(value); // Make sure we return this value as our current value.
+    if (value != null) {
+      // Update the cache.
+      cacheValue(value); // Make sure we return this value as our current value.
 
-    currentValue = value;
+      currentValue = value;
+    }
   } // Now we have everything, let's return it.
 
 
   return [currentValue, cacheValue];
 };
 
+const DefaultScope$1 = "useCachedEffect";
+/**
+ * Hook to execute and cache an async operation on the client.
+ *
+ * This hook executes the given handler on the client if there is no
+ * cached result to use.
+ *
+ * Results are cached so they can be shared between equivalent invocations.
+ * In-flight requests are also shared, so that concurrent calls will
+ * behave as one might exect. Cache updates invoked by one hook instance
+ * do not trigger renders in components that use the same requestID; however,
+ * that should not matter since concurrent requests will share the same
+ * in-flight request, and subsequent renders will grab from the cache.
+ *
+ * Once the request has been tried once and a non-loading response has been
+ * cached, the request will not executed made again.
+ */
+
+const useCachedEffect = (requestId, handler, options = {}) => {
+  const {
+    skip: hardSkip = false,
+    retainResultOnChange = false,
+    onResultChanged,
+    scope = DefaultScope$1
+  } = options; // Plug in to the request interception framework for code that wants
+  // to use that.
+
+  const interceptedHandler = useRequestInterception(requestId, handler); // Instead of using state, which would be local to just this hook instance,
+  // we use a shared in-memory cache.
+
+  const [mostRecentResult, setMostRecentResult] = useSharedCache(requestId, // The key of the cached item
+  scope // The scope of the cached items
+  // No default value. We don't want the loading status there; to ensure
+  // that all calls when the request is in-flight will update once that
+  // request is done, we want the cache to be empty until that point.
+  ); // Build a function that will update the cache and either invoke the
+  // callback provided in options, or force an update.
+
+  const forceUpdate = useForceUpdate();
+  const setCacheAndNotify = React.useCallback(value => {
+    setMostRecentResult(value); // If our caller provided a cacheUpdated callback, we use that.
+    // Otherwise, we toggle our little state update.
+
+    if (onResultChanged != null) {
+      onResultChanged(value);
+    } else {
+      forceUpdate();
+    }
+  }, [setMostRecentResult, onResultChanged, forceUpdate]); // We need to trigger a re-render when the request ID changes as that
+  // indicates its a different request. We don't default the current id as
+  // this is a proxy for the first render, where we will make the request
+  // if we don't already have a cached value.
+
+  const requestIdRef = React.useRef();
+  const previousRequestId = requestIdRef.current; // Calculate our soft skip state.
+  // Soft skip changes are things that should skip the effect if something
+  // else triggers the effect to run, but should not itself trigger the effect
+  // (which would cancel a previous invocation).
+
+  const softSkip = React.useMemo(() => {
+    if (requestId === previousRequestId) {
+      // If the requestId is unchanged, it means we already rendered at
+      // least once and so we already made the request at least once. So
+      // we can bail out right here.
+      return true;
+    } // If we already have a cached value, we're going to skip.
+
+
+    if (mostRecentResult != null) {
+      return true;
+    }
+
+    return false;
+  }, [requestId, previousRequestId, mostRecentResult]); // So now we make sure the client-side request happens per our various
+  // options.
+
+  React.useEffect(() => {
+    let cancel = false; // We don't do anything if we've been told to hard skip (a hard skip
+    // means we should cancel the previous request and is therefore a
+    // dependency on that), or we have determined we have already done
+    // enough and can soft skip (a soft skip doesn't trigger the request
+    // to re-run; we don't want to cancel the in progress effect if we're
+    // soft skipping.
+
+    if (hardSkip || softSkip) {
+      return;
+    } // If we got here, we're going to perform the request.
+    // Let's make sure our ref is set to the most recent requestId.
+
+
+    requestIdRef.current = requestId; // OK, we've done all our checks and things. It's time to make the
+    // request. We use our request fulfillment here so that in-flight
+    // requests are shared.
+    // NOTE: Our request fulfillment handles the error cases here.
+    // Catching shouldn't serve a purpose.
+    // eslint-disable-next-line promise/catch-or-return
+
+    RequestFulfillment.Default.fulfill(requestId, {
+      handler: interceptedHandler
+    }).then(result => {
+      if (cancel) {
+        // We don't modify our result if an earlier effect was
+        // cancelled as it means that this hook no longer cares about
+        // that old request.
+        return;
+      }
+
+      setCacheAndNotify(result);
+      return; // Shut up eslint always-return rule.
+    });
+    return () => {
+      // TODO(somewhatabstract, FEI-4276): Eventually, we will want to be
+      // able abort in-flight requests, but for now, we don't have that.
+      // (Of course, we will only want to abort them if no one is waiting
+      // on them)
+      // For now, we just block cancelled requests from changing our
+      // cache.
+      cancel = true;
+    }; // We only want to run this effect if the requestId, or skip values
+    // change. These are the only two things that should affect the
+    // cancellation of a pending request. We do not update if the handler
+    // changes, in order to simplify the API - otherwise, callers would
+    // not be able to use inline functions with this hook.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hardSkip, requestId]); // We track the last result we returned in order to support the
+  // "retainResultOnChange" option.
+
+  const lastResultAgnosticOfIdRef = React.useRef(Status.loading());
+  const loadingResult = retainResultOnChange ? lastResultAgnosticOfIdRef.current : Status.loading(); // Loading is a transient state, so we only use it here; it's not something
+  // we cache.
+
+  const result = React.useMemo(() => mostRecentResult != null ? mostRecentResult : loadingResult, [mostRecentResult, loadingResult]);
+  lastResultAgnosticOfIdRef.current = result;
+  return result;
+};
+
+/**
+ * Policies to define how a hydratable effect should behave client-side.
+ */
+const WhenClientSide = require("flow-enums-runtime").Mirrored(["DoNotHydrate", "ExecuteWhenNoResult", "ExecuteWhenNoSuccessResult", "AlwaysExecute"]);
+const DefaultScope = "useHydratableEffect";
+/**
+ * Hook to execute an async operation on server and client.
+ *
+ * This hook executes the given handler on the server and on the client,
+ * and, depending on the given options, can hydrate the server-side result.
+ *
+ * Results are cached on the client so they can be shared between equivalent
+ * invocations. Cache changes from one hook instance do not trigger renders
+ * in components that use the same requestID.
+ */
+
+const useHydratableEffect = (requestId, handler, options = {}) => {
+  const {
+    clientBehavior = WhenClientSide.ExecuteWhenNoSuccessResult,
+    skip = false,
+    retainResultOnChange = false,
+    onResultChanged,
+    scope = DefaultScope
+  } = options; // Now we instruct the server to perform the operation.
+  // When client-side, this will look up any response for hydration; it does
+  // not invoke the handler.
+
+  const serverResult = useServerEffect(requestId, // If we're skipped (unlikely in server worlds, but maybe),
+  // just give an aborted response.
+  skip ? () => Promise.reject(new AbortError("skipped")) : handler, // Only hydrate if our behavior isn't telling us not to.
+  clientBehavior !== WhenClientSide.DoNotHydrate);
+  const getDefaultCacheValue = React.useCallback(() => {
+    // If we don't have a requestId, it's our first render, the one
+    // where we hydrated. So defer to our clientBehavior value.
+    switch (clientBehavior) {
+      case WhenClientSide.DoNotHydrate:
+      case WhenClientSide.AlwaysExecute:
+        // Either we weren't hydrating at all, or we don't care
+        // if we hydrated something or not, either way, we're
+        // doing a request.
+        return null;
+
+      case WhenClientSide.ExecuteWhenNoResult:
+        // We only execute if we didn't hydrate something.
+        // So, returning the hydration result as default for our
+        // cache, will then prevent the cached effect running.
+        return serverResult;
+
+      case WhenClientSide.ExecuteWhenNoSuccessResult:
+        // We only execute if we didn't hydrate a success result.
+        if ((serverResult == null ? void 0 : serverResult.status) === "success") {
+          // So, returning the hydration result as default for our
+          // cache, will then prevent the cached effect running.
+          return serverResult;
+        }
+
+        return null;
+    } // There is no reason for this to change after the first render,
+    // you might think, but the function closes around serverResult and if
+    // the requestId changes, it still returns the hydrate result of the
+    // first render of the previous requestId. This then means that the
+    // hydrate result is still the same, and the effect is not re-executed
+    // because the cache gets incorrectly defaulted.
+    // However, we don't want to bother doing anything with this on
+    // client behavior changing since that truly is irrelevant.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+
+  }, [serverResult]); // Instead of using state, which would be local to just this hook instance,
+  // we use a shared in-memory cache.
+
+  useSharedCache(requestId, // The key of the cached item
+  scope, // The scope of the cached items
+  getDefaultCacheValue); // When we're client-side, we ultimately want the result from this call.
+
+  const clientResult = useCachedEffect(requestId, handler, {
+    skip,
+    onResultChanged,
+    retainResultOnChange,
+    scope
+  }); // OK, now which result do we return.
+  // Well, we return the serverResult on our very first call and then
+  // the clientResult thereafter. The great thing is that after the very
+  // first call, the serverResult is going to be `null` anyway.
+
+  return serverResult != null ? serverResult : clientResult;
+};
+
+/**
+ * This component is the main component of Wonder Blocks Data. With this, data
+ * requirements can be placed in a React application in a manner that will
+ * support server-side rendering and efficient caching.
+ */
+const Data = ({
+  requestId,
+  handler,
+  children,
+  retainResultOnChange: _retainResultOnChange = false,
+  clientBehavior: _clientBehavior = WhenClientSide.ExecuteWhenNoSuccessResult
+}) => {
+  const result = useHydratableEffect(requestId, handler, {
+    retainResultOnChange: _retainResultOnChange,
+    clientBehavior: _clientBehavior
+  });
+  return children(result);
+};
+
+/**
+ * This component provides a mechanism to intercept data requests.
+ * This is for use in testing.
+ *
+ * This component is not recommended for use in production code as it
+ * can prevent predictable functioning of the Wonder Blocks Data framework.
+ * One possible side-effect is that inflight requests from the interceptor could
+ * be picked up by `Data` component requests from outside the children of this
+ * component.
+ *
+ * Interceptions within the same component tree are chained such that the
+ * interceptor closest to the intercepted request is called first, and the
+ * furthest interceptor is called last.
+ */
+const InterceptRequests = ({
+  interceptor,
+  children
+}) => {
+  const interceptors = React.useContext(InterceptContext);
+  const updatedInterceptors = React.useMemo( // We could build this in reverse order so that our hook that does
+  // the interception didn't have to use reduceRight, but I think it
+  // is easier to think about if we do this in component tree order.
+  () => [].concat(interceptors, [interceptor]), [interceptors, interceptor]);
+  return /*#__PURE__*/React.createElement(InterceptContext.Provider, {
+    value: updatedInterceptors
+  }, children);
+};
+
 const GqlRouterContext = /*#__PURE__*/React.createContext(null);
 
 /**
@@ -816,17 +1133,57 @@ const GqlRouter = ({
   }, children);
 };
 
+/**
+ * Construct a complete GqlContext from current defaults and a partial context.
+ *
+ * Values in the partial context that are `undefined` will be ignored.
+ * Values in the partial context that are `null` will be deleted.
+ */
+const mergeGqlContext = (defaultContext, overrides) => {
+  // Let's merge the partial context default context. We deliberately
+  // don't spread because spreading would overwrite default context
+  // values with undefined or null if the partial context includes a value
+  // explicitly set to undefined or null.
+  return Object.keys(overrides).reduce((acc, key) => {
+    // Undefined values are ignored.
+    if (overrides[key] !== undefined) {
+      if (overrides[key] === null) {
+        // Null indicates we delete this context value.
+        delete acc[key];
+      } else {
+        // Otherwise, we set it.
+        acc[key] = overrides[key];
+      }
+    }
+
+    return acc;
+  }, _extends({}, defaultContext));
+};
+
 /**
  * Error kinds for GqlError.
  */
-const GqlErrors = Object.freeze(_extends({}, Errors, {
-  Network: "Network",
-  Parse: "Parse",
+const GqlErrors = Object.freeze({
+  /**
+   * An internal framework error.
+   */
+  Internal: "Internal",
+
+  /**
+   * Response does not have the correct structure for a GraphQL response.
+   */
   BadResponse: "BadResponse",
+
+  /**
+   * A valid GraphQL result with errors field in the payload.
+   */
   ErrorResult: "ErrorResult"
-}));
+});
 /**
  * An error from the GQL API.
+ *
+ * Errors of this type will have names of the format:
+ *     `${kind}GqlError`
  */
 
 class GqlError extends KindError {
@@ -837,12 +1194,48 @@ class GqlError extends KindError {
     super(message, kind, {
       metadata,
       cause,
-      prefix: "Gql"
+      name: "Gql"
     });
   }
 
 }
 
+/**
+ * Construct a GqlRouterContext from the current one and partial context.
+ */
+const useGqlRouterContext = (contextOverrides = {}) => {
+  // 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;
+  const contextRef = useRef(defaultContext);
+  const mergedContext = mergeGqlContext(defaultContext, contextOverrides); // Now, we can see if this represents a new context and if so,
+  // update our ref and return the merged value.
+
+  const refKeys = Object.keys(contextRef.current);
+  const mergedKeys = Object.keys(mergedContext);
+  const shouldWeUpdateRef = refKeys.length !== mergedKeys.length || mergedKeys.every(key => contextRef.current[key] !== mergedContext[key]);
+
+  if (shouldWeUpdateRef) {
+    contextRef.current = mergedContext;
+  } // OK, now we're up-to-date, let's memoize our final result.
+
+
+  const finalContext = contextRef.current;
+  const finalRouterContext = useMemo(() => ({
+    fetch,
+    defaultContext: finalContext
+  }), [fetch, finalContext]);
+  return finalRouterContext;
+};
+
 /**
  * Validate a GQL operation response and extract the data.
  */
@@ -856,7 +1249,7 @@ const getGqlDataFromResponse = async response => {
   try {
     result = JSON.parse(bodyText);
   } catch (e) {
-    throw new GqlError("Failed to parse response", GqlErrors.Parse, {
+    throw new DataError("Failed to parse response", DataErrors.Parse, {
       metadata: {
         statusCode: response.status,
         bodyText
@@ -867,7 +1260,7 @@ const getGqlDataFromResponse = async response => {
 
 
   if (response.status >= 300) {
-    throw new GqlError("Response unsuccessful", GqlErrors.Network, {
+    throw new DataError("Response unsuccessful", DataErrors.Network, {
       metadata: {
         statusCode: response.status,
         result
@@ -913,59 +1306,48 @@ const getGqlDataFromResponse = async response => {
  * Values in the partial context given to the returned fetch function will
  * only be included if they have a value other than undefined.
  */
-const useGql = () => {
+const useGql = (context = {}) => {
   // 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.
+  const gqlRouterContext = useGqlRouterContext(context); // 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(() => (operation, options = Object.freeze({})) => {
+  const gqlFetch = useCallback((operation, options = Object.freeze({})) => {
+    const {
+      fetch,
+      defaultContext
+    } = gqlRouterContext;
     const {
       variables,
       context = {}
-    } = options; // Let's merge the partial context of the fetch with the
-    // default context. We deliberately don't spread because
-    // spreading would overwrite default context values with
-    // undefined if the partial context includes a value explicitly
-    // set to undefined. Instead, we use a map/reduce of keys.
-
-    const mergedContext = Object.keys(context).reduce((acc, key) => {
-      if (context[key] !== undefined) {
-        acc[key] = context[key];
-      }
-
-      return acc;
-    }, _extends({}, defaultContext)); // Invoke the fetch and extract the data.
-
-    return fetch(operation, variables, mergedContext).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.
-
+    } = options;
+    const finalContext = mergeGqlContext(defaultContext, context); // Invoke the fetch and extract the data.
 
-      throw error;
-    });
-  }, [fetch, defaultContext]);
+    return fetch(operation, variables, finalContext).then(getGqlDataFromResponse);
+  }, [gqlRouterContext]);
   return gqlFetch;
 };
 
+/**
+ * Initialize the hydration cache.
+ *
+ * @param {ResponseCache} source The cache content to use for initializing the
+ * cache.
+ * @throws {Error} If the cache is already initialized.
+ */
 const initializeCache = source => SsrCache.Default.initialize(source);
+/**
+ * Fulfill 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 fulfilled.
+ */
+
 const fulfillAllDataRequests = () => {
   if (!Server.isServerSide()) {
     return Promise.reject(new Error("Data requests are not tracked when client-side"));
@@ -973,6 +1355,16 @@ const fulfillAllDataRequests = () => {
 
   return RequestTracker.Default.fulfillTrackedRequests();
 };
+/**
+ * Indicate if there are unfulfilled tracked requests.
+ *
+ * This is used in conjunction with `TrackData`.
+ *
+ * @throws {Error} If executed outside of server-side rendering.
+ * @returns {boolean} `true` if there are unfulfilled tracked requests;
+ * otherwise, `false`.
+ */
+
 const hasUnfulfilledRequests = () => {
   if (!Server.isServerSide()) {
     throw new Error("Data requests are not tracked when client-side");
@@ -980,7 +1372,21 @@ const hasUnfulfilledRequests = () => {
 
   return RequestTracker.Default.hasUnfulfilledRequests;
 };
+/**
+ * Remove the request identified from the cached hydration responses.
+ *
+ * @param {string} id The request ID of the response to remove from the cache.
+ */
+
 const removeFromCache = id => SsrCache.Default.remove(id);
+/**
+ * Remove all 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 removed.
+ */
+
 const removeAllFromCache = predicate => SsrCache.Default.removeAll(predicate);
 
-export { Data, GqlError, GqlErrors, GqlRouter, InterceptRequests, ScopedInMemoryCache, TrackData, clearSharedCache, fulfillAllDataRequests, hasUnfulfilledRequests, initializeCache, removeAllFromCache, removeFromCache, useGql, useRequestInterception, useServerEffect, useSharedCache };
+export { Data, DataError, DataErrors, GqlError, GqlErrors, GqlRouter, InterceptRequests, RequestFulfillment, ScopedInMemoryCache, SerializableInMemoryCache, Status, TrackData, WhenClientSide, clearSharedCache, fulfillAllDataRequests, hasUnfulfilledRequests, initializeCache, removeAllFromCache, removeFromCache, useCachedEffect, useGql, useHydratableEffect, useServerEffect, useSharedCache };