@khanacademy/wonder-blocks-data 3.0.0 → 3.1.2

package/CHANGELOG.md

@@ -1,7 +1,33 @@
 # @khanacademy/wonder-blocks-data
 
+## 3.1.2
+
+### Patch Changes
+
+-   @khanacademy/wonder-blocks-core@4.2.1
+
+## 3.1.1
+
+### Patch Changes
+
+-   4ff59815: Add GraphQL fetch mock support to wonder-blocks-testing
+
+## 3.1.0
+
+### Minor Changes
+
+-   b68cedfe: Add GqlRouter component
+-   c7233a97: Implement useGql hook
+
+## 3.0.1
+
+### Patch Changes
+
+-   d281dac8: Ensure server-side request fulfillments can be intercepted
+
 ## 3.0.0
+
 ### Major Changes
 
-- b252d9c8: Remove client-side caching
-- b252d9c8: Introduce useData hook
+-   b252d9c8: Remove client-side caching
+-   b252d9c8: Introduce useData hook

package/dist/es/index.js

@@ -1,7 +1,8 @@
 import { Server } from '@khanacademy/wonder-blocks-core';
 import * as React from 'react';
-import { useState, useContext, useRef, useEffect } from 'react';
+import { useState, useContext, useRef, useEffect, useMemo } from 'react';
 import _extends from '@babel/runtime/helpers/extends';
