relay-runtime 11.0.0-rc.0 → 12.0.0

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

@@ -0,0 +1,245 @@
+/**
+ * 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 {PayloadData, GraphQLResponse} from '../network/RelayNetworkTypes';
+import type RelayObservable from '../network/RelayObservable';
+import type RelayPublishQueue from '../store/RelayPublishQueue';
+import type {
+  OperationAvailability,
+  OperationDescriptor,
+  OptimisticResponseConfig,
+  OptimisticUpdateFunction,
+  SelectorStoreUpdater,
+  SingularReaderSelector,
+  Snapshot,
+  StoreUpdater,
+  IEnvironment,
+  ExecuteMutationConfig,
+  RecordSourceProxy,
+} 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(
+    actorEnvironment: IActorEnvironment,
+    optimisticConfig: OptimisticResponseConfig,
+  ): 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`).
+   *
+   * 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({...}).
+   */
+  execute(
+    actorEnvironment: IActorEnvironment,
+    config: {
+      operation: OperationDescriptor,
+      updater?: ?SelectorStoreUpdater,
+    },
+  ): 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(
+    actorEnvironment: IActorEnvironment,
+    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 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,27 @@
+/**
+ * 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 MultiActorEnvironment = require('./MultiActorEnvironment');
+
+const {getActorIdentifier} = require('./ActorIdentifier');
+
+export type {ActorIdentifier} from './ActorIdentifier';
+export type {
+  IActorEnvironment,
+  IMultiActorEnvironment,
+} from './MultiActorEnvironmentTypes';
+
+module.exports = {
+  MultiActorEnvironment,
+  getActorIdentifier,
+};

package/mutations/RelayRecordSourceSelectorProxy.js.flow

@@ -78,10 +78,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 ' +

package/mutations/commitMutation.js.flow

@@ -54,7 +54,7 @@ export type DEPRECATED_MutationConfig<T> = {|
 
 export type MutationParameters = {|
   +response: {...},
-  +variables: {...},
+  +variables: interface {},
   +rawResponse?: {...},
 |};
 
@@ -113,6 +113,8 @@ function commitMutation<T: MutationParameters>(
   } = config;
   const operation = createOperationDescriptor(
     mutation,
+    /* $FlowFixMe[class-object-subtyping] added when improving typing for this
+     * parameters */
     variables,
     cacheConfig,
     generateUniqueClientID(),

package/mutations/validateMutation.js.flow

@@ -30,8 +30,27 @@ type ValidationContext = {|
 
 const warning = require('warning');
 
+// $FlowFixMe[method-unbinding] added when improving typing for this parameters
 const hasOwnProperty = Object.prototype.hasOwnProperty;
 
+const {
+  ACTOR_CHANGE,
+  CONDITION,
+  CLIENT_COMPONENT,
+  CLIENT_EXTENSION,
+  DEFER,
+  FLIGHT_FIELD,
+  FRAGMENT_SPREAD,
+  INLINE_FRAGMENT,
+  LINKED_FIELD,
+  LINKED_HANDLE,
+  MODULE_IMPORT,
+  SCALAR_FIELD,
+  SCALAR_HANDLE,
+  STREAM,
+  TYPE_DISCRIMINATOR,
+} = require('../util/RelayConcreteNode');
+
 let validateMutation = () => {};
 if (__DEV__) {
   const addFieldToDiff = (path: string, diff: Object, isScalar) => {
@@ -96,21 +115,28 @@ if (__DEV__) {
     context: ValidationContext,
   ) => {
     switch (selection.kind) {
-      case 'Condition':
+      case CONDITION:
         validateSelections(optimisticResponse, selection.selections, context);
         return;
-      case 'FragmentSpread':
+      case CLIENT_COMPONENT:
+      case FRAGMENT_SPREAD:
         validateSelections(
           optimisticResponse,
           selection.fragment.selections,
           context,
         );
         return;
-      case 'ScalarField':
-      case 'LinkedField':
-      case 'FlightField':
+      case SCALAR_FIELD:
+      case LINKED_FIELD:
+      case FLIGHT_FIELD:
         return validateField(optimisticResponse, selection, context);
-      case 'InlineFragment':
+      case ACTOR_CHANGE:
+        return validateField(
+          optimisticResponse,
+          selection.linkedField,
+          context,
+        );
+      case INLINE_FRAGMENT:
         const type = selection.type;
         const isConcreteType = selection.abstractKey == null;
         selection.selections.forEach(subselection => {
@@ -120,18 +146,18 @@ if (__DEV__) {
           validateSelection(optimisticResponse, subselection, context);
         });
         return;
-      case 'ClientExtension':
+      case CLIENT_EXTENSION:
         selection.selections.forEach(subselection => {
           validateSelection(optimisticResponse, subselection, context);
         });
         return;
-      case 'ModuleImport':
+      case MODULE_IMPORT:
         return validateModuleImport(context);
-      case 'LinkedHandle':
-      case 'ScalarHandle':
-      case 'Defer':
-      case 'Stream':
-      case 'TypeDiscriminator': {
+      case LINKED_HANDLE:
+      case SCALAR_HANDLE:
+      case DEFER:
+      case STREAM:
+      case TYPE_DISCRIMINATOR: {
         // TODO(T35864292) - Add missing validations for these types
         return;
       }
@@ -154,12 +180,12 @@ if (__DEV__) {
     const path = `${context.path}.${fieldName}`;
     context.visitedPaths.add(path);
     switch (field.kind) {
-      case 'ScalarField':
+      case SCALAR_FIELD:
         if (hasOwnProperty.call(optimisticResponse, fieldName) === false) {
           addFieldToDiff(path, context.missingDiff, true);
         }
         return;
-      case 'LinkedField':
+      case LINKED_FIELD:
         const selections = field.selections;
         if (
           optimisticResponse[fieldName] === null ||
@@ -195,7 +221,7 @@ if (__DEV__) {
             return;
           }
         }
-      case 'FlightField':
+      case FLIGHT_FIELD:
         if (
           optimisticResponse[fieldName] === null ||
           (hasOwnProperty.call(optimisticResponse, fieldName) &&

package/network/RelayNetworkTypes.js.flow

@@ -20,14 +20,15 @@ import type RelayObservable, {ObservableFromValue} from './RelayObservable';
  * An interface for fetching the data for one or more (possibly interdependent)
  * queries.
  */
-export type INetwork = {|
-  execute: ExecuteFunction,
-|};
+export interface INetwork {
+  +execute: ExecuteFunction;
+}
+
 export type LogRequestInfoFunction = mixed => void;
 
-export type PayloadData = {[key: string]: mixed, ...};
+export type PayloadData = interface {[key: string]: mixed};
 
-export type PayloadError = {
+export type PayloadError = interface {
   message: string,
   locations?: Array<{
     line: number,
@@ -36,14 +37,13 @@ export type PayloadError = {
   }>,
   // Not officially part of the spec, but used at Facebook
   severity?: 'CRITICAL' | 'ERROR' | 'WARNING',
-  ...
 };
 
 export type PayloadExtensions = {[key: string]: mixed, ...};
 
 /**
  * The shape of a GraphQL response as dictated by the
- * [spec](https://graphql.github.io/graphql-spec/June2018/#sec-Response-Format)
+ * [spec](https://spec.graphql.org/June2018/#sec-Response-Format).
  */
 export type GraphQLResponseWithData = {|
   +data: PayloadData,
@@ -120,7 +120,7 @@ export type SubscribeFunction = (
 ) => RelayObservable<GraphQLResponse>;
 
 export type Uploadable = File | Blob;
-export type UploadableMap = {[key: string]: Uploadable, ...};
+export type UploadableMap = interface {[key: string]: Uploadable};
 
 /**
  * React Flight tree created on the server.
@@ -132,6 +132,13 @@ export type ReactFlightPayloadQuery = {|
   +response: GraphQLSingularResponse,
   +variables: Variables,
 |};
+export type ReactFlightPayloadFragment = {|
+  +__id: string,
+  +__typename: string,
+  +module: mixed,
+  +response: GraphQLSingularResponse,
+  +variables: Variables,
+|};
 export type ReactFlightServerError = {
   +message: string,
   +stack: string,
@@ -147,10 +154,12 @@ export type ReactFlightServerError = {
  * - queries: an array of queries that the server preloaded for the client.
  * - errors: an array of errors that were encountered while rendering the
  *           Server Component.
+ * - fragments: an array of fragments that the server preloaded for the client.
  */
 export type ReactFlightPayloadData = {|
   +status: string,
   +tree: ?Array<ReactFlightServerTree>,
   +queries: Array<ReactFlightPayloadQuery>,
   +errors: Array<ReactFlightServerError>,
+  +fragments: Array<ReactFlightPayloadFragment>,
 |};

package/network/RelayObservable.js.flow

@@ -355,11 +355,13 @@ class RelayObservable<+T> implements Subscribable<T> {
         }
       }
 
+      // $FlowFixMe[incompatible-call]
       this.subscribe({
         start,
         next(value) {
           try {
             if (!sink.closed) {
+              // $FlowFixMe[incompatible-call]
               RelayObservable.from(fn(value)).subscribe({
                 start,
                 next: sink.next,

package/network/RelayQueryResponseCache.js.flow

@@ -16,11 +16,14 @@ const invariant = require('invariant');
 const stableCopy = require('../util/stableCopy');
 
 import type {Variables} from '../util/RelayRuntimeTypes';
-import type {GraphQLSingularResponse} from './RelayNetworkTypes';
+import type {
+  GraphQLResponse,
+  GraphQLSingularResponse,
+} from './RelayNetworkTypes';
 
 type Response = {
   fetchTime: number,
-  payload: GraphQLSingularResponse,
+  payload: GraphQLResponse,
   ...
 };
 
@@ -55,7 +58,7 @@ class RelayQueryResponseCache {
     this._responses.clear();
   }
 
-  get(queryID: string, variables: Variables): ?GraphQLSingularResponse {
+  get(queryID: string, variables: Variables): ?GraphQLResponse {
     const cacheKey = getCacheKey(queryID, variables);
     this._responses.forEach((response, key) => {
       if (!isCurrent(response.fetchTime, this._ttl)) {
@@ -63,22 +66,33 @@ class RelayQueryResponseCache {
       }
     });
     const response = this._responses.get(cacheKey);
-    return response != null
-      ? ({
-          ...response.payload,
-          extensions: {
-            ...response.payload.extensions,
-            cacheTimestamp: response.fetchTime,
-          },
-        }: GraphQLSingularResponse)
-      : null;
+    if (response == null) {
+      return null;
+    }
+    if (Array.isArray(response.payload)) {
+      return response.payload.map(
+        payload =>
+          // $FlowFixMe[incompatible-cast]
+          ({
+            ...payload,
+            extensions: {
+              ...payload.extensions,
+              cacheTimestamp: response.fetchTime,
+            },
+          }: GraphQLSingularResponse),
+      );
+    }
+    // $FlowFixMe[incompatible-cast]
+    return ({
+      ...response.payload,
+      extensions: {
+        ...response.payload.extensions,
+        cacheTimestamp: response.fetchTime,
+      },
+    }: GraphQLSingularResponse);
   }
 
-  set(
-    queryID: string,
-    variables: Variables,
-    payload: GraphQLSingularResponse,
-  ): void {
+  set(queryID: string, variables: Variables, payload: GraphQLResponse): void {
     const fetchTime = Date.now();
     const cacheKey = getCacheKey(queryID, variables);
     this._responses.delete(cacheKey); // deletion resets key ordering

package/network/wrapNetworkWithLogObserver.js.flow

@@ -0,0 +1,99 @@
+/**
+ * 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
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const generateID = require('../util/generateID');
+
+import type ActorSpecificEnvironment from '../multi-actor-environment/ActorSpecificEnvironment';
+import type RelayModernEnvironment from '../store/RelayModernEnvironment';
+import type {RequestParameters} from '../util/RelayConcreteNode';
+import type {CacheConfig, Variables} from '../util/RelayRuntimeTypes';
+import type {
+  INetwork,
+  GraphQLResponse,
+  UploadableMap,
+} from './RelayNetworkTypes';
+import type RelayObservable from './RelayObservable';
+
+/**
+ * Wraps the network with logging to ensure that network requests are
+ * always logged. Relying on each network callsite to be wrapped is
+ * untenable and will eventually lead to holes in the logging.
+ * NOTE: This function takes an environment instance, because Relay
+ * devtools will mutate the `env.__log` method, and the devtools rely
+ * on it to receive network events.
+ */
+function wrapNetworkWithLogObserver(
+  env: RelayModernEnvironment | ActorSpecificEnvironment,
+  network: INetwork,
+): INetwork {
+  return {
+    execute(
+      params: RequestParameters,
+      variables: Variables,
+      cacheConfig: CacheConfig,
+      uploadables?: ?UploadableMap,
+    ): RelayObservable<GraphQLResponse> {
+      const networkRequestId = generateID();
+      const logObserver = {
+        start: subscription => {
+          env.__log({
+            name: 'network.start',
+            networkRequestId,
+            params,
+            variables,
+            cacheConfig,
+          });
+        },
+        next: response => {
+          env.__log({
+            name: 'network.next',
+            networkRequestId,
+            response,
+          });
+        },
+        error: error => {
+          env.__log({
+            name: 'network.error',
+            networkRequestId,
+            error,
+          });
+        },
+        complete: () => {
+          env.__log({
+            name: 'network.complete',
+            networkRequestId,
+          });
+        },
+        unsubscribe: () => {
+          env.__log({
+            name: 'network.unsubscribe',
+            networkRequestId,
+          });
+        },
+      };
+      const logRequestInfo = info => {
+        env.__log({
+          name: 'network.info',
+          networkRequestId,
+          info,
+        });
+      };
+      return network
+        .execute(params, variables, cacheConfig, uploadables, logRequestInfo)
+        .do(logObserver);
+    },
+  };
+}
+
+module.exports = wrapNetworkWithLogObserver;