relay-runtime 11.0.1 → 13.0.0-rc.1

package/multi-actor-environment/MultiActorEnvironmentTypes.js.flow

@@ -0,0 +1,261 @@
+/**
+ * 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.
+ *
+ * @emails oncall+relay
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+import type {GraphQLResponse, PayloadData} from '../network/RelayNetworkTypes';
+import type RelayObservable from '../network/RelayObservable';
+import type RelayPublishQueue from '../store/RelayPublishQueue';
+import type {
+  ExecuteMutationConfig,
+  IEnvironment,
+  MutationParameters,
+  OperationAvailability,
+  OperationDescriptor,
+  OptimisticResponseConfig,
+  OptimisticUpdateFunction,
+  RecordSourceProxy,
+  SelectorStoreUpdater,
+  SingularReaderSelector,
+  Snapshot,
+  StoreUpdater,
+} from '../store/RelayStoreTypes';
+import type {Disposable} from '../util/RelayRuntimeTypes';
+import type {ActorIdentifier} from './ActorIdentifier';
+
+export type MultiActorStoreUpdater = (
+  actorIdentifier: ActorIdentifier,
+  environment: IActorEnvironment,
+  store: RecordSourceProxy,
+) => void;
+
+/**
+ * Interface of actor specific sub-environment
+ */
+export interface IActorEnvironment extends IEnvironment {
+  /**
+   * Reference to the main MultiActorEnvironment that handles
+   * the network execution/and responsible for network integration
+   */
+  +multiActorEnvironment: IMultiActorEnvironment;
+
+  /**
+   * Identifier of the actor for the current active environment
+   */
+  +actorIdentifier: ActorIdentifier;
+
+  /**
+   * TODO: this needs to move the the MultiActorEnvironment with different API.
+   */
+  getPublishQueue(): RelayPublishQueue;
+
+  /**
+   * Optional. A human-readable identifier of the environment.
+   * This value should be visible in the dev tools.
+   */
+  +configName: ?string;
+}
+
+/**
+ * Interface for the main (or parent) multi-actor environment that contains
+ * the map of individual actor-specific sub-environments. These sub-environments
+ * implement the Relay IEnvironment interface.
+ */
+export interface IMultiActorEnvironment {
+  /**
+   * A factory of actor-specific environments.
+   */
+  forActor(actorIdentifier: ActorIdentifier): IActorEnvironment;
+
+  /**
+   * Determine if the operation can be resolved with data in the store (i.e. no
+   * fields are missing).
+   *
+   * Note that this operation effectively "executes" the selector against the
+   * cache and therefore takes time proportional to the size/complexity of the
+   * selector.
+   */
+  check(
+    actorEnvironment: IActorEnvironment,
+    operation: OperationDescriptor,
+  ): OperationAvailability;
+
+  /**
+   * Subscribe to changes to the results of a selector. The callback is called
+   * when data has been committed to the store that would cause the results of
+   * the snapshot's selector to change.
+   */
+  subscribe(
+    actorEnvironment: IActorEnvironment,
+    snapshot: Snapshot,
+    callback: (snapshot: Snapshot) => void,
+  ): Disposable;
+
+  /**
+   * Ensure that all the records necessary to fulfill the given selector are
+   * retained in-memory. The records will not be eligible for garbage collection
+   * until the returned reference is disposed.
+   */
+  retain(
+    actorEnvironment: IActorEnvironment,
+    operation: OperationDescriptor,
+  ): Disposable;
+
+  /**
+   * Apply an optimistic update to the environment. The mutation can be reverted
+   * by calling `dispose()` on the returned value.
+   */
+  applyUpdate(
+    actorEnvironment: IActorEnvironment,
+    optimisticUpdate: OptimisticUpdateFunction,
+  ): Disposable;
+
+  /**
+   * Revert updates for the `update` function.
+   */
+  revertUpdate(
+    actorEnvironment: IActorEnvironment,
+    update: OptimisticUpdateFunction,
+  ): void;
+
+  /**
+   * Revert updates for the `update` function, and apply the `replacement` update.
+   */
+  replaceUpdate(
+    actorEnvironment: IActorEnvironment,
+    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<TMutation: MutationParameters>(
+    actorEnvironment: IActorEnvironment,
+    optimisticConfig: OptimisticResponseConfig<TMutation>,
+  ): Disposable;
+
+  /**
+   * Commit an updater to the environment. This mutation cannot be reverted and
+   * should therefore not be used for optimistic updates. This is mainly
+   * intended for updating fields from client schema extensions.
+   */
+  commitUpdate(
+    actorEnvironment: IActorEnvironment,
+    updater: StoreUpdater,
+  ): void;
+
+  /**
+   * Commit store updates for each actor-specific environment known to MultiActorEnvironment
+   */
+  commitMultiActorUpdate(updater: MultiActorStoreUpdater): void;
+
+  /**
+   * Commit a payload to the environment using the given operation selector.
+   */
+  commitPayload(
+    actorEnvironment: IActorEnvironment,
+    operationDescriptor: OperationDescriptor,
+    payload: PayloadData,
+  ): void;
+
+  /**
+   * Read the results of a selector from in-memory records in the store.
+   */
+  lookup(
+    actorEnvironment: IActorEnvironment,
+    selector: SingularReaderSelector,
+  ): Snapshot;
+
+  /**
+   * Send a query 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`).
+   *
+   * Note: Observables are lazy, so calling this method will do nothing until
+   * the result is subscribed to: environment.execute({...}).subscribe({...}).
+   */
+  execute(
+    actorEnvironment: IActorEnvironment,
+    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.executeSubscription({...}).subscribe({...}).
+   */
+  executeSubscription<TMutation: MutationParameters>(
+    actorEnvironment: IActorEnvironment,
+    config: {
+      operation: OperationDescriptor,
+      updater?: ?SelectorStoreUpdater<TMutation['response']>,
+    },
+  ): RelayObservable<GraphQLResponse>;
+
+  /**
+   * Returns an Observable of GraphQLResponse resulting from executing the
+   * provided Mutation operation, the result of which is then normalized and
+   * committed to the publish queue along with an optional optimistic response
+   * or updater.
+   *
+   * Note: Observables are lazy, so calling this method will do nothing until
+   * the result is subscribed to:
+   * environment.executeMutation({...}).subscribe({...}).
+   */
+  executeMutation<TMutation: MutationParameters>(
+    actorEnvironment: IActorEnvironment,
+    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 committed to the publish queue.
+   *
+   * Note: Observables are lazy, so calling this method will do nothing until
+   * the result is subscribed to:
+   * environment.executeWithSource({...}).subscribe({...}).
+   */
+  executeWithSource(
+    actorEnvironment: IActorEnvironment,
+    {
+      operation: OperationDescriptor,
+      source: RelayObservable<GraphQLResponse>,
+    },
+  ): RelayObservable<GraphQLResponse>;
+
+  /**
+   * Returns true if a request is currently "active", meaning it's currently
+   * actively receiving payloads or downloading modules, and has not received
+   * a final payload yet. Note that a request might still be pending (or "in flight")
+   * without actively receiving payload, for example a live query or an
+   * active GraphQL subscription
+   */
+  isRequestActive(
+    actorEnvironment: IActorEnvironment,
+    requestIdentifier: string,
+  ): boolean;
+
+  /**
+   * Returns `true` if execute in the server environment
+   */
+  isServer(): boolean;
+}

package/multi-actor-environment/index.js.flow

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ *
+ * @emails oncall+relay
+ * @flow strict-local
+ * @format
+ */
+
+'use strict';
+
+const {getActorIdentifier} = require('./ActorIdentifier');
+const MultiActorEnvironment = require('./MultiActorEnvironment');
+
+export type {ActorIdentifier} from './ActorIdentifier';
+export type {
+  IActorEnvironment,
+  IMultiActorEnvironment,
+} from './MultiActorEnvironmentTypes';
+
+module.exports = {
+  MultiActorEnvironment,
+  getActorIdentifier,
+};

package/mutations/RelayDeclarativeMutationConfig.js.flow

@@ -12,11 +12,8 @@
 
 'use strict';
 
-const ConnectionHandler = require('../handlers/connection/ConnectionHandler');
-
-const warning = require('warning');
-
 import type {
+  MutationParameters,
   RecordSourceSelectorProxy,
   SelectorData,
   SelectorStoreUpdater,
@@ -24,6 +21,9 @@ import type {
 import type {ConcreteRequest} from '../util/RelayConcreteNode';
 import type {Variables} from '../util/RelayRuntimeTypes';
 
+const ConnectionHandler = require('../handlers/connection/ConnectionHandler');
+const warning = require('warning');
+
 const MutationTypes = Object.freeze({
   RANGE_ADD: 'RANGE_ADD',
   RANGE_DELETE: 'RANGE_DELETE',
@@ -39,7 +39,7 @@ export type RangeOperation = $Values<typeof RangeOperations>;
 
 type RangeBehaviorsFunction = (connectionArgs: {
   [name: string]: $FlowFixMe,
-  ...,
+  ...
 }) => RangeOperation;
 type RangeBehaviorsObject = {[key: string]: RangeOperation, ...};
 export type RangeBehaviors = RangeBehaviorsFunction | RangeBehaviorsObject;
@@ -84,18 +84,21 @@ export type DeclarativeMutationConfig =
   | RangeDeleteConfig
   | NodeDeleteConfig;
 
-function convert(
+function convert<TMutation: MutationParameters>(
   configs: Array<DeclarativeMutationConfig>,
   request: ConcreteRequest,
-  optimisticUpdater?: ?SelectorStoreUpdater,
-  updater?: ?SelectorStoreUpdater,
+  optimisticUpdater?: ?SelectorStoreUpdater<TMutation['response']>,
+  updater?: ?SelectorStoreUpdater<TMutation['response']>,
 ): {
-  optimisticUpdater: SelectorStoreUpdater,
-  updater: SelectorStoreUpdater,
+  optimisticUpdater: SelectorStoreUpdater<TMutation['response']>,
+  updater: SelectorStoreUpdater<TMutation['response']>,
   ...
 } {
-  const configOptimisticUpdates = optimisticUpdater ? [optimisticUpdater] : [];
-  const configUpdates = updater ? [updater] : [];
+  const configOptimisticUpdates: Array<
+    SelectorStoreUpdater<TMutation['response']>,
+  > = optimisticUpdater ? [optimisticUpdater] : [];
+  const configUpdates: Array<SelectorStoreUpdater<TMutation['response']>> =
+    updater ? [updater] : [];
   configs.forEach(config => {
     switch (config.type) {
       case 'NODE_DELETE':
@@ -124,13 +127,16 @@ function convert(
   return {
     optimisticUpdater: (
       store: RecordSourceSelectorProxy,
-      data: ?SelectorData,
+      data: ?TMutation['response'],
     ) => {
       configOptimisticUpdates.forEach(eachOptimisticUpdater => {
         eachOptimisticUpdater(store, data);
       });
     },
-    updater: (store: RecordSourceSelectorProxy, data: ?SelectorData) => {
+    updater: (
+      store: RecordSourceSelectorProxy,
+      data: ?TMutation['response'],
+    ) => {
       configUpdates.forEach(eachUpdater => {
         eachUpdater(store, data);
       });
@@ -141,13 +147,13 @@ function convert(
 function nodeDelete(
   config: NodeDeleteConfig,
   request: ConcreteRequest,
-): ?SelectorStoreUpdater {
+): ?SelectorStoreUpdater<mixed> {
   const {deletedIDFieldName} = config;
   const rootField = getRootField(request);
   if (!rootField) {
     return null;
   }
-  return (store: RecordSourceSelectorProxy, data: ?SelectorData) => {
+  return (store: RecordSourceSelectorProxy, data: ?mixed) => {
     const payload = store.getRootField(rootField);
     if (!payload) {
       return;
@@ -165,7 +171,7 @@ function nodeDelete(
 function rangeAdd(
   config: RangeAddConfig,
   request: ConcreteRequest,
-): ?SelectorStoreUpdater {
+): ?SelectorStoreUpdater<mixed> {
   const {parentID, connectionInfo, edgeName} = config;
   if (!parentID) {
     warning(
@@ -179,7 +185,7 @@ function rangeAdd(
   if (!connectionInfo || !rootField) {
     return null;
   }
-  return (store: RecordSourceSelectorProxy, data: ?SelectorData) => {
+  return (store: RecordSourceSelectorProxy, data: ?mixed) => {
     const parent = store.get(parentID);
     if (!parent) {
       return;
@@ -233,13 +239,9 @@ function rangeAdd(
 function rangeDelete(
   config: RangeDeleteConfig,
   request: ConcreteRequest,
-): ?SelectorStoreUpdater {
-  const {
-    parentID,
-    connectionKeys,
-    pathToConnection,
-    deletedIDFieldName,
-  } = config;
+): ?SelectorStoreUpdater<mixed> {
+  const {parentID, connectionKeys, pathToConnection, deletedIDFieldName} =
+    config;
   if (!parentID) {
     warning(
       false,
@@ -252,12 +254,16 @@ function rangeDelete(
   if (!rootField) {
     return null;
   }
-  return (store: RecordSourceSelectorProxy, data: ?SelectorData) => {
+  return (store: RecordSourceSelectorProxy, data: ?mixed) => {
     if (!data) {
       return;
     }
     const deleteIDs = [];
+    // the type of data should come from a type parameter associated with ConcreteRequest,
+    // but ConcreteRequest does not contain a type parameter. Hence, we use a FlowFixMe.
+    // $FlowFixMe[incompatible-use] see above
     let deletedIDField = data[rootField];
+
     if (deletedIDField && Array.isArray(deletedIDFieldName)) {
       for (const eachField of deletedIDFieldName) {
         if (deletedIDField && typeof deletedIDField === 'object') {

package/mutations/RelayRecordProxy.js.flow

@@ -12,17 +12,16 @@
 
 'use strict';
 
-const invariant = require('invariant');
-
-const {generateClientID} = require('../store/ClientID');
-const {getStableStorageKey} = require('../store/RelayStoreUtils');
-
 import type {RecordProxy} from '../store/RelayStoreTypes';
 import type {Arguments} from '../store/RelayStoreUtils';
 import type {DataID} from '../util/RelayRuntimeTypes';
 import type RelayRecordSourceMutator from './RelayRecordSourceMutator';
 import type RelayRecordSourceProxy from './RelayRecordSourceProxy';
 
+const {generateClientID} = require('../store/ClientID');
+const {getStableStorageKey} = require('../store/RelayStoreUtils');
+const invariant = require('invariant');
+
 /**
  * @internal
  *

package/mutations/RelayRecordSourceMutator.js.flow

@@ -12,12 +12,6 @@
 
 'use strict';
 
-const RelayModernRecord = require('../store/RelayModernRecord');
-
-const invariant = require('invariant');
-
-const {EXISTENT} = require('../store/RelayRecordState');
-
 import type {RecordState} from '../store/RelayRecordState';
 import type {
   MutableRecordSource,
@@ -26,6 +20,10 @@ import type {
 } from '../store/RelayStoreTypes';
 import type {DataID} from '../util/RelayRuntimeTypes';
 
+const RelayModernRecord = require('../store/RelayModernRecord');
+const {EXISTENT} = require('../store/RelayRecordState');
+const invariant = require('invariant');
+
 /**
  * @internal
  *

package/mutations/RelayRecordSourceProxy.js.flow

@@ -12,26 +12,28 @@
 
 'use strict';
 
-const RelayModernRecord = require('../store/RelayModernRecord');
-const RelayRecordProxy = require('./RelayRecordProxy');
-
-const invariant = require('invariant');
-
-const {EXISTENT, NONEXISTENT} = require('../store/RelayRecordState');
-const {ROOT_ID, ROOT_TYPE} = require('../store/RelayStoreUtils');
-
 import type {HandlerProvider} from '../handlers/RelayDefaultHandlerProvider';
+import type {GraphQLTaggedNode} from '../query/GraphQLTag';
 import type {GetDataID} from '../store/RelayResponseNormalizer';
 import type {
   DataIDSet,
   HandleFieldPayload,
-  RecordSource,
   RecordProxy,
+  RecordSource,
   RecordSourceProxy,
 } from '../store/RelayStoreTypes';
-import type {DataID} from '../util/RelayRuntimeTypes';
+import type {DataID, OperationType} from '../util/RelayRuntimeTypes';
 import type RelayRecordSourceMutator from './RelayRecordSourceMutator';
 
+const RelayModernRecord = require('../store/RelayModernRecord');
+const {EXISTENT, NONEXISTENT} = require('../store/RelayRecordState');
+const {ROOT_ID, ROOT_TYPE} = require('../store/RelayStoreUtils');
+const {
+  readUpdatableQuery_EXPERIMENTAL,
+} = require('./readUpdatableQuery_EXPERIMENTAL');
+const RelayRecordProxy = require('./RelayRecordProxy');
+const invariant = require('invariant');
+
 /**
  * @internal
  *
@@ -160,6 +162,13 @@ class RelayRecordSourceProxy implements RecordSourceProxy {
   getIDsMarkedForInvalidation(): DataIDSet {
     return this._idsMarkedForInvalidation;
   }
+
+  readUpdatableQuery_EXPERIMENTAL<TQuery: OperationType>(
+    query: GraphQLTaggedNode,
+    variables: TQuery['variables'],
+  ): TQuery['response'] {
+    return readUpdatableQuery_EXPERIMENTAL(query, variables, this);
+  }
 }
 
 module.exports = RelayRecordSourceProxy;

package/mutations/RelayRecordSourceSelectorProxy.js.flow

@@ -12,10 +12,7 @@
 
 'use strict';
 
-const invariant = require('invariant');
-
-const {getStorageKey, ROOT_TYPE} = require('../store/RelayStoreUtils');
-
+import type {GraphQLTaggedNode} from '../query/GraphQLTag';
 import type {
   RecordProxy,
   RecordSourceProxy,
@@ -23,9 +20,15 @@ import type {
   SingularReaderSelector,
 } from '../store/RelayStoreTypes';
 import type {ReaderLinkedField} from '../util/ReaderNode';
-import type {DataID} from '../util/RelayRuntimeTypes';
+import type {DataID, OperationType} from '../util/RelayRuntimeTypes';
 import type RelayRecordSourceMutator from './RelayRecordSourceMutator';
 
+const {ROOT_TYPE, getStorageKey} = require('../store/RelayStoreUtils');
+const {
+  readUpdatableQuery_EXPERIMENTAL,
+} = require('./readUpdatableQuery_EXPERIMENTAL');
+const invariant = require('invariant');
+
 /**
  * @internal
  *
@@ -78,10 +81,15 @@ class RelayRecordSourceSelectorProxy implements RecordSourceSelectorProxy {
     fieldName: string,
     plural: boolean,
   ): ReaderLinkedField {
-    const field = selector.node.selections.find(
+    let field = selector.node.selections.find(
       selection =>
-        selection.kind === 'LinkedField' && selection.name === fieldName,
+        (selection.kind === 'LinkedField' && selection.name === fieldName) ||
+        (selection.kind === 'RequiredField' &&
+          selection.field.name === fieldName),
     );
+    if (field && field.kind === 'RequiredField') {
+      field = field.field;
+    }
     invariant(
       field && field.kind === 'LinkedField',
       'RelayRecordSourceSelectorProxy#getRootField(): Cannot find root ' +
@@ -114,6 +122,13 @@ class RelayRecordSourceSelectorProxy implements RecordSourceSelectorProxy {
   invalidateStore(): void {
     this.__recordSource.invalidateStore();
   }
+
+  readUpdatableQuery_EXPERIMENTAL<TQuery: OperationType>(
+    query: GraphQLTaggedNode,
+    variables: TQuery['variables'],
+  ): TQuery['response'] {
+    return readUpdatableQuery_EXPERIMENTAL(query, variables, this);
+  }
 }
 
 module.exports = RelayRecordSourceSelectorProxy;

package/mutations/applyOptimisticMutation.js.flow

@@ -12,29 +12,28 @@
 
 'use strict';
 
-const RelayDeclarativeMutationConfig = require('./RelayDeclarativeMutationConfig');
-
-const invariant = require('invariant');
-const isRelayModernEnvironment = require('../store/isRelayModernEnvironment');
-
-const {getRequest} = require('../query/GraphQLTag');
-const {
-  createOperationDescriptor,
-} = require('../store/RelayModernOperationDescriptor');
-
 import type {GraphQLTaggedNode} from '../query/GraphQLTag';
 import type {
   IEnvironment,
+  MutationParameters,
   SelectorStoreUpdater,
 } from '../store/RelayStoreTypes';
 import type {Disposable, Variables} from '../util/RelayRuntimeTypes';
 import type {DeclarativeMutationConfig} from './RelayDeclarativeMutationConfig';
 
-export type OptimisticMutationConfig = {|
+const {getRequest} = require('../query/GraphQLTag');
+const isRelayModernEnvironment = require('../store/isRelayModernEnvironment');
+const {
+  createOperationDescriptor,
+} = require('../store/RelayModernOperationDescriptor');
+const RelayDeclarativeMutationConfig = require('./RelayDeclarativeMutationConfig');
+const invariant = require('invariant');
+
+export type OptimisticMutationConfig<TMutation: MutationParameters> = {|
   configs?: ?Array<DeclarativeMutationConfig>,
   mutation: GraphQLTaggedNode,
   variables: Variables,
-  optimisticUpdater?: ?SelectorStoreUpdater,
+  optimisticUpdater?: ?SelectorStoreUpdater<TMutation['response']>,
   optimisticResponse?: Object,
 |};
 
@@ -42,9 +41,9 @@ export type OptimisticMutationConfig = {|
  * Higher-level helper function to execute a mutation against a specific
  * environment.
  */
-function applyOptimisticMutation(
+function applyOptimisticMutation<TMutation: MutationParameters>(
   environment: IEnvironment,
-  config: OptimisticMutationConfig,
+  config: OptimisticMutationConfig<TMutation>,
 ): Disposable {
   invariant(
     isRelayModernEnvironment(environment),

package/mutations/commitLocalUpdate.js.flow

@@ -12,7 +12,7 @@
 
 'use strict';
 
-import type {StoreUpdater, IEnvironment} from '../store/RelayStoreTypes';
+import type {IEnvironment, StoreUpdater} from '../store/RelayStoreTypes';
 
 function commitLocalUpdate(
   environment: IEnvironment,