relay-runtime 11.0.2 → 13.0.0-rc.2

package/store/RelayReader.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.
@@ -12,12 +12,39 @@
 
 'use strict';
 
-const RelayFeatureFlags = require('../util/RelayFeatureFlags');
-const RelayModernRecord = require('./RelayModernRecord');
-
-const invariant = require('invariant');
+import type {
+  ReaderActorChange,
+  ReaderClientEdge,
+  ReaderFlightField,
+  ReaderFragment,
+  ReaderFragmentSpread,
+  ReaderInlineDataFragmentSpread,
+  ReaderLinkedField,
+  ReaderModuleImport,
+  ReaderNode,
+  ReaderRelayResolver,
+  ReaderRequiredField,
+  ReaderScalarField,
+  ReaderSelection,
+} from '../util/ReaderNode';
+import type {DataID, Variables} from '../util/RelayRuntimeTypes';
+import type {
+  ClientEdgeTraversalInfo,
+  DataIDSet,
+  MissingClientEdgeRequestInfo,
+  MissingRequiredFields,
+  Record,
+  RecordSource,
+  RequestDescriptor,
+  SelectorData,
+  SingularReaderSelector,
+  Snapshot,
+} from './RelayStoreTypes';
+import type {ResolverCache} from './ResolverCache';
 
 const {
+  ACTOR_CHANGE,
+  CLIENT_EDGE,
   CLIENT_EXTENSION,
   CONDITION,
   DEFER,
@@ -27,57 +54,43 @@ const {
   INLINE_FRAGMENT,
   LINKED_FIELD,
   MODULE_IMPORT,
-  REQUIRED_FIELD,
   RELAY_RESOLVER,
+  REQUIRED_FIELD,
   SCALAR_FIELD,
   STREAM,
 } = require('../util/RelayConcreteNode');
+const RelayFeatureFlags = require('../util/RelayFeatureFlags');
+const ClientID = require('./ClientID');
+const RelayModernRecord = require('./RelayModernRecord');
 const {getReactFlightClientResponse} = require('./RelayStoreReactFlightUtils');
 const {
-  FRAGMENTS_KEY,
+  CLIENT_EDGE_TRAVERSAL_PATH,
   FRAGMENT_OWNER_KEY,
   FRAGMENT_PROP_NAME_KEY,
+  FRAGMENTS_KEY,
   ID_KEY,
   IS_WITHIN_UNMATCHED_TYPE_REFINEMENT,
   MODULE_COMPONENT_KEY,
   ROOT_ID,
   getArgumentValues,
-  getStorageKey,
   getModuleComponentKey,
+  getStorageKey,
 } = require('./RelayStoreUtils');
+const {NoopResolverCache} = require('./ResolverCache');
 const {withResolverContext} = require('./ResolverFragments');
 const {generateTypeID} = require('./TypeID');
-
-import type {
-  ReaderFlightField,
-  ReaderFragment,
-  ReaderFragmentSpread,
-  ReaderInlineDataFragmentSpread,
-  ReaderLinkedField,
-  ReaderModuleImport,
-  ReaderNode,
-  ReaderRelayResolver,
-  ReaderRequiredField,
-  ReaderScalarField,
-  ReaderSelection,
-} from '../util/ReaderNode';
-import type {DataID, Variables} from '../util/RelayRuntimeTypes';
-import type {
-  Record,
-  RecordSource,
-  RequestDescriptor,
-  SelectorData,
-  SingularReaderSelector,
-  Snapshot,
-  MissingRequiredFields,
-  DataIDSet,
-} from './RelayStoreTypes';
+const invariant = require('invariant');
 
 function read(
   recordSource: RecordSource,
   selector: SingularReaderSelector,
+  resolverCache?: ResolverCache,
 ): Snapshot {
-  const reader = new RelayReader(recordSource, selector);
+  const reader = new RelayReader(
+    recordSource,
+    selector,
+    resolverCache ?? new NoopResolverCache(),
+  );
   return reader.read();
 }
 
@@ -85,7 +98,9 @@ function read(
  * @private
  */
 class RelayReader {
+  _clientEdgeTraversalPath: Array<ClientEdgeTraversalInfo | null>;
   _isMissingData: boolean;
+  _missingClientEdges: Array<MissingClientEdgeRequestInfo>;
   _isWithinUnmatchedTypeRefinement: boolean;
   _missingRequiredFields: ?MissingRequiredFields;
   _owner: RequestDescriptor;
@@ -93,8 +108,19 @@ class RelayReader {
   _seenRecords: DataIDSet;
   _selector: SingularReaderSelector;
   _variables: Variables;
+  _resolverCache: ResolverCache;
 
-  constructor(recordSource: RecordSource, selector: SingularReaderSelector) {
+  constructor(
+    recordSource: RecordSource,
+    selector: SingularReaderSelector,
+    resolverCache: ResolverCache,
+  ) {
+    this._clientEdgeTraversalPath =
+      RelayFeatureFlags.ENABLE_CLIENT_EDGES &&
+      selector.clientEdgeTraversalPath?.length
+        ? [...selector.clientEdgeTraversalPath]
+        : [];
+    this._missingClientEdges = [];
     this._isMissingData = false;
     this._isWithinUnmatchedTypeRefinement = false;
     this._missingRequiredFields = null;
@@ -103,6 +129,7 @@ class RelayReader {
     this._seenRecords = new Set();
     this._selector = selector;
     this._variables = selector.variables;
+    this._resolverCache = resolverCache;
   }
 
   read(): Snapshot {
@@ -126,7 +153,18 @@ class RelayReader {
     // match, then no data is expected to be present.
     if (isDataExpectedToBePresent && abstractKey == null && record != null) {
       const recordType = RelayModernRecord.getType(record);
-      if (recordType !== node.type && dataID !== ROOT_ID) {
+      if (
+        recordType !== node.type &&
+        // The root record type is a special `__Root` type and may not match the
+        // type on the ast, so ignore type mismatches at the root.
+        // We currently detect whether we're at the root by checking against ROOT_ID,
+        // but this does not work for mutations/subscriptions which generate unique
+        // root ids. This is acceptable in practice as we don't read data for mutations/
+        // subscriptions in a situation where we would use isMissingData to decide whether
+        // to suspend or not.
+        // TODO T96653810: Correctly detect reading from root of mutation/subscription
+        dataID !== ROOT_ID
+      ) {
         isDataExpectedToBePresent = false;
       }
     }
@@ -135,12 +173,7 @@ class RelayReader {
     // then data is only expected to be present if the record type is known to
     // implement the interface. If we aren't sure whether the record implements
     // the interface, that itself constitutes "expected" data being missing.
-    if (
-      isDataExpectedToBePresent &&
-      abstractKey != null &&
-      record != null &&
-      RelayFeatureFlags.ENABLE_PRECISE_TYPE_REFINEMENT
-    ) {
+    if (isDataExpectedToBePresent && abstractKey != null && record != null) {
       const recordType = RelayModernRecord.getType(record);
       const typeID = generateTypeID(recordType);
       const typeRecord = this._recordSource.get(typeID);
@@ -162,12 +195,36 @@ class RelayReader {
     return {
       data,
       isMissingData: this._isMissingData && isDataExpectedToBePresent,
+      missingClientEdges:
+        RelayFeatureFlags.ENABLE_CLIENT_EDGES && this._missingClientEdges.length
+          ? this._missingClientEdges
+          : null,
       seenRecords: this._seenRecords,
       selector: this._selector,
       missingRequiredFields: this._missingRequiredFields,
     };
   }
 
+  _markDataAsMissing(): void {
+    this._isMissingData = true;
+    if (
+      RelayFeatureFlags.ENABLE_CLIENT_EDGES &&
+      this._clientEdgeTraversalPath.length
+    ) {
+      const top =
+        this._clientEdgeTraversalPath[this._clientEdgeTraversalPath.length - 1];
+      // Top can be null if we've traversed past a client edge into an ordinary
+      // client extension field; we never want to fetch in response to missing
+      // data off of a client extension field.
+      if (top !== null) {
+        this._missingClientEdges.push({
+          request: top.readerClientEdge.operation,
+          clientEdgeDestinationID: top.clientEdgeDestinationID,
+        });
+      }
+    }
+  }
+
   _traverse(
     node: ReaderNode,
     dataID: DataID,
@@ -177,7 +234,7 @@ class RelayReader {
     this._seenRecords.add(dataID);
     if (record == null) {
       if (record === undefined) {
-        this._isMissingData = true;
+        this._markDataAsMissing();
       }
       return record;
     }
@@ -196,7 +253,6 @@ class RelayReader {
       'RelayReader(): Undefined variable `%s`.',
       name,
     );
-    // $FlowFixMe[cannot-write]
     return this._variables[name];
   }
 
@@ -237,13 +293,6 @@ class RelayReader {
       const selection = selections[i];
       switch (selection.kind) {
         case REQUIRED_FIELD:
-          invariant(
-            RelayFeatureFlags.ENABLE_REQUIRED_DIRECTIVES,
-            'RelayReader(): Encountered a `@required` directive at path "%s" in `%s` without the `ENABLE_REQUIRED_DIRECTIVES` feature flag enabled.',
-            selection.path,
-            this._selector.node.name,
-          );
-
           const fieldValue = this._readRequiredField(selection, record, data);
           if (fieldValue == null) {
             const {action} = selection;
@@ -267,7 +316,9 @@ class RelayReader {
           }
           break;
         case CONDITION:
-          const conditionValue = this._getVariableValue(selection.condition);
+          const conditionValue = Boolean(
+            this._getVariableValue(selection.condition),
+          );
           if (conditionValue === selection.passingValue) {
             const hasExpectedData = this._traverseSelections(
               selection.selections,
@@ -294,15 +345,15 @@ class RelayReader {
                 return false;
               }
             }
-          } else if (RelayFeatureFlags.ENABLE_PRECISE_TYPE_REFINEMENT) {
+          } else {
             // Similar to the logic in read(): data is only expected to be present
             // if the record is known to conform to the interface. If we don't know
             // whether the type conforms or not, that constitutes missing data.
 
             // store flags to reset after reading
             const parentIsMissingData = this._isMissingData;
-            const parentIsWithinUnmatchedTypeRefinement = this
-              ._isWithinUnmatchedTypeRefinement;
+            const parentIsWithinUnmatchedTypeRefinement =
+              this._isWithinUnmatchedTypeRefinement;
 
             const typeName = RelayModernRecord.getType(record);
             const typeID = generateTypeID(typeName);
@@ -315,19 +366,16 @@ class RelayReader {
               parentIsWithinUnmatchedTypeRefinement ||
               implementsInterface === false;
             this._traverseSelections(selection.selections, record, data);
-            this._isWithinUnmatchedTypeRefinement = parentIsWithinUnmatchedTypeRefinement;
+            this._isWithinUnmatchedTypeRefinement =
+              parentIsWithinUnmatchedTypeRefinement;
 
             if (implementsInterface === false) {
               // Type known to not implement the interface, no data expected
               this._isMissingData = parentIsMissingData;
             } else if (implementsInterface == null) {
               // Don't know if the type implements the interface or not
-              this._isMissingData = true;
+              this._markDataAsMissing();
             }
-          } else {
-            // legacy behavior for abstract refinements: always read even
-            // if the type doesn't conform and don't reset isMissingData
-            this._traverseSelections(selection.selections, record, data);
           }
           break;
         }
@@ -354,12 +402,24 @@ class RelayReader {
         case DEFER:
         case CLIENT_EXTENSION: {
           const isMissingData = this._isMissingData;
+          const alreadyMissingClientEdges = this._missingClientEdges.length;
+          if (RelayFeatureFlags.ENABLE_CLIENT_EDGES) {
+            this._clientEdgeTraversalPath.push(null);
+          }
           const hasExpectedData = this._traverseSelections(
             selection.selections,
             record,
             data,
           );
-          this._isMissingData = isMissingData;
+          // The only case where we want to suspend due to missing data off of
+          // a client extension is if we reached a client edge that we might be
+          // able to fetch:
+          this._isMissingData =
+            isMissingData ||
+            this._missingClientEdges.length > alreadyMissingClientEdges;
+          if (RelayFeatureFlags.ENABLE_CLIENT_EDGES) {
+            this._clientEdgeTraversalPath.pop();
+          }
           if (!hasExpectedData) {
             return false;
           }
@@ -383,6 +443,16 @@ class RelayReader {
             throw new Error('Flight fields are not yet supported.');
           }
           break;
+        case ACTOR_CHANGE:
+          this._readActorChange(selection, record, data);
+          break;
+        case CLIENT_EDGE:
+          if (RelayFeatureFlags.ENABLE_CLIENT_EDGES) {
+            this._readClientEdge(selection, record, data);
+          } else {
+            throw new Error('Client edges are not yet supported.');
+          }
+          break;
         default:
           (selection: empty);
           invariant(
@@ -409,6 +479,12 @@ class RelayReader {
         } else {
           return this._readLink(selection.field, record, data);
         }
+      case RELAY_RESOLVER:
+        if (!RelayFeatureFlags.ENABLE_RELAY_RESOLVERS) {
+          throw new Error('Relay Resolver fields are not yet supported.');
+        }
+        this._readResolverField(selection.field, record, data);
+        break;
       default:
         (selection.field.kind: empty);
         invariant(
@@ -420,40 +496,142 @@ class RelayReader {
   }
 
   _readResolverField(
-    selection: ReaderRelayResolver,
+    field: ReaderRelayResolver,
     record: Record,
     data: SelectorData,
-  ): ?mixed {
-    const {name, alias, resolverModule, fragment} = selection;
-    const key = {
-      __id: RelayModernRecord.getDataID(record),
-      __fragmentOwner: this._owner,
-      __fragments: {
-        [fragment.name]: {}, // Arguments to this fragment; not yet supported.
-      },
-    };
-    const resolverContext = {
-      getDataForResolverFragment: singularReaderSelector => {
+  ): void {
+    const {resolverModule, fragment} = field;
+    const storageKey = getStorageKey(field, this._variables);
+    const resolverID = ClientID.generateClientID(
+      RelayModernRecord.getDataID(record),
+      storageKey,
+    );
+
+    // Found when reading the resolver fragment, which can happen either when
+    // evaluating the resolver and it calls readFragment, or when checking if the
+    // inputs have changed since a previous evaluation:
+    let fragmentValue;
+    let fragmentReaderSelector;
+    const fragmentSeenRecordIDs = new Set();
+
+    const getDataForResolverFragment = singularReaderSelector => {
+      if (fragmentValue != null) {
+        // It was already read when checking for input staleness; no need to read it again.
+        // Note that the variables like fragmentSeenRecordIDs in the outer closure will have
+        // already been set and will still be used in this case.
+        return fragmentValue;
+      }
+      fragmentReaderSelector = singularReaderSelector;
+      const existingSeenRecords = this._seenRecords;
+      try {
+        this._seenRecords = fragmentSeenRecordIDs;
         const resolverFragmentData = {};
         this._createInlineDataOrResolverFragmentPointer(
           singularReaderSelector.node,
           record,
           resolverFragmentData,
         );
-        const answer = resolverFragmentData[FRAGMENTS_KEY]?.[fragment.name];
+        fragmentValue = resolverFragmentData[FRAGMENTS_KEY]?.[fragment.name];
         invariant(
-          typeof answer === 'object' && answer !== null,
+          typeof fragmentValue === 'object' && fragmentValue !== null,
           `Expected reader data to contain a __fragments property with a property for the fragment named ${fragment.name}, but it is missing.`,
         );
-        return answer;
-      },
+        return fragmentValue;
+      } finally {
+        this._seenRecords = existingSeenRecords;
+      }
     };
-    const resolverResult = withResolverContext(resolverContext, () =>
-      // $FlowFixMe[prop-missing] - resolver module's type signature is a lie
-      resolverModule(key),
+    const resolverContext = {getDataForResolverFragment};
+
+    const [result, seenRecord] = this._resolverCache.readFromCacheOrEvaluate(
+      record,
+      field,
+      this._variables,
+      () => {
+        const key = {
+          __id: RelayModernRecord.getDataID(record),
+          __fragmentOwner: this._owner,
+          __fragments: {
+            [fragment.name]: {}, // Arguments to this fragment; not yet supported.
+          },
+        };
+        return withResolverContext(resolverContext, () => {
+          // $FlowFixMe[prop-missing] - resolver module's type signature is a lie
+          const resolverResult = resolverModule(key);
+          return {
+            resolverResult,
+            fragmentValue,
+            resolverID,
+            seenRecordIDs: fragmentSeenRecordIDs,
+            readerSelector: fragmentReaderSelector,
+          };
+        });
+      },
+      getDataForResolverFragment,
+    );
+    if (seenRecord != null) {
+      this._seenRecords.add(seenRecord);
+    }
+
+    const applicationName = field.alias ?? field.name;
+    data[applicationName] = result;
+  }
+
+  _readClientEdge(
+    field: ReaderClientEdge,
+    record: Record,
+    data: SelectorData,
+  ): void {
+    const backingField = field.backingField;
+
+    // Because ReaderClientExtension doesn't have `alias` or `name` and so I don't know
+    // how to get its applicationName or storageKey yet:
+    invariant(
+      backingField.kind !== 'ClientExtension',
+      'Client extension client edges are not yet implemented.',
+    );
+
+    const applicationName = backingField.alias ?? backingField.name;
+
+    const backingFieldData = {};
+    this._traverseSelections([backingField], record, backingFieldData);
+    const destinationDataID = backingFieldData[applicationName];
+
+    if (destinationDataID == null) {
+      data[applicationName] = destinationDataID;
+      return;
+    }
+
+    invariant(
+      typeof destinationDataID === 'string',
+      'Plural client edges not are yet implemented',
+    ); // FIXME support plural
+
+    // Not wrapping the push/pop in a try/finally because if we throw, the
+    // Reader object is not usable after that anyway.
+    this._clientEdgeTraversalPath.push({
+      readerClientEdge: field,
+      clientEdgeDestinationID: destinationDataID,
+    });
+
+    const prevData = data[applicationName];
+    invariant(
+      prevData == null || typeof prevData === 'object',
+      'RelayReader(): Expected data for field `%s` on record `%s` ' +
+        'to be an object, got `%s`.',
+      applicationName,
+      RelayModernRecord.getDataID(record),
+      prevData,
     );
-    data[alias ?? name] = resolverResult;
-    return resolverResult;
+    const value = this._traverse(
+      field.linkedField,
+      destinationDataID,
+      // $FlowFixMe[incompatible-variance]
+      prevData,
+    );
+    data[applicationName] = value;
+
+    this._clientEdgeTraversalPath.pop();
   }
 
   _readFlightField(
@@ -463,14 +641,12 @@ class RelayReader {
   ): ?mixed {
     const applicationName = field.alias ?? field.name;
     const storageKey = getStorageKey(field, this._variables);
-    const reactFlightClientResponseRecordID = RelayModernRecord.getLinkedRecordID(
-      record,
-      storageKey,
-    );
+    const reactFlightClientResponseRecordID =
+      RelayModernRecord.getLinkedRecordID(record, storageKey);
     if (reactFlightClientResponseRecordID == null) {
       data[applicationName] = reactFlightClientResponseRecordID;
       if (reactFlightClientResponseRecordID === undefined) {
-        this._isMissingData = true;
+        this._markDataAsMissing();
       }
       return reactFlightClientResponseRecordID;
     }
@@ -481,7 +657,7 @@ class RelayReader {
     if (reactFlightClientResponseRecord == null) {
       data[applicationName] = reactFlightClientResponseRecord;
       if (reactFlightClientResponseRecord === undefined) {
-        this._isMissingData = true;
+        this._markDataAsMissing();
       }
       return reactFlightClientResponseRecord;
     }
@@ -501,7 +677,7 @@ class RelayReader {
     const storageKey = getStorageKey(field, this._variables);
     const value = RelayModernRecord.getValue(record, storageKey);
     if (value === undefined) {
-      this._isMissingData = true;
+      this._markDataAsMissing();
     }
     data[applicationName] = value;
     return value;
@@ -518,7 +694,7 @@ class RelayReader {
     if (linkedID == null) {
       data[applicationName] = linkedID;
       if (linkedID === undefined) {
-        this._isMissingData = true;
+        this._markDataAsMissing();
       }
       return linkedID;
     }
@@ -538,6 +714,42 @@ class RelayReader {
     return value;
   }
 
+  _readActorChange(
+    field: ReaderActorChange,
+    record: Record,
+    data: SelectorData,
+  ): ?mixed {
+    const applicationName = field.alias ?? field.name;
+    const storageKey = getStorageKey(field, this._variables);
+    const externalRef = RelayModernRecord.getActorLinkedRecordID(
+      record,
+      storageKey,
+    );
+
+    if (externalRef == null) {
+      data[applicationName] = externalRef;
+      if (externalRef === undefined) {
+        this._markDataAsMissing();
+      }
+      return data[applicationName];
+    }
+    const [actorIdentifier, dataID] = externalRef;
+
+    const fragmentRef = {};
+    this._createFragmentPointer(
+      field.fragmentSpread,
+      {
+        __id: dataID,
+      },
+      fragmentRef,
+    );
+    data[applicationName] = {
+      __fragmentRef: fragmentRef,
+      __viewer: actorIdentifier,
+    };
+    return data[applicationName];
+  }
+
   _readPluralLink(
     field: ReaderLinkedField,
     record: Record,
@@ -550,7 +762,7 @@ class RelayReader {
     if (linkedIDs == null) {
       data[applicationName] = linkedIDs;
       if (linkedIDs === undefined) {
-        this._isMissingData = true;
+        this._markDataAsMissing();
       }
       return linkedIDs;
     }
@@ -568,7 +780,7 @@ class RelayReader {
     linkedIDs.forEach((linkedID, nextIndex) => {
       if (linkedID == null) {
         if (linkedID === undefined) {
-          this._isMissingData = true;
+          this._markDataAsMissing();
         }
         // $FlowFixMe[cannot-write]
         linkedArray[nextIndex] = linkedID;
@@ -606,7 +818,7 @@ class RelayReader {
     const component = RelayModernRecord.getValue(record, componentKey);
     if (component == null) {
       if (component === undefined) {
-        this._isMissingData = true;
+        this._markDataAsMissing();
       }
       return;
     }
@@ -620,7 +832,7 @@ class RelayReader {
       {
         kind: 'FragmentSpread',
         name: moduleImport.fragmentName,
-        args: null,
+        args: moduleImport.args,
       },
       record,
       data,
@@ -651,11 +863,18 @@ class RelayReader {
       ? getArgumentValues(fragmentSpread.args, this._variables)
       : {};
     data[FRAGMENT_OWNER_KEY] = this._owner;
-
-    if (RelayFeatureFlags.ENABLE_PRECISE_TYPE_REFINEMENT) {
-      data[
-        IS_WITHIN_UNMATCHED_TYPE_REFINEMENT
-      ] = this._isWithinUnmatchedTypeRefinement;
+    data[IS_WITHIN_UNMATCHED_TYPE_REFINEMENT] =
+      this._isWithinUnmatchedTypeRefinement;
+
+    if (RelayFeatureFlags.ENABLE_CLIENT_EDGES) {
+      if (
+        this._clientEdgeTraversalPath.length > 0 &&
+        this._clientEdgeTraversalPath[
+          this._clientEdgeTraversalPath.length - 1
+        ] !== null
+      ) {
+        data[CLIENT_EDGE_TRAVERSAL_PATH] = [...this._clientEdgeTraversalPath];
+      }
     }
   }