react-relay 18.0.0 → 18.2.0

package/relay-hooks/useLoadMoreFunction_EXPERIMENTAL.js.flow

@@ -0,0 +1,280 @@
+/**
+ * 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 {
+  ConcreteRequest,
+  Direction,
+  Disposable,
+  GraphQLResponse,
+  Observer,
+  ReaderFragment,
+  ReaderPaginationMetadata,
+  Subscription,
+  Variables,
+} from 'relay-runtime';
+
+const getConnectionState = require('./getConnectionState');
+const useIsMountedRef = require('./useIsMountedRef');
+const useIsOperationNodeActive = require('./useIsOperationNodeActive');
+const useRelayEnvironment = require('./useRelayEnvironment');
+const invariant = require('invariant');
+const {useCallback, useRef, useState} = require('react');
+const {
+  __internal: {fetchQuery},
+  createOperationDescriptor,
+  getPaginationVariables,
+  getRefetchMetadata,
+  getSelector,
+} = require('relay-runtime');
+const warning = require('warning');
+
+export type LoadMoreFn<TVariables: Variables> = (
+  count: number,
+  options?: {
+    onComplete?: (Error | null) => void,
+    UNSTABLE_extraVariables?: Partial<TVariables>,
+  },
+) => Disposable;
+
+export type UseLoadMoreFunctionArgs = {
+  direction: Direction,
+  fragmentNode: ReaderFragment,
+  fragmentRef: mixed,
+  fragmentIdentifier: string,
+  fragmentData: mixed,
+  connectionPathInFragmentData: $ReadOnlyArray<string | number>,
+  paginationRequest: ConcreteRequest,
+  paginationMetadata: ReaderPaginationMetadata,
+  componentDisplayName: string,
+  observer: Observer<GraphQLResponse>,
+  onReset: () => void,
+};
+
+hook useLoadMoreFunction_EXPERIMENTAL<TVariables: Variables>(
+  args: UseLoadMoreFunctionArgs,
+): [
+  // Function to load more data
+  LoadMoreFn<TVariables>,
+  // Whether the connection has more data to load
+  boolean,
+  // Force dispose function which cancels the in-flight fetch itself, and callbacks
+  () => void,
+] {
+  const {
+    direction,
+    fragmentNode,
+    fragmentRef,
+    fragmentIdentifier,
+    fragmentData,
+    connectionPathInFragmentData,
+    paginationRequest,
+    paginationMetadata,
+    componentDisplayName,
+    observer,
+    onReset,
+  } = args;
+  const environment = useRelayEnvironment();
+
+  const {identifierInfo} = getRefetchMetadata(
+    fragmentNode,
+    componentDisplayName,
+  );
+  const identifierValue =
+    identifierInfo?.identifierField != null &&
+    fragmentData != null &&
+    typeof fragmentData === 'object'
+      ? fragmentData[identifierInfo.identifierField]
+      : null;
+
+  const fetchStatusRef = useRef<
+    {kind: 'fetching', subscription: Subscription} | {kind: 'none'},
+  >({kind: 'none'});
+  const [mirroredEnvironment, setMirroredEnvironment] = useState(environment);
+  const [mirroredFragmentIdentifier, setMirroredFragmentIdentifier] =
+    useState(fragmentIdentifier);
+
+  const isParentQueryActive = useIsOperationNodeActive(
+    fragmentNode,
+    fragmentRef,
+  );
+
+  const forceDisposeFn = useCallback(() => {
+    // $FlowFixMe[react-rule-unsafe-ref]
+    if (fetchStatusRef.current.kind === 'fetching') {
+      // $FlowFixMe[react-rule-unsafe-ref]
+      fetchStatusRef.current.subscription.unsubscribe();
+    }
+    // $FlowFixMe[react-rule-unsafe-ref]
+    fetchStatusRef.current = {kind: 'none'};
+  }, []);
+
+  const shouldReset =
+    environment !== mirroredEnvironment ||
+    fragmentIdentifier !== mirroredFragmentIdentifier;
+  if (shouldReset) {
+    forceDisposeFn();
+    onReset();
+    setMirroredEnvironment(environment);
+    setMirroredFragmentIdentifier(fragmentIdentifier);
+  }
+
+  const {cursor, hasMore} = getConnectionState(
+    direction,
+    fragmentNode,
+    fragmentData,
+    connectionPathInFragmentData,
+  );
+
+  const isMountedRef = useIsMountedRef();
+  const loadMore = useCallback(
+    (
+      count: number,
+      options: void | {
+        UNSTABLE_extraVariables?: Partial<TVariables>,
+        onComplete?: (Error | null) => void,
+      },
+    ) => {
+      // TODO(T41131846): Fetch/Caching policies for loadMore
+
+      const onComplete = options?.onComplete;
+      if (isMountedRef.current !== true) {
+        // Bail out and warn if we're trying to paginate after the component
+        // has unmounted
+        warning(
+          false,
+          'Relay: Unexpected fetch on unmounted component for fragment ' +
+            '`%s` in `%s`. It looks like some instances of your component are ' +
+            'still trying to fetch data but they already unmounted. ' +
+            'Please make sure you clear all timers, intervals, ' +
+            'async calls, etc that may trigger a fetch.',
+          fragmentNode.name,
+          componentDisplayName,
+        );
+        return {dispose: () => {}};
+      }
+
+      const fragmentSelector = getSelector(fragmentNode, fragmentRef);
+      if (
+        fetchStatusRef.current.kind === 'fetching' ||
+        fragmentData == null ||
+        isParentQueryActive
+      ) {
+        if (fragmentSelector == null) {
+          warning(
+            false,
+            'Relay: Unexpected fetch while using a null fragment ref ' +
+              'for fragment `%s` in `%s`. When fetching more items, we expect ' +
+              "initial fragment data to be non-null. Please make sure you're " +
+              'passing a valid fragment ref to `%s` before paginating.',
+            fragmentNode.name,
+            componentDisplayName,
+            componentDisplayName,
+          );
+        }
+
+        if (onComplete) {
+          onComplete(null);
+        }
+        return {dispose: () => {}};
+      }
+
+      invariant(
+        fragmentSelector != null &&
+          fragmentSelector.kind !== 'PluralReaderSelector',
+        'Relay: Expected to be able to find a non-plural fragment owner for ' +
+          "fragment `%s` when using `%s`. If you're seeing this, " +
+          'this is likely a bug in Relay.',
+        fragmentNode.name,
+        componentDisplayName,
+      );
+
+      const parentVariables = fragmentSelector.owner.variables;
+      const fragmentVariables = fragmentSelector.variables;
+      const extraVariables = options?.UNSTABLE_extraVariables;
+      const baseVariables = {
+        ...parentVariables,
+        ...fragmentVariables,
+      };
+      const paginationVariables = getPaginationVariables(
+        direction,
+        count,
+        cursor,
+        baseVariables,
+        {...extraVariables},
+        paginationMetadata,
+      );
+
+      // If the query needs an identifier value ('id' or similar) and one
+      // was not explicitly provided, read it from the fragment data.
+      if (identifierInfo != null) {
+        // @refetchable fragments are guaranteed to have an `id` selection
+        // if the type is Node, implements Node, or is @fetchable. Double-check
+        // that there actually is a value at runtime.
+        if (typeof identifierValue !== 'string') {
+          warning(
+            false,
+            'Relay: Expected result to have a string  ' +
+              '`%s` in order to refetch, got `%s`.',
+            identifierInfo.identifierField,
+            identifierValue,
+          );
+        }
+        paginationVariables[identifierInfo.identifierQueryVariableName] =
+          identifierValue;
+      }
+
+      const paginationQuery = createOperationDescriptor(
+        paginationRequest,
+        paginationVariables,
+        {force: true},
+      );
+      fetchQuery(environment, paginationQuery).subscribe({
+        ...observer,
+        start: subscription => {
+          fetchStatusRef.current = {kind: 'fetching', subscription};
+          observer.start && observer.start(subscription);
+        },
+        complete: () => {
+          fetchStatusRef.current = {kind: 'none'};
+          observer.complete && observer.complete();
+          onComplete && onComplete(null);
+        },
+        error: error => {
+          fetchStatusRef.current = {kind: 'none'};
+          observer.complete && observer.complete();
+          onComplete && onComplete(error);
+        },
+      });
+      return {
+        dispose: () => {},
+      };
+    },
+    // NOTE: We disable react-hooks-deps warning because all values
+    // inside paginationMetadata are static
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [
+      environment,
+      identifierValue,
+      direction,
+      cursor,
+      isParentQueryActive,
+      fragmentData,
+      fragmentNode.name,
+      fragmentRef,
+      componentDisplayName,
+    ],
+  );
+  return [loadMore, hasMore, forceDisposeFn];
+}
+
+module.exports = useLoadMoreFunction_EXPERIMENTAL;

package/relay-hooks/usePrefetchableForwardPaginationFragment_EXPERIMENTAL.js.flow

@@ -0,0 +1,433 @@
+/**
+ * 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 {RefetchFn} from './useRefetchableFragment';
+import type {Options} from './useRefetchableFragmentInternal';
+import type {FragmentType, Variables} from 'relay-runtime';
+import type {PrefetchableRefetchableFragment} from 'relay-runtime';
+
+const useFragment = require('./useFragment');
+const useLoadMoreFunction = require('./useLoadMoreFunction');
+const useRefetchableFragmentInternal = require('./useRefetchableFragmentInternal');
+const useRelayEnvironment = require('./useRelayEnvironment');
+const useStaticFragmentNodeWarning = require('./useStaticFragmentNodeWarning');
+const invariant = require('invariant');
+const {
+  useCallback,
+  useDebugValue,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} = require('react');
+const {
+  getFragment,
+  getFragmentIdentifier,
+  getPaginationMetadata,
+} = require('relay-runtime');
+const {
+  ConnectionInterface,
+  getSelector,
+  getValueAtPath,
+} = require('relay-runtime');
+
+type LoadMoreFn<TVariables: Variables> = (
+  count: number,
+  options?: {
+    onComplete?: (Error | null) => void,
+    UNSTABLE_extraVariables?: Partial<TVariables>,
+  },
+) => void;
+
+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, ...}]
+    ? TData
+    : ?TData,
+  loadNext: LoadMoreFn<TVariables>,
+  hasNext: boolean,
+  isLoadingNext: boolean,
+  refetch: RefetchFn<TVariables, TKey>,
+  edges: TEdgeData,
+};
+
+type LoadMoreOptions<TVariables> = {
+  UNSTABLE_extraVariables?: Partial<TVariables>,
+  onComplete?: (Error | null) => void,
+};
+
+export type GetExtraVariablesFn<TEdgeData, TData, TVariables, TKey> = ({
+  hasNext: boolean,
+  data: [+key: TKey] extends [+key: {+$fragmentSpreads: mixed, ...}]
+    ? TData
+    : ?TData,
+  getServerEdges: () => TEdgeData,
+}) => Partial<TVariables>;
+
+hook usePrefetchableForwardPaginationFragment_EXPERIMENTAL<
+  TFragmentType: FragmentType,
+  TVariables: Variables,
+  TData,
+  TEdgeData,
+  TKey: ?{+$fragmentSpreads: TFragmentType, ...},
+>(
+  fragmentInput: PrefetchableRefetchableFragment<
+    TFragmentType,
+    TData,
+    TEdgeData,
+    TVariables,
+  >,
+  parentFragmentRef: TKey,
+  bufferSize: number,
+  initialSize?: ?number,
+  prefetchingLoadMoreOptions?: {
+    UNSTABLE_extraVariables?:
+      | Partial<TVariables>
+      | GetExtraVariablesFn<TEdgeData, TData, TVariables, TKey>,
+    onComplete?: (Error | null) => void,
+  },
+  minimalFetchSize: number = 1,
+): ReturnType<TVariables, TData, TEdgeData, TKey> {
+  const fragmentNode = getFragment(fragmentInput);
+  useStaticFragmentNodeWarning(
+    fragmentNode,
+    'first argument of usePrefetchableForwardPaginationFragment_EXPERIMENTAL()',
+  );
+  const componentDisplayName =
+    'usePrefetchableForwardPaginationFragment_EXPERIMENTAL()';
+
+  const {connectionPathInFragmentData, paginationRequest, paginationMetadata} =
+    getPaginationMetadata(fragmentNode, componentDisplayName);
+
+  const {fragmentData, fragmentRef, refetch} = useRefetchableFragmentInternal<
+    {variables: TVariables, response: TData},
+    {data?: TData},
+  >(fragmentNode, parentFragmentRef, componentDisplayName);
+  // TODO: Get rid of `getFragmentIdentifier`
+  const fragmentIdentifier = getFragmentIdentifier(fragmentNode, fragmentRef);
+
+  const edgeKeys = useMemo(() => {
+    const connection = getValueAtPath(
+      fragmentData,
+      connectionPathInFragmentData,
+    );
+    if (connection == null) {
+      return null;
+    }
+    const {EDGES} = ConnectionInterface.get();
+    // $FlowFixMe[incompatible-use]
+    return connection[EDGES];
+  }, [connectionPathInFragmentData, fragmentData]);
+
+  const sourceSize = edgeKeys == null ? -1 : edgeKeys.length;
+
+  const [_numInUse, setNumInUse] = useState(
+    initialSize != null ? initialSize : sourceSize,
+  );
+  let numInUse = _numInUse;
+  // We can only reset the source size when the component is
+  // updated with new edgeKeys
+  if (_numInUse === -1 && sourceSize !== -1) {
+    numInUse = initialSize != null ? initialSize : sourceSize;
+    setNumInUse(numInUse);
+  }
+
+  const environment = useRelayEnvironment();
+  const [isLoadingMore, reallySetIsLoadingMore] = useState(false);
+  const [isRefetching, setIsRefetching] = useState(false);
+  const availableSizeRef = useRef(0);
+  // Schedule this update since it must be observed by components at the same
+  // batch as when hasNext changes. hasNext is read from the store and store
+  // updates are scheduled, so this must be scheduled too.
+  const setIsLoadingMore = useCallback(
+    (value: boolean) => {
+      const schedule = environment.getScheduler()?.schedule;
+      if (schedule) {
+        schedule(() => {
+          reallySetIsLoadingMore(value);
+        });
+      } else {
+        reallySetIsLoadingMore(value);
+      }
+    },
+    [environment],
+  );
+
+  // `isLoadingMore` state is updated in a low priority, internally we need
+  // to synchronously get the loading state to decide whether to load more
+  const isLoadingMoreRef = useRef(false);
+
+  const observer = useMemo(
+    () => ({
+      start: () => {
+        isLoadingMoreRef.current = true;
+        // We want to make sure that `isLoadingMore` is updated immediately, to avoid
+        // product code triggering multiple `loadMore` calls
+        reallySetIsLoadingMore(true);
+      },
+      complete: () => {
+        isLoadingMoreRef.current = false;
+        setIsLoadingMore(false);
+      },
+      error: () => {
+        isLoadingMoreRef.current = false;
+        setIsLoadingMore(false);
+      },
+    }),
+    [setIsLoadingMore],
+  );
+  const handleReset = useCallback(() => {
+    if (!isRefetching) {
+      // Do not reset items count during refetching
+      const schedule = environment.getScheduler()?.schedule;
+      if (schedule) {
+        schedule(() => {
+          setNumInUse(-1);
+        });
+      } else {
+        setNumInUse(-1);
+      }
+    }
+    isLoadingMoreRef.current = false;
+    setIsLoadingMore(false);
+  }, [environment, isRefetching, setIsLoadingMore]);
+
+  const [loadMore, hasNext, disposeFetchNext] = useLoadMoreFunction<TVariables>(
+    {
+      componentDisplayName,
+      connectionPathInFragmentData,
+      direction: 'forward',
+      fragmentData,
+      fragmentIdentifier,
+      fragmentNode,
+      fragmentRef,
+      paginationMetadata,
+      paginationRequest,
+      observer,
+      onReset: handleReset,
+    },
+  );
+
+  useLayoutEffect(() => {
+    // Make sure `availableSize` is updated before `showMore` from current render can be called
+    availableSizeRef.current = sourceSize - numInUse;
+  }, [numInUse, sourceSize]);
+
+  const prefetchingUNSTABLE_extraVariables =
+    prefetchingLoadMoreOptions?.UNSTABLE_extraVariables;
+  const prefetchingOnComplete = prefetchingLoadMoreOptions?.onComplete;
+
+  const showMore = useCallback(
+    (numToAdd: number, options?: LoadMoreOptions<TVariables>) => {
+      // Matches the behavior of `usePaginationFragment`. If there is a `loadMore` ongoing,
+      // the hook handles making the `loadMore` a no-op.
+      if (!isLoadingMoreRef.current || availableSizeRef.current >= 0) {
+        // Preemtively update `availableSizeRef`, so if two `loadMore` is called in the same tick,
+        // a second `loadMore` can be no-op
+        availableSizeRef.current -= numToAdd;
+
+        setNumInUse(lastNumInUse => {
+          return lastNumInUse + numToAdd;
+        });
+
+        // If the product needs more items from network, load the amount needed to fullfil
+        // the requirement and cache, capped at the current amount defined by product
+        if (!isLoadingMoreRef.current && availableSizeRef.current < 0) {
+          loadMore(
+            Math.max(
+              minimalFetchSize,
+              Math.min(numToAdd, bufferSize - availableSizeRef.current),
+            ),
+            // Keep options For backward compatibility
+            options ?? {
+              onComplete: prefetchingOnComplete,
+              UNSTABLE_extraVariables:
+                typeof prefetchingUNSTABLE_extraVariables === 'function'
+                  ? // $FlowFixMe[incompatible-call]
+                    prefetchingUNSTABLE_extraVariables({
+                      hasNext,
+                      // $FlowFixMe[incompatible-call]
+                      data: fragmentData,
+                      getServerEdges: () => {
+                        const selector = getSelector(
+                          // $FlowFixMe[incompatible-call]
+                          edgesFragment,
+                          edgeKeys,
+                        );
+                        if (selector == null) {
+                          // $FlowFixMe[incompatible-call]
+                          return [];
+                        }
+                        invariant(
+                          selector.kind === 'PluralReaderSelector',
+                          'Expected a plural selector',
+                        );
+                        // $FlowFixMe[incompatible-call]
+                        return selector.selectors.map(
+                          sel => environment.lookup(sel).data,
+                        );
+                      },
+                    })
+                  : prefetchingUNSTABLE_extraVariables,
+            },
+          );
+        }
+      }
+    },
+    [
+      bufferSize,
+      loadMore,
+      minimalFetchSize,
+      edgeKeys,
+      fragmentData,
+      prefetchingUNSTABLE_extraVariables,
+      prefetchingOnComplete,
+    ],
+  );
+
+  const edgesFragment = fragmentInput.metadata?.refetch?.edgesFragment;
+  invariant(
+    edgesFragment != null,
+    'usePrefetchableForwardPaginationFragment_EXPERIMENTAL: Expected the edge fragment to be defined, ' +
+      'please make sure you have added `prefetchable_pagination: true`  to `@connection`',
+  );
+
+  // Always try to keep `bufferSize` items in the buffer
+  // Or load the number of items that have been registred to show
+  useEffect(() => {
+    if (
+      // Check the ref to avoid infinite `loadMore`, when a `loadMore` has started,
+      // but `isLoadingMore` isn't updated
+      !isLoadingMoreRef.current &&
+      // Check the original `isLoadingMore` so when `loadMore` is called,  the internal
+      // `loadMore` hook has been updated with the latest cursor
+      !isLoadingMore &&
+      !isRefetching &&
+      hasNext &&
+      (sourceSize - numInUse < bufferSize || numInUse > sourceSize)
+    ) {
+      const onComplete = prefetchingOnComplete;
+      loadMore(
+        Math.max(
+          bufferSize - Math.max(sourceSize - numInUse, 0),
+          numInUse - sourceSize,
+          minimalFetchSize,
+        ),
+        {
+          onComplete,
+          UNSTABLE_extraVariables:
+            typeof prefetchingUNSTABLE_extraVariables === 'function'
+              ? // $FlowFixMe[incompatible-call]
+                prefetchingUNSTABLE_extraVariables({
+                  hasNext,
+                  // $FlowFixMe[incompatible-call]
+                  data: fragmentData,
+                  getServerEdges: () => {
+                    const selector = getSelector(edgesFragment, edgeKeys);
+                    if (selector == null) {
+                      // $FlowFixMe[incompatible-call]
+                      return [];
+                    }
+                    invariant(
+                      selector.kind === 'PluralReaderSelector',
+                      'Expected a plural selector',
+                    );
+                    // $FlowFixMe[incompatible-call]
+                    return selector.selectors.map(
+                      sel => environment.lookup(sel).data,
+                    );
+                  },
+                })
+              : prefetchingUNSTABLE_extraVariables,
+        },
+      );
+    }
+  }, [
+    hasNext,
+    bufferSize,
+    isRefetching,
+    loadMore,
+    numInUse,
+    prefetchingUNSTABLE_extraVariables,
+    prefetchingOnComplete,
+    sourceSize,
+    edgeKeys,
+    isLoadingMore,
+    minimalFetchSize,
+    environment,
+    edgesFragment,
+  ]);
+
+  const realNumInUse = Math.min(numInUse, sourceSize);
+
+  const derivedEdgeKeys: $ReadOnlyArray<mixed> = useMemo(
+    () => edgeKeys?.slice(0, realNumInUse) ?? [],
+    [edgeKeys, realNumInUse],
+  );
+
+  // $FlowExpectedError[incompatible-call] - we know derivedEdgeKeys are the correct keys
+  const edges: TEdgeData = useFragment(edgesFragment, derivedEdgeKeys);
+
+  const refetchPagination = useCallback(
+    (variables: TVariables, options?: Options) => {
+      disposeFetchNext();
+      setIsRefetching(true);
+      return refetch(variables, {
+        ...options,
+        onComplete: maybeError => {
+          // Need to be batched with the store update
+          const schedule = environment.getScheduler()?.schedule;
+          if (schedule) {
+            schedule(() => {
+              setIsRefetching(false);
+              setNumInUse(-1);
+            });
+          } else {
+            setIsRefetching(false);
+            setNumInUse(-1);
+          }
+          options?.onComplete?.(maybeError);
+        },
+        __environment: undefined,
+      });
+    },
+    [disposeFetchNext, environment, refetch],
+  );
+
+  if (__DEV__) {
+    // $FlowFixMe[react-rule-hook]
+    useDebugValue({
+      fragment: fragmentNode.name,
+      data: fragmentData,
+      hasNext,
+      isLoadingNext: isLoadingMore,
+    });
+  }
+
+  return {
+    edges,
+    // $FlowFixMe[incompatible-return]
+    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,
+    refetch: refetchPagination,
+  };
+}
+
+module.exports = usePrefetchableForwardPaginationFragment_EXPERIMENTAL;