relay-runtime 10.0.1 → 10.1.0

package/store/RelayResponseNormalizer.js.flow

@@ -16,6 +16,7 @@ const RelayFeatureFlags = require('../util/RelayFeatureFlags');
 const RelayModernRecord = require('./RelayModernRecord');
 const RelayProfiler = require('../util/RelayProfiler');
 
+const areEqual = require('areEqual');
 const invariant = require('invariant');
 const warning = require('warning');
 
@@ -23,6 +24,7 @@ const {
   CONDITION,
   CLIENT_EXTENSION,
   DEFER,
+  FLIGHT_FIELD,
   INLINE_FRAGMENT,
   LINKED_FIELD,
   LINKED_HANDLE,
@@ -34,6 +36,12 @@ const {
 } = require('../util/RelayConcreteNode');
 const {generateClientID, isClientID} = require('./ClientID');
 const {createNormalizationSelector} = require('./RelayModernSelector');
+const {
+  refineToReactFlightPayloadData,
+  REACT_FLIGHT_QUERIES_STORAGE_KEY,
+  REACT_FLIGHT_TREE_STORAGE_KEY,
+  REACT_FLIGHT_TYPE_NAME,
+} = require('./RelayStoreReactFlightUtils');
 const {
   getArgumentValues,
   getHandleStorageKey,
@@ -42,12 +50,14 @@ const {
   getStorageKey,
   TYPENAME_KEY,
   ROOT_ID,
+  ROOT_TYPE,
 } = require('./RelayStoreUtils');
 const {generateTypeID, TYPE_SCHEMA_TYPE} = require('./TypeID');
 
 import type {PayloadData} from '../network/RelayNetworkTypes';
 import type {
   NormalizationDefer,
+  NormalizationFlightField,
   NormalizationLinkedField,
   NormalizationModuleImport,
   NormalizationNode,
@@ -61,6 +71,8 @@ import type {
   ModuleImportPayload,
   MutableRecordSource,
   NormalizationSelector,
+  ReactFlightReachableQuery,
+  ReactFlightPayloadDeserializer,
   Record,
   RelayResponsePayload,
 } from './RelayStoreTypes';
@@ -74,6 +86,7 @@ export type NormalizationOptions = {|
   +getDataID: GetDataID,
   +treatMissingFieldsAsNull: boolean,
   +path?: $ReadOnlyArray<string>,
+  +reactFlightPayloadDeserializer?: ?ReactFlightPayloadDeserializer,
 |};
 
 /**
@@ -111,6 +124,7 @@ class RelayResponseNormalizer {
   _path: Array<string>;
   _recordSource: MutableRecordSource;
   _variables: Variables;
+  _reactFlightPayloadDeserializer: ?ReactFlightPayloadDeserializer;
 
   constructor(
     recordSource: MutableRecordSource,
@@ -127,6 +141,8 @@ class RelayResponseNormalizer {
     this._path = options.path ? [...options.path] : [];
     this._recordSource = recordSource;
     this._variables = variables;
+    this._reactFlightPayloadDeserializer =
+      options.reactFlightPayloadDeserializer;
   }
 
   normalizeResponse(
@@ -277,6 +293,13 @@ class RelayResponseNormalizer {
           this._traverseSelections(selection, record, data);
           this._isClientExtension = isClientExtension;
           break;
+        case FLIGHT_FIELD:
+          if (RelayFeatureFlags.ENABLE_REACT_FLIGHT_COMPONENT_FIELD) {
+            this._normalizeFlightField(node, selection, record, data);
+          } else {
+            throw new Error('Flight fields are not yet supported.');
+          }
+          break;
         default:
           (selection: empty);
           invariant(
@@ -441,23 +464,27 @@ class RelayResponseNormalizer {
           return;
         }
       }
-      if (selection.kind === SCALAR_FIELD && __DEV__) {
-        this._validateConflictingFieldsWithIdenticalId(
-          record,
-          storageKey,
-          fieldValue,
-        );
+      if (__DEV__) {
+        if (selection.kind === SCALAR_FIELD) {
+          this._validateConflictingFieldsWithIdenticalId(
+            record,
+            storageKey,
+            fieldValue,
+          );
+        }
       }
       RelayModernRecord.setValue(record, storageKey, null);
       return;
     }
 
     if (selection.kind === SCALAR_FIELD) {
-      this._validateConflictingFieldsWithIdenticalId(
-        record,
-        storageKey,
-        fieldValue,
-      );
+      if (__DEV__) {
+        this._validateConflictingFieldsWithIdenticalId(
+          record,
+          storageKey,
+          fieldValue,
+        );
+      }
       RelayModernRecord.setValue(record, storageKey, fieldValue);
     } else if (selection.kind === LINKED_FIELD) {
       this._path.push(responseKey);
@@ -477,6 +504,84 @@ class RelayResponseNormalizer {
     }
   }
 
+  _normalizeFlightField(
+    parent: NormalizationNode,
+    selection: NormalizationFlightField,
+    record: Record,
+    data: PayloadData,
+  ) {
+    const responseKey = selection.alias || selection.name;
+    const storageKey = getStorageKey(selection, this._variables);
+    const fieldValue = data[responseKey];
+
+    if (fieldValue == null) {
+      RelayModernRecord.setValue(record, storageKey, null);
+      return;
+    }
+
+    const reactFlightPayload = refineToReactFlightPayloadData(fieldValue);
+
+    invariant(
+      reactFlightPayload != null,
+      'RelayResponseNormalizer(): Expected React Flight payload data ' +
+        'to be an object with `tree` and `queries` properties, got `%s`.',
+      fieldValue,
+    );
+    invariant(
+      typeof this._reactFlightPayloadDeserializer === 'function',
+      'RelayResponseNormalizer: Expected reactFlightPayloadDeserializer to ' +
+        'be a function, got `%s`.',
+      this._reactFlightPayloadDeserializer,
+    );
+
+    // We store the deserialized reactFlightClientResponse in a separate
+    // record and link it to the parent record. This is so we can GC the Flight
+    // tree later even if the parent record is still reachable.
+    const reactFlightClientResponse = this._reactFlightPayloadDeserializer(
+      reactFlightPayload.tree,
+    );
+    const reactFlightID = generateClientID(
+      RelayModernRecord.getDataID(record),
+      getStorageKey(selection, this._variables),
+    );
+    let reactFlightClientResponseRecord = this._recordSource.get(reactFlightID);
+    if (reactFlightClientResponseRecord == null) {
+      reactFlightClientResponseRecord = RelayModernRecord.create(
+        reactFlightID,
+        REACT_FLIGHT_TYPE_NAME,
+      );
+      this._recordSource.set(reactFlightID, reactFlightClientResponseRecord);
+    }
+    RelayModernRecord.setValue(
+      reactFlightClientResponseRecord,
+      REACT_FLIGHT_TREE_STORAGE_KEY,
+      reactFlightClientResponse,
+    );
+    const reachableQueries: Array<ReactFlightReachableQuery> = [];
+    for (const query of reactFlightPayload.queries) {
+      if (query.response.data != null) {
+        this._moduleImportPayloads.push({
+          data: query.response.data,
+          dataID: ROOT_ID,
+          operationReference: query.module,
+          path: [],
+          typeName: ROOT_TYPE,
+          variables: query.variables,
+        });
+      }
+      reachableQueries.push({
+        module: query.module,
+        variables: query.variables,
+      });
+    }
+    RelayModernRecord.setValue(
+      reactFlightClientResponseRecord,
+      REACT_FLIGHT_QUERIES_STORAGE_KEY,
+      reachableQueries,
+    );
+    RelayModernRecord.setLinkedRecordID(record, storageKey, reactFlightID);
+  }
+
   _normalizeLink(
     field: NormalizationLinkedField,
     record: Record,
@@ -582,13 +687,17 @@ class RelayResponseNormalizer {
       } else if (__DEV__) {
         this._validateRecordType(nextRecord, field, item);
       }
-      if (prevIDs && __DEV__) {
-        this._validateConflictingLinkedFieldsWithIdenticalId(
-          record,
-          prevIDs[nextIndex],
-          nextID,
-          storageKey,
-        );
+      // NOTE: the check to strip __DEV__ code only works for simple
+      // `if (__DEV__)`
+      if (__DEV__) {
+        if (prevIDs) {
+          this._validateConflictingLinkedFieldsWithIdenticalId(
+            record,
+            prevIDs[nextIndex],
+            nextID,
+            storageKey,
+          );
+        }
       }
       // $FlowFixMe[incompatible-variance]
       this._traverseSelections(field, nextRecord, item);
@@ -629,13 +738,14 @@ class RelayResponseNormalizer {
     storageKey: string,
     fieldValue: mixed,
   ): void {
+    // NOTE: Only call this function in DEV
     if (__DEV__) {
       const dataID = RelayModernRecord.getDataID(record);
       var previousValue = RelayModernRecord.getValue(record, storageKey);
       warning(
         storageKey === TYPENAME_KEY ||
           previousValue === undefined ||
-          previousValue === fieldValue,
+          areEqual(previousValue, fieldValue),
         'RelayResponseNormalizer: Invalid record. The record contains two ' +
           'instances of the same id: `%s` with conflicting field, %s and its values: %s and %s. ' +
           'If two fields are different but share ' +
@@ -657,6 +767,7 @@ class RelayResponseNormalizer {
     nextID: DataID,
     storageKey: string,
   ): void {
+    // NOTE: Only call this function in DEV
     if (__DEV__) {
       warning(
         prevID === undefined || prevID === nextID,

package/store/RelayStoreReactFlightUtils.js.flow

@@ -0,0 +1,64 @@
+/**
+ * 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 invariant = require('invariant');
+
+const {getType} = require('./RelayModernRecord');
+
+import type {ReactFlightPayloadData} from '../network/RelayNetworkTypes';
+import type {ReactFlightClientResponse, Record} from './RelayStoreTypes';
+
+const REACT_FLIGHT_QUERIES_STORAGE_KEY = 'queries';
+const REACT_FLIGHT_TREE_STORAGE_KEY = 'tree';
+const REACT_FLIGHT_TYPE_NAME = 'ReactFlightComponent';
+
+function refineToReactFlightPayloadData(
+  payload: mixed,
+): ?ReactFlightPayloadData {
+  if (
+    payload == null ||
+    typeof payload !== 'object' ||
+    !Array.isArray(payload.tree) ||
+    !Array.isArray(payload.queries)
+  ) {
+    return null;
+  }
+  return (payload: $FlowFixMe);
+}
+
+function getReactFlightClientResponse(
+  record: Record,
+): ?ReactFlightClientResponse {
+  invariant(
+    getType(record) === REACT_FLIGHT_TYPE_NAME,
+    'getReactFlightClientResponse(): Expected a ReactFlightComponentRecord, ' +
+      'got %s.',
+    record,
+  );
+  const response: ?ReactFlightClientResponse = (record[
+    REACT_FLIGHT_TREE_STORAGE_KEY
+  ]: $FlowFixMe);
+  if (response != null) {
+    return response;
+  }
+  return null;
+}
+
+module.exports = {
+  REACT_FLIGHT_QUERIES_STORAGE_KEY,
+  REACT_FLIGHT_TREE_STORAGE_KEY,
+  REACT_FLIGHT_TYPE_NAME,
+  getReactFlightClientResponse,
+  refineToReactFlightPayloadData,
+};

package/store/RelayStoreTypes.js.flow

@@ -17,14 +17,15 @@ import type {
   INetwork,
   PayloadData,
   PayloadError,
+  ReactFlightServerTree,
   UploadableMap,
 } from '../network/RelayNetworkTypes';
 import type RelayObservable from '../network/RelayObservable';
 import type {
   NormalizationLinkedField,
+  NormalizationRootNode,
   NormalizationScalarField,
   NormalizationSelectableNode,
-  NormalizationSplitOperation,
 } from '../util/NormalizationNode';
 import type {ReaderFragment} from '../util/ReaderNode';
 import type {
@@ -83,6 +84,7 @@ export type RequestDescriptor = {|
   +identifier: RequestIdentifier,
   +node: ConcreteRequest,
   +variables: Variables,
+  +cacheConfig: ?CacheConfig,
 |};
 
 /**
@@ -95,16 +97,25 @@ export type NormalizationSelector = {|
   +variables: Variables,
 |};
 
+type MissingRequiredField = {|
+  path: string,
+  owner: string,
+|};
+
+export type MissingRequiredFields =
+  | {|action: 'THROW', field: MissingRequiredField|}
+  | {|action: 'LOG', fields: Array<MissingRequiredField>|};
+
 /**
  * A representation of a selector and its results at a particular point in time.
  */
-export type TypedSnapshot<TData> = {|
-  +data: TData,
+export type Snapshot = {|
+  +data: ?SelectorData,
   +isMissingData: boolean,
   +seenRecords: RecordMap,
   +selector: SingularReaderSelector,
+  +missingRequiredFields: ?MissingRequiredFields,
 |};
-export type Snapshot = TypedSnapshot<?SelectorData>;
 
 /**
  * An operation selector describes a specific instance of a GraphQL operation
@@ -236,8 +247,6 @@ export interface Store {
 
   /**
    * Read the results of a selector from in-memory records in the store.
-   * Optionally takes an owner, corresponding to the operation that
-   * owns this selector (fragment).
    */
   lookup(selector: SingularReaderSelector): Snapshot;
 
@@ -247,7 +256,7 @@ export interface Store {
    * Optionally provide an OperationDescriptor indicating the source operation
    * that was being processed to produce this run.
    *
-   * This method should return an array of the affected fragment owners
+   * This method should return an array of the affected fragment owners.
    */
   notify(
     sourceOperation?: OperationDescriptor,
@@ -263,7 +272,7 @@ export interface Store {
 
   /**
    * Ensure that all the records necessary to fulfill the given selector are
-   * retained in-memory. The records will not be eligible for garbage collection
+   * retained in memory. The records will not be eligible for garbage collection
    * until the returned reference is disposed.
    */
   retain(operation: OperationDescriptor): Disposable;
@@ -472,7 +481,13 @@ export type LogEvent =
       +name: 'store.notify.complete',
       +updatedRecordIDs: UpdatedRecords,
       +invalidatedRecordIDs: Set<DataID>,
+    |}
+  | {|
+      +name: 'entrypoint.root.consume',
+      +profilerContext: mixed,
+      +rootModuleID: string,
     |};
+
 export type LogFunction = LogEvent => void;
 export type LogRequestInfoFunction = mixed => void;
 
@@ -563,14 +578,12 @@ export interface IEnvironment {
   /**
    * EXPERIMENTAL
    * Returns the default render policy to use when rendering a query
-   * that uses Relay Hooks
+   * that uses Relay Hooks.
    */
   UNSTABLE_getDefaultRenderPolicy(): RenderPolicy;
 
   /**
    * Read the results of a selector from in-memory records in the store.
-   * Optionally takes an owner, corresponding to the operation that
-   * owns this selector (fragment).
    */
   lookup(selector: SingularReaderSelector): Snapshot;
 
@@ -587,7 +600,6 @@ export interface IEnvironment {
    */
   execute(config: {|
     operation: OperationDescriptor,
-    cacheConfig?: ?CacheConfig,
     updater?: ?SelectorStoreUpdater,
   |}): RelayObservable<GraphQLResponse>;
 
@@ -602,7 +614,6 @@ export interface IEnvironment {
    * environment.executeMutation({...}).subscribe({...}).
    */
   executeMutation({|
-    cacheConfig?: ?CacheConfig,
     operation: OperationDescriptor,
     optimisticUpdater?: ?SelectorStoreUpdater,
     optimisticResponse?: ?Object,
@@ -639,18 +650,13 @@ export interface IEnvironment {
    * whether we need to set up certain caches and timeout's.
    */
   isServer(): boolean;
-}
 
-/**
- * The results of reading data for a fragment. This is similar to a `Selector`,
- * but references the (fragment) node by name rather than by value.
- */
-export type FragmentPointer = {
-  __id: DataID,
-  __fragments: {[fragmentName: string]: Variables, ...},
-  __fragmentOwner: RequestDescriptor,
-  ...
-};
+  /**
+   * Called by Relay when it encounters a missing field that has been annotated
+   * with `@required(action: LOG)`.
+   */
+  requiredFieldLogger: RequiredFieldLogger;
+}
 
 /**
  * The partial shape of an object with a '...Fragment @module(name: "...")'
@@ -699,7 +705,9 @@ export type HandleFieldPayload = {|
 
 /**
  * A payload that represents data necessary to process the results of an object
- * with a `@module` fragment spread:
+ * with a `@module` fragment spread, or a Flight field's:
+ *
+ * ## @module Fragment Spread
  * - 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
@@ -710,6 +718,21 @@ export type HandleFieldPayload = {|
  * 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.
+ *
+ * ## Flight fields
+ * In Flight, data for additional components rendered by the requested server
+ * component are included in the response returned by a Flight compliant server.
+ *
+ * - data: Data used by additional components rendered by the server component
+ *     being requested.
+ * - dataID: For Flight fields, this should always be ROOT_ID. This is because
+ *     the query data isn't relative to the parent record–it's root data.
+ * - operationReference: The query's module that will be later used by an
+ *     operation loader.
+ * - variables: The query's variables.
+ * - typeName: For Flight fields, this should always be ROOT_TYPE. This is
+ *     because the query data isn't relative to the parent record–it's
+ *     root data.
  */
 export type ModuleImportPayload = {|
   +data: PayloadData,
@@ -744,22 +767,22 @@ export type StreamPlaceholder = {|
 export type IncrementalDataPlaceholder = DeferPlaceholder | StreamPlaceholder;
 
 /**
- * A user-supplied object to load a generated operation (SplitOperation) AST
- * by a module reference. The exact format of a module reference is left to
- * the application, but it must be a plain JavaScript value (string, number,
- * or object/array of same).
+ * A user-supplied object to load a generated operation (SplitOperation or
+ * ConcreteRequest) AST by a module reference. The exact format of a module
+ * reference is left to the application, but it must be a plain JavaScript value
+ * (string, number, or object/array of same).
  */
 export type OperationLoader = {|
   /**
    * Synchronously load an operation, returning either the node or null if it
    * cannot be resolved synchronously.
    */
-  get(reference: mixed): ?NormalizationSplitOperation,
+  get(reference: mixed): ?NormalizationRootNode,
 
   /**
    * Asynchronously load an operation.
    */
-  load(reference: mixed): Promise<?NormalizationSplitOperation>,
+  load(reference: mixed): Promise<?NormalizationRootNode>,
 |};
 
 /**
@@ -837,6 +860,23 @@ export type MissingFieldHandler =
       ) => ?Array<?DataID>,
     |};
 
+/**
+ * A handler for events related to @required fields. Currently reports missing
+ * fields with either `action: LOG` or `action: THROW`.
+ */
+export type RequiredFieldLogger = (
+  | {|
+      +kind: 'missing_field.log',
+      +owner: string,
+      +fieldPath: string,
+    |}
+  | {|
+      +kind: 'missing_field.throw',
+      +owner: string,
+      +fieldPath: string,
+    |},
+) => void;
+
 /**
  * The results of normalizing a query.
  */
@@ -897,3 +937,22 @@ export interface PublishQueue {
    */
   run(sourceOperation?: OperationDescriptor): $ReadOnlyArray<RequestDescriptor>;
 }
+
+/**
+ * ReactFlightDOMRelayClient processes a ReactFlightServerTree into a
+ * ReactFlightClientResponse object. readRoot() can suspend.
+ */
+export type ReactFlightClientResponse = {readRoot: () => mixed, ...};
+
+export type ReactFlightReachableQuery = {|
+  +module: mixed,
+  +variables: Variables,
+|};
+
+/**
+ * A user-supplied function that takes a ReactFlightServerTree, and deserializes
+ * it into a ReactFlightClientResponse object.
+ */
+export type ReactFlightPayloadDeserializer = (
+  tree: ReactFlightServerTree,
+) => ReactFlightClientResponse;

package/store/defaultRequiredFieldLogger.js.flow

@@ -0,0 +1,23 @@
+/**
+ * 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
+ */
+
+'use strict';
+
+import type {RequiredFieldLogger} from './RelayStoreTypes';
+
+const defaultRequiredFieldLogger: RequiredFieldLogger = event => {
+  if (__DEV__ && event.kind === 'missing_field.log') {
+    throw new Error(
+      'Relay Environment Configuration Error (dev only): `@required(action: LOG)` requires that the Relay Environment be configured with a `requiredFieldLogger`.',
+    );
+  }
+};
+
+module.exports = defaultRequiredFieldLogger;

package/subscription/requestSubscription.js.flow

@@ -60,7 +60,11 @@ function requestSubscription<TSubscriptionPayload>(
     variables,
     cacheConfig,
   } = config;
-  const operation = createOperationDescriptor(subscription, variables);
+  const operation = createOperationDescriptor(
+    subscription,
+    variables,
+    cacheConfig,
+  );
 
   warning(
     !(config.updater && configs),
@@ -80,7 +84,6 @@ function requestSubscription<TSubscriptionPayload>(
     .execute({
       operation,
       updater,
-      cacheConfig,
     })
     .map(() => {
       const data = environment.lookup(operation.fragment).data;

package/util/NormalizationNode.js.flow

@@ -12,6 +12,8 @@
 
 'use strict';
 
+import type {ConcreteRequest} from './RelayConcreteNode';
+
 /**
  * Represents a single operation used to processing and normalize runtime
  * request results.
@@ -34,7 +36,6 @@ export type NormalizationLinkedHandle = {|
   +args: ?$ReadOnlyArray<NormalizationArgument>,
   +handle: string,
   +key: string,
-  // T45504512: new connection model
   // NOTE: this property is optional because it's expected to be rarely used
   +dynamicKey?: ?NormalizationArgument,
   +filters: ?$ReadOnlyArray<string>,
@@ -48,10 +49,10 @@ export type NormalizationScalarHandle = {|
   +args: ?$ReadOnlyArray<NormalizationArgument>,
   +handle: string,
   +key: string,
-  // T45504512: new connection model
   // NOTE: this property is optional because it's expected to be rarely used
   +dynamicKey?: ?NormalizationArgument,
   +filters: ?$ReadOnlyArray<string>,
+  +handleArgs?: $ReadOnlyArray<NormalizationArgument>,
 |};
 
 export type NormalizationArgument =
@@ -73,6 +74,7 @@ export type NormalizationClientExtension = {|
 |};
 
 export type NormalizationField =
+  | NormalizationFlightField
   | NormalizationScalarField
   | NormalizationLinkedField;
 
@@ -138,6 +140,14 @@ export type NormalizationScalarField = {|
   +storageKey: ?string,
 |};
 
+export type NormalizationFlightField = {|
+  +kind: 'FlightField',
+  +alias: ?string,
+  +name: string,
+  +args: ?$ReadOnlyArray<NormalizationArgument>,
+  +storageKey: ?string,
+|};
+
 export type NormalizationTypeDiscriminator = {|
   +kind: 'TypeDiscriminator',
   +abstractKey: string,
@@ -148,6 +158,7 @@ export type NormalizationSelection =
   | NormalizationClientExtension
   | NormalizationDefer
   | NormalizationField
+  | NormalizationFlightField
   | NormalizationHandle
   | NormalizationInlineFragment
   | NormalizationModuleImport
@@ -196,3 +207,7 @@ export type NormalizationSelectableNode =
   | NormalizationOperation
   | NormalizationSplitOperation
   | NormalizationStream;
+
+export type NormalizationRootNode =
+  | ConcreteRequest
+  | NormalizationSplitOperation;