react-relay 12.0.0 → 13.0.0-rc.0

package/relay-hooks/FragmentResource.js.flow

@@ -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/LazyLoadEntryPointContainer_DEPRECATED.react.js.flow

@@ -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

@@ -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/QueryResource.js.flow

@@ -13,19 +13,7 @@
 
 'use strict';
 
-const LRUCache = require('./LRUCache');
-
-const invariant = require('invariant');
-const warning = require('warning');
-
-const {isPromise} = require('relay-runtime');
-
-const CACHE_CAPACITY = 1000;
-
-const DEFAULT_FETCH_POLICY = 'store-or-network';
-
-const DATA_RETENTION_TIMEOUT = 5 * 60 * 1000;
-
+import type {Cache} from './LRUCache';
 import type {
   Disposable,
   FetchPolicy,
@@ -40,7 +28,15 @@ import type {
   Snapshot,
   Subscription,
 } from 'relay-runtime';
-import type {Cache} from './LRUCache';
+
+const LRUCache = require('./LRUCache');
+const SuspenseResource = require('./SuspenseResource');
+const invariant = require('invariant');
+const {RelayFeatureFlags, isPromise} = require('relay-runtime');
+const warning = require('warning');
+
+const CACHE_CAPACITY = 1000;
+const DEFAULT_FETCH_POLICY = 'store-or-network';
 
 export type QueryResource = QueryResourceImpl;
 
@@ -63,7 +59,7 @@ type QueryResourceCacheEntry = {|
   permanentRetain(environment: IEnvironment): Disposable,
   releaseTemporaryRetain(): void,
 |};
-opaque type QueryResult: {
+export opaque type QueryResult: {
   fragmentNode: ReaderFragment,
   fragmentRef: mixed,
   ...
@@ -129,6 +125,106 @@ function createCacheEntry(
   value: Error | Promise<void> | QueryResult,
   networkSubscription: ?Subscription,
   onDispose: QueryResourceCacheEntry => void,
+): QueryResourceCacheEntry {
+  // There should be no behavior difference between createCacheEntry_new and
+  // createCacheEntry_old, and it doesn't directly relate to Client Edges.
+  // It was just a refactoring that was needed for Client Edges but that
+  // is behind the feature flag just in case there is any accidental breakage.
+  if (RelayFeatureFlags.REFACTOR_SUSPENSE_RESOURCE) {
+    return createCacheEntry_new(
+      cacheIdentifier,
+      operation,
+      operationAvailability,
+      value,
+      networkSubscription,
+      onDispose,
+    );
+  } else {
+    return createCacheEntry_old(
+      cacheIdentifier,
+      operation,
+      operationAvailability,
+      value,
+      networkSubscription,
+      onDispose,
+    );
+  }
+}
+
+function createCacheEntry_new(
+  cacheIdentifier: string,
+  operation: OperationDescriptor,
+  operationAvailability: ?OperationAvailability,
+  value: Error | Promise<void> | QueryResult,
+  networkSubscription: ?Subscription,
+  onDispose: QueryResourceCacheEntry => void,
+): QueryResourceCacheEntry {
+  const isLiveQuery = operationIsLiveQuery(operation);
+
+  let currentValue: Error | Promise<void> | QueryResult = value;
+  let currentNetworkSubscription: ?Subscription = networkSubscription;
+
+  const suspenseResource = new SuspenseResource(environment => {
+    const retention = environment.retain(operation);
+    return {
+      dispose: () => {
+        // Normally if this entry never commits, the request would've ended by the
+        // time this timeout expires and the temporary retain is released. However,
+        // we need to do this for live queries which remain open indefinitely.
+        if (isLiveQuery && currentNetworkSubscription != null) {
+          currentNetworkSubscription.unsubscribe();
+        }
+        retention.dispose();
+        onDispose(cacheEntry);
+      },
+    };
+  });
+
+  const cacheEntry = {
+    cacheIdentifier,
+    id: nextID++,
+    processedPayloadsCount: 0,
+    operationAvailability,
+    getValue() {
+      return currentValue;
+    },
+    setValue(val: QueryResult | Promise<void> | Error) {
+      currentValue = val;
+    },
+    getRetainCount() {
+      return suspenseResource.getRetainCount();
+    },
+    getNetworkSubscription() {
+      return currentNetworkSubscription;
+    },
+    setNetworkSubscription(subscription: ?Subscription) {
+      if (isLiveQuery && currentNetworkSubscription != null) {
+        currentNetworkSubscription.unsubscribe();
+      }
+      currentNetworkSubscription = subscription;
+    },
+    temporaryRetain(environment: IEnvironment): Disposable {
+      return suspenseResource.temporaryRetain(environment);
+    },
+    permanentRetain(environment: IEnvironment): Disposable {
+      return suspenseResource.permanentRetain(environment);
+    },
+    releaseTemporaryRetain() {
+      suspenseResource.releaseTemporaryRetain();
+    },
+  };
+
+  return cacheEntry;
+}
+
+const DATA_RETENTION_TIMEOUT = 5 * 60 * 1000;
+function createCacheEntry_old(
+  cacheIdentifier: string,
+  operation: OperationDescriptor,
+  operationAvailability: ?OperationAvailability,
+  value: Error | Promise<void> | QueryResult,
+  networkSubscription: ?Subscription,
+  onDispose: QueryResourceCacheEntry => void,
 ): QueryResourceCacheEntry {
   const isLiveQuery = operationIsLiveQuery(operation);
 
@@ -168,7 +264,7 @@ function createCacheEntry(
     getValue() {
       return currentValue;
     },
-    setValue(val) {
+    setValue(val: QueryResult | Promise<void> | Error) {
       currentValue = val;
     },
     getRetainCount() {
@@ -436,8 +532,14 @@ class QueryResourceImpl {
   }
 
   _clearCacheEntry = (cacheEntry: QueryResourceCacheEntry): void => {
-    if (cacheEntry.getRetainCount() <= 0) {
+    // The new code does this retainCount <= 0 check within SuspenseResource
+    // before calling _clearCacheEntry, whereas with the old code we do it here.
+    if (RelayFeatureFlags.REFACTOR_SUSPENSE_RESOURCE) {
       this._cache.delete(cacheEntry.cacheIdentifier);
+    } else {
+      if (cacheEntry.getRetainCount() <= 0) {
+        this._cache.delete(cacheEntry.cacheIdentifier);
+      }
     }
   };