react-relay 14.0.0 → 15.0.0

package/relay-hooks/useBlockingPaginationFragment.js.flow

@@ -4,23 +4,22 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
+import type {RefetchableFragment} from '../../relay-runtime/util/RelayRuntimeTypes';
 import type {LoadMoreFn, UseLoadMoreFunctionArgs} from './useLoadMoreFunction';
-import type {RefetchFnDynamic} from './useRefetchableFragmentNode';
+import type {Options} from './useRefetchableFragmentNode';
 import type {
+  Disposable,
   FragmentType,
   GraphQLResponse,
-  GraphQLTaggedNode,
   Observer,
-  OperationType,
+  Variables,
 } from 'relay-runtime';
 
 const useLoadMoreFunction = require('./useLoadMoreFunction');
@@ -34,35 +33,54 @@ const {
   getPaginationMetadata,
 } = require('relay-runtime');
 
-export type ReturnType<TQuery: OperationType, TKey, TFragmentData> = {|
-  data: TFragmentData,
-  loadNext: LoadMoreFn<TQuery>,
-  loadPrevious: LoadMoreFn<TQuery>,
-  hasNext: boolean,
-  hasPrevious: boolean,
-  refetch: RefetchFnDynamic<TQuery, TKey>,
-|};
+type RefetchVariables<TVariables, TKey> =
+  // NOTE: This $Call ensures that the type of the variables is either:
+  //   - nullable if the provided ref type is non-nullable
+  //   - non-nullable if the provided ref type is nullable, and the caller need to provide the full set of variables
+  // prettier-ignore
+  $Call<
+    & (<TFragmentType>( { +$fragmentSpreads: TFragmentType, ... }) => $Shape<TVariables>)
+    & (<TFragmentType>(?{ +$fragmentSpreads: TFragmentType, ... }) => TVariables),
+    TKey,
+  >;
 
