react-relay 13.1.1 → 14.1.0

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

@@ -0,0 +1,70 @@
+/**
+ * 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
+ * @emails oncall+relay
+ * @format
+ */
+
+'use strict';
+
+import type {
+  CacheConfig,
+  FetchPolicy,
+  Query,
+  RenderPolicy,
+  Variables,
+} from 'relay-runtime';
+
+const {useTrackLoadQueryInRender} = require('../loadQuery');
+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>,
+  variables: TVariables,
+  options?: {
+    fetchKey?: string | number,
+    fetchPolicy?: FetchPolicy,
+    networkCacheConfig?: CacheConfig,
+    UNSTABLE_renderPolicy?: RenderPolicy,
+  },
+): TData {
+  useTrackLoadQueryInRender();
+  const environment = useRelayEnvironment();
+
+  const queryOperationDescriptor = useMemoOperationDescriptor(
+    gqlQuery,
+    variables,
+    options?.networkCacheConfig ?? {force: true},
+  );
+
+  // Get the query going if needed -- this may suspend.
+  const [queryResult, effect] = getQueryResultOrFetchQuery(
+    environment,
+    queryOperationDescriptor,
+    {
+      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,
+  });
+}
+
+module.exports = useLazyLoadQuery_REACT_CACHE;

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

@@ -0,0 +1,171 @@
+/**
+ * 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
+ */
+
+'use strict';
+
+import type {LoadMoreFn, UseLoadMoreFunctionArgs} from '../useLoadMoreFunction';
+import type {RefetchFnDynamic} from './useRefetchableFragmentInternal_REACT_CACHE';
+import type {
+  FragmentType,
+  GraphQLResponse,
+  GraphQLTaggedNode,
+  Observer,
+  OperationType,
+} from 'relay-runtime';
+
+const useLoadMoreFunction = require('../useLoadMoreFunction');
+const useStaticFragmentNodeWarning = require('../useStaticFragmentNodeWarning');
+const useRefetchableFragmentInternal = require('./useRefetchableFragmentInternal_REACT_CACHE');
+const {useCallback, useDebugValue, useState} = require('react');
+const {
+  getFragment,
+  getFragmentIdentifier,
+  getPaginationMetadata,
+} = require('relay-runtime');
+
+export type ReturnType<TQuery: OperationType, TKey, TFragmentData> = {
+  data: TFragmentData,
+  loadNext: LoadMoreFn<TQuery>,
+  loadPrevious: LoadMoreFn<TQuery>,
+  hasNext: boolean,
+  hasPrevious: boolean,
+  isLoadingNext: boolean,
+  isLoadingPrevious: boolean,
+  refetch: RefetchFnDynamic<TQuery, TKey>,
+};
+
+function usePaginationFragment<
+  TQuery: OperationType,
+  TKey: ?{+$data?: mixed, +$fragmentSpreads: FragmentType, ...},
+>(
+  fragmentInput: GraphQLTaggedNode,
+  parentFragmentRef: TKey,
+): ReturnType<
+  TQuery,
+  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),
+    TKey,
+  >,
+> {
+  const fragmentNode = getFragment(fragmentInput);
+  useStaticFragmentNodeWarning(
+    fragmentNode,
+    'first argument of usePaginationFragment()',
+  );
+  const componentDisplayName = 'usePaginationFragment()';
+
+  const {
+    connectionPathInFragmentData,
+    paginationRequest,
+    paginationMetadata,
+    identifierField,
+  } = getPaginationMetadata(fragmentNode, componentDisplayName);
+
+  const {fragmentData, fragmentRef, refetch} = useRefetchableFragmentInternal<
+    TQuery,
+    TKey,
+  >(fragmentNode, parentFragmentRef, componentDisplayName);
+  const fragmentIdentifier = getFragmentIdentifier(fragmentNode, fragmentRef);
+
+  // Backward pagination
+  const [loadPrevious, hasPrevious, isLoadingPrevious, disposeFetchPrevious] =
+    useLoadMore<TQuery>({
+      componentDisplayName,
+      connectionPathInFragmentData,
+      direction: 'backward',
+      fragmentData,
+      fragmentIdentifier,
+      fragmentNode,
+      fragmentRef,
+      identifierField,
+      paginationMetadata,
+      paginationRequest,
+    });
+
+  // Forward pagination
+  const [loadNext, hasNext, isLoadingNext, disposeFetchNext] =
+    useLoadMore<TQuery>({
+      componentDisplayName,
+      connectionPathInFragmentData,
+      direction: 'forward',
+      fragmentData,
+      fragmentIdentifier,
+      fragmentNode,
+      fragmentRef,
+      identifierField,
+      paginationMetadata,
+      paginationRequest,
+    });
+
+  const refetchPagination: RefetchFnDynamic<TQuery, TKey> = useCallback(
+    (variables, options) => {
+      disposeFetchNext();
+      disposeFetchPrevious();
+      return refetch(variables, {...options, __environment: undefined});
+    },
+    [disposeFetchNext, disposeFetchPrevious, refetch],
+  );
+
+  if (__DEV__) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useDebugValue({
+      fragment: fragmentNode.name,
+      data: fragmentData,
+      hasNext,
+      isLoadingNext,
+      hasPrevious,
+      isLoadingPrevious,
+    });
+  }
+  return {
+    data: fragmentData,
+    loadNext,
+    loadPrevious,
+    hasNext,
+    hasPrevious,
+    isLoadingNext,
+    isLoadingPrevious,
+    refetch: refetchPagination,
+  };
+}
+
+function useLoadMore<TQuery: OperationType>(
+  args: $Diff<
+    UseLoadMoreFunctionArgs,
+    {
+      observer: Observer<GraphQLResponse>,
+      onReset: () => void,
+      ...
+    },
+  >,
+): [LoadMoreFn<TQuery>, boolean, boolean, () => void] {
+  const [isLoadingMore, setIsLoadingMore] = useState(false);
+  const observer = {
+    start: () => setIsLoadingMore(true),
+    complete: () => setIsLoadingMore(false),
+    error: () => setIsLoadingMore(false),
+  };
+  const handleReset = () => setIsLoadingMore(false);
+  const [loadMore, hasMore, disposeFetch] = useLoadMoreFunction({
+    ...args,
+    observer,
+    onReset: handleReset,
+  });
+  return [loadMore, hasMore, isLoadingMore, disposeFetch];
+}
+
+module.exports = usePaginationFragment;

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

