relay-runtime 11.0.0-rc.0 → 12.0.0

package/store/RelayStoreTypes.js.flow

@@ -12,6 +12,10 @@
 
 'use strict';
 
+import type {
+  ActorIdentifier,
+  IActorEnvironment,
+} from '../multi-actor-environment';
 import type {
   GraphQLResponse,
   INetwork,
@@ -27,6 +31,7 @@ import type {
   NormalizationRootNode,
   NormalizationScalarField,
   NormalizationSelectableNode,
+  NormalizationArgument,
 } from '../util/NormalizationNode';
 import type {ReaderFragment} from '../util/ReaderNode';
 import type {
@@ -144,6 +149,9 @@ export type Props = {[key: string]: mixed, ...};
  */
 export type RelayContext = {|
   environment: IEnvironment,
+  getEnvironmentForActor?: ?(
+    actorIdentifier: ActorIdentifier,
+  ) => IActorEnvironment,
 |};
 
 /**
@@ -190,7 +198,7 @@ export interface FragmentSpecResolver {
    * Subscribe to resolver updates.
    * Overrides existing callback (if one has been specified).
    */
-  setCallback(callback: () => void): void;
+  setCallback(props: Props, callback: () => void): void;
 }
 
 /**
@@ -216,8 +224,10 @@ export interface MutableRecordSource extends RecordSource {
 }
 
 export type CheckOptions = {|
-  target: MutableRecordSource,
   handlers: $ReadOnlyArray<MissingFieldHandler>,
+  defaultActorIdentifier: ActorIdentifier,
+  getTargetForActor: (actorIdentifier: ActorIdentifier) => MutableRecordSource,
+  getSourceForActor: (actorIdentifier: ActorIdentifier) => RecordSource,
 |};
 
 export type OperationAvailability =
@@ -332,6 +342,11 @@ export interface Store {
     invalidationState: InvalidationState,
     callback: () => void,
   ): Disposable;
+
+  /**
+   * Get the current write epoch
+   */
+  getEpoch(): number;
 }
 
 export interface StoreSubscriptions {
@@ -359,7 +374,7 @@ export interface StoreSubscriptions {
   /**
    * Notifies each subscription if the snapshot for the subscription selector has changed.
    * Mutates the updatedOwners array with any owners (RequestDescriptors) associated
-   * with the subscriptions that were notifed; i.e. the owners affected by the changes.
+   * with the subscriptions that were notified; i.e. the owners affected by the changes.
    */
   updateSubscriptions(
     source: RecordSource,
@@ -445,6 +460,23 @@ export interface RecordSourceSelectorProxy extends RecordSourceProxy {
 }
 
 export type LogEvent =
+  | {|
+      +name: 'suspense.fragment',
+      +data: mixed,
+      +fragment: ReaderFragment,
+      +isRelayHooks: boolean,
+      +isMissingData: boolean,
+      +isPromiseCached: boolean,
+      +pendingOperations: $ReadOnlyArray<RequestDescriptor>,
+    |}
+  | {|
+      +name: 'suspense.query',
+      +fetchPolicy: string,
+      +isPromiseCached: boolean,
+      +operation: OperationDescriptor,
+      +queryAvailability: ?OperationAvailability,
+      +renderPolicy: RenderPolicy,
+    |}
   | {|
       +name: 'queryresource.fetch',
       // ID of this query resource request and will be the same
@@ -456,7 +488,7 @@ export type LogEvent =
       // FetchPolicy from Relay Hooks
       +fetchPolicy: string,
       // RenderPolicy from Relay Hooks
-      +renderPolicy: string,
+      +renderPolicy: RenderPolicy,
       +queryAvailability: OperationAvailability,
       +shouldFetch: boolean,
     |}
@@ -468,33 +500,67 @@ export type LogEvent =
     |}
   | {|
       +name: 'network.info',
-      +transactionID: number,
+      +networkRequestId: number,
       +info: mixed,
     |}
   | {|
       +name: 'network.start',
-      +transactionID: number,
+      +networkRequestId: number,
       +params: RequestParameters,
       +variables: Variables,
       +cacheConfig: CacheConfig,
     |}
   | {|
       +name: 'network.next',
-      +transactionID: number,
+      +networkRequestId: number,
       +response: GraphQLResponse,
     |}
   | {|
       +name: 'network.error',
-      +transactionID: number,
+      +networkRequestId: number,
       +error: Error,
     |}
   | {|
       +name: 'network.complete',
-      +transactionID: number,
+      +networkRequestId: number,
     |}
   | {|
       +name: 'network.unsubscribe',
-      +transactionID: number,
+      +networkRequestId: number,
+    |}
+  | {|
+      +name: 'execute.start',
+      +executeId: number,
+      +params: RequestParameters,
+      +variables: Variables,
+      +cacheConfig: CacheConfig,
+    |}
+  | {|
+      +name: 'execute.next',
+      +executeId: number,
+      +response: GraphQLResponse,
+      +duration: number,
+    |}
+  | {|
+      +name: 'execute.async.module',
+      +executeId: number,
+      +operationName: string,
+      +duration: number,
+    |}
+  | {|
+      +name: 'execute.flight.payload_deserialize',
+      +executeId: number,
+      +operationName: string,
+      +duration: number,
+    |}
+  | {|
+      +name: 'execute.error',
+      +executeId: number,
+      +error: Error,
+    |}
+  | {|
+      +name: 'execute.complete',
+      +executeId: number,
     |}
   | {|
       +name: 'store.publish',
@@ -584,6 +650,19 @@ export interface IEnvironment {
    */
   applyUpdate(optimisticUpdate: OptimisticUpdateFunction): Disposable;
 
+  /**
+   * Revert updates for the `update` function.
+   */
+  revertUpdate(update: OptimisticUpdateFunction): void;
+
+  /**
+   * Revert updates for the `update` function, and apply the `replacement` update.
+   */
+  replaceUpdate(
+    update: OptimisticUpdateFunction,
+    replacement: OptimisticUpdateFunction,
+  ): void;
+
   /**
    * Apply an optimistic mutation response and/or updater. The mutation can be
    * reverted by calling `dispose()` on the returned value.
@@ -658,18 +737,14 @@ export interface IEnvironment {
    * the result is subscribed to:
    * environment.executeMutation({...}).subscribe({...}).
    */
-  executeMutation({|
-    operation: OperationDescriptor,
-    optimisticUpdater?: ?SelectorStoreUpdater,
-    optimisticResponse?: ?Object,
-    updater?: ?SelectorStoreUpdater,
-    uploadables?: ?UploadableMap,
-  |}): RelayObservable<GraphQLResponse>;
+  executeMutation(
+    config: ExecuteMutationConfig,
+  ): RelayObservable<GraphQLResponse>;
 
   /**
    * Returns an Observable of GraphQLResponse resulting from executing the
    * provided Query or Subscription operation responses, the result of which is
-   * then normalized and comitted to the publish queue.
+   * then normalized and committed to the publish queue.
    *
    * Note: Observables are lazy, so calling this method will do nothing until
    * the result is subscribed to:
@@ -754,6 +829,7 @@ export type HandleFieldPayload = {|
  * with a `@module` fragment spread, or a Flight field's:
  *
  * ## @module Fragment Spread
+ * - args: Local arguments from the parent
  * - data: The GraphQL response value for the @match field.
  * - dataID: The ID of the store object linked to by the @match field.
  * - operationReference: A reference to a generated module containing the
@@ -781,14 +857,48 @@ export type HandleFieldPayload = {|
  *     root data.
  */
 export type ModuleImportPayload = {|
+  +kind: 'ModuleImportPayload',
+  +args: ?$ReadOnlyArray<NormalizationArgument>,
   +data: PayloadData,
   +dataID: DataID,
   +operationReference: mixed,
   +path: $ReadOnlyArray<string>,
   +typeName: string,
   +variables: Variables,
+  +actorIdentifier: ?ActorIdentifier,
+|};
+
+/**
+ * A payload that represents data necessary to process the results of an object
+ * with experimental actor change directive.
+ *
+ * - data: The GraphQL response value for the actor change field.
+ * - dataID: The ID of the store object linked to by the actor change field.
+ * - node: NormalizationLinkedField, where the actor change directive is used
+ * - path: to a field in the response
+ * - variables: Query variables.
+ * - typeName: the type that matched.
+ *
+ * The dataID, variables, and fragmentName can be used to create a Selector
+ * which can in turn be used to normalize and publish the data. The dataID and
+ * typeName can also be used to construct a root record for normalization.
+ */
+export type ActorPayload = {|
+  +kind: 'ActorPayload',
+  +data: PayloadData,
+  +dataID: DataID,
+  +node: NormalizationLinkedField,
+  +path: $ReadOnlyArray<string>,
+  +typeName: string,
+  +variables: Variables,
+  +actorIdentifier: ActorIdentifier,
 |};
 
+/**
+ * Union type of possible payload followups we may handle during normalization.
+ */
+export type FollowupPayload = ModuleImportPayload | ActorPayload;
+
 /**
  * Data emitted after processing a Defer or Stream node during normalization
  * that describes how to process the corresponding response chunk when it
@@ -801,6 +911,7 @@ export type DeferPlaceholder = {|
   +path: $ReadOnlyArray<string>,
   +selector: NormalizationSelector,
   +typeName: string,
+  +actorIdentifier: ?ActorIdentifier,
 |};
 export type StreamPlaceholder = {|
   +kind: 'stream',
@@ -809,6 +920,7 @@ export type StreamPlaceholder = {|
   +parentID: DataID,
   +node: NormalizationSelectableNode,
   +variables: Variables,
+  +actorIdentifier: ?ActorIdentifier,
 |};
 export type IncrementalDataPlaceholder = DeferPlaceholder | StreamPlaceholder;
 
@@ -930,13 +1042,24 @@ export type RelayResponsePayload = {|
   +errors: ?Array<PayloadError>,
   +fieldPayloads: ?Array<HandleFieldPayload>,
   +incrementalPlaceholders: ?Array<IncrementalDataPlaceholder>,
-  +moduleImportPayloads: ?Array<ModuleImportPayload>,
+  +followupPayloads: ?Array<FollowupPayload>,
   +source: MutableRecordSource,
   +isFinal: boolean,
 |};
 
 /**
- * Public interface for Publish Queue
+ * Configuration on the executeMutation(...).
+ */
+export type ExecuteMutationConfig = {|
+  operation: OperationDescriptor,
+  optimisticUpdater?: ?SelectorStoreUpdater,
+  optimisticResponse?: ?Object,
+  updater?: ?SelectorStoreUpdater,
+  uploadables?: ?UploadableMap,
+|};
+
+/**
+ * Public interface for Publish Queue.
  */
 export interface PublishQueue {
   /**
@@ -990,7 +1113,7 @@ export interface PublishQueue {
  */
 export type ReactFlightClientResponse = {readRoot: () => mixed, ...};
 
-export type ReactFlightReachableQuery = {|
+export type ReactFlightReachableExecutableDefinitions = {|
   +module: mixed,
   +variables: Variables,
 |};

package/store/RelayStoreUtils.js.flow

@@ -23,10 +23,14 @@ import type {
   NormalizationArgument,
   NormalizationField,
 } from '../util/NormalizationNode';
-import type {ReaderArgument, ReaderField} from '../util/ReaderNode';
+import type {
+  ReaderArgument,
+  ReaderField,
+  ReaderActorChange,
+} from '../util/ReaderNode';
 import type {Variables} from '../util/RelayRuntimeTypes';
 
-export type Arguments = {+[string]: mixed, ...};
+export type Arguments = interface {+[string]: mixed};
 
 const {VARIABLE, LITERAL, OBJECT_VALUE, LIST_VALUE} = RelayConcreteNode;
 
@@ -121,14 +125,19 @@ function getHandleStorageKey(
  * used here for consistency.
  */
 function getStorageKey(
-  field: NormalizationField | NormalizationHandle | ReaderField,
+  field:
+    | NormalizationField
+    | NormalizationHandle
+    | ReaderField
+    | ReaderActorChange,
   variables: Variables,
 ): string {
   if (field.storageKey) {
     // TODO T23663664: Handle nodes do not yet define a static storageKey.
     return (field: $FlowFixMe).storageKey;
   }
-  const {args, name} = field;
+  const args = typeof field.args === 'undefined' ? undefined : field.args;
+  const name = field.name;
   return args && args.length !== 0
     ? formatStorageKey(name, getArgumentValues(args, variables))
     : name;
@@ -178,6 +187,7 @@ function getStableVariableValue(name: string, variables: Variables): mixed {
     'getVariableValue(): Undefined variable `%s`.',
     name,
   );
+  // $FlowFixMe[cannot-write]
   return stableCopy(variables[name]);
 }
 
@@ -193,6 +203,7 @@ function getModuleOperationKey(documentName: string): string {
  * Constants shared by all implementations of RecordSource/MutableRecordSource/etc.
  */
 const RelayStoreUtils = {
+  ACTOR_IDENTIFIER_KEY: '__actorIdentifier',
   FRAGMENTS_KEY: '__fragments',
   FRAGMENT_OWNER_KEY: '__fragmentOwner',
   FRAGMENT_PROP_NAME_KEY: '__fragmentPropName',
@@ -205,6 +216,10 @@ const RelayStoreUtils = {
   TYPENAME_KEY: '__typename',
   INVALIDATED_AT_KEY: '__invalidated_at',
   IS_WITHIN_UNMATCHED_TYPE_REFINEMENT: '__isWithinUnmatchedTypeRefinement',
+  RELAY_RESOLVER_VALUE_KEY: '__resolverValue',
+  RELAY_RESOLVER_INVALIDATION_KEY: '__resolverValueMayBeInvalid',
+  RELAY_RESOLVER_INPUTS_KEY: '__resolverInputValues',
+  RELAY_RESOLVER_READER_SELECTOR_KEY: '__resolverReaderSelector',
 
   formatStorageKey,
   getArgumentValue,

package/store/ResolverCache.js.flow

@@ -0,0 +1,247 @@
+/**
+ * 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
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const RelayModernRecord = require('./RelayModernRecord');
+
+const recycleNodesInto = require('../util/recycleNodesInto');
+const warning = require('warning');
+
+const {generateClientID} = require('./ClientID');
+const {
+  RELAY_RESOLVER_VALUE_KEY,
+  RELAY_RESOLVER_INVALIDATION_KEY,
+  RELAY_RESOLVER_INPUTS_KEY,
+  RELAY_RESOLVER_READER_SELECTOR_KEY,
+  getStorageKey,
+} = require('./RelayStoreUtils');
+
+import type {ReaderRelayResolver} from '../util/ReaderNode';
+import type {DataID, Variables} from '../util/RelayRuntimeTypes';
+import type {
+  MutableRecordSource,
+  Record,
+  SingularReaderSelector,
+} from './RelayStoreTypes';
+
+type ResolverID = string;
+
+type EvaluationResult<T> = {|
+  resolverResult: T,
+  fragmentValue: {...},
+  resolverID: ResolverID,
+  seenRecordIDs: Set<DataID>,
+  readerSelector: SingularReaderSelector,
+|};
+
+export interface ResolverCache {
+  readFromCacheOrEvaluate<T>(
+    record: Record,
+    field: ReaderRelayResolver,
+    variables: Variables,
+    evaluate: () => EvaluationResult<T>,
+    getDataForResolverFragment: (SingularReaderSelector) => mixed,
+  ): [T /* Answer */, ?DataID /* Seen record */];
+  invalidateDataIDs(
+    updatedDataIDs: Set<DataID>, // Mutated in place
+  ): void;
+}
+
+// $FlowFixMe[unclear-type] - will always be empty
+const emptySet: $ReadOnlySet<any> = new Set();
+
+class NoopResolverCache implements ResolverCache {
+  readFromCacheOrEvaluate<T>(
+    record: Record,
+    field: ReaderRelayResolver,
+    variables: Variables,
+    evaluate: () => EvaluationResult<T>,
+    getDataForResolverFragment: SingularReaderSelector => mixed,
+  ): [T /* Answer */, ?DataID /* Seen record */] {
+    return [evaluate().resolverResult, undefined];
+  }
+  invalidateDataIDs(updatedDataIDs: Set<DataID>): void {}
+}
+
+function addDependencyEdge(edges, from, to): void {
+  let set = edges.get(from);
+  if (!set) {
+    set = new Set();
+    edges.set(from, set);
+  }
+  set.add(to);
+}
+
+class RecordResolverCache implements ResolverCache {
+  _resolverIDToRecordIDs: Map<ResolverID, Set<DataID>>;
+  _recordIDToResolverIDs: Map<DataID, Set<ResolverID>>;
+
+  _getRecordSource: () => MutableRecordSource;
+
+  constructor(getRecordSource: () => MutableRecordSource) {
+    this._resolverIDToRecordIDs = new Map();
+    this._recordIDToResolverIDs = new Map();
+    this._getRecordSource = getRecordSource;
+  }
+
+  readFromCacheOrEvaluate<T>(
+    record: Record,
+    field: ReaderRelayResolver,
+    variables: Variables,
+    evaluate: () => EvaluationResult<T>,
+    getDataForResolverFragment: SingularReaderSelector => mixed,
+  ): [T /* Answer */, ?DataID /* Seen record */] {
+    const recordSource = this._getRecordSource();
+    const recordID = RelayModernRecord.getDataID(record);
+
+    const storageKey = getStorageKey(field, variables);
+    let linkedID = RelayModernRecord.getLinkedRecordID(record, storageKey);
+    let linkedRecord = linkedID == null ? null : recordSource.get(linkedID);
+    if (
+      linkedRecord == null ||
+      this._isInvalid(linkedRecord, getDataForResolverFragment)
+    ) {
+      // Cache miss; evaluate the selector and store the result in a new record:
+      linkedID = linkedID ?? generateClientID(recordID, storageKey);
+      linkedRecord = RelayModernRecord.create(linkedID, '__RELAY_RESOLVER__');
+
+      const evaluationResult = evaluate();
+      RelayModernRecord.setValue(
+        linkedRecord,
+        RELAY_RESOLVER_VALUE_KEY,
+        evaluationResult.resolverResult,
+      );
+      RelayModernRecord.setValue(
+        linkedRecord,
+        RELAY_RESOLVER_INPUTS_KEY,
+        evaluationResult.fragmentValue,
+      );
+      RelayModernRecord.setValue(
+        linkedRecord,
+        RELAY_RESOLVER_READER_SELECTOR_KEY,
+        evaluationResult.readerSelector,
+      );
+      recordSource.set(linkedID, linkedRecord);
+
+      // Link the resolver value record to the resolver field of the record being read:
+      const nextRecord = RelayModernRecord.clone(record);
+      RelayModernRecord.setLinkedRecordID(nextRecord, storageKey, linkedID);
+      recordSource.set(RelayModernRecord.getDataID(nextRecord), nextRecord);
+
+      // Put records observed by the resolver into the dependency graph:
+      const resolverID = evaluationResult.resolverID;
+      addDependencyEdge(this._resolverIDToRecordIDs, resolverID, linkedID);
+      addDependencyEdge(this._recordIDToResolverIDs, recordID, resolverID);
+      for (const seenRecordID of evaluationResult.seenRecordIDs) {
+        addDependencyEdge(
+          this._recordIDToResolverIDs,
+          seenRecordID,
+          resolverID,
+        );
+      }
+    }
+
+    // $FlowFixMe[incompatible-type] - will always be empty
+    const answer: T = linkedRecord[RELAY_RESOLVER_VALUE_KEY];
+    return [answer, linkedID];
+  }
+
+  invalidateDataIDs(
+    updatedDataIDs: Set<DataID>, // Mutated in place
+  ): void {
+    const recordSource = this._getRecordSource();
+    const visited: Set<string> = new Set();
+    const recordsToVisit = Array.from(updatedDataIDs);
+    while (recordsToVisit.length) {
+      const recordID = recordsToVisit.pop();
+      updatedDataIDs.add(recordID);
+      for (const fragment of this._recordIDToResolverIDs.get(recordID) ??
+        emptySet) {
+        if (!visited.has(fragment)) {
+          for (const anotherRecordID of this._resolverIDToRecordIDs.get(
+            fragment,
+          ) ?? emptySet) {
+            this._markInvalidatedResolverRecord(
+              anotherRecordID,
+              recordSource,
+              updatedDataIDs,
+            );
+            if (!visited.has(anotherRecordID)) {
+              recordsToVisit.push(anotherRecordID);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  _markInvalidatedResolverRecord(
+    dataID: DataID,
+    recordSource: MutableRecordSource, // Written to
+    updatedDataIDs: Set<DataID>, // Mutated in place
+  ) {
+    const record = recordSource.get(dataID);
+    if (!record) {
+      warning(
+        false,
+        'Expected a resolver record with ID %s, but it was missing.',
+        dataID,
+      );
+      return;
+    }
+    const nextRecord = RelayModernRecord.clone(record);
+    RelayModernRecord.setValue(
+      nextRecord,
+      RELAY_RESOLVER_INVALIDATION_KEY,
+      true,
+    );
+    recordSource.set(dataID, nextRecord);
+  }
+
+  _isInvalid(
+    record: Record,
+    getDataForResolverFragment: SingularReaderSelector => mixed,
+  ): boolean {
+    if (!RelayModernRecord.getValue(record, RELAY_RESOLVER_INVALIDATION_KEY)) {
+      return false;
+    }
+    const originalInputs = RelayModernRecord.getValue(
+      record,
+      RELAY_RESOLVER_INPUTS_KEY,
+    );
+    // $FlowFixMe[incompatible-type] - storing values in records is not typed
+    const readerSelector: ?SingularReaderSelector = RelayModernRecord.getValue(
+      record,
+      RELAY_RESOLVER_READER_SELECTOR_KEY,
+    );
+    if (originalInputs == null || readerSelector == null) {
+      warning(
+        false,
+        'Expected previous inputs and reader selector on resolver record with ID %s, but they were missing.',
+        RelayModernRecord.getDataID(record),
+      );
+      return true;
+    }
+    const latestValues = getDataForResolverFragment(readerSelector);
+    const recycled = recycleNodesInto(originalInputs, latestValues);
+    if (recycled !== originalInputs) {
+      return true;
+    }
+    return false;
+  }
+}
+
+module.exports = {
+  NoopResolverCache,
+  RecordResolverCache,
+};