react-relay 12.0.0 → 13.0.0

package/relay-hooks/FragmentResource.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * 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.
@@ -13,28 +13,35 @@
 
 'use strict';
 
-const LRUCache = require('./LRUCache');
+import type {Cache} from './LRUCache';
+import type {QueryResource, QueryResult} from './QueryResource';
+import type {
+  ConcreteRequest,
+  DataID,
+  Disposable,
+  IEnvironment,
+  ReaderFragment,
+  RequestDescriptor,
+  Snapshot,
+} from 'relay-runtime';
 
+const LRUCache = require('./LRUCache');
+const {getQueryResourceForEnvironment} = require('./QueryResource');
+const SuspenseResource = require('./SuspenseResource');
 const invariant = require('invariant');
-
 const {
+  RelayFeatureFlags,
+  __internal: {fetchQuery, getPromiseForActiveRequest},
+  createOperationDescriptor,
   getFragmentIdentifier,
   getPendingOperationsForFragment,
   getSelector,
+  getVariablesFromFragment,
   isPromise,
   recycleNodesInto,
   reportMissingRequiredFields,
 } = require('relay-runtime');
 
-import type {Cache} from './LRUCache';
-import type {
-  Disposable,
-  IEnvironment,
-  ReaderFragment,
-  RequestDescriptor,
-  Snapshot,
-} from 'relay-runtime';
-
 export type FragmentResource = FragmentResourceImpl;
 
 type FragmentResourceCache = Cache<
@@ -78,6 +85,24 @@ function isMissingData(snapshot: SingularOrPluralSnapshot): boolean {
   return snapshot.isMissingData;
 }
 
+function hasMissingClientEdges(snapshot: SingularOrPluralSnapshot): boolean {
+  if (Array.isArray(snapshot)) {
+    return snapshot.some(s => (s.missingClientEdges?.length ?? 0) > 0);
+  }
+  return (snapshot.missingClientEdges?.length ?? 0) > 0;
+}
+
+function singularOrPluralForEach(
+  snapshot: SingularOrPluralSnapshot,
+  f: Snapshot => void,
+): void {
+  if (Array.isArray(snapshot)) {
+    snapshot.forEach(f);
+  } else {
+    f(snapshot);
+  }
+}
+
 function getFragmentResult(
   cacheKey: string,
   snapshot: SingularOrPluralSnapshot,
@@ -101,13 +126,75 @@ function getFragmentResult(
   };
 }
 
