react-relay 20.1.0 → 21.0.0

package/relay-hooks/useLazyLoadQueryNode.js.flow

@@ -17,6 +17,7 @@ import type {
   Observable,
   OperationDescriptor,
   OperationType,
+  ReaderFragment,
   RenderPolicy,
 } from 'relay-runtime';
 
@@ -32,47 +33,74 @@ const React = require('react');
 
 const {useContext, useEffect, useState, useRef} = React;
 
-hook useLazyLoadQueryNode<TQuery: OperationType>({
-  query,
-  componentDisplayName,
-  fetchObservable,
-  fetchPolicy,
-  fetchKey,
-  renderPolicy,
-}: {
+export type LazyLoadQueryNodeParamsWithQuery = Readonly<{
   query: OperationDescriptor,
   componentDisplayName: string,
   fetchObservable: Observable<GraphQLResponse>,
   fetchPolicy?: ?FetchPolicy,
   fetchKey?: ?string | ?number,
   renderPolicy?: ?RenderPolicy,
-}): TQuery['response'] {
+}>;
+
+/**
+ * This param will be used when the query key is not provided
+ * (e.g. in usePreloadedQuery)
+ */
+export type LazyLoadQueryNodeParamsWithoutQuery = Readonly<{
+  componentDisplayName: string,
+  fragmentNode: ReaderFragment,
+}>;
+
+export type LazyLoadQueryNodeParams =
+  | LazyLoadQueryNodeParamsWithQuery
+  | LazyLoadQueryNodeParamsWithoutQuery;
+
+hook useLazyLoadQueryNode<
+  TQuery extends OperationType,
+  TParams extends LazyLoadQueryNodeParams = LazyLoadQueryNodeParams,
+>(
+  params: TParams,
+): TParams extends LazyLoadQueryNodeParamsWithQuery
+  ? TQuery['response']
+  : null {
   const environment = useRelayEnvironment();
   const profilerContext = useContext(ProfilerContext);
   const QueryResource = getQueryResourceForEnvironment(environment);
 
   const [forceUpdateKey, forceUpdate] = useState(0);
   const {startFetch, completeFetch} = useFetchTrackingRef();
-  const cacheBreaker = `${forceUpdateKey}-${fetchKey ?? ''}`;
-  const cacheIdentifier = getQueryCacheIdentifier(
-    environment,
-    query,
-    fetchPolicy,
-    renderPolicy,
-    cacheBreaker,
-  );
 
-  const preparedQueryResult = profilerContext.wrapPrepareQueryResource(() => {
-    return QueryResource.prepareWithIdentifier(
-      cacheIdentifier,
+  let cacheIdentifier = null;
+  let preparedQueryResult = null;
+  let fragmentNode;
+  if (params.query != null) {
+    const {query, fetchObservable, fetchPolicy, fetchKey, renderPolicy} =
+      params;
+    const cacheBreaker = `${forceUpdateKey}-${fetchKey ?? ''}`;
+    const queryCacheIdentifier = getQueryCacheIdentifier(
+      environment,
       query,
-      fetchObservable,
       fetchPolicy,
       renderPolicy,
-      {start: startFetch, complete: completeFetch, error: completeFetch},
-      profilerContext,
+      cacheBreaker,
     );
-  });
+    cacheIdentifier = queryCacheIdentifier;
+
+    preparedQueryResult = profilerContext.wrapPrepareQueryResource(() => {
+      return QueryResource.prepareWithIdentifier(
+        queryCacheIdentifier,
+        query,
+        fetchObservable,
+        fetchPolicy,
+        renderPolicy,
+        {start: startFetch, complete: completeFetch, error: completeFetch},
+        profilerContext,
+      );
+    });
+    fragmentNode = preparedQueryResult.fragmentNode;
+  } else {
+    fragmentNode = params.fragmentNode;
+  }
 
   const maybeHiddenOrFastRefresh = useRef(false);
   useEffect(() => {
@@ -103,6 +131,10 @@ hook useLazyLoadQueryNode<TQuery: OperationType>({
       return;
     }
 
+    if (preparedQueryResult == null) {
+      return;
+    }
+
     const disposable = QueryResource.retain(
       preparedQueryResult,
       profilerContext,
@@ -117,6 +149,10 @@ hook useLazyLoadQueryNode<TQuery: OperationType>({
   }, [environment, cacheIdentifier]);
 
   useEffect(() => {
+    if (preparedQueryResult == null) {
+      return;
+    }
+
     // Release any temporary retain that's not released. At this point, if the
     // cacheIdentifier doesn't change, the query is still permanently retained,
     // and the temporary retain is redundant.
@@ -124,13 +160,16 @@ hook useLazyLoadQueryNode<TQuery: OperationType>({
     // This effect is intended to run on every commit, thus no dependency
   });
 
-  const {fragmentNode, fragmentRef} = preparedQueryResult;
   const data = useFragmentInternal(
     fragmentNode,
-    fragmentRef,
-    componentDisplayName,
+    preparedQueryResult?.fragmentRef,
+    params.componentDisplayName,
   );
-  return data;
+
+  // Flow is confused in understanding the conditional type.
+  // We know data is the query response if input params is LazyLoadQueryNodeParamsWithQuery,
+  // and void if otherwise.
+  return data as $FlowFixMe;
 }
 
 module.exports = useLazyLoadQueryNode;

package/relay-hooks/useLoadMoreFunction.js.flow

@@ -40,7 +40,7 @@ const {
 } = require('relay-runtime');
 const warning = require('warning');
 
-export type LoadMoreFn<TVariables: Variables> = (
+export type LoadMoreFn<TVariables extends Variables> = (
   count: number,
   options?: {
     onComplete?: (Error | null) => void,
@@ -51,10 +51,10 @@ export type LoadMoreFn<TVariables: Variables> = (
 export type UseLoadMoreFunctionArgs = {
   direction: Direction,
   fragmentNode: ReaderFragment,
-  fragmentRef: mixed,
+  fragmentRef: unknown,
   fragmentIdentifier: string,
-  fragmentData: mixed,
-  connectionPathInFragmentData: $ReadOnlyArray<string | number>,
+  fragmentData: unknown,
+  connectionPathInFragmentData: ReadonlyArray<string | number>,
   paginationRequest: ConcreteRequest,
   paginationMetadata: ReaderPaginationMetadata,
   componentDisplayName: string,
@@ -62,12 +62,13 @@ export type UseLoadMoreFunctionArgs = {
   onReset: () => void,
 };
 
-hook useLoadMoreFunction<TVariables: Variables>(
+hook useLoadMoreFunction<TVariables extends Variables>(
   args: UseLoadMoreFunctionArgs,
 ): [LoadMoreFn<TVariables>, boolean, () => void] {
   if (RelayFeatureFlags.ENABLE_ACTIVITY_COMPATIBILITY) {
     // $FlowFixMe[react-rule-hook] - the condition is static
     // $FlowFixMe[react-rule-hook-conditional]
+    // $FlowFixMe[incompatible-type]
     return useLoadMoreFunction_EXPERIMENTAL(args);
   }
   // $FlowFixMe[react-rule-hook] - the condition is static
@@ -75,7 +76,7 @@ hook useLoadMoreFunction<TVariables: Variables>(
   return useLoadMoreFunction_CURRENT(args);
 }
 
-hook useLoadMoreFunction_CURRENT<TVariables: Variables>(
+hook useLoadMoreFunction_CURRENT<TVariables extends Variables>(
   args: UseLoadMoreFunctionArgs,
 ): [LoadMoreFn<TVariables>, boolean, () => void] {
   const {

package/relay-hooks/useLoadMoreFunction_EXPERIMENTAL.js.flow

@@ -38,7 +38,7 @@ const {
 } = require('relay-runtime');
 const warning = require('warning');
 
-export type LoadMoreFn<TVariables: Variables> = (
+export type LoadMoreFn<TVariables extends Variables> = (
   count: number,
   options?: {
     onComplete?: (Error | null) => void,
@@ -49,10 +49,10 @@ export type LoadMoreFn<TVariables: Variables> = (
 export type UseLoadMoreFunctionArgs = {
   direction: Direction,
   fragmentNode: ReaderFragment,
-  fragmentRef: mixed,
+  fragmentRef: unknown,
   fragmentIdentifier: string,
-  fragmentData: mixed,
-  connectionPathInFragmentData: $ReadOnlyArray<string | number>,
+  fragmentData: unknown,
+  connectionPathInFragmentData: ReadonlyArray<string | number>,
   paginationRequest: ConcreteRequest,
   paginationMetadata: ReaderPaginationMetadata,
   componentDisplayName: string,
@@ -60,7 +60,7 @@ export type UseLoadMoreFunctionArgs = {
   onReset: () => void,
 };
 
-hook useLoadMoreFunction_EXPERIMENTAL<TVariables: Variables>(
+hook useLoadMoreFunction_EXPERIMENTAL<TVariables extends Variables>(
   args: UseLoadMoreFunctionArgs,
 ): [
   // Function to load more data

package/relay-hooks/useMemoVariables.js.flow

@@ -21,7 +21,7 @@ const {useState} = require('react');
  * This is useful when a `variables` object is used as a value in a depencency
  * array as it might often be constructed during render.
  */
-hook useMemoVariables<TVariables: Variables | null>(
+hook useMemoVariables<TVariables extends Variables | null>(
   variables: TVariables,
 ): TVariables {
   const [mirroredVariables, setMirroredVariables] = useState(variables);

package/relay-hooks/useMutation.js.flow

@@ -24,14 +24,13 @@ import type {
   Variables,
 } from 'relay-runtime';
 
-const useIsMountedRef = require('./useIsMountedRef');
 const useRelayEnvironment = require('./useRelayEnvironment');
 const React = require('react');
 const {commitMutation: defaultCommitMutation} = require('relay-runtime');
 
 const {useState, useEffect, useRef, useCallback} = React;
 
-export type UseMutationConfig<TMutation: MutationParameters> = {
+export type UseMutationConfig<TMutation extends MutationParameters> = {
   configs?: Array<DeclarativeMutationConfig>,
   onError?: ?(error: Error) => void,
   onCompleted?: ?(
@@ -64,7 +63,7 @@ type UseMutationConfigInternal<TVariables, TData, TRawResponse> = {
   variables: TVariables,
 };
 
-hook useMutation<TVariables: Variables, TData, TRawResponse = {...}>(
+hook useMutation<TVariables extends Variables, TData, TRawResponse = {...}>(
   mutation: Mutation<TVariables, TData, TRawResponse>,
   commitMutationFn?: (
     environment: IEnvironment,
@@ -75,7 +74,6 @@ hook useMutation<TVariables: Variables, TData, TRawResponse = {...}>(
   boolean,
 ] {
   const environment = useRelayEnvironment();
-  const isMountedRef = useIsMountedRef();
   const environmentRef = useRef(environment);
   const mutationRef = useRef(mutation);
   const inFlightMutationsRef = useRef(new Set<Disposable>());
@@ -88,12 +86,10 @@ hook useMutation<TVariables: Variables, TData, TRawResponse = {...}>(
         mutationRef.current === mutation
       ) {
         inFlightMutationsRef.current.delete(disposable);
-        if (isMountedRef.current) {
-          setMutationInFlight(inFlightMutationsRef.current.size > 0);
-        }
+        setMutationInFlight(inFlightMutationsRef.current.size > 0);
       }
     },
-    [environment, isMountedRef, mutation],
+    [environment, mutation],
   );
 
   useEffect(() => {
@@ -102,19 +98,15 @@ hook useMutation<TVariables: Variables, TData, TRawResponse = {...}>(
       mutationRef.current !== mutation
     ) {
       inFlightMutationsRef.current = new Set();
-      if (isMountedRef.current) {
-        setMutationInFlight(false);
-      }
+      setMutationInFlight(false);
       environmentRef.current = environment;
       mutationRef.current = mutation;
     }
-  }, [environment, isMountedRef, mutation]);
+  }, [environment, mutation]);
 
   const commit = useCallback(
     (config: UseMutationConfigInternal<TVariables, TData, TRawResponse>) => {
-      if (isMountedRef.current) {
-        setMutationInFlight(true);
-      }
+      setMutationInFlight(true);
       const disposable: Disposable = commitMutationFn(environment, {
         ...config,
         mutation,
@@ -137,7 +129,7 @@ hook useMutation<TVariables: Variables, TData, TRawResponse = {...}>(
       inFlightMutationsRef.current.add(disposable);
       return disposable;
     },
-    [cleanup, commitMutationFn, environment, isMountedRef, mutation],
+    [cleanup, commitMutationFn, environment, mutation],
   );
 
   return [commit, isMutationInFlight];

package/relay-hooks/useMutationAction_EXPERIMENTAL.js.flow

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ *
+ * @flow strict-local
+ * @format
+ * @oncall relay
+ */
+
+'use strict';
+
+import type {Mutation, Variables} from 'relay-runtime';
+
+const useRelayEnvironment = require('./useRelayEnvironment');
+const React = require('react');
+const {commitMutation} = require('relay-runtime');
+
+const {useCallback} = React;
+
+/**
+ * A variant of useMutation that returns an action function suitable for use
+ * with React's action prop pattern. The returned action is an async function
+ * that can be passed to `startTransition` or used as an action prop, enabling
+ * optimistic UI updates via `useOptimistic`.
+ * https://react.dev/reference/react/useTransition#starttransition
+ *
+ * Usage:
+ *   const commitAction = useMutationAction_EXPERIMENTAL(mutation);
+ *
+ *   // In a startTransition or action prop:
+ *   startTransition(async () => {
+ *     setOptimisticValue(newValue);
+ *     await commitAction({input: newValue});
+ *   });
+ */
+hook useMutationAction_EXPERIMENTAL<
+  TVariables extends Variables,
+  TData,
+  TRawResponse = {...},
+>(
+  mutation: Mutation<TVariables, TData, TRawResponse>,
+): (variables: TVariables) => Promise<TData> {
+  const environment = useRelayEnvironment();
+
+  const commitAction = useCallback(
+    (variables: TVariables): Promise<TData> => {
+      return new Promise((resolve, reject) => {
+        commitMutation(environment, {
+          mutation,
+          variables,
+          onCompleted: (response: TData) => {
+            resolve(response);
+          },
+          onError: (error: Error) => {
+            reject(error);
+          },
+        });
+      });
+    },
+    [environment, mutation],
+  );
+
+  return commitAction;
+}
+
+module.exports = useMutationAction_EXPERIMENTAL;

package/relay-hooks/usePaginationFragment.js.flow

@@ -32,11 +32,14 @@ const {
   getPaginationMetadata,
 } = require('relay-runtime');
 
-type RefetchVariables<TVariables, TKey: ?{+$fragmentSpreads: mixed, ...}> =
+type RefetchVariables<
+  TVariables,
+  TKey extends ?{+$fragmentSpreads: unknown, ...},
+> =
   // NOTE: This type ensures that the type of the returned variables is either:
   //   - nullable if the provided ref type is nullable
   //   - non-nullable if the provided ref type is non-nullable
-  [+key: TKey] extends [+key: {+$fragmentSpreads: mixed, ...}]
+  [+key: TKey] extends [+key: {+$fragmentSpreads: unknown, ...}]
     ? Partial<TVariables>
     : TVariables;
 
@@ -54,7 +57,7 @@ export type ReturnType<TVariables, TData, TKey> = {
   // NOTE: This type ensures that the type of the returned data is either:
   //   - nullable if the provided ref type is nullable
   //   - non-nullable if the provided ref type is non-nullable
-  data: [+key: TKey] extends [+key: {+$fragmentSpreads: mixed, ...}]
+  data: [+key: TKey] extends [+key: {+$fragmentSpreads: unknown, ...}]
     ? TData
     : ?TData,
   loadNext: LoadMoreFn<TVariables>,
@@ -70,20 +73,20 @@ export type ReturnType<TVariables, TData, TKey> = {
 // a separate hooks implementation in ./HooksImplementation -- it can
 // be removed after we stop doing that.
 export type UsePaginationFragmentType = <
-  TFragmentType: FragmentType,
-  TVariables: Variables,
+  TFragmentType extends FragmentType,
+  TVariables extends Variables,
   TData,
-  TKey: ?{+$fragmentSpreads: TFragmentType, ...},
+  TKey extends ?{+$fragmentSpreads: TFragmentType, ...},
 >(
   fragmentInput: RefetchableFragment<TFragmentType, TData, TVariables>,
   parentFragmentRef: TKey,
 ) => ReturnType<TVariables, TData, TKey>;
 
 hook usePaginationFragment<
-  TFragmentType: FragmentType,
-  TVariables: Variables,
+  TFragmentType extends FragmentType,
+  TVariables extends Variables,
   TData,
-  TKey: ?{+$fragmentSpreads: TFragmentType, ...},
+  TKey extends ?{+$fragmentSpreads: TFragmentType, ...},
 >(
   fragmentInput: RefetchableFragment<TFragmentType, TData, TVariables>,
   parentFragmentRef: TKey,
@@ -155,7 +158,7 @@ hook usePaginationFragment<
     });
   }
   return {
-    // $FlowFixMe[incompatible-return]
+    // $FlowFixMe[incompatible-type]
     data: fragmentData,
     loadNext,
     loadPrevious,
@@ -163,11 +166,12 @@ hook usePaginationFragment<
     hasPrevious,
     isLoadingNext,
     isLoadingPrevious,
+    // $FlowFixMe[incompatible-type]
     refetch: refetchPagination,
   };
 }
 
-hook useLoadMore<TVariables: Variables>(
+hook useLoadMore<TVariables extends Variables>(
   args: Omit<UseLoadMoreFunctionArgs, 'observer' | 'onReset'>,
 ): [LoadMoreFn<TVariables>, boolean, boolean, () => void] {
   const environment = useRelayEnvironment();

package/relay-hooks/usePrefetchableForwardPaginationFragment.js.flow

@@ -43,7 +43,7 @@ const {
   getValueAtPath,
 } = require('relay-runtime');
 
-type LoadMoreFn<TVariables: Variables> = (
+type LoadMoreFn<TVariables extends Variables> = (
   count: number,
   options?: {
     onComplete?: (Error | null) => void,
@@ -55,7 +55,7 @@ export type ReturnType<TVariables, TData, TEdgeData, TKey> = {
   // NOTE: This type ensures that the type of the returned data is either:
   //   - nullable if the provided ref type is nullable
   //   - non-nullable if the provided ref type is non-nullable
-  data: [+key: TKey] extends [+key: {+$fragmentSpreads: mixed, ...}]
+  data: [+key: TKey] extends [+key: {+$fragmentSpreads: unknown, ...}]
     ? TData
     : ?TData,
   loadNext: LoadMoreFn<TVariables>,
@@ -72,18 +72,18 @@ type LoadMoreOptions<TVariables> = {
 
 export type GetExtraVariablesFn<TEdgeData, TData, TVariables, TKey> = ({
   hasNext: boolean,
-  data: [+key: TKey] extends [+key: {+$fragmentSpreads: mixed, ...}]
+  data: [+key: TKey] extends [+key: {+$fragmentSpreads: unknown, ...}]
     ? TData
     : ?TData,
   getServerEdges: () => TEdgeData,
 }) => Partial<TVariables>;
 
 hook usePrefetchableForwardPaginationFragment<
-  TFragmentType: FragmentType,
-  TVariables: Variables,
+  TFragmentType extends FragmentType,
+  TVariables extends Variables,
   TData,
   TEdgeData,
-  TKey: ?{+$fragmentSpreads: TFragmentType, ...},
+  TKey extends ?{+$fragmentSpreads: TFragmentType, ...},
 >(
   fragmentInput: PrefetchableRefetchableFragment<
     TFragmentType,
@@ -257,26 +257,26 @@ hook usePrefetchableForwardPaginationFragment<
               onComplete: prefetchingOnComplete,
               UNSTABLE_extraVariables:
                 typeof prefetchingUNSTABLE_extraVariables === 'function'
-                  ? // $FlowFixMe[incompatible-call]
+                  ? // $FlowFixMe[incompatible-type]
                     prefetchingUNSTABLE_extraVariables({
                       hasNext,
-                      // $FlowFixMe[incompatible-call]
+                      // $FlowFixMe[incompatible-type]
                       data: fragmentData,
                       getServerEdges: () => {
                         const selector = getSelector(
-                          // $FlowFixMe[incompatible-call]
+                          // $FlowFixMe[incompatible-type]
                           edgesFragment,
                           edgeKeys,
                         );
                         if (selector == null) {
-                          // $FlowFixMe[incompatible-call]
+                          // $FlowFixMe[incompatible-type]
                           return [];
                         }
                         invariant(
                           selector.kind === 'PluralReaderSelector',
                           'Expected a plural selector',
                         );
-                        // $FlowFixMe[incompatible-call]
+                        // $FlowFixMe[incompatible-type]
                         return selector.selectors.map(
                           sel => environment.lookup(sel).data,
                         );
@@ -332,22 +332,22 @@ hook usePrefetchableForwardPaginationFragment<
           onComplete,
           UNSTABLE_extraVariables:
             typeof prefetchingUNSTABLE_extraVariables === 'function'
-              ? // $FlowFixMe[incompatible-call]
+              ? // $FlowFixMe[incompatible-type]
                 prefetchingUNSTABLE_extraVariables({
                   hasNext,
-                  // $FlowFixMe[incompatible-call]
+                  // $FlowFixMe[incompatible-type]
                   data: fragmentData,
                   getServerEdges: () => {
                     const selector = getSelector(edgesFragment, edgeKeys);
                     if (selector == null) {
-                      // $FlowFixMe[incompatible-call]
+                      // $FlowFixMe[incompatible-type]
                       return [];
                     }
                     invariant(
                       selector.kind === 'PluralReaderSelector',
                       'Expected a plural selector',
                     );
-                    // $FlowFixMe[incompatible-call]
+                    // $FlowFixMe[incompatible-type]
                     return selector.selectors.map(
                       sel => environment.lookup(sel).data,
                     );
@@ -375,12 +375,12 @@ hook usePrefetchableForwardPaginationFragment<
 
   const realNumInUse = Math.min(numInUse, sourceSize);
 
-  const derivedEdgeKeys: $ReadOnlyArray<mixed> = useMemo(
+  const derivedEdgeKeys: ReadonlyArray<unknown> = useMemo(
     () => edgeKeys?.slice(0, realNumInUse) ?? [],
     [edgeKeys, realNumInUse],
   );
 
-  // $FlowExpectedError[incompatible-call] - we know derivedEdgeKeys are the correct keys
+  // $FlowExpectedError[incompatible-type] - we know derivedEdgeKeys are the correct keys
   const edges: TEdgeData = useFragment(edgesFragment, derivedEdgeKeys);
 
   const refetchPagination = useCallback(
@@ -422,13 +422,14 @@ hook usePrefetchableForwardPaginationFragment<
 
   return {
     edges,
-    // $FlowFixMe[incompatible-return]
+    // $FlowFixMe[incompatible-type]
     data: fragmentData,
     loadNext: showMore,
     hasNext: hasNext || sourceSize > numInUse,
     // Only reflect `isLoadingMore` if the product depends on it, do not refelect
     // `isLoaindgMore` state if it is for fufilling the buffer
     isLoadingNext: isLoadingMore && numInUse > sourceSize,
+    // $FlowFixMe[incompatible-type]
     refetch: refetchPagination,
   };
 }