-function useBlockingPaginationFragment<
-  TQuery: OperationType,
-  TKey: ?{+$data?: mixed, +$fragmentSpreads: FragmentType, ...},
->(
-  fragmentInput: GraphQLTaggedNode,
-  parentFragmentRef: TKey,
-  componentDisplayName: string = 'useBlockingPaginationFragment()',
-): ReturnType<
-  TQuery,
-  TKey,
+type RefetchFnBase<TVars, TOptions> = (
+  vars: TVars,
+  options?: TOptions,
+) => Disposable;
+
+type RefetchFn<TVariables, TKey, TOptions = Options> = RefetchFnBase<
+  RefetchVariables<TVariables, TKey>,
+  TOptions,
+>;
+
+type ReturnType<TVariables, TData, TKey> = {
   // NOTE: This $Call 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
   // prettier-ignore
-  $Call<
-    & (<TFragmentData>( { +$data?: TFragmentData, ... }) =>  TFragmentData)
-    & (<TFragmentData>(?{ +$data?: TFragmentData, ... }) => ?TFragmentData),
+  data: $Call<
+    & (<TFragmentType>( { +$fragmentSpreads: TFragmentType, ... }) =>  TData)
+    & (<TFragmentType>(?{ +$fragmentSpreads: TFragmentType, ... }) => ?TData),
     TKey,
   >,
-> {
+  loadNext: LoadMoreFn<TVariables>,
+  loadPrevious: LoadMoreFn<TVariables>,
+  hasNext: boolean,
+  hasPrevious: boolean,
+  refetch: RefetchFn<TVariables, TKey>,
+};
+
+function useBlockingPaginationFragment<
+  TFragmentType: FragmentType,
+  TVariables: Variables,
+  TData,
+  TKey: ?{+$fragmentSpreads: TFragmentType, ...},
+>(
+  fragmentInput: RefetchableFragment<TFragmentType, TData, TVariables>,
+  parentFragmentRef: TKey,
+  componentDisplayName: string = 'useBlockingPaginationFragment()',
+): ReturnType<TVariables, TData, TKey> {
   const fragmentNode = getFragment(fragmentInput);
   useStaticFragmentNodeWarning(
     fragmentNode,
@@ -88,33 +106,39 @@ function useBlockingPaginationFragment<
     refetch,
     disableStoreUpdates,
     enableStoreUpdates,
-  } = useRefetchableFragmentNode<TQuery, TKey>(
-    fragmentNode,
-    parentFragmentRef,
-    componentDisplayName,
-  );
+  } = useRefetchableFragmentNode<
+    {
+      response: TData,
+      variables: TVariables,
+    },
+    {
+      +$data: mixed,
+      ...
+    },
+  >(fragmentNode, parentFragmentRef, componentDisplayName);
   const fragmentIdentifier = getFragmentIdentifier(fragmentNode, fragmentRef);
 
   // Backward pagination
-  const [loadPrevious, hasPrevious, disposeFetchPrevious] = useLoadMore<TQuery>(
-    {
-      componentDisplayName,
-      connectionPathInFragmentData,
-      direction: 'backward',
-      disableStoreUpdates,
-      enableStoreUpdates,
-      fragmentData,
-      fragmentIdentifier,
-      fragmentNode,
-      fragmentRef,
-      identifierField,
-      paginationMetadata,
-      paginationRequest,
-    },
-  );
+  const [loadPrevious, hasPrevious, disposeFetchPrevious] = useLoadMore<
+    TVariables,
+    TData,
+  >({
+    componentDisplayName,
+    connectionPathInFragmentData,
+    direction: 'backward',
+    disableStoreUpdates,
+    enableStoreUpdates,
+    fragmentData,
+    fragmentIdentifier,
+    fragmentNode,
+    fragmentRef,
+    identifierField,
+    paginationMetadata,
+    paginationRequest,
+  });
 
   // Forward pagination
-  const [loadNext, hasNext, disposeFetchNext] = useLoadMore<TQuery>({
+  const [loadNext, hasNext, disposeFetchNext] = useLoadMore<TVariables, TData>({
     componentDisplayName,
     connectionPathInFragmentData,
     direction: 'forward',
@@ -129,8 +153,8 @@ function useBlockingPaginationFragment<
     paginationRequest,
   });
 
-  const refetchPagination: RefetchFnDynamic<TQuery, TKey> = useCallback(
-    (variables, options) => {
+  const refetchPagination: RefetchFn<TVariables, TKey> = useCallback(
+    (variables: TVariables, options: void | Options) => {
       disposeFetchNext();
       disposeFetchPrevious();
       return refetch(variables, {...options, __environment: undefined});
@@ -139,7 +163,8 @@ function useBlockingPaginationFragment<
   );
 
   return {
-    data: fragmentData,
+    // $FlowFixMe[incompatible-cast]
+    data: (fragmentData: TData),
     loadNext,
     loadPrevious,
     hasNext,
@@ -148,7 +173,7 @@ function useBlockingPaginationFragment<
   };
 }
 
-function useLoadMore<TQuery: OperationType>(args: {|
+function useLoadMore<TVariables: Variables>(args: {
   disableStoreUpdates: () => void,
   enableStoreUpdates: () => void,
   ...$Exact<
@@ -161,11 +186,13 @@ function useLoadMore<TQuery: OperationType>(args: {|
       },
     >,
   >,
-|}): [LoadMoreFn<TQuery>, boolean, () => void] {
+}): [LoadMoreFn<TVariables>, boolean, () => void] {
   const {disableStoreUpdates, enableStoreUpdates, ...loadMoreArgs} = args;
-  const [requestPromise, setRequestPromise] = useState(null);
-  const requestPromiseRef = useRef(null);
-  const promiseResolveRef = useRef(null);
+  const [requestPromise, setRequestPromise] = useState<null | Promise<mixed>>(
+    null,
+  );
+  const requestPromiseRef = useRef<null | Promise<mixed>>(null);
+  const promiseResolveRef = useRef<null | (() => void)>(null);
 
   const promiseResolve = () => {
     if (promiseResolveRef.current != null) {
@@ -210,7 +237,7 @@ function useLoadMore<TQuery: OperationType>(args: {|
     // and blow away the whole list of items.
     error: promiseResolve,
   };
-  const [loadMore, hasMore, disposeFetch] = useLoadMoreFunction<TQuery>({
+  const [loadMore, hasMore, disposeFetch] = useLoadMoreFunction<TVariables>({
     ...loadMoreArgs,
     observer,
     onReset: handleReset,

package/relay-hooks/useClientQuery.js.flow

@@ -0,0 +1,39 @@
+/**
+ * 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 {ClientQuery, Query, RenderPolicy, Variables} from 'relay-runtime';
+
+const useLazyLoadQuery = require('./useLazyLoadQuery');
+
+/**
+ * This hook can be used to render client-only queries.
+ * These queries are consist of queries for client-only data,
+ * schematized via local schema extensions and/or Relay resolvers.
+ */
+function useClientQuery<TVariables: Variables, TData>(
+  gqlQuery: ClientQuery<TVariables, TData>,
+  variables: TVariables,
+  options?: {
+    UNSTABLE_renderPolicy?: RenderPolicy,
+  },
+): TData {
+  // $FlowFixMe[incompatible-type] client queries can be used with useLazyLoadQuery, but only with `store-only` policy.
+  const query: Query<TVariables, TData> = gqlQuery;
+
+  return useLazyLoadQuery(query, variables, {
+    ...options,
+    fetchPolicy: 'store-only',
+  });
+}
+
+module.exports = useClientQuery;

package/relay-hooks/useEntryPointLoader.js.flow

@@ -4,13 +4,11 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
 import type {
@@ -47,9 +45,9 @@ type UseEntryPointLoaderHookReturnType<
 // NullEntryPointReference needs to implement referential equality,
 // so that multiple NullEntryPointReferences can be in the same set
 // (corresponding to multiple calls to disposeEntryPoint).
-type NullEntryPointReference = {|
+type NullEntryPointReference = {
   kind: 'NullEntryPointReference',
-|};
+};
 const initialNullEntryPointReferenceState = {kind: 'NullEntryPointReference'};
 
 function useLoadEntryPoint<
@@ -68,14 +66,14 @@ function useLoadEntryPoint<
 >(
   environmentProvider: IEnvironmentProvider<EnvironmentProviderOptions>,
   entryPoint: TEntryPoint,
-  options?: ?{|
+  options?: ?{
     // TODO(T83890478): Remove once Offscreen API lands in xplat
     // and we can use it in tests
-    TEST_ONLY__initialEntryPointData?: ?{|
+    TEST_ONLY__initialEntryPointData?: ?{
       entryPointReference: ?PreloadedEntryPoint<TEntryPointComponent>,
       entryPointParams: ?TEntryPointParams,
-    |},
-  |},
+    },
+  },
 ): UseEntryPointLoaderHookReturnType<
   TEntryPointParams,
   TPreloadedQueries,
@@ -136,11 +134,15 @@ function useLoadEntryPoint<
   const entryPointLoaderCallback = useCallback(
     (params: TEntryPointParams) => {
       if (isMountedRef.current) {
-        const updatedEntryPointReference = loadEntryPoint(
-          environmentProvider,
-          entryPoint,
-          params,
-        );
+        const updatedEntryPointReference = loadEntryPoint<
+          TEntryPointParams,
+          TPreloadedQueries,
+          TPreloadedEntryPoints,
+          TRuntimeProps,
+          TExtraProps,
+          TEntryPointComponent,
+          TEntryPoint,
+        >(environmentProvider, entryPoint, params);
         undisposedEntryPointReferencesRef.current.add(
           updatedEntryPointReference,
         );

package/relay-hooks/useFetchTrackingRef.js.flow

@@ -4,18 +4,17 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
 import type {Subscription} from 'relay-runtime';
 
-const {useCallback, useEffect, useRef} = require('react');
+const useUnsafeRef_DEPRECATED = require('./useUnsafeRef_DEPRECATED');
+const {useCallback, useEffect} = require('react');
 
 /**
  * This hook returns a mutable React ref that holds the value of whether a
@@ -29,14 +28,14 @@ const {useCallback, useEffect, useRef} = require('react');
  * The additional functions returned by this Hook can be used to mutate
  * the ref.
  */
-function useFetchTrackingRef(): {|
+function useFetchTrackingRef(): {
   isFetchingRef: {current: ?boolean, ...},
   startFetch: Subscription => void,
   disposeFetch: () => void,
   completeFetch: () => void,
-|} {
-  const subscriptionRef = useRef<?Subscription>(null);
-  const isFetchingRef = useRef<?boolean>(false);
+} {
+  const subscriptionRef = useUnsafeRef_DEPRECATED<?Subscription>(null);
+  const isFetchingRef = useUnsafeRef_DEPRECATED<?boolean>(false);
 
   const disposeFetch = useCallback(() => {
     if (subscriptionRef.current != null) {

package/relay-hooks/useFragment.js.flow

@@ -4,13 +4,11 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
 import type {Fragment, FragmentType, GraphQLTaggedNode} from 'relay-runtime';
@@ -52,7 +50,7 @@ function useFragment_LEGACY(fragment: GraphQLTaggedNode, key: mixed): mixed {
 
   const fragmentNode = getFragment(fragment);
   useStaticFragmentNodeWarning(fragmentNode, 'first argument of useFragment()');
-  const {data} = useFragmentNode<_>(fragmentNode, key, 'useFragment()');
+  const {data} = useFragmentNode<mixed>(fragmentNode, key, 'useFragment()');
   if (__DEV__) {
     // eslint-disable-next-line react-hooks/rules-of-hooks
     useDebugValue({fragment: fragmentNode.name, data});

package/relay-hooks/useFragmentNode.js.flow

@@ -4,28 +4,27 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
 import type {ReaderFragment} from 'relay-runtime';
 
 const {getFragmentResourceForEnvironment} = require('./FragmentResource');
 const useRelayEnvironment = require('./useRelayEnvironment');
-const {useEffect, useRef, useState} = require('react');
+const useUnsafeRef_DEPRECATED = require('./useUnsafeRef_DEPRECATED');
+const {useEffect, useState} = require('react');
 const {getFragmentIdentifier} = require('relay-runtime');
 const warning = require('warning');
 
-type ReturnType<TFragmentData: mixed> = {|
+type ReturnType<TFragmentData: mixed> = {
   data: TFragmentData,
   disableStoreUpdates: () => void,
   enableStoreUpdates: () => void,
-|};
+};
 
 function useFragmentNode<TFragmentData: mixed>(
   fragmentNode: ReaderFragment,
@@ -35,7 +34,7 @@ function useFragmentNode<TFragmentData: mixed>(
   const environment = useRelayEnvironment();
   const FragmentResource = getFragmentResourceForEnvironment(environment);
 
-  const isMountedRef = useRef(false);
+  const isMountedRef = useUnsafeRef_DEPRECATED(false);
   const [, forceUpdate] = useState(0);
   const fragmentIdentifier = getFragmentIdentifier(fragmentNode, fragmentRef);
 
@@ -47,7 +46,7 @@ function useFragmentNode<TFragmentData: mixed>(
     componentDisplayName,
   );
 
-  const isListeningForUpdatesRef = useRef(true);
+  const isListeningForUpdatesRef = useUnsafeRef_DEPRECATED(true);
   function enableStoreUpdates() {
     isListeningForUpdatesRef.current = true;
     const didMissUpdates =

package/relay-hooks/useIsMountedRef.js.flow

@@ -4,18 +4,16 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
 const {useEffect, useRef} = require('react');
 
-function useIsMountedRef(): {|current: boolean|} {
+function useIsMountedRef(): {current: boolean} {
   const isMountedRef = useRef(true);
 
   useEffect(() => {

package/relay-hooks/useIsOperationNodeActive.js.flow

@@ -4,9 +4,9 @@
  * 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
+ * @oncall relay
  */
 
 'use strict';

package/relay-hooks/useIsParentQueryActive.js.flow

@@ -4,9 +4,9 @@
  * 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
+ * @oncall relay
  */
 
 'use strict';

package/relay-hooks/useLazyLoadQuery.js.flow

@@ -4,25 +4,21 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
 import type {
   CacheConfig,
-  ClientQuery,
   FetchPolicy,
   Query,
   RenderPolicy,
   Variables,
 } from 'relay-runtime';
 
-const HooksImplementation = require('./HooksImplementation');
 const {useTrackLoadQueryInRender} = require('./loadQuery');
 const useLazyLoadQueryNode = require('./useLazyLoadQueryNode');
 const useMemoOperationDescriptor = require('./useMemoOperationDescriptor');
@@ -35,25 +31,25 @@ const {
 // a separate hooks implementation in ./HooksImplementation -- it can
 // be removed after we stop doing that.
 export type UseLazyLoadQueryHookType = <TVariables: Variables, TData>(
-  gqlQuery: Query<TVariables, TData> | ClientQuery<TVariables, TData>,
+  gqlQuery: Query<TVariables, TData>,
   variables: TVariables,
-  options?: {|
+  options?: {
     fetchKey?: string | number,
     fetchPolicy?: FetchPolicy,
     networkCacheConfig?: CacheConfig,
     UNSTABLE_renderPolicy?: RenderPolicy,
-  |},
+  },
 ) => TData;
 
-function useLazyLoadQuery_LEGACY<TVariables: Variables, TData>(
-  gqlQuery: Query<TVariables, TData> | ClientQuery<TVariables, TData>,
+function useLazyLoadQuery<TVariables: Variables, TData>(
+  gqlQuery: Query<TVariables, TData>,
   variables: TVariables,
-  options?: {|
+  options?: {
     fetchKey?: string | number,
     fetchPolicy?: FetchPolicy,
     networkCacheConfig?: CacheConfig,
     UNSTABLE_renderPolicy?: RenderPolicy,
-  |},
+  },
 ): TData {
   // We need to use this hook in order to be able to track if
   // loadQuery was called during render
@@ -68,7 +64,7 @@ function useLazyLoadQuery_LEGACY<TVariables: Variables, TData>(
       ? options.networkCacheConfig
       : {force: true},
   );
-  const data = useLazyLoadQueryNode({
+  const data = useLazyLoadQueryNode<$FlowFixMe>({
     componentDisplayName: 'useLazyLoadQuery()',
     fetchKey: options?.fetchKey,
     fetchObservable: fetchQuery(environment, query),
@@ -79,23 +75,4 @@ function useLazyLoadQuery_LEGACY<TVariables: Variables, TData>(
   return data;
 }
 
-function useLazyLoadQuery<TVariables: Variables, TData>(
-  gqlQuery: Query<TVariables, TData> | ClientQuery<TVariables, TData>,
-  variables: TVariables,
-  options?: {|
-    fetchKey?: string | number,
-    fetchPolicy?: FetchPolicy,
-    networkCacheConfig?: CacheConfig,
-    UNSTABLE_renderPolicy?: RenderPolicy,
-  |},
-): TData {
-  const impl = HooksImplementation.get();
-  if (impl) {
-    return impl.useLazyLoadQuery(gqlQuery, variables, options);
-  } else {
-    // eslint-disable-next-line react-hooks/rules-of-hooks
-    return useLazyLoadQuery_LEGACY(gqlQuery, variables, options);
-  }
-}
-
 module.exports = (useLazyLoadQuery: UseLazyLoadQueryHookType);

package/relay-hooks/useLazyLoadQueryNode.js.flow

@@ -4,13 +4,11 @@
  * 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
+ * @oncall relay
  */
 
-// flowlint ambiguous-object-type:error
-
 'use strict';
 
 import type {
@@ -41,14 +39,14 @@ function useLazyLoadQueryNode<TQuery: OperationType>({
   fetchPolicy,
   fetchKey,
   renderPolicy,
-}: {|
+}: {
   query: OperationDescriptor,
   componentDisplayName: string,
   fetchObservable: Observable<GraphQLResponse>,
   fetchPolicy?: ?FetchPolicy,
   fetchKey?: ?string | ?number,
   renderPolicy?: ?RenderPolicy,
-|}): TQuery['response'] {
+}): TQuery['response'] {
   const environment = useRelayEnvironment();
   const profilerContext = useContext(ProfilerContext);
   const QueryResource = getQueryResourceForEnvironment(environment);
@@ -127,7 +125,7 @@ function useLazyLoadQueryNode<TQuery: OperationType>({
   });
 
   const {fragmentNode, fragmentRef} = preparedQueryResult;
-  const {data} = useFragmentNode(
+  const {data} = useFragmentNode<$FlowFixMe>(
     fragmentNode,
     fragmentRef,
     componentDisplayName,