react-relay 18.2.0 → 20.0.0

package/relay-hooks/loadEntryPoint.js.flow

@@ -62,6 +62,12 @@ function loadEntryPoint<
       const {environmentProviderOptions, options, parameters, variables} =
         query;
 
+      // $FlowFixMe[prop-missing] Exists for types that wrap EntryPoint
+      if (options?.includeIf === false) {
+        // don't preload this query since the includeIf is false
+        return;
+      }
+
       const environment = environmentProvider.getEnvironment(
         environmentProviderOptions,
       );

package/relay-hooks/loadQuery.js.flow

@@ -28,6 +28,7 @@ import type {
   RequestIdentifier,
   RequestParameters,
 } from 'relay-runtime';
+import type {OperationAvailability} from 'relay-runtime/store/RelayStoreTypes';
 
 const invariant = require('invariant');
 const {
@@ -42,7 +43,7 @@ const {
 
 let fetchKey = 100001;
 
-type QueryType<T> =
+export type QueryType<T> =
   T extends Query<infer V, infer D, infer RR>
     ? {
         variables: V,
@@ -125,11 +126,12 @@ function loadQuery<
   let networkError = null;
   // makeNetworkRequest will immediately start a raw network request if
   // one isn't already in flight and return an Observable that when
-  // subscribed to will replay the network events that have occured so far,
+  // subscribed to will replay the network events that have occurred so far,
   // as well as subsequent events.
   let didMakeNetworkRequest = false;
   const makeNetworkRequest = (
     params: RequestParameters,
+    checkOperation?: () => OperationAvailability,
   ): Observable<GraphQLResponse> => {
     // N.B. this function is called synchronously or not at all
     // didMakeNetworkRequest is safe to rely on in the returned value
@@ -160,7 +162,16 @@ function loadQuery<
       'raw-network-request-' + getRequestIdentifier(params, variables);
     const observable = fetchQueryDeduped(environment, identifier, () => {
       const network = environment.getNetwork();
-      return network.execute(params, variables, networkCacheConfig);
+      return network.execute(
+        params,
+        variables,
+        networkCacheConfig,
+        undefined,
+        undefined,
+        undefined,
+        undefined,
+        checkOperation,
+      );
     });
 
     const {unsubscribe} = observable.subscribe({
@@ -247,13 +258,18 @@ function loadQuery<
     // then we do nothing.
     const shouldFetch =
       fetchPolicy !== 'store-or-network' ||
+      // environment.check can trigger store updates through missing field handlers,
+      // short circuiting the check avoids unnecessary updates
       environment.check(operation).status !== 'available';
 
     if (shouldFetch) {
       executeDeduped(operation, () => {
         // N.B. Since we have the operation synchronously available here,
         // we can immediately fetch and execute the operation.
-        const networkObservable = makeNetworkRequest(concreteRequest.params);
+        const networkObservable = makeNetworkRequest(
+          concreteRequest.params,
+          () => environment.check(operation),
+        );
         const executeObservable = executeWithNetworkSource(
           operation,
           networkObservable,

package/relay-hooks/preloadQuery_DEPRECATED.js.flow

@@ -24,6 +24,7 @@ import type {
   GraphQLResponse,
   GraphQLTaggedNode,
   IEnvironment,
+  OperationAvailability,
   OperationType,
   Subscription,
 } from 'relay-runtime';
@@ -167,12 +168,17 @@ function preloadQueryDeduped<TQuery: OperationType>(
   }`;
   const prevQueryEntry = pendingQueries.get(cacheKey);
 
-  const availability =
-    fetchPolicy === STORE_OR_NETWORK_DEFAULT && query != null && query != null
+  function checkOperation(): OperationAvailability {
+    return query != null
       ? environment.check(
           createOperationDescriptor(query, variables, networkCacheConfig),
         )
       : {status: 'missing'};
+  }
+  const availability =
+    fetchPolicy === STORE_OR_NETWORK_DEFAULT
+      ? checkOperation()
+      : {status: 'missing'};
 
   let nextQueryEntry: ?PendingQueryEntry;
   if (availability.status === 'available' && query != null) {
@@ -203,7 +209,16 @@ function preloadQueryDeduped<TQuery: OperationType>(
     }
   } else if (prevQueryEntry == null || prevQueryEntry.kind !== 'network') {
     // Should fetch but we're not already fetching: fetch!
-    const source = network.execute(params, variables, networkCacheConfig, null);
+    const source = network.execute(
+      params,
+      variables,
+      networkCacheConfig,
+      null,
+      undefined,
+      undefined,
+      undefined,
+      checkOperation,
+    );
     const subject = new ReplaySubject<GraphQLResponse>();
     nextQueryEntry = {
       cacheKey,

package/relay-hooks/readFragmentInternal.js.flow

@@ -83,13 +83,10 @@ function handlePotentialSnapshotErrorsForState(
   state: FragmentState,
 ): void {
   if (state.kind === 'singular') {
-    handlePotentialSnapshotErrors(
-      environment,
-      state.snapshot.errorResponseFields,
-    );
+    handlePotentialSnapshotErrors(environment, state.snapshot.fieldErrors);
   } else if (state.kind === 'plural') {
     for (const snapshot of state.snapshots) {
-      handlePotentialSnapshotErrors(environment, snapshot.errorResponseFields);
+      handlePotentialSnapshotErrors(environment, snapshot.fieldErrors);
     }
   }
 }
@@ -216,7 +213,10 @@ function readFragmentInternal(
   // Handle the queries for any missing client edges; this may suspend.
   // FIXME handle client edges in parallel.
   let clientEdgeQueries = null;
-  if (fragmentNode.metadata?.hasClientEdges === true) {
+  if (
+    fragmentNode.metadata?.hasClientEdges === true ||
+    RelayFeatureFlags.CHECK_ALL_FRAGMENTS_FOR_MISSING_CLIENT_EDGES
+  ) {
     const missingClientEdges = getMissingClientEdges(state);
     if (missingClientEdges?.length) {
       clientEdgeQueries = ([]: Array<QueryResult>);

package/relay-hooks/useEntryPointLoader.js.flow

@@ -48,7 +48,9 @@ type UseEntryPointLoaderHookReturnType<
 type NullEntryPointReference = {
   kind: 'NullEntryPointReference',
 };
-const initialNullEntryPointReferenceState = {kind: 'NullEntryPointReference'};
+const initialNullEntryPointReferenceState: NullEntryPointReference = {
+  kind: 'NullEntryPointReference',
+};
 
 hook useLoadEntryPoint<
   TEntryPointParams: {...},
@@ -122,7 +124,7 @@ hook useLoadEntryPoint<
 
   const disposeEntryPoint = useCallback(() => {
     if (isMountedRef.current) {
-      const nullEntryPointReference = {
+      const nullEntryPointReference: NullEntryPointReference = {
         kind: 'NullEntryPointReference',
       };
       undisposedEntryPointReferencesRef.current.add(nullEntryPointReference);
@@ -156,7 +158,7 @@ hook useLoadEntryPoint<
   useEffect(() => {
     return () => {
       // Attempt to detect if the component was
-      // hidden (by Offscreen API), or fast refresh occured;
+      // hidden (by Offscreen API), or fast refresh occurred;
       // Only in these situations would the effect cleanup
       // for "unmounting" run multiple times, so if
       // we are ever able to read this ref with a value

package/relay-hooks/useFragment.js.flow

@@ -54,6 +54,7 @@ hook useFragment(fragment: GraphQLTaggedNode, key: mixed): mixed {
   if (__DEV__) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     useDebugValue({fragment: fragmentNode.name, data});
   }
   return data;

package/relay-hooks/useFragmentInternal.js.flow

@@ -26,6 +26,7 @@ hook useFragmentInternal(
 ): ?SelectorData | Array<?SelectorData> {
   if (RelayFeatureFlags.ENABLE_ACTIVITY_COMPATIBILITY) {
     // $FlowFixMe[react-rule-hook] - the condition is static
+    // $FlowFixMe[react-rule-hook-conditional]
     return useFragmentInternal_EXPERIMENTAL(
       fragmentNode,
       fragmentRef,
@@ -34,6 +35,7 @@ hook useFragmentInternal(
     );
   }
   // $FlowFixMe[react-rule-hook] - the condition is static
+  // $FlowFixMe[react-rule-hook-conditional]
   return useFragmentInternal_CURRENT(
     fragmentNode,
     fragmentRef,

package/relay-hooks/useFragmentInternal_CURRENT.js.flow

@@ -26,6 +26,7 @@ import type {MissingClientEdgeRequestInfo} from 'relay-runtime/store/RelayStoreT
 
 const {getQueryResourceForEnvironment} = require('./QueryResource');
 const useRelayEnvironment = require('./useRelayEnvironment');
+const useRelayLoggingContext = require('./useRelayLoggingContext');
 const invariant = require('invariant');
 const {useDebugValue, useEffect, useMemo, useRef, useState} = require('react');
 const {
@@ -109,15 +110,21 @@ function getSuspendingLiveResolver(
 function handlePotentialSnapshotErrorsForState(
   environment: IEnvironment,
   state: FragmentState,
+  loggingContext: mixed | void,
 ): void {
   if (state.kind === 'singular') {
     handlePotentialSnapshotErrors(
       environment,
-      state.snapshot.errorResponseFields,
+      state.snapshot.fieldErrors,
+      loggingContext,
     );
   } else if (state.kind === 'plural') {
     for (const snapshot of state.snapshots) {
-      handlePotentialSnapshotErrors(environment, snapshot.errorResponseFields);
+      handlePotentialSnapshotErrors(
+        environment,
+        snapshot.fieldErrors,
+        loggingContext,
+      );
     }
   }
 }
@@ -153,7 +160,7 @@ function handleMissedUpdates(
       missingLiveResolverFields: currentSnapshot.missingLiveResolverFields,
       seenRecords: currentSnapshot.seenRecords,
       selector: currentSnapshot.selector,
-      errorResponseFields: currentSnapshot.errorResponseFields,
+      fieldErrors: currentSnapshot.fieldErrors,
     };
     return [
       updatedData !== state.snapshot.data,
@@ -177,7 +184,7 @@ function handleMissedUpdates(
         missingLiveResolverFields: currentSnapshot.missingLiveResolverFields,
         seenRecords: currentSnapshot.seenRecords,
         selector: currentSnapshot.selector,
-        errorResponseFields: currentSnapshot.errorResponseFields,
+        fieldErrors: currentSnapshot.fieldErrors,
       };
       if (updatedData !== snapshot.data) {
         didMissUpdates = true;
@@ -403,6 +410,12 @@ hook useFragmentInternal(
   );
 
   const environment = useRelayEnvironment();
+  let loggerContext;
+  if (RelayFeatureFlags.ENABLE_UI_CONTEXT_ON_RELAY_LOGGER) {
+    // $FlowFixMe[react-rule-hook] - the condition is static
+    // $FlowFixMe[react-rule-hook-conditional]
+    loggerContext = useRelayLoggingContext();
+  }
   const [_state, setState] = useState<FragmentState>(() =>
     getFragmentState(environment, fragmentSelector),
   );
@@ -448,12 +461,16 @@ hook useFragmentInternal(
 
   // Handle the queries for any missing client edges; this may suspend.
   // FIXME handle client edges in parallel.
-  if (fragmentNode.metadata?.hasClientEdges === true) {
+  if (
+    fragmentNode.metadata?.hasClientEdges === true ||
+    RelayFeatureFlags.CHECK_ALL_FRAGMENTS_FOR_MISSING_CLIENT_EDGES
+  ) {
     // The fragment is validated to be static (in useFragment) and hasClientEdges is
     // a static (constant) property of the fragment. In practice, this effect will
     // always or never run for a given invocation of this hook.
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     const [clientEdgeQueries, activeRequestPromises] = useMemo(() => {
       const missingClientEdges = getMissingClientEdges(state);
       // eslint-disable-next-line no-shadow
@@ -485,6 +502,7 @@ hook useFragmentInternal(
     // See above note
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     useEffect(() => {
       const QueryResource = getQueryResourceForEnvironment(environment);
       if (clientEdgeQueries?.length) {
@@ -541,7 +559,7 @@ hook useFragmentInternal(
 
   // Report required fields only if we're not suspending, since that means
   // they're missing even though we are out of options for possibly fetching them:
-  handlePotentialSnapshotErrorsForState(environment, state);
+  handlePotentialSnapshotErrorsForState(environment, state, loggerContext);
 
   const hasPendingStateChanges = useRef<boolean>(false);
 
@@ -594,6 +612,7 @@ hook useFragmentInternal(
     const fragmentRefIsNullish = fragmentRef == null; // for less sensitive memoization
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     data = useMemo(() => {
       if (state.kind === 'bailout') {
         // Bailout state can happen if the fragmentRef is a plural array that is empty or has no
@@ -645,6 +664,7 @@ hook useFragmentInternal(
   if (__DEV__) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     useDebugValue({fragment: fragmentNode.name, data});
   }
 

package/relay-hooks/useFragmentInternal_EXPERIMENTAL.js.flow

@@ -26,6 +26,7 @@ import type {MissingClientEdgeRequestInfo} from 'relay-runtime/store/RelayStoreT
 
 const {getQueryResourceForEnvironment} = require('./QueryResource');
 const useRelayEnvironment = require('./useRelayEnvironment');
+const useRelayLoggingContext = require('./useRelayLoggingContext');
 const invariant = require('invariant');
 const {useDebugValue, useEffect, useMemo, useRef, useState} = require('react');
 const {
@@ -121,15 +122,21 @@ function getSuspendingLiveResolver(
 function handlePotentialSnapshotErrorsForState(
   environment: IEnvironment,
   state: FragmentState,
+  loggingContext: mixed | void,
 ): void {
   if (state.kind === 'singular') {
     handlePotentialSnapshotErrors(
       environment,
-      state.snapshot.errorResponseFields,
+      state.snapshot.fieldErrors,
+      loggingContext,
     );
   } else if (state.kind === 'plural') {
     for (const snapshot of state.snapshots) {
-      handlePotentialSnapshotErrors(environment, snapshot.errorResponseFields);
+      handlePotentialSnapshotErrors(
+        environment,
+        snapshot.fieldErrors,
+        loggingContext,
+      );
     }
   }
 }
@@ -165,7 +172,7 @@ function handleMissedUpdates(
       missingLiveResolverFields: currentSnapshot.missingLiveResolverFields,
       seenRecords: currentSnapshot.seenRecords,
       selector: currentSnapshot.selector,
-      errorResponseFields: currentSnapshot.errorResponseFields,
+      fieldErrors: currentSnapshot.fieldErrors,
     };
     return [
       updatedData !== state.snapshot.data,
@@ -191,7 +198,7 @@ function handleMissedUpdates(
         missingLiveResolverFields: currentSnapshot.missingLiveResolverFields,
         seenRecords: currentSnapshot.seenRecords,
         selector: currentSnapshot.selector,
-        errorResponseFields: currentSnapshot.errorResponseFields,
+        fieldErrors: currentSnapshot.fieldErrors,
       };
       if (updatedData !== snapshot.data) {
         didMissUpdates = true;
@@ -215,13 +222,15 @@ function handleMissedUpdates(
   }
 }
 
+type PromiseWithDisplayName = Promise<mixed> & {displayName?: string};
+
 function handleMissingClientEdge(
   environment: IEnvironment,
   parentFragmentNode: ReaderFragment,
   parentFragmentRef: mixed,
   missingClientEdgeRequestInfo: MissingClientEdgeRequestInfo,
   queryOptions?: FragmentQueryOptions,
-): [QueryResult, ?Promise<mixed>] {
+): [QueryResult, ?PromiseWithDisplayName] {
   const originalVariables = getVariablesFromFragment(
     parentFragmentNode,
     parentFragmentRef,
@@ -246,10 +255,17 @@ function handleMissingClientEdge(
     queryOptions?.fetchPolicy,
   );
 
-  return [
-    queryResult,
-    getPromiseForActiveRequest(environment, queryOperationDescriptor.request),
-  ];
+  const promise = getPromiseForActiveRequest(
+    environment,
+    queryOperationDescriptor.request,
+  );
+  // $FlowExpectedError[prop-missing]
+  if (promise != null && promise.displayName == null) {
+    // $FlowExpectedError[prop-missing]
+    promise.displayName = missingClientEdgeRequestInfo.request.params.name;
+  }
+  // $FlowFixMe[incompatible-exact] - Intentionally bypassing exactness check
+  return [queryResult, promise];
 }
 
 function subscribeToSnapshot(
@@ -431,6 +447,12 @@ hook useFragmentInternal_EXPERIMENTAL(
   );
 
   const environment = useRelayEnvironment();
+  let loggerContext;
+  if (RelayFeatureFlags.ENABLE_UI_CONTEXT_ON_RELAY_LOGGER) {
+    // $FlowFixMe[react-rule-hook] - the condition is static
+    // $FlowFixMe[react-rule-hook-conditional]
+    loggerContext = useRelayLoggingContext();
+  }
   const [_state, setState] = useState<FragmentState>(() =>
     getFragmentState(environment, fragmentSelector),
   );
@@ -463,17 +485,21 @@ hook useFragmentInternal_EXPERIMENTAL(
 
   // Handle the queries for any missing client edges; this may suspend.
   // FIXME handle client edges in parallel.
-  if (fragmentNode.metadata?.hasClientEdges === true) {
+  if (
+    fragmentNode.metadata?.hasClientEdges === true ||
+    RelayFeatureFlags.CHECK_ALL_FRAGMENTS_FOR_MISSING_CLIENT_EDGES
+  ) {
     // The fragment is validated to be static (in useFragment) and hasClientEdges is
     // a static (constant) property of the fragment. In practice, this effect will
     // always or never run for a given invocation of this hook.
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     const [clientEdgeQueries, activeRequestPromises] = useMemo(() => {
       const missingClientEdges = getMissingClientEdges(state);
       // eslint-disable-next-line no-shadow
       let clientEdgeQueries;
-      const activeRequestPromises = [];
+      const activeRequestPromises: Array<PromiseWithDisplayName> = [];
       if (missingClientEdges?.length) {
         clientEdgeQueries = ([]: Array<QueryResult>);
         for (const edge of missingClientEdges) {
@@ -494,12 +520,18 @@ hook useFragmentInternal_EXPERIMENTAL(
     }, [state, environment, fragmentNode, fragmentRef, queryOptions]);
 
     if (activeRequestPromises.length) {
-      throw Promise.all(activeRequestPromises);
+      const allPromises = Promise.all(activeRequestPromises);
+      // $FlowExpectedError[prop-missing] Expando to annotate Promises.
+      allPromises.displayName = `RelayClientEdge(${activeRequestPromises
+        .map(promise => promise.displayName)
+        .join(',')})`;
+      throw allPromises;
     }
 
     // See above note
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     useEffect(() => {
       const QueryResource = getQueryResourceForEnvironment(environment);
       if (clientEdgeQueries?.length) {
@@ -520,12 +552,15 @@ hook useFragmentInternal_EXPERIMENTAL(
     // Suspend if a Live Resolver within this fragment is in a suspended state:
     const suspendingLiveResolvers = getSuspendingLiveResolver(state);
     if (suspendingLiveResolvers != null && suspendingLiveResolvers.length > 0) {
-      throw Promise.all(
+      const promise = Promise.all(
         suspendingLiveResolvers.map(liveStateID => {
           // $FlowFixMe[prop-missing] This is expected to be a RelayModernStore
           return environment.getStore().getLiveResolverPromise(liveStateID);
         }),
       );
+      // $FlowExpectedError[prop-missing] Expando to annotate Promises.
+      promise.displayName = 'RelayLiveResolver(' + fragmentNode.name + ')';
+      throw promise;
     }
     // Suspend if an active operation bears on this fragment, either the
     // fragment's owner or some other mutation etc. that could affect it.
@@ -556,7 +591,7 @@ hook useFragmentInternal_EXPERIMENTAL(
 
   // Report required fields only if we're not suspending, since that means
   // they're missing even though we are out of options for possibly fetching them:
-  handlePotentialSnapshotErrorsForState(environment, state);
+  handlePotentialSnapshotErrorsForState(environment, state, loggerContext);
 
   // We emulate CRUD effects using a ref and two effects:
   // - The ref tracks the current state (including updates from the subscription)
@@ -577,6 +612,7 @@ hook useFragmentInternal_EXPERIMENTAL(
     selector: ?ReaderSelector,
     environment: IEnvironment,
   } | null>(null);
+  // $FlowFixMe[react-rule-hook] - the condition is static
   useEffect(() => {
     const storeSubscription = storeSubscriptionRef.current;
     if (storeSubscription != null) {
@@ -629,6 +665,7 @@ hook useFragmentInternal_EXPERIMENTAL(
       environment: state.environment,
     };
   }, [state]);
+  // $FlowFixMe[react-rule-hook] - the condition is static
   useEffect(() => {
     if (storeSubscriptionRef.current == null && state.kind !== 'bailout') {
       const dispose = subscribeToSnapshot(state.environment, state, setState);
@@ -656,6 +693,7 @@ hook useFragmentInternal_EXPERIMENTAL(
     const fragmentRefIsNullish = fragmentRef == null; // for less sensitive memoization
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     data = useMemo(() => {
       if (state.kind === 'bailout') {
         // Bailout state can happen if the fragmentRef is a plural array that is empty or has no
@@ -707,6 +745,7 @@ hook useFragmentInternal_EXPERIMENTAL(
   if (__DEV__) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     // $FlowFixMe[react-rule-hook]
+    // $FlowFixMe[react-rule-hook-conditional]
     useDebugValue({fragment: fragmentNode.name, data});
   }
 

package/relay-hooks/useLazyLoadQuery.js.flow

@@ -32,23 +32,72 @@ const {
 export type UseLazyLoadQueryHookType = hook <TVariables: Variables, TData>(
   gqlQuery: Query<TVariables, TData>,
   variables: TVariables,
-  options?: {
-    fetchKey?: string | number,
-    fetchPolicy?: FetchPolicy,
-    networkCacheConfig?: CacheConfig,
-    UNSTABLE_renderPolicy?: RenderPolicy,
-  },
+  options?: Options,
 ) => TData;
 
+type Options = {
+  /**
+   * Determines if cached data should be used, and when to send a network request based on the cached data that is currently available in the Relay store (for more details, see our [Fetch Policies](../../guided-tour/reusing-cached-data/fetch-policies) and [Garbage Collection](../../guided-tour/reusing-cached-data/presence-of-data) guides):
+   *      * "store-or-network": _*(default)*_ *will* reuse locally cached data and will *only* send a network request if any data for the query is missing. If the query is fully cached, a network request will *not* be made.
+   *      * "store-and-network": *will* reuse locally cached data and will *always* send a network request, regardless of whether any data was missing from the local cache or not.
+   *      * "network-only": *will* *not* reuse locally cached data, and will *always* send a network request to fetch the query, ignoring any data that might be locally cached in Relay.
+   *      * "store-only": *will* *only* reuse locally cached data, and will *never* send a network request to fetch the query. In this case, the responsibility of fetching the query falls to the caller, but this policy could also be used to read and operate on data that is entirely [local](../../guided-tour/updating-data/local-data-updates).
+   */
+  +fetchPolicy?: FetchPolicy,
+  /**
+   * A `fetchKey` can be passed to force a re-evaluation of the current query and variables when the component re-renders, even if the variables didn't change, or even if the component isn't remounted (similarly to how passing a different `key` to a React component will cause it to remount). If the `fetchKey` is different from the one used in the previous render, the current query will be re-evaluated against the store, and it might be refetched depending on the current `fetchPolicy` and the state of the cache.
+   */
+  +fetchKey?: string | number,
+  /**
+   * Default value: `{force: true}`. Object containing cache config options for the *network layer*. Note that the network layer may contain an *additional* query response cache which will reuse network responses for identical queries. If you want to bypass this cache completely (which is the default behavior), pass `{force: true}` as the value for this option.
+   */
+  +networkCacheConfig?: CacheConfig,
+  /**
+   * Undocumented option.
+   */
+  +UNSTABLE_renderPolicy?: RenderPolicy,
+};
+
+/**
+ * Hook used to fetch a GraphQL query during render. This hook can trigger multiple nested or waterfalling round trips if used without caution, and waits until render to start a data fetch (when it can usually start a lot sooner than render), thereby degrading performance. Instead, prefer [`usePreloadedQuery`](../use-preloaded-query).
+ *
+ * @example
+ * const React = require('React');
+ *
+ * const {graphql, useLazyLoadQuery} = require('react-relay');
+ *
+ * function App() {
+ *   const data = useLazyLoadQuery(
+ *     graphql`
+ *       query AppQuery($id: ID!) {
+ *         user(id: $id) {
+ *           name
+ *         }
+ *       }
+ *     `,
+ *     {id: 4},
+ *     {fetchPolicy: 'store-or-network'},
+ *   );
+ *
+ *  return <h1>{data.user?.name}</h1>;
+ * }
+ *
+ * @returns - `data`: Object that contains data which has been read out from the Relay store; the object matches the shape of specified query.
+ *   - The Flow type for data will also match this shape, and contain types derived from the GraphQL Schema. For example, the type of `data` above is: `{| user: ?{| name: ?string |} |}`.
+ */
 hook useLazyLoadQuery<TVariables: Variables, TData>(
+  /**
+   * GraphQL query specified using a `graphql` template literal.
+   */
   gqlQuery: Query<TVariables, TData>,
+  /**
+   * Object containing the variable values to fetch the query. These variables need to match GraphQL variables declared inside the query.
+   */
   variables: TVariables,
-  options?: {
-    fetchKey?: string | number,
-    fetchPolicy?: FetchPolicy,
-    networkCacheConfig?: CacheConfig,
-    UNSTABLE_renderPolicy?: RenderPolicy,
-  },
+  /**
+   * options object
+   */
+  options?: Options,
 ): TData {
   const environment = useRelayEnvironment();
 
@@ -71,4 +120,4 @@ hook useLazyLoadQuery<TVariables: Variables, TData>(
 }
 
 // $FlowFixMe[react-rule-hook-incompatible]
-module.exports = (useLazyLoadQuery: UseLazyLoadQueryHookType);
+module.exports = useLazyLoadQuery;

package/relay-hooks/useLazyLoadQueryNode.js.flow

@@ -78,7 +78,7 @@ hook useLazyLoadQueryNode<TQuery: OperationType>({
   useEffect(() => {
     return () => {
       // Attempt to detect if the component was
-      // hidden (by Offscreen API), or fast refresh occured;
+      // hidden (by Offscreen API), or fast refresh occurred;
       // Only in these situations would the effect cleanup
       // for "unmounting" run multiple times, so if
       // we are ever able to read this ref with a value

package/relay-hooks/useLoadMoreFunction.js.flow

@@ -67,9 +67,11 @@ hook useLoadMoreFunction<TVariables: Variables>(
 ): [LoadMoreFn<TVariables>, boolean, () => void] {
   if (RelayFeatureFlags.ENABLE_ACTIVITY_COMPATIBILITY) {
     // $FlowFixMe[react-rule-hook] - the condition is static
+    // $FlowFixMe[react-rule-hook-conditional]
     return useLoadMoreFunction_EXPERIMENTAL(args);
   }
   // $FlowFixMe[react-rule-hook] - the condition is static
+  // $FlowFixMe[react-rule-hook-conditional]
   return useLoadMoreFunction_CURRENT(args);
 }
 
@@ -138,6 +140,8 @@ hook useLoadMoreFunction_CURRENT<TVariables: Variables>(
     };
   }, [disposeFetch]);
 
+  const isRequestInvalid = fragmentData == null || isParentQueryActive;
+
   const loadMore = useCallback(
     (
       count: number,
@@ -166,11 +170,8 @@ hook useLoadMoreFunction_CURRENT<TVariables: Variables>(
       }
 
       const fragmentSelector = getSelector(fragmentNode, fragmentRef);
-      if (
-        isFetchingRef.current === true ||
-        fragmentData == null ||
-        isParentQueryActive
-      ) {
+
+      if (isFetchingRef.current === true || isRequestInvalid) {
         if (fragmentSelector == null) {
           warning(
             false,
@@ -271,8 +272,7 @@ hook useLoadMoreFunction_CURRENT<TVariables: Variables>(
       disposeFetch,
       completeFetch,
       isFetchingRef,
-      isParentQueryActive,
-      fragmentData,
+      isRequestInvalid,
       fragmentNode.name,
       fragmentRef,
       componentDisplayName,