@@ -0,0 +1,151 @@
+/**
+ * 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
+ * @emails oncall+relay
+ * @format
+ */
+
+'use strict';
+
+import type {PreloadedQuery} from '../EntryPointTypes.flow';
+import type {
+  GraphQLTaggedNode,
+  OperationType,
+  RenderPolicy,
+} from 'relay-runtime';
+
+const {useTrackLoadQueryInRender} = require('../loadQuery');
+const useMemoOperationDescriptor = require('../useMemoOperationDescriptor');
+const useRelayEnvironment = require('../useRelayEnvironment');
+const getQueryResultOrFetchQuery = require('./getQueryResultOrFetchQuery_REACT_CACHE');
+const useFragmentInternal = require('./useFragmentInternal_REACT_CACHE');
+const invariant = require('invariant');
+const {useDebugValue, useEffect} = require('react');
+const {
+  __internal: {fetchQueryDeduped, fetchQuery},
+} = require('relay-runtime');
+const warning = require('warning');
+
+function usePreloadedQuery_REACT_CACHE<TQuery: OperationType>(
+  gqlQuery: GraphQLTaggedNode,
+  preloadedQuery: PreloadedQuery<TQuery>,
+  options?: {
+    UNSTABLE_renderPolicy?: RenderPolicy,
+  },
+): TQuery['response'] {
+  const environment = useRelayEnvironment();
+
+  useTrackLoadQueryInRender();
+
+  const {fetchKey, fetchPolicy, source, variables, networkCacheConfig} =
+    preloadedQuery;
+  const operation = useMemoOperationDescriptor(
+    gqlQuery,
+    variables,
+    networkCacheConfig,
+  );
+
+  let fetchObservable;
+  if (preloadedQuery.kind === 'PreloadedQuery_DEPRECATED') {
+    invariant(
+      operation.request.node.params.name === preloadedQuery.name,
+      'usePreloadedQuery(): Expected data to be prefetched for query `%s`, ' +
+        'got prefetch results for query `%s`.',
+      operation.request.node.params.name,
+      preloadedQuery.name,
+    );
+    fetchObservable = fetchQueryDeduped(
+      environment,
+      operation.request.identifier,
+      () => {
+        if (environment === preloadedQuery.environment && source != null) {
+          return environment.executeWithSource({operation, source});
+        } else {
+          return environment.execute({operation});
+        }
+      },
+    );
+  } else {
+    warning(
+      preloadedQuery.isDisposed === false,
+      'usePreloadedQuery(): Expected preloadedQuery to not be disposed yet. ' +
+        'This is because disposing the query marks it for future garbage ' +
+        'collection, and as such query results may no longer be present in the Relay ' +
+        'store. In the future, this will become a hard error.',
+    );
+    const fallbackFetchObservable = fetchQuery(environment, operation);
+    if (source != null && environment === preloadedQuery.environment) {
+      // If the source observable exists and the environments match, reuse
+      // the source observable.
+      // If the source observable happens to be empty, we need to fall back
+      // and re-execute and de-dupe the query (at render time).
+      fetchObservable = source.ifEmpty(fallbackFetchObservable);
+    } else if (environment !== preloadedQuery.environment) {
+      // If a call to loadQuery is made with a particular environment, and that
+      // preloaded query is passed to usePreloadedQuery in a different environment
+      // context, we cannot re-use the existing preloaded query.
+      // Instead, we need to fall back and re-execute and de-dupe the query with
+      // the new environment (at render time).
+      // TODO T68036756 track occurences of this warning and turn it into a hard error
+      warning(
+        false,
+        'usePreloadedQuery(): usePreloadedQuery was passed a preloaded query ' +
+          'that was created with a different environment than the one that is currently ' +
+          'in context. In the future, this will become a hard error.',
+      );
+      fetchObservable = fallbackFetchObservable;
+    } else {
+      // if (source == null)
+      // If the source observable does not exist, we need to
+      // fall back and re-execute and de-dupe the query (at render time).
+      fetchObservable = fallbackFetchObservable;
+    }
+  }
+
+  // Get the query going if needed -- this may suspend.
+  const [queryResult, effect] = getQueryResultOrFetchQuery(
+    environment,
+    operation,
+    {
+      fetchPolicy,
+      renderPolicy: options?.UNSTABLE_renderPolicy,
+      fetchKey,
+      fetchObservable,
+    },
+  );
+
+  useEffect(effect);
+
+  // Read the query's root fragment -- this may suspend.
+  const {fragmentNode, fragmentRef} = queryResult;
+  // $FlowExpectedError[incompatible-return] Is this a fixable incompatible-return?
+  const data = useFragmentInternal(
+    fragmentNode,
+    fragmentRef,
+    'usePreloadedQuery()',
+    {
+      fetchPolicy: fetchPolicy,
+      networkCacheConfig: networkCacheConfig,
+    },
+  );
+
+  if (__DEV__) {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useDebugValue({
+      query: preloadedQuery.name,
+      variables: preloadedQuery.variables,
+      data,
+      fetchKey,
+      fetchPolicy,
+      renderPolicy: options?.UNSTABLE_renderPolicy,
+    });
+  }
+
+  return data;
+}
+
+module.exports = usePreloadedQuery_REACT_CACHE;