react-relay 13.2.0 → 14.0.0

package/relay-hooks/react-cache/useFragmentInternal_REACT_CACHE.js.flow

@@ -37,10 +37,11 @@ const {
   handlePotentialSnapshotErrors,
   recycleNodesInto,
 } = require('relay-runtime');
+const warning = require('warning');
 
 type FragmentQueryOptions = {|
   fetchPolicy?: FetchPolicy,
-  networkCacheConfig?: CacheConfig,
+  networkCacheConfig?: ?CacheConfig,
 |};
 
 type FragmentState = $ReadOnly<
@@ -50,6 +51,7 @@ type FragmentState = $ReadOnly<
 >;
 
 type StateUpdater<T> = (T | (T => T)) => void;
+type StateUpdaterFunction<T> = ((T) => T) => void;
 
 function isMissingData(state: FragmentState): boolean {
   if (state.kind === 'bailout') {
@@ -103,17 +105,21 @@ function handlePotentialSnapshotErrorsForState(
   }
 }
 
+/**
+ * Check for updates to the store that occurred concurrently with rendering the given `state` value,
+ * returning a new (updated) state if there were updates or null if there were no changes.
+ */
 function handleMissedUpdates(
   environment: IEnvironment,
   state: FragmentState,
-  setState: StateUpdater<FragmentState>,
-): void {
+): null | [/* has data changed */ boolean, FragmentState] {
   if (state.kind === 'bailout') {
-    return;
+    return null;
   }
+  // FIXME this is invalid if we've just switched environments.
   const currentEpoch = environment.getStore().getEpoch();
   if (currentEpoch === state.epoch) {
-    return;
+    return null;
   }
   // The store has updated since we rendered (without us being subscribed yet),
   // so check for any updates to the data we're rendering:
@@ -123,42 +129,58 @@ function handleMissedUpdates(
       state.snapshot.data,
       currentSnapshot.data,
     );
-    if (updatedData !== state.snapshot.data) {
-      setState({
+    const updatedCurrentSnapshot: Snapshot = {
+      data: updatedData,
+      isMissingData: currentSnapshot.isMissingData,
+      missingClientEdges: currentSnapshot.missingClientEdges,
+      missingLiveResolverFields: currentSnapshot.missingLiveResolverFields,
+      seenRecords: currentSnapshot.seenRecords,
+      selector: currentSnapshot.selector,
+      missingRequiredFields: currentSnapshot.missingRequiredFields,
+      relayResolverErrors: currentSnapshot.relayResolverErrors,
+    };
+    return [
+      updatedData !== state.snapshot.data,
+      {
         kind: 'singular',
-        snapshot: currentSnapshot,
+        snapshot: updatedCurrentSnapshot,
         epoch: currentEpoch,
-      });
-    }
+      },
+    ];
   } else {
-    let updates = null;
+    let didMissUpdates = false;
+    const currentSnapshots = [];
     for (let index = 0; index < state.snapshots.length; index++) {
       const snapshot = state.snapshots[index];
       const currentSnapshot = environment.lookup(snapshot.selector);
       const updatedData = recycleNodesInto(snapshot.data, currentSnapshot.data);
+      const updatedCurrentSnapshot: Snapshot = {
+        data: updatedData,
+        isMissingData: currentSnapshot.isMissingData,
+        missingClientEdges: currentSnapshot.missingClientEdges,
+        missingLiveResolverFields: currentSnapshot.missingLiveResolverFields,
+        seenRecords: currentSnapshot.seenRecords,
+        selector: currentSnapshot.selector,
+        missingRequiredFields: currentSnapshot.missingRequiredFields,
+        relayResolverErrors: currentSnapshot.relayResolverErrors,
+      };
       if (updatedData !== snapshot.data) {
-        updates =
-          updates === null ? new Array(state.snapshots.length) : updates;
-        updates[index] = snapshot;
+        didMissUpdates = true;
       }
+      currentSnapshots.push(updatedCurrentSnapshot);
     }
-    if (updates !== null) {
-      const theUpdates = updates; // preserve flow refinement.
-      setState(existing => {
-        invariant(
-          existing.kind === 'plural',
-          'Cannot go from singular to plural or from bailout to plural.',
-        );
-        const updated = [...existing.snapshots];
-        for (let index = 0; index < theUpdates.length; index++) {
-          const updatedSnapshot = theUpdates[index];
-          if (updatedSnapshot) {
-            updated[index] = updatedSnapshot;
-          }
-        }
-        return {kind: 'plural', snapshots: updated, epoch: currentEpoch};
-      });
-    }
+    invariant(
+      currentSnapshots.length === state.snapshots.length,
+      'Expected same number of snapshots',
+    );
+    return [
+      didMissUpdates,
+      {
+        kind: 'plural',
+        snapshots: currentSnapshots,
+        epoch: currentEpoch,
+      },
+    ];
   }
 }
 