+/**
+ * The purpose of this cache is to allow information to be passed from an
+ * initial read which suspends through to the commit that follows a subsequent
+ * successful read. Specifically, the QueryResource result for the data fetch
+ * is passed through so that that query can be retained on commit.
+ */
+class ClientEdgeQueryResultsCache {
+  _cache: Map<string, [Array<QueryResult>, SuspenseResource]> = new Map();
+  _retainCounts: Map<string, number> = new Map();
+  _environment: IEnvironment;
+
+  constructor(environment: IEnvironment) {
+    this._environment = environment;
+  }
+
+  get(fragmentIdentifier: string): void | Array<QueryResult> {
+    return this._cache.get(fragmentIdentifier)?.[0] ?? undefined;
+  }
+
+  recordQueryResults(
+    fragmentIdentifier: string,
+    value: Array<QueryResult>, // may be mutated after being passed here
+  ): void {
+    const existing = this._cache.get(fragmentIdentifier);
+    if (!existing) {
+      const suspenseResource = new SuspenseResource(() =>
+        this._retain(fragmentIdentifier),
+      );
+      this._cache.set(fragmentIdentifier, [value, suspenseResource]);
+      suspenseResource.temporaryRetain(this._environment);
+    } else {
+      const [existingResults, suspenseResource] = existing;
+      value.forEach(queryResult => {
+        existingResults.push(queryResult);
+      });
+      suspenseResource.temporaryRetain(this._environment);
+    }
+  }
+
+  _retain(id) {
+    const retainCount = (this._retainCounts.get(id) ?? 0) + 1;
+    this._retainCounts.set(id, retainCount);
+    return {
+      dispose: () => {
+        const newRetainCount = (this._retainCounts.get(id) ?? 0) - 1;
+        if (newRetainCount > 0) {
+          this._retainCounts.set(id, newRetainCount);
+        } else {
+          this._retainCounts.delete(id);
+          this._cache.delete(id);
+        }
+      },
+    };
+  }
+}
+
 class FragmentResourceImpl {
   _environment: IEnvironment;
   _cache: FragmentResourceCache;
+  _clientEdgeQueryResultsCache: void | ClientEdgeQueryResultsCache;
 
   constructor(environment: IEnvironment) {
     this._environment = environment;
     this._cache = LRUCache.create(CACHE_CAPACITY);
+    if (RelayFeatureFlags.ENABLE_CLIENT_EDGES) {
+      this._clientEdgeQueryResultsCache = new ClientEdgeQueryResultsCache(
+        environment,
+      );
+    }
   }
 
   /**
@@ -252,24 +339,75 @@ class FragmentResourceImpl {
       return fragmentResult;
     }
 
-    // 3. If we don't have data in the store, check if a request is in
-    // flight for the fragment's parent query, or for another operation
-    // that may affect the parent's query data, such as a mutation
-    // or subscription. If a promise exists, cache the promise and use it
-    // to suspend.
+    // 3. If we don't have data in the store, there's two cases where we should
+    // suspend to await the data: First if any client edges were traversed where
+    // the destination record was missing data; in that case we initiate a query
+    // here to fetch the missing data. Second, there may already be a request
+    // in flight for the fragment's parent query, or for another operation that
+    //  may affect the parent's query data, such as a mutation or subscription.
+    // For any of these cases we can get a promise, which we will cache and
+    // suspend on.
+
+    // First, initiate a query for any client edges that were missing data:
+    let clientEdgeRequests: ?Array<RequestDescriptor> = null;
+    if (
+      RelayFeatureFlags.ENABLE_CLIENT_EDGES &&
+      hasMissingClientEdges(snapshot)
+    ) {
+      clientEdgeRequests = [];
+      const queryResource = getQueryResourceForEnvironment(this._environment);
+      const queryResults = [];
+      singularOrPluralForEach(snapshot, snap => {
+        snap.missingClientEdges?.forEach(
+          ({request, clientEdgeDestinationID}) => {
+            const {queryResult, requestDescriptor} =
+              this._performClientEdgeQuery(
+                queryResource,
+                fragmentNode,
+                fragmentRef,
+                request,
+                clientEdgeDestinationID,
+              );
+            queryResults.push(queryResult);
+            clientEdgeRequests?.push(requestDescriptor);
+          },
+        );
+      });
+      // Store the query so that it can be retained when our own fragment is
+      // subscribed to. This merges with any existing query results:
+      invariant(
+        this._clientEdgeQueryResultsCache != null,
+        'Client edge query result cache should exist when ENABLE_CLIENT_EDGES is on.',
+      );
+      this._clientEdgeQueryResultsCache.recordQueryResults(
+        fragmentIdentifier,
+        queryResults,
+      );
+    }
+    let clientEdgePromises = null;
+    if (RelayFeatureFlags.ENABLE_CLIENT_EDGES && clientEdgeRequests) {
+      clientEdgePromises = clientEdgeRequests
+        .map(request => getPromiseForActiveRequest(this._environment, request))
+        .filter(p => p != null);
+    }
+
+    // Finally look for operations in flight for our parent query:
     const fragmentOwner =
       fragmentSelector.kind === 'PluralReaderSelector'
         ? fragmentSelector.selectors[0].owner
         : fragmentSelector.owner;
-    const networkPromiseResult = this._getAndSavePromiseForFragmentRequestInFlight(
-      fragmentIdentifier,
-      fragmentNode,
-      fragmentOwner,
-      fragmentResult,
-    );
+    const parentQueryPromiseResult =
+      this._getAndSavePromiseForFragmentRequestInFlight(
+        fragmentIdentifier,
+        fragmentNode,
+        fragmentOwner,
+        fragmentResult,
+      );
+    const parentQueryPromiseResultPromise = parentQueryPromiseResult?.promise; // for refinement
+
     if (
-      networkPromiseResult != null &&
-      isPromise(networkPromiseResult.promise)
+      clientEdgePromises?.length ||
+      isPromise(parentQueryPromiseResultPromise)
     ) {
       environment.__log({
         name: 'suspense.fragment',
@@ -278,15 +416,52 @@ class FragmentResourceImpl {
         isRelayHooks: true,
         isPromiseCached: false,
         isMissingData: fragmentResult.isMissingData,
-        pendingOperations: networkPromiseResult.pendingOperations,
+        pendingOperations: [
+          ...(parentQueryPromiseResult?.pendingOperations ?? []),
+          ...(clientEdgeRequests ?? []),
+        ],
       });
-      throw networkPromiseResult.promise;
+      throw clientEdgePromises?.length
+        ? Promise.all([parentQueryPromiseResultPromise, ...clientEdgePromises])
+        : parentQueryPromiseResultPromise;
     }
 
     this._reportMissingRequiredFieldsInSnapshot(snapshot);
     return getFragmentResult(fragmentIdentifier, snapshot, storeEpoch);
   }
 
+  _performClientEdgeQuery(
+    queryResource: QueryResource,
+    fragmentNode: ReaderFragment,
+    fragmentRef: mixed,
+    request: ConcreteRequest,
+    clientEdgeDestinationID: DataID,
+  ) {
+    const originalVariables = getVariablesFromFragment(
+      fragmentNode,
+      fragmentRef,
+    );
+    const variables = {
+      ...originalVariables,
+      id: clientEdgeDestinationID, // TODO should be a reserved name
+    };
+    const operation = createOperationDescriptor(
+      request,
+      variables,
+      {}, //  TODO cacheConfig should probably inherent from parent operation
+    );
+    const fetchObservable = fetchQuery(this._environment, operation);
+    const queryResult = queryResource.prepare(
+      operation,
+      fetchObservable,
+      // TODO should inherent render policy etc. from parent operation
+    );
+    return {
+      requestDescriptor: operation.request,
+      queryResult,
+    };
+  }
+
   _reportMissingRequiredFieldsInSnapshot(snapshot: SingularOrPluralSnapshot) {
     if (Array.isArray(snapshot)) {
       snapshot.forEach(s => {
@@ -334,9 +509,8 @@ class FragmentResourceImpl {
 
     // 1. Check for any updates missed during render phase
     // TODO(T44066760): More efficiently detect if we missed an update
-    const [didMissUpdates, currentSnapshot] = this.checkMissedUpdates(
-      fragmentResult,
-    );
+    const [didMissUpdates, currentSnapshot] =
+      this.checkMissedUpdates(fragmentResult);
 
     // 2. If an update was missed, notify the component so it updates with
     // the latest data.
@@ -345,7 +519,7 @@ class FragmentResourceImpl {
     }
 
     // 3. Establish subscriptions on the snapshot(s)
-    const dataSubscriptions = [];
+    const disposables = [];
     if (Array.isArray(renderedSnapshot)) {
       invariant(
         Array.isArray(currentSnapshot),
@@ -353,7 +527,7 @@ class FragmentResourceImpl {
           "If you're seeing this, this is likely a bug in Relay.",
       );
       currentSnapshot.forEach((snapshot, idx) => {
-        dataSubscriptions.push(
+        disposables.push(
           environment.subscribe(snapshot, latestSnapshot => {
             const storeEpoch = environment.getStore().getEpoch();
             this._updatePluralSnapshot(
@@ -373,7 +547,7 @@ class FragmentResourceImpl {
         'Relay: Expected snapshot to be singular. ' +
           "If you're seeing this, this is likely a bug in Relay.",
       );
-      dataSubscriptions.push(
+      disposables.push(
         environment.subscribe(currentSnapshot, latestSnapshot => {
           const storeEpoch = environment.getStore().getEpoch();
           this._cache.set(cacheKey, {
@@ -385,9 +559,20 @@ class FragmentResourceImpl {
       );
     }
 
+    if (RelayFeatureFlags.ENABLE_CLIENT_EDGES) {
+      const clientEdgeQueryResults =
+        this._clientEdgeQueryResultsCache?.get(cacheKey) ?? undefined;
+      if (clientEdgeQueryResults?.length) {
+        const queryResource = getQueryResourceForEnvironment(this._environment);
+        clientEdgeQueryResults.forEach(queryResult => {
+          disposables.push(queryResource.retain(queryResult));
+        });
+      }
+    }
+
     return {
       dispose: () => {
-        dataSubscriptions.map(s => s.dispose());
+        disposables.forEach(s => s.dispose());
         this._cache.delete(cacheKey);
       },
     };
@@ -458,6 +643,7 @@ class FragmentResourceImpl {
     const updatedCurrentSnapshot: Snapshot = {
       data: updatedData,
       isMissingData: currentSnapshot.isMissingData,
+      missingClientEdges: currentSnapshot.missingClientEdges,
       seenRecords: currentSnapshot.seenRecords,
       selector: currentSnapshot.selector,
       missingRequiredFields: currentSnapshot.missingRequiredFields,
@@ -473,7 +659,7 @@ class FragmentResourceImpl {
 
   checkMissedUpdatesSpec(fragmentResults: {
     [string]: FragmentResult,
-    ...,
+    ...
   }): boolean {
     return Object.keys(fragmentResults).some(
       key => this.checkMissedUpdates(fragmentResults[key])[0],

package/relay-hooks/InternalLogger.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * 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.

package/relay-hooks/LRUCache.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * 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.

package/relay-hooks/LazyLoadEntryPointContainer_DEPRECATED.react.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * 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.
@@ -13,36 +13,28 @@
 
 'use strict';
 
-const ProfilerContext = require('./ProfilerContext');
-const React = require('react');
+import type {
+  EntryPoint,
+  EntryPointComponent,
+  EnvironmentProviderOptions,
+  IEnvironmentProvider,
+} from './EntryPointTypes.flow';
 
 const preloadQuery_DEPRECATED = require('./preloadQuery_DEPRECATED');
+const ProfilerContext = require('./ProfilerContext');
 const useRelayEnvironment = require('./useRelayEnvironment');
-
+const React = require('react');
 const {useContext, useEffect, useMemo} = require('react');
 const {stableCopy} = require('relay-runtime');
 
 type PreloadedEntryPoint<TEntryPointComponent> = $ReadOnly<{|
-  entryPoints: $PropertyType<
-    React.ElementConfig<TEntryPointComponent>,
-    'entryPoints',
-  >,
-  extraProps: $PropertyType<
-    React.ElementConfig<TEntryPointComponent>,
-    'extraProps',
-  >,
+  entryPoints: React.ElementConfig<TEntryPointComponent>['entryPoints'],
+  extraProps: React.ElementConfig<TEntryPointComponent>['extraProps'],
   getComponent: () => TEntryPointComponent,
-  queries: $PropertyType<React.ElementConfig<TEntryPointComponent>, 'queries'>,
+  queries: React.ElementConfig<TEntryPointComponent>['queries'],
   rootModuleID: string,
 |}>;
 
-import type {
-  EntryPoint,
-  EntryPointComponent,
-  EnvironmentProviderOptions,
-  IEnvironmentProvider,
-} from './EntryPointTypes.flow';
-
 type EntryPointContainerProps<
   TEntryPointParams,
   TPreloadedQueries,
@@ -100,12 +92,8 @@ function prepareEntryPoint<
   if (queries != null) {
     const queriesPropNames = Object.keys(queries);
     queriesPropNames.forEach(queryPropName => {
-      const {
-        environmentProviderOptions,
-        options,
-        parameters,
-        variables,
-      } = queries[queryPropName];
+      const {environmentProviderOptions, options, parameters, variables} =
+        queries[queryPropName];
 
       const environment = environmentProvider.getEnvironment(
         environmentProviderOptions,
@@ -128,10 +116,8 @@ function prepareEntryPoint<
       if (entryPointDescription == null) {
         return;
       }
-      const {
-        entryPoint: nestedEntryPoint,
-        entryPointParams: nestedParams,
-      } = entryPointDescription;
+      const {entryPoint: nestedEntryPoint, entryPointParams: nestedParams} =
+        entryPointDescription;
       preloadedEntryPoints[entryPointPropName] = prepareEntryPoint(
         environmentProvider,
         nestedEntryPoint,
@@ -180,23 +166,23 @@ function LazyLoadEntryPointContainer_DEPRECATED<
   // *must* be computed first to fetch the component's data-dependencies in
   // parallel with the component itself (the code).
   const entryPointParamsHash = stableStringify(entryPointParams);
-  const {
-    getComponent,
-    queries,
-    entryPoints,
-    extraProps,
-    rootModuleID,
-  } = useMemo(() => {
-    return prepareEntryPoint(
-      environmentProvider ?? {
-        getEnvironment: () => environment,
-      },
-      entryPoint,
-      entryPointParams,
-    );
-    // NOTE: stableParams encodes the information from params
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [environment, environmentProvider, getPreloadProps, entryPointParamsHash]);
+  const {getComponent, queries, entryPoints, extraProps, rootModuleID} =
+    useMemo(() => {
+      return prepareEntryPoint(
+        environmentProvider ?? {
+          getEnvironment: () => environment,
+        },
+        entryPoint,
+        entryPointParams,
+      );
+      // NOTE: stableParams encodes the information from params
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+      environment,
+      environmentProvider,
+      getPreloadProps,
+      entryPointParamsHash,
+    ]);
   const Component = useMemo(() => {
     return getComponent();
   }, [getComponent]);

package/relay-hooks/MatchContainer.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * 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.
@@ -14,6 +14,7 @@
 'use strict';
 
 const React = require('react');
+
 const {useMemo} = React;
 
 /**
@@ -90,7 +91,7 @@ type TypenameOnlyPointer = {|+__typename: string|};
 export type MatchPointer = {
   +__fragmentPropName?: ?string,
   +__module_component?: mixed,
-  +$fragmentRefs: mixed,
+  +$fragmentSpreads: mixed,
   ...
 };
 
@@ -115,7 +116,7 @@ function MatchContainer<TProps: {...}, TFallback: React.Node | null>({
       'MatchContainer: Expected `match` value to be an object or null/undefined.',
     );
   }
-  // NOTE: the MatchPointer type has a $fragmentRefs field to ensure that only
+  // NOTE: the MatchPointer type has a $fragmentSpreads field to ensure that only
   // an object that contains a FragmentSpread can be passed. If the fragment
   // spread matches, then the metadata fields below (__id, __fragments, etc.)
   // will be present. But they can be missing if all the fragment spreads use

package/relay-hooks/ProfilerContext.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * 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.