react-relay 13.2.0 → 14.0.0

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

@@ -15,19 +15,25 @@
 
 import type {
   FetchPolicy,
+  GraphQLResponse,
   IEnvironment,
+  Observable,
   OperationDescriptor,
   ReaderFragment,
   RenderPolicy,
 } from 'relay-runtime';
 
+const SuspenseResource = require('../SuspenseResource');
 const {getCacheForType, getCacheSignal} = require('./RelayReactCache');
 const invariant = require('invariant');
 const {
+  RelayFeatureFlags,
   __internal: {fetchQuery: fetchQueryInternal},
 } = require('relay-runtime');
 const warning = require('warning');
 
+type QueryCacheCommitable = () => () => void;
+
 type QueryResult = {|
   fragmentNode: ReaderFragment,
   fragmentRef: mixed,
@@ -36,26 +42,96 @@ type QueryResult = {|
 // Note that the status of a cache entry will be 'resolved' when partial
 // rendering is allowed, even if a fetch is ongoing. The pending status
 // is specifically to indicate that we should suspend.
-type QueryCacheEntry =
-  | {|status: 'resolved', result: QueryResult|}
-  | {|status: 'pending', promise: Promise<void>|}
-  | {|status: 'rejected', error: Error|};
+// Note also that the retainCount is different from the retain count of
+// an operation, which is maintained by the Environment. This retain
+// count is used in Legacy Timeouts mode to count how many components
+// are mounted that use the entry, plus one count for the temporary retain
+// before any components have mounted. It is unused when Legacy Timeouts
+// mode is off.
+type QueryCacheEntryStatus =
+  | {|
+      status: 'resolved',
+      result: QueryResult,
+    |}
+  | {|
+      status: 'pending',
+      promise: Promise<void>,
+    |}
+  | {|
+      status: 'rejected',
+      error: Error,
+    |};
 
-type QueryCache = Map<string, QueryCacheEntry>;
+type QueryCacheEntry = {|
+  ...QueryCacheEntryStatus,
+  onCommit: QueryCacheCommitable,
+  suspenseResource: SuspenseResource | null,
+|};
 
 const DEFAULT_FETCH_POLICY = 'store-or-network';
 
+type QueryCacheKey = string;
+
+class QueryCache {
+  _map: Map<IEnvironment, Map<QueryCacheKey, QueryCacheEntry>>;
+
+  constructor() {
+    this._map = new Map();
+  }
+
+  get(environment: IEnvironment, key: QueryCacheKey): QueryCacheEntry | void {
+    let forEnv = this._map.get(environment);
+    if (!forEnv) {
+      forEnv = new Map();
+      this._map.set(environment, forEnv);
+    }
+    return forEnv.get(key);
+  }
+
+  set(
+    environment: IEnvironment,
+    key: QueryCacheKey,
+    value: QueryCacheEntry,
+  ): void {
+    let forEnv = this._map.get(environment);
+    if (!forEnv) {
+      forEnv = new Map();
+      this._map.set(environment, forEnv);
+    }
+    forEnv.set(key, value);
+  }
+
+  delete(environment: IEnvironment, key: QueryCacheKey): void {
+    const forEnv = this._map.get(environment);
+    if (!forEnv) {
+      return;
+    }
+    forEnv.delete(key);
+    if (forEnv.size === 0) {
+      this._map.delete(environment);
+    }
+  }
+}
+
 function createQueryCache(): QueryCache {
-  return new Map();
+  return new QueryCache();
 }
 
+const noopOnCommit = () => {
+  return () => undefined;
+};
+
+const noopPromise = new Promise(() => {});
+
 function getQueryCacheKey(
   operation: OperationDescriptor,
   fetchPolicy: FetchPolicy,
   renderPolicy: RenderPolicy,
-): string {
-  const cacheIdentifier = `${fetchPolicy}-${renderPolicy}-${operation.request.identifier}`;
-  return cacheIdentifier;
+  fetchKey?: ?string | ?number,
+): QueryCacheKey {
+  return `${fetchPolicy}-${renderPolicy}-${operation.request.identifier}-${
+    fetchKey ?? ''
+  }`;
 }
 
 function constructQueryResult(operation: OperationDescriptor): QueryResult {
@@ -72,14 +148,28 @@ function constructQueryResult(operation: OperationDescriptor): QueryResult {
   };
 }
 
+function makeInitialCacheEntry() {
+  return {
+    status: 'pending',
+    promise: noopPromise,
+    onCommit: noopOnCommit,
+    suspenseResource: null,
+  };
+}
+
 function getQueryResultOrFetchQuery_REACT_CACHE(
   environment: IEnvironment,
   queryOperationDescriptor: OperationDescriptor,
-  fetchPolicy: FetchPolicy = DEFAULT_FETCH_POLICY,
-  maybeRenderPolicy?: RenderPolicy,
-): QueryResult {
+  options?: {|
+    fetchPolicy?: FetchPolicy,
+    renderPolicy?: RenderPolicy,
+    fetchKey?: ?string | ?number,
+    fetchObservable?: Observable<GraphQLResponse>,
+  |},
+): [QueryResult, QueryCacheCommitable] {
+  const fetchPolicy = options?.fetchPolicy ?? DEFAULT_FETCH_POLICY;
   const renderPolicy =
-    maybeRenderPolicy ?? environment.UNSTABLE_getDefaultRenderPolicy();
+    options?.renderPolicy ?? environment.UNSTABLE_getDefaultRenderPolicy();
 
   const cache = getCacheForType(createQueryCache);
 
@@ -87,43 +177,111 @@ function getQueryResultOrFetchQuery_REACT_CACHE(
     queryOperationDescriptor,
     fetchPolicy,
     renderPolicy,
+    options?.fetchKey,
   );
 
-  let entry = cache.get(cacheKey);
-  if (entry === undefined) {
-    // Initiate a query to fetch the data if needed:
-    entry = onCacheMiss(
-      environment,
-      queryOperationDescriptor,
-      fetchPolicy,
-      renderPolicy,
-      newCacheEntry => {
-        cache.set(cacheKey, newCacheEntry);
-      },
-    );
-    cache.set(cacheKey, entry);
-
-    // Since this is the first time rendering, retain the query. React will
-    // trigger the abort signal when this cache entry is no longer needed.
-    const retention = environment.retain(queryOperationDescriptor);
-    const abortSignal = getCacheSignal();
-    abortSignal.addEventListener(
-      'abort',
-      () => {
+  const initialEntry = cache.get(environment, cacheKey);
+
+  function updateCache(
+    updater: QueryCacheEntryStatus => QueryCacheEntryStatus,
+  ) {
+    let currentEntry = cache.get(environment, cacheKey);
+    if (!currentEntry) {
+      currentEntry = makeInitialCacheEntry();
+      cache.set(environment, cacheKey, currentEntry);
+    }
+    // $FlowExpectedError[prop-missing] Extra properties are passed in -- this is fine
+    const newStatus: {...} = updater(currentEntry);
+    // $FlowExpectedError[cannot-spread-inexact] Flow cannot understand that this is valid...
+    cache.set(environment, cacheKey, {...currentEntry, ...newStatus});
+    // ... but we can because QueryCacheEntry spreads QueryCacheEntryStatus, so spreading
+    // a QueryCacheEntryStatus into a QueryCacheEntry will result in a valid QueryCacheEntry.
+  }
+
+  // Initiate a query to fetch the data if needed:
+  if (RelayFeatureFlags.USE_REACT_CACHE_LEGACY_TIMEOUTS) {
+    let entry;
+    if (initialEntry === undefined) {
+      onCacheMiss(
+        environment,
+        queryOperationDescriptor,
+        fetchPolicy,
+        renderPolicy,
+        updateCache,
+        options?.fetchObservable,
+      );
+      const createdEntry = cache.get(environment, cacheKey);
+      invariant(
+        createdEntry !== undefined,
+        'An entry should have been created by onCacheMiss. This is a bug in Relay.',
+      );
+      entry = createdEntry;
+    } else {
+      entry = initialEntry;
+    }
+    if (!entry.suspenseResource) {
+      entry.suspenseResource = new SuspenseResource(() => {
+        const retention = environment.retain(queryOperationDescriptor);
+        return {
+          dispose: () => {
+            retention.dispose();
+            cache.delete(environment, cacheKey);
+          },
+        };
+      });
+    }
+    if (entry.onCommit === noopOnCommit) {
+      entry.onCommit = () => {
+        invariant(
+          entry.suspenseResource,
+          'SuspenseResource should have been initialized. This is a bug in Relay.',
+        );
+        const retention = entry.suspenseResource.permanentRetain(environment);
+        return () => {
+          retention.dispose();
+        };
+      };
+    }
+    entry.suspenseResource.temporaryRetain(environment);
+  } else {
+    if (initialEntry === undefined) {
+      // This is the behavior we eventually want: We retain the query until the
+      // presiding Cache component unmounts, at which point the AbortSignal
+      // will be triggered.
+      onCacheMiss(
+        environment,
+        queryOperationDescriptor,
+        fetchPolicy,
+        renderPolicy,
+        updateCache,
+        options?.fetchObservable,
+      );
+
+      // Since this is the first time rendering, retain the query. React will
+      // trigger the abort signal when this cache entry is no longer needed.
+      const retention = environment.retain(queryOperationDescriptor);
+
+      const dispose = () => {
         retention.dispose();
-        cache.delete(cacheKey);
-      },
-      {once: true},
-    );
+        cache.delete(environment, cacheKey);
+      };
+      const abortSignal = getCacheSignal();
+      abortSignal.addEventListener('abort', dispose, {once: true});
+    }
   }
 
+  const entry = cache.get(environment, cacheKey); // could be a different entry now if synchronously resolved
+  invariant(
+    entry !== undefined,
+    'An entry should have been created by onCacheMiss. This is a bug in Relay.',
+  );
   switch (entry.status) {
     case 'pending':
       throw entry.promise;
     case 'rejected':
       throw entry.error;
     case 'resolved':
-      return entry.result;
+      return [entry.result, entry.onCommit];
   }
   invariant(false, 'switch statement should be exhaustive');
 }
@@ -133,8 +291,9 @@ function onCacheMiss(
   operation: OperationDescriptor,
   fetchPolicy: FetchPolicy,
   renderPolicy: RenderPolicy,
-  updateCache: QueryCacheEntry => void,
-): QueryCacheEntry {
+  updateCache: ((QueryCacheEntryStatus) => QueryCacheEntryStatus) => void,
+  customFetchObservable?: Observable<GraphQLResponse>,
+): void {
   // NB: Besides checking if the data is available, calling `check` will write missing
   // data to the store using any missing data handlers specified in the environment.
   const queryAvailability = environment.check(operation);
@@ -169,25 +328,46 @@ function onCacheMiss(
     }
   }
 
-  const promise = shouldFetch
-    ? executeOperationAndKeepUpToDate(environment, operation, updateCache)
-    : undefined;
-  if (shouldRenderNow) {
-    return {status: 'resolved', result: constructQueryResult(operation)};
+  if (shouldFetch) {
+    executeOperationAndKeepUpToDate(
+      environment,
+      operation,
+      updateCache,
+      customFetchObservable,
+    );
+    updateCache(existing => {
+      switch (existing.status) {
+        case 'resolved':
+          return existing;
+        case 'rejected':
+          return existing;
+        case 'pending':
+          return shouldRenderNow
+            ? {
+                status: 'resolved',
+                result: constructQueryResult(operation),
+              }
+            : existing;
+      }
+    });
   } else {
     invariant(
-      promise,
-      'Should either fetch or render (or both), otherwise we would suspend forever.',
+      shouldRenderNow,
+      'Should either fetch or be willing to render. This is a bug in Relay.',
     );
-    return {status: 'pending', promise: promise};
+    updateCache(_existing => ({
+      status: 'resolved',
+      result: constructQueryResult(operation),
+    }));
   }
 }
 
 function executeOperationAndKeepUpToDate(
   environment: IEnvironment,
   operation: OperationDescriptor,
-  updateCache: QueryCacheEntry => void,
-): Promise<void> {
+  updateCache: ((QueryCacheEntryStatus) => QueryCacheEntryStatus) => void,
+  customFetchObservable?: Observable<GraphQLResponse>,
+) {
   let resolvePromise;
   const promise = new Promise(r => {
     resolvePromise = r;
@@ -198,12 +378,16 @@ function executeOperationAndKeepUpToDate(
   let isFirstPayload = true;
 
   // FIXME We may still need to cancel network requests for live queries.
-  const fetchObservable = fetchQueryInternal(environment, operation);
+  const fetchObservable =
+    customFetchObservable ?? fetchQueryInternal(environment, operation);
   fetchObservable.subscribe({
     start: subscription => {},
     error: error => {
       if (isFirstPayload) {
-        updateCache({status: 'rejected', error});
+        updateCache(_existing => ({
+          status: 'rejected',
+          error,
+        }));
       } else {
         // TODO:T92030819 Remove this warning and actually throw the network error
         // To complete this task we need to have a way of precisely tracking suspendable points
@@ -220,24 +404,21 @@ function executeOperationAndKeepUpToDate(
     },
     next: response => {
       // Stop suspending on the first payload because of streaming, defer, etc.
-      updateCache({
-        status: 'resolved',
-        result: constructQueryResult(operation),
-      });
-      resolvePromise();
-      isFirstPayload = false;
-    },
-    complete: () => {
-      updateCache({
+      updateCache(_existing => ({
         status: 'resolved',
         result: constructQueryResult(operation),
-      });
+      }));
       resolvePromise();
       isFirstPayload = false;
     },
   });
 
-  return promise;
+  // If the above subscription yields a value synchronously, then one of the updates
+  // above will have already happened and we'll now be in a resolved or rejected state.
+  // But in the usual case, we save the promise to the entry here:
+  updateCache(existing =>
+    existing.status === 'pending' ? {status: 'pending', promise} : existing,
+  );
 }
 
 module.exports = getQueryResultOrFetchQuery_REACT_CACHE;