react-relay 0.0.0-main-f0fc1eea → 0.0.0-main-c454f22f

package/relay-hooks/FragmentResource.js.flow

@@ -14,7 +14,10 @@
 'use strict';
 
 import type {Cache} from './LRUCache';
+import type {QueryResource, QueryResult} from './QueryResource';
 import type {
+  ConcreteRequest,
+  DataID,
   Disposable,
   IEnvironment,
   ReaderFragment,
@@ -23,11 +26,17 @@ import type {
 } 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,
@@ -76,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,
@@ -99,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,
+      );
+    }
   }
 
   /**
@@ -250,25 +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 =
+    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',
@@ -277,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 => {
@@ -343,7 +519,7 @@ class FragmentResourceImpl {
     }
 
     // 3. Establish subscriptions on the snapshot(s)
-    const dataSubscriptions = [];
+    const disposables = [];
     if (Array.isArray(renderedSnapshot)) {
       invariant(
         Array.isArray(currentSnapshot),
@@ -351,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(
@@ -371,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, {
@@ -383,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);
       },
     };
@@ -456,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,

package/relay-hooks/QueryResource.js.flow

@@ -30,13 +30,13 @@ import type {
 } from 'relay-runtime';
 
 const LRUCache = require('./LRUCache');
+const SuspenseResource = require('./SuspenseResource');
 const invariant = require('invariant');
-const {isPromise} = require('relay-runtime');
+const {RelayFeatureFlags, isPromise} = require('relay-runtime');
 const warning = require('warning');
 
 const CACHE_CAPACITY = 1000;
 const DEFAULT_FETCH_POLICY = 'store-or-network';
-const DATA_RETENTION_TIMEOUT = 5 * 60 * 1000;
 
 export type QueryResource = QueryResourceImpl;
 
@@ -59,7 +59,7 @@ type QueryResourceCacheEntry = {|
   permanentRetain(environment: IEnvironment): Disposable,
   releaseTemporaryRetain(): void,
 |};
-opaque type QueryResult: {
+export opaque type QueryResult: {
   fragmentNode: ReaderFragment,
   fragmentRef: mixed,
   ...
@@ -125,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);
 
@@ -432,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);
+      }
     }
   };
 

package/relay-hooks/SuspenseResource.js.flow

@@ -0,0 +1,115 @@
+/**
+ * Copyright (c) Facebook, Inc. and its 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
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+import type {Disposable, IEnvironment} from 'relay-runtime';
+
+const invariant = require('invariant');
+
+const TEMPORARY_RETAIN_DURATION_MS = 5 * 60 * 1000;
+
+/**
+ * Allows you to retain a resource as part of a component lifecycle accounting
+ * for Suspense. You temporarily retain the resource during render, then
+ * permanently retain it during commit and release it during unmount.
+ */
+class SuspenseResource {
+  _retainCount = 0;
+  _retainDisposable: ?Disposable = null;
+  _releaseTemporaryRetain: ?() => void = null;
+  _retain: IEnvironment => Disposable;
+
+  constructor(retain: (environment: IEnvironment) => Disposable) {
+    this._retain = (environment: IEnvironment): Disposable => {
+      this._retainCount++;
+      if (this._retainCount === 1) {
+        this._retainDisposable = retain(environment);
+      }
+      return {
+        dispose: () => {
+          this._retainCount = Math.max(0, this._retainCount - 1);
+          if (this._retainCount === 0) {
+            invariant(
+              this._retainDisposable != null,
+              'Relay: Expected disposable to release query to be defined.' +
+                "If you're seeing this, this is likely a bug in Relay.",
+            );
+            this._retainDisposable.dispose();
+            this._retainDisposable = null;
+          }
+        },
+      };
+    };
+  }
+
+  temporaryRetain(environment: IEnvironment): Disposable {
+    // If we're executing in a server environment, there's no need
+    // to create temporary retains, since the component will never commit.
+    if (environment.isServer()) {
+      return {dispose: () => {}};
+    }
+
+    // temporaryRetain is called during the render phase. However,
+    // given that we can't tell if this render will eventually commit or not,
+    // we create a timer to autodispose of this retain in case the associated
+    // component never commits.
+    // If the component /does/ commit, permanentRetain will clear this timeout
+    // and permanently retain the data.
+    const retention = this._retain(environment);
+    let releaseQueryTimeout = null;
+    const releaseTemporaryRetain = () => {
+      clearTimeout(releaseQueryTimeout);
+      releaseQueryTimeout = null;
+      this._releaseTemporaryRetain = null;
+      retention.dispose();
+    };
+    releaseQueryTimeout = setTimeout(
+      releaseTemporaryRetain,
+      TEMPORARY_RETAIN_DURATION_MS,
+    );
+
+    // NOTE: Since temporaryRetain can be called multiple times, we release
+    // the previous temporary retain after we re-establish a new one, since
+    // we only ever need a single temporary retain until the permanent retain is
+    // established.
+    // temporaryRetain may be called multiple times by React during the render
+    // phase, as well as multiple times by other query components that are
+    // rendering the same query/variables.
+    this._releaseTemporaryRetain?.();
+    this._releaseTemporaryRetain = releaseTemporaryRetain;
+
+    return {
+      dispose: () => {
+        this._releaseTemporaryRetain?.();
+      },
+    };
+  }
+
+  permanentRetain(environment: IEnvironment): Disposable {
+    const disposable = this._retain(environment);
+    this.releaseTemporaryRetain();
+    return disposable;
+  }
+
+  releaseTemporaryRetain(): void {
+    this._releaseTemporaryRetain?.();
+    this._releaseTemporaryRetain = null;
+  }
+
+  getRetainCount(): number {
+    return this._retainCount;
+  }
+}
+
+module.exports = SuspenseResource;