relay-runtime 20.1.0 → 21.0.0

package/store/RelayModernSelector.js.flow

@@ -66,7 +66,7 @@ const warning = require('warning');
  */
 function getSingularSelector(
   fragment: ReaderFragment,
-  item: mixed,
+  item: unknown,
 ): ?SingularReaderSelector {
   invariant(
     typeof item === 'object' && item !== null && !Array.isArray(item),
@@ -90,9 +90,9 @@ function getSingularSelector(
     (mixedClientEdgeTraversalPath == null ||
       Array.isArray(mixedClientEdgeTraversalPath))
   ) {
-    const owner: RequestDescriptor = (mixedOwner: $FlowFixMe);
+    const owner: RequestDescriptor = mixedOwner as $FlowFixMe;
     const clientEdgeTraversalPath: ?ClientEdgeTraversalPath =
-      (mixedClientEdgeTraversalPath: $FlowFixMe);
+      mixedClientEdgeTraversalPath as $FlowFixMe;
 
     const argumentVariables = fragments[fragment.name];
     const fragmentVariables = getFragmentVariables(
@@ -146,7 +146,7 @@ function getSingularSelector(
  */
 function getPluralSelector(
   fragment: ReaderFragment,
-  items: $ReadOnlyArray<mixed>,
+  items: ReadonlyArray<unknown>,
 ): ?PluralReaderSelector {
   let selectors: null | Array<SingularReaderSelector> = null;
   items.forEach((item, ii) => {
@@ -168,7 +168,7 @@ function getPluralSelector(
 
 function getSelector(
   fragment: ReaderFragment,
-  item: mixed | Array<mixed>,
+  item: unknown | Array<unknown>,
 ): ?ReaderSelector {
   if (item == null) {
     return item;
@@ -207,7 +207,7 @@ function getSelector(
  */
 function getSelectorsFromObject(
   fragments: {[key: string]: ReaderFragment, ...},
-  object: {[key: string]: mixed, ...},
+  object: {[key: string]: unknown, ...},
 ): {[key: string]: ?ReaderSelector, ...} {
   const selectors: {[string]: ?ReaderSelector} = {};
   for (const key in fragments) {
@@ -231,7 +231,7 @@ function getSelectorsFromObject(
  */
 function getDataIDsFromObject(
   fragments: {[key: string]: ReaderFragment, ...},
-  object: {[key: string]: mixed, ...},
+  object: {[key: string]: unknown, ...},
 ): {[key: string]: ?(DataID | Array<DataID>), ...} {
   const ids: {[string]: ?(DataID | Array<DataID>)} = {};
   for (const key in fragments) {
@@ -246,7 +246,7 @@ function getDataIDsFromObject(
 
 function getDataIDsFromFragment(
   fragment: ReaderFragment,
-  item: mixed | Array<mixed>,
+  item: unknown | Array<unknown>,
 ): ?DataID | ?Array<DataID> {
   if (item == null) {
     return item;
@@ -278,7 +278,7 @@ function getDataIDsFromFragment(
  */
 function getDataIDs(
   fragment: ReaderFragment,
-  items: $ReadOnlyArray<mixed>,
+  items: ReadonlyArray<unknown>,
 ): ?Array<DataID> {
   let ids: null | Array<DataID> = null;
   items.forEach(item => {
@@ -294,7 +294,7 @@ function getDataIDs(
 /**
  * @internal
  */
-function getDataID(fragment: ReaderFragment, item: mixed): ?DataID {
+function getDataID(fragment: ReaderFragment, item: unknown): ?DataID {
   invariant(
     typeof item === 'object' && item !== null && !Array.isArray(item),
     'RelayModernSelector: Expected value for fragment `%s` to be an object, got ' +
@@ -332,7 +332,7 @@ function getDataID(fragment: ReaderFragment, item: mixed): ?DataID {
  */
 function getVariablesFromObject(
   fragments: {[key: string]: ReaderFragment, ...},
-  object: {[key: string]: mixed, ...},
+  object: {[key: string]: unknown, ...},
 ): Variables {
   const variables = {};
   for (const key in fragments) {
@@ -349,7 +349,7 @@ function getVariablesFromObject(
 
 function getVariablesFromFragment(
   fragment: ReaderFragment,
-  item: mixed | $ReadOnlyArray<mixed>,
+  item: unknown | ReadonlyArray<unknown>,
 ): Variables {
   if (item == null) {
     return {};
@@ -380,7 +380,7 @@ function getVariablesFromFragment(
 
 function getVariablesFromSingularFragment(
   fragment: ReaderFragment,
-  item: mixed,
+  item: unknown,
 ): ?Variables {
   const selector = getSingularSelector(fragment, item);
   if (!selector) {
@@ -391,7 +391,7 @@ function getVariablesFromSingularFragment(
 
 function getVariablesFromPluralFragment(
   fragment: ReaderFragment,
-  items: $ReadOnlyArray<mixed>,
+  items: ReadonlyArray<unknown>,
 ): Variables {
   const variables = {};
   items.forEach((value, ii) => {
@@ -519,13 +519,13 @@ function createReaderSelector(
   clientEdgeTraversalPath: ?ClientEdgeTraversalPath,
 ): SingularReaderSelector {
   return {
-    kind: 'SingularReaderSelector',
+    clientEdgeTraversalPath: clientEdgeTraversalPath ?? null,
     dataID,
     isWithinUnmatchedTypeRefinement,
-    clientEdgeTraversalPath: clientEdgeTraversalPath ?? null,
+    kind: 'SingularReaderSelector',
     node: fragment,
-    variables,
     owner: request,
+    variables,
   };
 }
 
@@ -539,16 +539,16 @@ function createNormalizationSelector(
 
 module.exports = {
   areEqualSelectors,
-  createReaderSelector,
   createNormalizationSelector,
+  createReaderSelector,
   getDataIDsFromFragment,
   getDataIDsFromObject,
-  getSingularSelector,
   getPluralSelector,
   getSelector,
   getSelectorsFromObject,
-  getVariablesFromSingularFragment,
-  getVariablesFromPluralFragment,
+  getSingularSelector,
   getVariablesFromFragment,
   getVariablesFromObject,
+  getVariablesFromPluralFragment,
+  getVariablesFromSingularFragment,
 };

package/store/RelayModernStore.js.flow

@@ -40,6 +40,7 @@ const {
   assertInternalActorIdentifier,
 } = require('../multi-actor-environment/ActorIdentifier');
 const deepFreeze = require('../util/deepFreeze');
+const RelayFeatureFlags = require('../util/RelayFeatureFlags');
 const resolveImmediate = require('../util/resolveImmediate');
 const DataChecker = require('./DataChecker');
 const defaultGetDataID = require('./defaultGetDataID');
@@ -54,11 +55,16 @@ const RelayReader = require('./RelayReader');
 const RelayReferenceMarker = require('./RelayReferenceMarker');
 const RelayStoreSubscriptions = require('./RelayStoreSubscriptions');
 const RelayStoreUtils = require('./RelayStoreUtils');
-const {ROOT_ID, ROOT_TYPE} = require('./RelayStoreUtils');
+const {
+  FIELD_GRANULAR_NOTIFICATIONS_KEY,
+  ROOT_ID,
+  ROOT_TYPE,
+  getFieldNotificationKey,
+} = require('./RelayStoreUtils');
 const invariant = require('invariant');
 
 export opaque type InvalidationState = {
-  dataIDs: $ReadOnlyArray<DataID>,
+  dataIDs: ReadonlyArray<DataID>,
   invalidations: Map<DataID, ?number>,
 };
 
@@ -67,6 +73,11 @@ type InvalidationSubscription = {
   invalidationState: InvalidationState,
 };
 
+type Batch = {
+  sourceOperations: Array<OperationDescriptor>,
+  invalidateStore: boolean,
+};
+
 const DEFAULT_RELEASE_BUFFER_SIZE = 10;
 
 /**
@@ -115,6 +126,8 @@ class RelayModernStore implements Store {
   _resolverContext: ?ResolverContext;
   _actorIdentifier: ?ActorIdentifier;
   _treatMissingFieldsAsNull: boolean;
+  _deferDeduplicatedFields: boolean;
+  _batch: Batch | null;
 
   constructor(
     source: MutableRecordSource,
@@ -134,6 +147,7 @@ class RelayModernStore implements Store {
       // These additional config options are only used if the experimental
       // @outputType resolver feature is used
       treatMissingFieldsAsNull?: ?boolean,
+      deferDeduplicatedFields?: ?boolean,
       actorIdentifier?: ?ActorIdentifier,
     },
   ) {
@@ -182,7 +196,9 @@ class RelayModernStore implements Store {
       options?.shouldProcessClientComponents ?? false;
 
     this._treatMissingFieldsAsNull = options?.treatMissingFieldsAsNull ?? false;
+    this._deferDeduplicatedFields = options?.deferDeduplicatedFields ?? false;
     this._actorIdentifier = options?.actorIdentifier;
+    this._batch = null;
 
     initializeRecordSource(this._recordSource);
   }
@@ -235,6 +251,60 @@ class RelayModernStore implements Store {
     }
   }
 
+  /**
+   * Batch multiple store updates into a single notification pass.
+   *
+   * Fragments will still correctly Suspend on their own parent query during
+   * a batch. However, cross-operation Suspense (a fragment suspending on a
+   * *different* in-flight operation) may not work correctly for operations
+   * that complete during the batch.
+   */
+  experimental_batchUpdates(callback: () => void): void {
+    if (this._batch != null) {
+      throw new Error(
+        'RelayModernStore: Cannot batch updates while already batching updates.',
+      );
+    }
+    const log = this.__log;
+    if (log != null) {
+      log({name: 'store.batch.start'});
+    }
+    const batch: Batch = {sourceOperations: [], invalidateStore: false};
+    this._batch = batch;
+    try {
+      callback();
+    } finally {
+      this._batch = null;
+      this.notify(undefined, batch.invalidateStore);
+      for (const sourceOperation of batch.sourceOperations) {
+        this._recordSourceOperation(sourceOperation);
+      }
+      if (log != null) {
+        log({
+          name: 'store.batch.complete',
+          sourceOperations: batch.sourceOperations,
+          invalidateStore: batch.invalidateStore,
+        });
+      }
+    }
+  }
+
+  batchLiveStateUpdatesWithoutNotify(callback: () => void): boolean {
+    if (this.__log != null) {
+      this.__log({name: 'liveresolver.batch.start'});
+    }
+    let hasPublished = false;
+    try {
+      hasPublished =
+        this._resolverCache.batchLiveStateUpdatesWithoutNotify(callback);
+    } finally {
+      if (this.__log != null) {
+        this.__log({name: 'liveresolver.batch.end'});
+      }
+    }
+    return hasPublished;
+  }
+
   check(
     operation: OperationDescriptor,
     options?: CheckOptions,
@@ -341,7 +411,7 @@ class RelayModernStore implements Store {
           if (this._releaseBuffer.length > this._gcReleaseBufferSize) {
             const _id = this._releaseBuffer.shift();
             if (!this._shouldRetainWithinTTL_EXPERIMENTAL) {
-              // $FlowFixMe[incompatible-call]
+              // $FlowFixMe[incompatible-type]
               this._roots.delete(_id);
             }
             this.scheduleGC();
@@ -385,6 +455,7 @@ class RelayModernStore implements Store {
     const snapshot = RelayReader.read(
       source,
       selector,
+      log,
       this._resolverCache,
       this._resolverContext,
     );
@@ -404,7 +475,22 @@ class RelayModernStore implements Store {
   notify(
     sourceOperation?: OperationDescriptor,
     invalidateStore?: boolean,
-  ): $ReadOnlyArray<RequestDescriptor> {
+  ): ReadonlyArray<RequestDescriptor> {
+    // If we're inside a batchUpdates() call, defer notification.
+    const batch = this._batch;
+    if (batch != null) {
+      if (sourceOperation != null) {
+        batch.sourceOperations.push(sourceOperation);
+      }
+      if (invalidateStore === true) {
+        batch.invalidateStore = true;
+      }
+      // Returning [] here means the OperationExecutor's _updateOperationTracker
+      // will be a no-op for this call, since it relies on notify() returning
+      // the list of affected owners. See the experimental_batchUpdates JSDoc.
+      return [];
+    }
+
     const log = this.__log;
     if (log != null) {
       log({
@@ -413,69 +499,78 @@ class RelayModernStore implements Store {
       });
     }
 
-    // Increment the current write when notifying after executing
-    // a set of changes to the store.
-    this._currentWriteEpoch++;
+    if (!RelayFeatureFlags.OPTIMIZE_NOTIFY) {
+      // Increment the current write when notifying after executing
+      // a set of changes to the store.
+      this._currentWriteEpoch++;
 
-    if (invalidateStore === true) {
-      this._globalInvalidationEpoch = this._currentWriteEpoch;
+      if (invalidateStore === true) {
+        this._globalInvalidationEpoch = this._currentWriteEpoch;
+      }
     }
 
     // When a record is updated, we need to also handle records that depend on it,
     // specifically Relay Resolver result records containing results based on the
     // updated records. This both adds to updatedRecordIDs and invalidates any
     // cached data as needed.
-    this._resolverCache.invalidateDataIDs(this._updatedRecordIDs);
+    if (!RelayFeatureFlags.OPTIMIZE_NOTIFY || this._updatedRecordIDs.size > 0) {
+      this._resolverCache.invalidateDataIDs(this._updatedRecordIDs);
+    }
 
     const source = this.getSource();
     const updatedOwners: Array<RequestDescriptor> = [];
-    this._storeSubscriptions.updateSubscriptions(
-      source,
-      this._updatedRecordIDs,
-      updatedOwners,
-      sourceOperation,
-    );
-    this._invalidationSubscriptions.forEach(subscription => {
-      this._updateInvalidationSubscription(
-        subscription,
-        invalidateStore === true,
+    if (!RelayFeatureFlags.OPTIMIZE_NOTIFY || this._updatedRecordIDs.size > 0) {
+      this._storeSubscriptions.updateSubscriptions(
+        source,
+        this._updatedRecordIDs,
+        updatedOwners,
+        sourceOperation,
       );
-    });
+    } else {
+      // If no record is updated, we still need to traverse stale subscriptions for
+      // subscriptions that were using values from optimistic updates
+      this._storeSubscriptions.updateStaleSubscriptions(
+        source,
+        this._updatedRecordIDs,
+        updatedOwners,
+        sourceOperation,
+      );
+    }
 
-    // If a source operation was provided (indicating the operation
-    // that produced this update to the store), record the current epoch
-    // at which this operation was written.
-    if (sourceOperation != null) {
-      // We only track the epoch at which the operation was written if
-      // it was previously retained, to keep the size of our operation
-      // epoch map bounded. If a query wasn't retained, we assume it can
-      // may be deleted at any moment and thus is not relevant for us to track
-      // for the purposes of invalidation.
-      const id = sourceOperation.request.identifier;
-      const rootEntry = this._roots.get(id);
-      if (rootEntry != null) {
-        rootEntry.epoch = this._currentWriteEpoch;
-        rootEntry.fetchTime = Date.now();
-      } else if (
-        sourceOperation.request.node.params.operationKind === 'query' &&
-        this._gcReleaseBufferSize > 0 &&
-        this._releaseBuffer.length < this._gcReleaseBufferSize
-      ) {
-        // The operation isn't retained but there is space in the release buffer:
-        // temporarily track this operation in case the data can be reused soon.
-        const temporaryRootEntry = {
-          operation: sourceOperation,
-          refCount: 0,
-          epoch: this._currentWriteEpoch,
-          fetchTime: Date.now(),
-        };
-        this._releaseBuffer.push(id);
-        /* $FlowFixMe[incompatible-call] Natural Inference rollout. See
-         * https://fburl.com/gdoc/y8dn025u */
-        this._roots.set(id, temporaryRootEntry);
+    if (
+      RelayFeatureFlags.OPTIMIZE_NOTIFY &&
+      (this._updatedRecordIDs.size > 0 ||
+        updatedOwners.length > 0 ||
+        this._invalidatedRecordIDs.size > 0 ||
+        invalidateStore === true ||
+        this._globalInvalidationEpoch === this._currentWriteEpoch)
+    ) {
+      // Increment the current write when notifying after executing
+      // a set of changes to the store.
+      this._currentWriteEpoch++;
+
+      if (invalidateStore === true) {
+        this._globalInvalidationEpoch = this._currentWriteEpoch;
       }
     }
 
+    if (
+      !RelayFeatureFlags.OPTIMIZE_NOTIFY ||
+      this._invalidatedRecordIDs.size > 0 ||
+      invalidateStore === true
+    ) {
+      this._invalidationSubscriptions.forEach(subscription => {
+        this._updateInvalidationSubscription(
+          subscription,
+          invalidateStore === true,
+        );
+      });
+    }
+
+    if (sourceOperation != null) {
+      this._recordSourceOperation(sourceOperation);
+    }
+
     if (log != null) {
       log({
         name: 'store.notify.complete',
@@ -493,6 +588,40 @@ class RelayModernStore implements Store {
     return updatedOwners;
   }
 
+  /**
+   * Record that a source operation was written at the current epoch.
+   * We only track the epoch at which the operation was written if
+   * it was previously retained, to keep the size of our operation
+   * epoch map bounded. If a query wasn't retained, we assume it can
+   * be deleted at any moment and thus is not relevant for us to track
+   * for the purposes of invalidation.
+   */
+  _recordSourceOperation(sourceOperation: OperationDescriptor): void {
+    const id = sourceOperation.request.identifier;
+    const rootEntry = this._roots.get(id);
+    if (rootEntry != null) {
+      rootEntry.epoch = this._currentWriteEpoch;
+      rootEntry.fetchTime = Date.now();
+    } else if (
+      sourceOperation.request.node.params.operationKind === 'query' &&
+      this._gcReleaseBufferSize > 0 &&
+      this._releaseBuffer.length < this._gcReleaseBufferSize
+    ) {
+      // The operation isn't retained but there is space in the release buffer:
+      // temporarily track this operation in case the data can be reused soon.
+      const temporaryRootEntry = {
+        operation: sourceOperation,
+        refCount: 0,
+        epoch: this._currentWriteEpoch,
+        fetchTime: Date.now(),
+      };
+      this._releaseBuffer.push(id);
+      /* $FlowFixMe[incompatible-type] Natural Inference rollout. See
+       * https://fburl.com/gdoc/y8dn025u */
+      this._roots.set(id, temporaryRootEntry);
+    }
+  }
+
   publish(source: RecordSource, idsMarkedForInvalidation?: DataIDSet): void {
     const target = this._getMutableRecordSource();
     updateTargetFromSource(
@@ -543,7 +672,7 @@ class RelayModernStore implements Store {
     return {dispose};
   }
 
-  toJSON(): mixed {
+  toJSON(): unknown {
     return 'RelayModernStore()';
   }
 
@@ -556,7 +685,7 @@ class RelayModernStore implements Store {
     return this._updatedRecordIDs;
   }
 
-  lookupInvalidationState(dataIDs: $ReadOnlyArray<DataID>): InvalidationState {
+  lookupInvalidationState(dataIDs: ReadonlyArray<DataID>): InvalidationState {
     const invalidations = new Map<DataID, ?number>();
     dataIDs.forEach(dataID => {
       const record = this.getSource().get(dataID);
@@ -795,7 +924,7 @@ class RelayModernStore implements Store {
               RELAY_RESOLVER_LIVE_STATE_SUBSCRIPTION_KEY,
             );
             if (maybeResolverSubscription != null) {
-              // $FlowFixMe - this value if it is not null, it is a function
+              // $FlowFixMe[not-a-function] - this value if it is not null, it is a function
               maybeResolverSubscription();
             }
           }
@@ -819,14 +948,13 @@ class RelayModernStore implements Store {
   }
 
   // Internal API for normalizing @outputType payloads in LiveResolverCache.
-  __getNormalizationOptions(
-    path: $ReadOnlyArray<string>,
-  ): NormalizationOptions {
+  __getNormalizationOptions(path: ReadonlyArray<string>): NormalizationOptions {
     return {
       path,
       getDataID: this._getDataID,
       log: this.__log,
       treatMissingFieldsAsNull: this._treatMissingFieldsAsNull,
+      deferDeduplicatedFields: this._deferDeduplicatedFields,
       shouldProcessClientComponents: this._shouldProcessClientComponents,
       actorIdentifier: this._actorIdentifier,
     };
@@ -846,6 +974,13 @@ class RelayModernStore implements Store {
 function initializeRecordSource(target: MutableRecordSource) {
   if (!target.has(ROOT_ID)) {
     const rootRecord = RelayModernRecord.create(ROOT_ID, ROOT_TYPE);
+    if (RelayFeatureFlags.ENABLE_FIELD_GRANULAR_NOTIFICATIONS) {
+      RelayModernRecord.setValue(
+        rootRecord,
+        FIELD_GRANULAR_NOTIFICATIONS_KEY,
+        true,
+      );
+    }
     target.set(ROOT_ID, rootRecord);
   }
 }
@@ -930,6 +1065,32 @@ function updateTargetFromSource(
         }
         updatedRecordIDs.add(dataID);
         target.set(dataID, nextRecord);
+
+        // Add per-field notification keys for field-granular records
+        if (
+          RelayModernRecord.getValue(
+            nextRecord,
+            FIELD_GRANULAR_NOTIFICATIONS_KEY,
+          )
+        ) {
+          const fields = RelayModernRecord.getFields(nextRecord);
+          for (let jj = 0; jj < fields.length; jj++) {
+            const storageKey = fields[jj];
+            // Skip internal metadata keys (all start with '__')
+            if (storageKey.startsWith('__')) {
+              continue;
+            }
+            if (
+              RelayModernRecord.hasFieldChanged(
+                targetRecord,
+                nextRecord,
+                storageKey,
+              )
+            ) {
+              updatedRecordIDs.add(getFieldNotificationKey(dataID, storageKey));
+            }
+          }
+        }
       }
     } else if (sourceRecord === null) {
       target.delete(dataID);

package/store/RelayOperationTracker.js.flow

@@ -23,7 +23,7 @@ class RelayOperationTracker {
     {
       promise: Promise<void>,
       resolve: () => void,
-      pendingOperations: $ReadOnlyArray<RequestDescriptor>,
+      pendingOperations: ReadonlyArray<RequestDescriptor>,
     },
   >;
 
@@ -150,7 +150,7 @@ class RelayOperationTracker {
 
   getPendingOperationsAffectingOwner(owner: RequestDescriptor): {
     promise: Promise<void>,
-    pendingOperations: $ReadOnlyArray<RequestDescriptor>,
+    pendingOperations: ReadonlyArray<RequestDescriptor>,
   } | null {
     const ownerIdentifier = owner.identifier;
     const pendingOperationsForOwner =

package/store/RelayOptimisticRecordSource.js.flow

@@ -25,7 +25,7 @@ const RelayRecordSource = require('./RelayRecordSource');
 const invariant = require('invariant');
 
 const UNPUBLISH_RECORD_SENTINEL = RelayModernRecord.fromObject(
-  // $FlowFixMe[incompatible-call] frozen objects are readonly
+  // $FlowFixMe[incompatible-type] frozen objects are readonly
   Object.freeze({
     __UNPUBLISH_RECORD_SENTINEL: true,
   }),
@@ -88,7 +88,7 @@ class RelayOptimisticRecordSource implements MutableRecordSource {
   }
 
   remove(dataID: DataID): void {
-    // $FlowFixMe[incompatible-call] frozen objects are readonly
+    // $FlowFixMe[incompatible-type] frozen objects are readonly
     this._sink.set(dataID, UNPUBLISH_RECORD_SENTINEL);
   }