@@ -168,7 +190,7 @@ function handleMissingClientEdge(
   parentFragmentRef: mixed,
   missingClientEdgeRequestInfo: MissingClientEdgeRequestInfo,
   queryOptions?: FragmentQueryOptions,
-): void {
+): () => () => void {
   const originalVariables = getVariablesFromFragment(
     parentFragmentNode,
     parentFragmentRef,
@@ -186,27 +208,30 @@ function handleMissingClientEdge(
   // doing here is started the query if needed and retaining and releasing it
   // according to the component mount/suspense cycle; getQueryResultOrFetchQuery
   // already handles this by itself.
-  getQueryResultOrFetchQuery(
+  const [_, effect] = getQueryResultOrFetchQuery(
     environment,
     queryOperationDescriptor,
-    queryOptions?.fetchPolicy,
+    {
+      fetchPolicy: queryOptions?.fetchPolicy,
+    },
   );
+  return effect;
 }
 
 function subscribeToSnapshot(
   environment: IEnvironment,
   state: FragmentState,
-  setState: StateUpdater<FragmentState>,
+  setState: StateUpdaterFunction<FragmentState>,
 ): () => void {
   if (state.kind === 'bailout') {
     return () => {};
   } else if (state.kind === 'singular') {
     const disposable = environment.subscribe(state.snapshot, latestSnapshot => {
-      setState({
+      setState(_ => ({
         kind: 'singular',
         snapshot: latestSnapshot,
         epoch: environment.getStore().getEpoch(),
-      });
+      }));
     });
     return () => {
       disposable.dispose();
@@ -240,6 +265,7 @@ function subscribeToSnapshot(
 function getFragmentState(
   environment: IEnvironment,
   fragmentSelector: ?ReaderSelector,
+  isPlural: boolean,
 ): FragmentState {
   if (fragmentSelector == null) {
     return {kind: 'bailout'};
@@ -265,16 +291,17 @@ function useFragmentInternal_REACT_CACHE(
   hookDisplayName: string,
   queryOptions?: FragmentQueryOptions,
   fragmentKey?: string,
-): {|
-  data: ?SelectorData | Array<?SelectorData>,
-  disableStoreUpdates: () => void,
-  enableStoreUpdates: () => void,
-|} {
-  const fragmentSelector = getSelector(fragmentNode, fragmentRef);
+): ?SelectorData | Array<?SelectorData> {
+  const fragmentSelector = useMemo(
+    () => getSelector(fragmentNode, fragmentRef),
+    [fragmentNode, fragmentRef],
+  );
+
+  const isPlural = fragmentNode?.metadata?.plural === true;
 
-  if (fragmentNode?.metadata?.plural === true) {
+  if (isPlural) {
     invariant(
-      Array.isArray(fragmentRef),
+      fragmentRef == null || Array.isArray(fragmentRef),
       'Relay: Expected fragment pointer%s for fragment `%s` to be ' +
         'an array, instead got `%s`. Remove `@relay(plural: true)` ' +
         'from fragment `%s` to allow the prop to be an object.',
@@ -296,7 +323,9 @@ function useFragmentInternal_REACT_CACHE(
     );
   }
   invariant(
-    fragmentRef == null || fragmentSelector != null,
+    fragmentRef == null ||
+      (isPlural && Array.isArray(fragmentRef) && fragmentRef.length === 0) ||
+      fragmentSelector != null,
     'Relay: Expected to receive an object where `...%s` was spread, ' +
       'but the fragment reference was not found`. This is most ' +
       'likely the result of:\n' +
@@ -317,38 +346,94 @@ function useFragmentInternal_REACT_CACHE(
 
   const environment = useRelayEnvironment();
   const [rawState, setState] = useState<FragmentState>(() =>
-    getFragmentState(environment, fragmentSelector),
+    getFragmentState(environment, fragmentSelector, isPlural),
   );
+  // On second look this separate rawState may not be needed at all, it can just be
+  // put into getFragmentState. Exception: can we properly handle the case where the
+  // fragmentRef goes from non-null to null?
+  const stateFromRawState = (state: FragmentState) => {
+    if (fragmentRef == null) {
+      return {kind: 'bailout'};
+    } else if (state.kind === 'plural' && state.snapshots.length === 0) {
+      return {kind: 'bailout'};
+    } else {
+      return state;
+    }
+  };
+  let state = stateFromRawState(rawState);
+
+  // This copy of the state we only update when something requires us to
+  // unsubscribe and re-subscribe, namely a changed environment or
+  // fragment selector.
+  const [rawSubscribedState, setSubscribedState] = useState(state);
+  // FIXME since this is used as an effect dependency, it needs to be memoized.
+  let subscribedState = stateFromRawState(rawSubscribedState);
 
   const [previousFragmentSelector, setPreviousFragmentSelector] =
     useState(fragmentSelector);
-  if (!areEqualSelectors(fragmentSelector, previousFragmentSelector)) {
+  const [previousEnvironment, setPreviousEnvironment] = useState(environment);
+  if (
+    !areEqualSelectors(fragmentSelector, previousFragmentSelector) ||
+    environment !== previousEnvironment
+  ) {
+    // Enqueue setState to record the new selector and state
     setPreviousFragmentSelector(fragmentSelector);
-    setState(getFragmentState(environment, fragmentSelector));
-  }
-
-  let state;
-  if (fragmentRef == null) {
-    state = {kind: 'bailout'};
-  } else if (rawState.kind === 'plural' && rawState.snapshots.length === 0) {
-    state = {kind: 'bailout'};
-  } else {
-    state = rawState;
+    setPreviousEnvironment(environment);
+    const newState = stateFromRawState(
+      getFragmentState(environment, fragmentSelector, isPlural),
+    );
+    setState(newState);
+    setSubscribedState(newState); // This causes us to form a new subscription
+    // But render with the latest state w/o waiting for the setState. Otherwise
+    // the component would render the wrong information temporarily (including
+    // possibly incorrectly triggering some warnings below).
+    state = newState;
+    subscribedState = newState;
   }
 
   // Handle the queries for any missing client edges; this may suspend.
   // FIXME handle client edges in parallel.
-  const missingClientEdges = getMissingClientEdges(state);
-  if (missingClientEdges?.length) {
-    for (const edge of missingClientEdges) {
-      handleMissingClientEdge(
-        environment,
-        fragmentNode,
-        fragmentRef,
-        edge,
-        queryOptions,
-      );
-    }
+  if (fragmentNode.metadata?.hasClientEdges === true) {
+    // 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
+    const effects = useMemo(() => {
+      const missingClientEdges = getMissingClientEdges(state);
+      // eslint-disable-next-line no-shadow
+      let effects;
+      if (missingClientEdges?.length) {
+        effects = [];
+        for (const edge of missingClientEdges) {
+          effects.push(
+            handleMissingClientEdge(
+              environment,
+              fragmentNode,
+              fragmentRef,
+              edge,
+              queryOptions,
+            ),
+          );
+        }
+      }
+      return effects;
+    }, [state, environment, fragmentNode, fragmentRef, queryOptions]);
+
+    // See above note
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useEffect(() => {
+      if (effects?.length) {
+        const cleanups = [];
+        for (const effect of effects) {
+          cleanups.push(effect());
+        }
+        return () => {
+          for (const cleanup of cleanups) {
+            cleanup();
+          }
+        };
+      }
+    }, [effects]);
   }
 
   if (isMissingData(state)) {
@@ -372,45 +457,103 @@ function useFragmentInternal_REACT_CACHE(
     handlePotentialSnapshotErrorsForState(environment, state);
   }
 
-  // Subscriptions:
-  const isMountedRef = useRef(false);
-  const isListeningForUpdatesRef = useRef(true);
-  function enableStoreUpdates() {
-    isListeningForUpdatesRef.current = true;
-    handleMissedUpdates(environment, state, setState);
-  }
-  function disableStoreUpdates() {
-    isListeningForUpdatesRef.current = false;
-  }
   useEffect(() => {
-    const wasAlreadySubscribed = isMountedRef.current;
-    isMountedRef.current = true;
-    if (!wasAlreadySubscribed) {
-      handleMissedUpdates(environment, state, setState);
+    // Check for updates since the state was rendered
+    let currentState = subscribedState;
+    const updates = handleMissedUpdates(environment, subscribedState);
+    if (updates !== null) {
+      const [didMissUpdates, updatedState] = updates;
+      // TODO: didMissUpdates only checks for changes to snapshot data, but it's possible
+      // that other snapshot properties may have changed that should also trigger a re-render,
+      // such as changed missing resolver fields, missing client edges, etc.
+      // A potential alternative is for handleMissedUpdates() to recycle the entire state
+      // value, and return the new (recycled) state only if there was some change. In that
+      // case the code would always setState if something in the snapshot changed, in addition
+      // to using the latest snapshot to subscribe.
+      if (didMissUpdates) {
+        setState(updatedState);
+      }
+      currentState = updatedState;
     }
-    return subscribeToSnapshot(environment, state, setState);
-  }, [environment, state]);
+    return subscribeToSnapshot(environment, currentState, updater => {
+      setState(latestState => {
+        if (
+          latestState.snapshot?.selector !== currentState.snapshot?.selector
+        ) {
+          // Ignore updates to the subscription if it's for a previous fragment selector
+          // than the latest one to be rendered. This can happen if the store is updated
+          // after we re-render with a new fragmentRef prop but before the effect fires
+          // in which we unsubscribe to the old one and subscribe to the new one.
+          // (NB: it's safe to compare the selectors by reference because the selector
+          // is recycled into new snapshots.)
+          return latestState;
+        } else {
+          return updater(latestState);
+        }
+      });
+    });
+  }, [environment, subscribedState]);
 
-  const data = useMemo(
-    () =>
-      state.kind === 'bailout'
-        ? {}
-        : state.kind === 'singular'
-        ? state.snapshot.data
-        : state.snapshots.map(s => s.data),
-    [state],
-  );
+  let data: ?SelectorData | Array<?SelectorData>;
+  if (isPlural) {
+    // Plural fragments require allocating an array of the snasphot data values,
+    // which has to be memoized to avoid triggering downstream re-renders.
+    //
+    // Note that isPlural is a constant property of the fragment and does not change
+    // for a particular useFragment invocation site
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    data = useMemo(() => {
+      if (state.kind === 'bailout') {
+        return [];
+      } else {
+        invariant(
+          state.kind === 'plural',
+          'Expected state to be plural because fragment is plural',
+        );
+        return state.snapshots.map(s => s.data);
+      }
+    }, [state]);
+  } else if (state.kind === 'bailout') {
+    // This case doesn't allocate a new object so it doesn't have to be memoized
+    data = null;
+  } else {
+    // This case doesn't allocate a new object so it doesn't have to be memoized
+    invariant(
+      state.kind === 'singular',
+      'Expected state to be singular because fragment is singular',
+    );
+    data = state.snapshot.data;
+  }
+
+  if (__DEV__) {
+    if (
+      fragmentRef != null &&
+      (data === undefined ||
+        (Array.isArray(data) &&
+          data.length > 0 &&
+          data.every(d => d === undefined)))
+    ) {
+      warning(
+        false,
+        'Relay: Expected to have been able to read non-null data for ' +
+          'fragment `%s` declared in ' +
+          '`%s`, since fragment reference was non-null. ' +
+          "Make sure that that `%s`'s parent isn't " +
+          'holding on to and/or passing a fragment reference for data that ' +
+          'has been deleted.',
+        fragmentNode.name,
+        hookDisplayName,
+        hookDisplayName,
+      );
+    }
+  }
 
   if (__DEV__) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     useDebugValue({fragment: fragmentNode.name, data});
   }
 
-  return {
-    data,
-    disableStoreUpdates,
-    enableStoreUpdates,
-  };
+  return data;
 }
 
 module.exports = useFragmentInternal_REACT_CACHE;

package/relay-hooks/react-cache/useFragment_REACT_CACHE.js.flow

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+relay
+ * @flow strict-local
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+import type {Fragment, FragmentType, GraphQLTaggedNode} from 'relay-runtime';
+
+const {useTrackLoadQueryInRender} = require('../loadQuery');
+const useStaticFragmentNodeWarning = require('../useStaticFragmentNodeWarning');
+const useFragmentInternal = require('./useFragmentInternal_REACT_CACHE');
+const {useDebugValue} = require('react');
+const {getFragment} = require('relay-runtime');
+
+type HasSpread<TFragmentType> = {
+  +$fragmentSpreads: TFragmentType,
+  ...
+};
+
+// if the key is non-nullable, return non-nullable value
+declare function useFragment<TFragmentType: FragmentType, TData>(
+  fragment: Fragment<TFragmentType, TData>,
+  key: HasSpread<TFragmentType>,
+): TData;
+
+// if the key is nullable, return nullable value
+declare function useFragment<TFragmentType: FragmentType, TData>(
+  fragment: Fragment<TFragmentType, TData>,
+  key: ?HasSpread<TFragmentType>,
+): ?TData;
+
+// if the key is a non-nullable array of keys, return non-nullable array
+declare function useFragment<TFragmentType: FragmentType, TData>(
+  fragment: Fragment<TFragmentType, TData>,
+  key: $ReadOnlyArray<HasSpread<TFragmentType>>,
+): TData;
+
+// if the key is a nullable array of keys, return nullable array
+declare function useFragment<TFragmentType: FragmentType, TData>(
+  fragment: Fragment<TFragmentType, TData>,
+  key: ?$ReadOnlyArray<HasSpread<TFragmentType>>,
+): ?TData;
+
+function useFragment(fragment: GraphQLTaggedNode, key: mixed): mixed {
+  // We need to use this hook in order to be able to track if
+  // loadQuery was called during render
+  useTrackLoadQueryInRender();
+
+  const fragmentNode = getFragment(fragment);
+  if (__DEV__) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useStaticFragmentNodeWarning(
+      fragmentNode,
+      'first argument of useFragment()',
+    );
+  }
+  const data = useFragmentInternal(fragmentNode, key, 'useFragment()');
+  if (__DEV__) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useDebugValue({fragment: fragmentNode.name, data});
+  }
+  return data;
+}
+
+module.exports = useFragment;

package/relay-hooks/react-cache/useLazyLoadQuery_REACT_CACHE.js.flow

@@ -26,6 +26,7 @@ const useMemoOperationDescriptor = require('../useMemoOperationDescriptor');
 const useRelayEnvironment = require('../useRelayEnvironment');
 const getQueryResultOrFetchQuery = require('./getQueryResultOrFetchQuery_REACT_CACHE');
 const useFragmentInternal = require('./useFragmentInternal_REACT_CACHE');
+const {useEffect} = require('react');
 
 function useLazyLoadQuery_REACT_CACHE<TVariables: Variables, TData>(
   gqlQuery: Query<TVariables, TData>,
@@ -47,20 +48,25 @@ function useLazyLoadQuery_REACT_CACHE<TVariables: Variables, TData>(
   );
 
   // Get the query going if needed -- this may suspend.
-  const queryResult = getQueryResultOrFetchQuery(
+  const [queryResult, effect] = getQueryResultOrFetchQuery(
     environment,
     queryOperationDescriptor,
-    options?.fetchPolicy,
+    {
+      fetchPolicy: options?.fetchPolicy,
+      renderPolicy: options?.UNSTABLE_renderPolicy,
+      fetchKey: options?.fetchKey,
+    },
   );
 
+  useEffect(effect);
+
   // Read the query's root fragment -- this may suspend.
   const {fragmentNode, fragmentRef} = queryResult;
-
   // $FlowExpectedError[incompatible-return] Is this a fixable incompatible-return?
   return useFragmentInternal(fragmentNode, fragmentRef, 'useLazyLoadQuery()', {
     fetchPolicy: options?.fetchPolicy,
     networkCacheConfig: options?.networkCacheConfig,
-  }).data;
+  });
 }
 
 module.exports = useLazyLoadQuery_REACT_CACHE;