relay-runtime 11.0.2 → 13.0.0-rc.2

package/store/RelayStoreTypes.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,23 +12,30 @@
 
 'use strict';
 
+import type {
+  ActorIdentifier,
+  IActorEnvironment,
+} from '../multi-actor-environment';
 import type {
   GraphQLResponse,
   INetwork,
   PayloadData,
   PayloadError,
-  ReactFlightServerTree,
   ReactFlightServerError,
+  ReactFlightServerTree,
   UploadableMap,
 } from '../network/RelayNetworkTypes';
 import type RelayObservable from '../network/RelayObservable';
+import type {GraphQLTaggedNode} from '../query/GraphQLTag';
+import type {RequestIdentifier} from '../util/getRequestIdentifier';
 import type {
+  NormalizationArgument,
   NormalizationLinkedField,
   NormalizationRootNode,
   NormalizationScalarField,
   NormalizationSelectableNode,
 } from '../util/NormalizationNode';
-import type {ReaderFragment} from '../util/ReaderNode';
+import type {ReaderClientEdge, ReaderFragment} from '../util/ReaderNode';
 import type {
   ConcreteRequest,
   RequestParameters,
@@ -37,17 +44,23 @@ import type {
   CacheConfig,
   DataID,
   Disposable,
+  OperationType,
   RenderPolicy,
   Variables,
 } from '../util/RelayRuntimeTypes';
-import type {RequestIdentifier} from '../util/getRequestIdentifier';
 import type {InvalidationState} from './RelayModernStore';
 import type RelayOperationTracker from './RelayOperationTracker';
 import type {RecordState} from './RelayRecordState';
 
-export opaque type FragmentReference = empty;
+export opaque type FragmentType = empty;
 export type OperationTracker = RelayOperationTracker;
 
+export type MutationParameters = {|
+  +response: {...},
+  +variables: interface {},
+  +rawResponse?: {...},
+|};
+
 /*
  * An individual cached graph object.
  */
@@ -69,6 +82,7 @@ export type SingularReaderSelector = {|
   +kind: 'SingularReaderSelector',
   +dataID: DataID,
   +isWithinUnmatchedTypeRefinement: boolean,
+  +clientEdgeTraversalPath: ClientEdgeTraversalPath | null,
   +node: ReaderFragment,
   +owner: RequestDescriptor,
   +variables: Variables,
@@ -107,12 +121,26 @@ export type MissingRequiredFields =
   | {|action: 'THROW', field: MissingRequiredField|}
   | {|action: 'LOG', fields: Array<MissingRequiredField>|};
 
+export type ClientEdgeTraversalInfo = {|
+  +readerClientEdge: ReaderClientEdge,
+  +clientEdgeDestinationID: DataID,
+|};
+
+export type ClientEdgeTraversalPath =
+  $ReadOnlyArray<ClientEdgeTraversalInfo | null>;
+
+export type MissingClientEdgeRequestInfo = {|
+  +request: ConcreteRequest,
+  +clientEdgeDestinationID: DataID,
+|};
+
 /**
  * A representation of a selector and its results at a particular point in time.
  */
 export type Snapshot = {|
   +data: ?SelectorData,
   +isMissingData: boolean,
+  +missingClientEdges: null | $ReadOnlyArray<MissingClientEdgeRequestInfo>,
   +seenRecords: DataIDSet,
   +selector: SingularReaderSelector,
   +missingRequiredFields: ?MissingRequiredFields,
@@ -144,6 +172,9 @@ export type Props = {[key: string]: mixed, ...};
  */
 export type RelayContext = {|
   environment: IEnvironment,
+  getEnvironmentForActor?: ?(
+    actorIdentifier: ActorIdentifier,
+  ) => IActorEnvironment,
 |};
 
 /**
@@ -190,7 +221,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 +247,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 +365,11 @@ export interface Store {
     invalidationState: InvalidationState,
     callback: () => void,
   ): Disposable;
+
+  /**
+   * Get the current write epoch
+   */
+  getEpoch(): number;
 }
 
 export interface StoreSubscriptions {
@@ -359,7 +397,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,
@@ -427,6 +465,10 @@ export interface RecordSourceProxy {
   get(dataID: DataID): ?RecordProxy;
   getRoot(): RecordProxy;
   invalidateStore(): void;
+  readUpdatableQuery_EXPERIMENTAL<TQuery: OperationType>(
+    query: GraphQLTaggedNode,
+    variables: TQuery['variables'],
+  ): TQuery['response'];
 }
 
 export interface ReadOnlyRecordSourceProxy {
@@ -445,6 +487,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 +515,7 @@ export type LogEvent =
       // FetchPolicy from Relay Hooks
       +fetchPolicy: string,
       // RenderPolicy from Relay Hooks
-      +renderPolicy: string,
+      +renderPolicy: RenderPolicy,
       +queryAvailability: OperationAvailability,
       +shouldFetch: boolean,
     |}
@@ -468,33 +527,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,11 +677,26 @@ 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.
    */
-  applyMutation(optimisticConfig: OptimisticResponseConfig): Disposable;
+  applyMutation<TMutation: MutationParameters>(
+    optimisticConfig: OptimisticResponseConfig<TMutation>,
+  ): Disposable;
 
   /**
    * Commit an updater to the environment. This mutation cannot be reverted and
@@ -637,15 +745,27 @@ export interface IEnvironment {
    * responses may be returned (via `next`) over time followed by either
    * the request completing (`completed`) or an error (`error`).
    *
+   * Note: Observables are lazy, so calling this method will do nothing until
+   * the result is subscribed to: environment.execute({...}).subscribe({...}).
+   */
+  execute(config: {|
+    operation: OperationDescriptor,
+  |}): RelayObservable<GraphQLResponse>;
+
+  /**
+   * Send a subscription to the server with Observer semantics: one or more
+   * responses may be returned (via `next`) over time followed by either
+   * the request completing (`completed`) or an error (`error`).
+   *
    * Networks/servers that support subscriptions may choose to hold the
    * subscription open indefinitely such that `complete` is not called.
    *
    * Note: Observables are lazy, so calling this method will do nothing until
-   * the result is subscribed to: environment.execute({...}).subscribe({...}).
+   * the result is subscribed to: environment.executeSubscription({...}).subscribe({...}).
    */
-  execute(config: {|
+  executeSubscription<TMutation: MutationParameters>(config: {|
     operation: OperationDescriptor,
-    updater?: ?SelectorStoreUpdater,
+    updater?: ?SelectorStoreUpdater<TMutation['response']>,
   |}): RelayObservable<GraphQLResponse>;
 
   /**
@@ -658,14 +778,14 @@ export interface IEnvironment {
    * the result is subscribed to:
    * environment.executeMutation({...}).subscribe({...}).
    */
-  executeMutation(
-    config: ExecuteMutationConfig,
+  executeMutation<TMutation: MutationParameters>(
+    config: ExecuteMutationConfig<TMutation>,
   ): 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:
@@ -706,7 +826,7 @@ export interface IEnvironment {
 export type ModuleImportPointer = {
   +__fragmentPropName: ?string,
   +__module_component: mixed,
-  +$fragmentRefs: mixed,
+  +$fragmentSpreads: mixed,
   ...
 };
 
@@ -750,6 +870,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
@@ -777,14 +898,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
@@ -797,6 +952,7 @@ export type DeferPlaceholder = {|
   +path: $ReadOnlyArray<string>,
   +selector: NormalizationSelector,
   +typeName: string,
+  +actorIdentifier: ?ActorIdentifier,
 |};
 export type StreamPlaceholder = {|
   +kind: 'stream',
@@ -805,6 +961,7 @@ export type StreamPlaceholder = {|
   +parentID: DataID,
   +node: NormalizationSelectableNode,
   +variables: Variables,
+  +actorIdentifier: ?ActorIdentifier,
 |};
 export type IncrementalDataPlaceholder = DeferPlaceholder | StreamPlaceholder;
 
@@ -838,35 +995,33 @@ export type StoreUpdater = (store: RecordSourceProxy) => void;
  * order to easily access the root fields of a query/mutation as well as a
  * second argument of the response object of the mutation.
  */
-export type SelectorStoreUpdater = (
+export type SelectorStoreUpdater<-TMutationResponse> = (
   store: RecordSourceSelectorProxy,
-  // Actually SelectorData, but mixed is inconvenient to access deeply in
-  // product code.
-  data: $FlowFixMe,
+  data: ?TMutationResponse,
 ) => void;
 
 /**
  * A set of configs that can be used to apply an optimistic update into the
  * store.
  */
-export type OptimisticUpdate =
+export type OptimisticUpdate<TMutation: MutationParameters> =
   | OptimisticUpdateFunction
-  | OptimisticUpdateRelayPayload;
+  | OptimisticUpdateRelayPayload<TMutation>;
 
 export type OptimisticUpdateFunction = {|
   +storeUpdater: StoreUpdater,
 |};
 
-export type OptimisticUpdateRelayPayload = {|
+export type OptimisticUpdateRelayPayload<TMutation: MutationParameters> = {|
   +operation: OperationDescriptor,
   +payload: RelayResponsePayload,
-  +updater: ?SelectorStoreUpdater,
+  +updater: ?SelectorStoreUpdater<TMutation['response']>,
 |};
 
-export type OptimisticResponseConfig = {|
+export type OptimisticResponseConfig<TMutation: MutationParameters> = {|
   +operation: OperationDescriptor,
   +response: ?PayloadData,
-  +updater: ?SelectorStoreUpdater,
+  +updater: ?SelectorStoreUpdater<TMutation['response']>,
 |};
 
 /**
@@ -926,7 +1081,7 @@ export type RelayResponsePayload = {|
   +errors: ?Array<PayloadError>,
   +fieldPayloads: ?Array<HandleFieldPayload>,
   +incrementalPlaceholders: ?Array<IncrementalDataPlaceholder>,
-  +moduleImportPayloads: ?Array<ModuleImportPayload>,
+  +followupPayloads: ?Array<FollowupPayload>,
   +source: MutableRecordSource,
   +isFinal: boolean,
 |};
@@ -934,11 +1089,11 @@ export type RelayResponsePayload = {|
 /**
  * Configuration on the executeMutation(...).
  */
-export type ExecuteMutationConfig = {|
+export type ExecuteMutationConfig<TMutation: MutationParameters> = {|
   operation: OperationDescriptor,
-  optimisticUpdater?: ?SelectorStoreUpdater,
+  optimisticUpdater?: ?SelectorStoreUpdater<TMutation['response']>,
   optimisticResponse?: ?Object,
-  updater?: ?SelectorStoreUpdater,
+  updater?: ?SelectorStoreUpdater<TMutation['response']>,
   uploadables?: ?UploadableMap,
 |};
 
@@ -949,12 +1104,16 @@ export interface PublishQueue {
   /**
    * Schedule applying an optimistic updates on the next `run()`.
    */
-  applyUpdate(updater: OptimisticUpdate): void;
+  applyUpdate<TMutation: MutationParameters>(
+    updater: OptimisticUpdate<TMutation>,
+  ): void;
 
   /**
    * Schedule reverting an optimistic updates on the next `run()`.
    */
-  revertUpdate(updater: OptimisticUpdate): void;
+  revertUpdate<TMutation: MutationParameters>(
+    updater: OptimisticUpdate<TMutation>,
+  ): void;
 
   /**
    * Schedule a revert of all optimistic updates on the next `run()`.
@@ -964,10 +1123,10 @@ export interface PublishQueue {
   /**
    * Schedule applying a payload to the store on the next `run()`.
    */
-  commitPayload(
+  commitPayload<TMutation: MutationParameters>(
     operation: OperationDescriptor,
     payload: RelayResponsePayload,
-    updater?: ?SelectorStoreUpdater,
+    updater?: ?SelectorStoreUpdater<TMutation['response']>,
   ): void;
 
   /**

package/store/RelayStoreUtils.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,20 +12,23 @@
 
 'use strict';
 
-const RelayConcreteNode = require('../util/RelayConcreteNode');
-
-const getRelayHandleKey = require('../util/getRelayHandleKey');
-const invariant = require('invariant');
-const stableCopy = require('../util/stableCopy');
-
 import type {
-  NormalizationHandle,
   NormalizationArgument,
   NormalizationField,
+  NormalizationHandle,
 } from '../util/NormalizationNode';
-import type {ReaderArgument, ReaderField} from '../util/ReaderNode';
+import type {
+  ReaderActorChange,
+  ReaderArgument,
+  ReaderField,
+} from '../util/ReaderNode';
 import type {Variables} from '../util/RelayRuntimeTypes';
 
+const getRelayHandleKey = require('../util/getRelayHandleKey');
+const RelayConcreteNode = require('../util/RelayConcreteNode');
+const stableCopy = require('../util/stableCopy');
+const invariant = require('invariant');
+
 export type Arguments = interface {+[string]: mixed};
 
 const {VARIABLE, LITERAL, OBJECT_VALUE, LIST_VALUE} = RelayConcreteNode;
@@ -121,14 +124,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,7 +186,6 @@ function getStableVariableValue(name: string, variables: Variables): mixed {
     'getVariableValue(): Undefined variable `%s`.',
     name,
   );
-  // $FlowFixMe[cannot-write]
   return stableCopy(variables[name]);
 }
 
@@ -194,6 +201,8 @@ function getModuleOperationKey(documentName: string): string {
  * Constants shared by all implementations of RecordSource/MutableRecordSource/etc.
  */
 const RelayStoreUtils = {
+  ACTOR_IDENTIFIER_KEY: '__actorIdentifier',
+  CLIENT_EDGE_TRAVERSAL_PATH: '__clientEdgeTraversalPath',
   FRAGMENTS_KEY: '__fragments',
   FRAGMENT_OWNER_KEY: '__fragmentOwner',
   FRAGMENT_PROP_NAME_KEY: '__fragmentPropName',
@@ -206,6 +215,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,