+import { Errors, KindError } from '@khanacademy/wonder-stuff-core';
 
 function deepClone(source) {
   /**
@@ -582,25 +583,49 @@ const useData = (handler, options) => {
   // 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 = ResponseCache.Default.getEntry(handler, options);
-  const [result, setResult] = useState(cachedResult); // We only track data requests when we are server-side and we don't
+  const [result, setResult] = useState(cachedResult); // Lookup to see if there's an interceptor for the handler.
+  // If we have one, we need to replace the handler with one that
+  // uses the interceptor.
+
+  const interceptorMap = useContext(InterceptContext);
+  const interceptor = interceptorMap[handler.type]; // If we have an interceptor, we need to replace the handler with one that
+  // uses the interceptor. This helper function generates a new handler.
+  // We need this before we track the request as we want the interceptor
+  // to also work for tracked requests to simplify testing the server-side
+  // request fulfillment.
+
+  const getMaybeInterceptedHandler = () => {
+    if (interceptor == null) {
+      return handler;
+    }
+
+    const fulfillRequestFn = options => {
+      var _interceptor$fulfillR;
+
+      return (_interceptor$fulfillR = interceptor.fulfillRequest(options)) != null ? _interceptor$fulfillR : handler.fulfillRequest(options);
+    };
+
+    return {
+      fulfillRequest: fulfillRequestFn,
+      getKey: options => handler.getKey(options),
+      type: handler.type,
+      hydrate: handler.hydrate
+    };
+  }; // 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).
 
+
   const maybeTrack = useContext(TrackerContext);
 
   if (result == null && Server.isServerSide()) {
-    maybeTrack == null ? void 0 : maybeTrack(handler, options);
-  } // Lookup to see if there's an interceptor for the handler.
-  // If we have one, we need to replace the handler with one that
-  // uses the interceptor.
-
-
-  const interceptorMap = useContext(InterceptContext);
-  const interceptor = interceptorMap[handler.type]; // We need to update our request when the handler changes or the key
+    maybeTrack == null ? void 0 : maybeTrack(getMaybeInterceptedHandler(), options);
+  } // We need to update our request when the handler changes or the key
   // to the options change, so we keep track of those.
   // However, even if we are hydrating from cache, we still need to make the
   // request at least once, so we do not initialize these references.
 
+
   const handlerRef = useRef();
   const keyRef = useRef();
   const interceptorRef = useRef(); // This effect will ensure that we fulfill the request as desired.
@@ -625,26 +650,7 @@ const useData = (handler, options) => {
     if (cachedResult == null) {
       // Mark ourselves as loading.
       setResult(null);
-    }
-
-    const getMaybeInterceptedHandler = () => {
-      if (interceptor == null) {
-        return handler;
-      }
-
-      const fulfillRequestFn = options => {
-        var _interceptor$fulfillR;
-
-        return (_interceptor$fulfillR = interceptor.fulfillRequest(options)) != null ? _interceptor$fulfillR : handler.fulfillRequest(options);
-      };
-
-      return {
-        fulfillRequest: fulfillRequestFn,
-        getKey: options => handler.getKey(options),
-        type: handler.type,
-        hydrate: handler.hydrate
-      };
-    }; // We aren't server-side, so let's make the request.
+    } // We aren't server-side, so let's make the request.
     // The request handler is in control of whether that request actually
     // happens or not.
 
@@ -733,6 +739,173 @@ class InterceptData extends React.Component {
 
 }
 
+const GqlRouterContext = /*#__PURE__*/React.createContext(null);
+
+/**
+ * Configure GraphQL routing for GraphQL hooks and components.
+ *
+ * These can be nested. Components and hooks relying on the GraphQL routing
+ * will use the configuration from their closest ancestral GqlRouter.
+ */
+const GqlRouter = ({
+  defaultContext: thisDefaultContext,
+  fetch: thisFetch,
+  children
+}) => {
+  // We don't care if we're nested. We always force our callers to define
+  // everything. It makes for a clearer API and requires less error checking
+  // code (assuming our flow types are correct). We also don't default fetch
+  // to anything - our callers can tell us what function to use quite easily.
+  // If code that consumes this wants more nuanced nesting, it can implement
+  // it within its own GqlRouter than then defers to this one.
+  // We want to always use the same object if things haven't changed to avoid
+  // over-rendering consumers of our context, let's memoize the configuration.
+  // By doing this, if a component under children that uses this context
+  // uses React.memo, we won't force it to re-render every time we render
+  // because we'll only change the context value if something has actually
+  // changed.
+  const configuration = React.useMemo(() => ({
+    fetch: thisFetch,
+    defaultContext: thisDefaultContext
+  }), [thisDefaultContext, thisFetch]);
+  return /*#__PURE__*/React.createElement(GqlRouterContext.Provider, {
+    value: configuration
+  }, children);
+};
+
+/**
+ * Error kinds for GqlError.
+ */
+const GqlErrors = Object.freeze(_extends({}, Errors, {
+  Network: "Network",
+  Parse: "Parse",
+  BadResponse: "BadResponse",
+  ErrorResult: "ErrorResult"
+}));
+/**
+ * An error from the GQL API.
+ */
+
+class GqlError extends KindError {
+  constructor(message, kind, {
+    metadata,
+    cause
+  } = {}) {
+    super(message, kind, {
+      metadata,
+      cause,
+      prefix: "Gql"
+    });
+  }
+
+}
+
+/**
+ * Validate a GQL operation response and extract the data.
+ */
+
+const getGqlDataFromResponse = async response => {
+  // 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;
+};
+
+/**
+ * Hook to obtain a gqlFetch function for performing GraphQL requests.
+ *
+ * The fetch function will resolve null if the request was aborted, otherwise
+ * it will resolve the data returned by the GraphQL server.
+ */
+const useGql = () => {
+  // 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.
+  // 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 {
+      variables,
+      context
+    } = options; // Invoke the fetch and extract the data.
+
+    return fetch(operation, variables, _extends({}, defaultContext, context)).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.
+
+
+      throw error;
+    });
+  }, [fetch, defaultContext]);
+  return gqlFetch;
+};
+
 const initializeCache = source => ResponseCache.Default.initialize(source);
 const fulfillAllDataRequests = () => {
   if (!Server.isServerSide()) {
@@ -751,4 +924,4 @@ const hasUnfulfilledRequests = () => {
 const removeFromCache = (handler, options) => ResponseCache.Default.remove(handler, options);
 const removeAllFromCache = (handler, predicate) => ResponseCache.Default.removeAll(handler, predicate);
 
-export { Data, InterceptData, RequestHandler, TrackData, fulfillAllDataRequests, hasUnfulfilledRequests, initializeCache, removeAllFromCache, removeFromCache, useData };
+export { Data, GqlError, GqlErrors, GqlRouter, InterceptData, RequestHandler, TrackData, fulfillAllDataRequests, hasUnfulfilledRequests, initializeCache, removeAllFromCache, removeFromCache, useData, useGql };