relay-runtime 9.0.0 → 10.1.0

package/mutations/commitMutation.js.flow

@@ -0,0 +1,181 @@
+/**
+ * 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 RelayDeclarativeMutationConfig = require('./RelayDeclarativeMutationConfig');
+
+const invariant = require('invariant');
+const isRelayModernEnvironment = require('../store/isRelayModernEnvironment');
+const validateMutation = require('./validateMutation');
+const warning = require('warning');
+
+const {getRequest} = require('../query/GraphQLTag');
+const {generateUniqueClientID} = require('../store/ClientID');
+const {
+  createOperationDescriptor,
+} = require('../store/RelayModernOperationDescriptor');
+
+import type {PayloadError, UploadableMap} from '../network/RelayNetworkTypes';
+import type {GraphQLTaggedNode} from '../query/GraphQLTag';
+import type {
+  IEnvironment,
+  SelectorStoreUpdater,
+} from '../store/RelayStoreTypes';
+import type {
+  CacheConfig,
+  Disposable,
+  Variables,
+} from '../util/RelayRuntimeTypes';
+import type {DeclarativeMutationConfig} from './RelayDeclarativeMutationConfig';
+
+export type DEPRECATED_MutationConfig<T> = {|
+  configs?: Array<DeclarativeMutationConfig>,
+  cacheConfig?: CacheConfig,
+  mutation: GraphQLTaggedNode,
+  variables: Variables,
+  uploadables?: UploadableMap,
+  onCompleted?: ?(response: T, errors: ?Array<PayloadError>) => void,
+  onError?: ?(error: Error) => void,
+  onUnsubscribe?: ?() => void,
+  optimisticUpdater?: ?SelectorStoreUpdater,
+  optimisticResponse?: Object,
+  updater?: ?SelectorStoreUpdater,
+|};
+
+export type MutationParameters = {|
+  +response: {...},
+  +variables: {...},
+  +rawResponse?: {...},
+|};
+
+export type MutationConfig<T: MutationParameters> = {|
+  configs?: Array<DeclarativeMutationConfig>,
+  cacheConfig?: CacheConfig,
+  mutation: GraphQLTaggedNode,
+  onError?: ?(error: Error) => void,
+  onCompleted?: ?(
+    response: $ElementType<T, 'response'>,
+    errors: ?Array<PayloadError>,
+  ) => void,
+  onUnsubscribe?: ?() => void,
+  optimisticResponse?: $ElementType<
+    {
+      +rawResponse?: {...},
+      ...T,
+      ...
+    },
+    'rawResponse',
+  >,
+  optimisticUpdater?: ?SelectorStoreUpdater,
+  updater?: ?SelectorStoreUpdater,
+  uploadables?: UploadableMap,
+  variables: $ElementType<T, 'variables'>,
+|};
+
+/**
+ * Higher-level helper function to execute a mutation against a specific
+ * environment.
+ */
+function commitMutation<T: MutationParameters>(
+  environment: IEnvironment,
+  config: MutationConfig<T>,
+): Disposable {
+  invariant(
+    isRelayModernEnvironment(environment),
+    'commitMutation: expected `environment` to be an instance of ' +
+      '`RelayModernEnvironment`.',
+  );
+  const mutation = getRequest(config.mutation);
+  if (mutation.params.operationKind !== 'mutation') {
+    throw new Error('commitMutation: Expected mutation operation');
+  }
+  if (mutation.kind !== 'Request') {
+    throw new Error('commitMutation: Expected mutation to be of type request');
+  }
+  let {optimisticResponse, optimisticUpdater, updater} = config;
+  const {
+    configs,
+    cacheConfig,
+    onError,
+    onUnsubscribe,
+    variables,
+    uploadables,
+  } = config;
+  const operation = createOperationDescriptor(
+    mutation,
+    variables,
+    cacheConfig,
+    generateUniqueClientID(),
+  );
+  // TODO: remove this check after we fix flow.
+  if (typeof optimisticResponse === 'function') {
+    optimisticResponse = optimisticResponse();
+    warning(
+      false,
+      'commitMutation: Expected `optimisticResponse` to be an object, ' +
+        'received a function.',
+    );
+  }
+  if (__DEV__) {
+    if (optimisticResponse instanceof Object) {
+      validateMutation(optimisticResponse, mutation, variables);
+    }
+  }
+  if (configs) {
+    ({optimisticUpdater, updater} = RelayDeclarativeMutationConfig.convert(
+      configs,
+      mutation,
+      optimisticUpdater,
+      updater,
+    ));
+  }
+  const errors = [];
+  const subscription = environment
+    .executeMutation({
+      operation,
+      optimisticResponse,
+      optimisticUpdater,
+      updater,
+      uploadables,
+    })
+    .subscribe({
+      next: payload => {
+        if (Array.isArray(payload)) {
+          payload.forEach(item => {
+            if (item.errors) {
+              errors.push(...item.errors);
+            }
+          });
+        } else {
+          if (payload.errors) {
+            errors.push(...payload.errors);
+          }
+        }
+      },
+      complete: () => {
+        const {onCompleted} = config;
+        if (onCompleted) {
+          const snapshot = environment.lookup(operation.fragment);
+          onCompleted(
+            (snapshot.data: $FlowFixMe),
+            errors.length !== 0 ? errors : null,
+          );
+        }
+      },
+      error: onError,
+      unsubscribe: onUnsubscribe,
+    });
+  return {dispose: subscription.unsubscribe};
+}
+
+module.exports = commitMutation;

package/mutations/validateMutation.js.flow

@@ -0,0 +1,242 @@
+/**
+ * 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';
+
+import type {
+  NormalizationSelection,
+  NormalizationField,
+} from '../util/NormalizationNode';
+import type {ConcreteRequest} from '../util/RelayConcreteNode';
+import type {Variables} from '../util/RelayRuntimeTypes';
+
+type ValidationContext = {|
+  visitedPaths: Set<string>,
+  path: string,
+  variables: Variables,
+  missingDiff: Object,
+  extraDiff: Object,
+  moduleImportPaths: Set<string>,
+|};
+
+const warning = require('warning');
+
+const hasOwnProperty = Object.prototype.hasOwnProperty;
+
+let validateMutation = () => {};
+if (__DEV__) {
+  const addFieldToDiff = (path: string, diff: Object, isScalar) => {
+    let deepLoc = diff;
+    path.split('.').forEach((key, index, arr) => {
+      if (deepLoc[key] == null) {
+        deepLoc[key] = {};
+      }
+      if (isScalar && index === arr.length - 1) {
+        deepLoc[key] = '<scalar>';
+      }
+      deepLoc = deepLoc[key];
+    });
+  };
+  validateMutation = (
+    optimisticResponse: Object,
+    mutation: ConcreteRequest,
+    variables: ?Object,
+  ) => {
+    const operationName = mutation.operation.name;
+    const context: ValidationContext = {
+      path: 'ROOT',
+      visitedPaths: new Set(),
+      variables: variables || {},
+      missingDiff: {},
+      extraDiff: {},
+      moduleImportPaths: new Set(),
+    };
+    validateSelections(
+      optimisticResponse,
+      mutation.operation.selections,
+      context,
+    );
+    validateOptimisticResponse(optimisticResponse, context);
+    warning(
+      context.missingDiff.ROOT == null,
+      'Expected `optimisticResponse` to match structure of server response for mutation `%s`, please define fields for all of\n%s',
+      operationName,
+      JSON.stringify(context.missingDiff.ROOT, null, 2),
+    );
+    warning(
+      context.extraDiff.ROOT == null,
+      'Expected `optimisticResponse` to match structure of server response for mutation `%s`, please remove all fields of\n%s',
+      operationName,
+      JSON.stringify(context.extraDiff.ROOT, null, 2),
+    );
+  };
+
+  const validateSelections = (
+    optimisticResponse: Object,
+    selections: $ReadOnlyArray<NormalizationSelection>,
+    context: ValidationContext,
+  ) => {
+    selections.forEach(selection =>
+      validateSelection(optimisticResponse, selection, context),
+    );
+  };
+
+  const validateSelection = (
+    optimisticResponse: Object,
+    selection: NormalizationSelection,
+    context: ValidationContext,
+  ) => {
+    switch (selection.kind) {
+      case 'Condition':
+        validateSelections(optimisticResponse, selection.selections, context);
+        return;
+      case 'ScalarField':
+      case 'LinkedField':
+      case 'FlightField':
+        return validateField(optimisticResponse, selection, context);
+      case 'InlineFragment':
+        const type = selection.type;
+        const isConcreteType = selection.abstractKey == null;
+        selection.selections.forEach(subselection => {
+          if (isConcreteType && optimisticResponse.__typename !== type) {
+            return;
+          }
+          validateSelection(optimisticResponse, subselection, context);
+        });
+        return;
+      case 'ClientExtension':
+        selection.selections.forEach(subselection => {
+          validateSelection(optimisticResponse, subselection, context);
+        });
+        return;
+      case 'ModuleImport':
+        return validateModuleImport(context);
+      case 'LinkedHandle':
+      case 'ScalarHandle':
+      case 'Defer':
+      case 'Stream':
+      case 'TypeDiscriminator': {
+        // TODO(T35864292) - Add missing validations for these types
+        return;
+      }
+      default:
+        (selection: empty);
+        return;
+    }
+  };
+
+  const validateModuleImport = (context: ValidationContext) => {
+    context.moduleImportPaths.add(context.path);
+  };
+
+  const validateField = (
+    optimisticResponse: Object,
+    field: NormalizationField,
+    context: ValidationContext,
+  ) => {
+    const fieldName = field.alias || field.name;
+    const path = `${context.path}.${fieldName}`;
+    context.visitedPaths.add(path);
+    switch (field.kind) {
+      case 'ScalarField':
+        if (hasOwnProperty.call(optimisticResponse, fieldName) === false) {
+          addFieldToDiff(path, context.missingDiff, true);
+        }
+        return;
+      case 'LinkedField':
+        const selections = field.selections;
+        if (
+          optimisticResponse[fieldName] === null ||
+          (hasOwnProperty.call(optimisticResponse, fieldName) &&
+            optimisticResponse[fieldName] === undefined)
+        ) {
+          return;
+        }
+        if (field.plural) {
+          if (Array.isArray(optimisticResponse[fieldName])) {
+            optimisticResponse[fieldName].forEach(r => {
+              if (r !== null) {
+                validateSelections(r, selections, {
+                  ...context,
+                  path,
+                });
+              }
+            });
+            return;
+          } else {
+            addFieldToDiff(path, context.missingDiff);
+            return;
+          }
+        } else {
+          if (optimisticResponse[fieldName] instanceof Object) {
+            validateSelections(optimisticResponse[fieldName], selections, {
+              ...context,
+              path,
+            });
+            return;
+          } else {
+            addFieldToDiff(path, context.missingDiff);
+            return;
+          }
+        }
+      case 'FlightField':
+        if (
+          optimisticResponse[fieldName] === null ||
+          (hasOwnProperty.call(optimisticResponse, fieldName) &&
+            optimisticResponse[fieldName] === undefined)
+        ) {
+          return;
+        }
+        throw new Error(
+          'validateMutation: Flight fields are not compatible with ' +
+            'optimistic updates, as React does not have the component code ' +
+            'necessary to process new data on the client. Instead, you ' +
+            'should update your code to require a full refetch of the Flight ' +
+            'field so your UI can be updated.',
+        );
+    }
+  };
+
+  const validateOptimisticResponse = (
+    optimisticResponse: Object,
+    context: ValidationContext,
+  ) => {
+    if (Array.isArray(optimisticResponse)) {
+      optimisticResponse.forEach(r => {
+        if (r instanceof Object) {
+          validateOptimisticResponse(r, context);
+        }
+      });
+      return;
+    }
+    Object.keys(optimisticResponse).forEach((key: string) => {
+      const value = optimisticResponse[key];
+      const path = `${context.path}.${key}`;
+      // if it's a module import path we don't have an ast so we cannot validate it
+      if (context.moduleImportPaths.has(path)) {
+        return;
+      }
+      if (!context.visitedPaths.has(path)) {
+        addFieldToDiff(path, context.extraDiff);
+        return;
+      }
+      if (value instanceof Object) {
+        validateOptimisticResponse(value, {
+          ...context,
+          path,
+        });
+      }
+    });
+  };
+}
+
+module.exports = (validateMutation: (Object, ConcreteRequest, ?Object) => void);

package/network/ConvertToExecuteFunction.js.flow

@@ -0,0 +1,49 @@
+/**
+ * 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 RelayObservable = require('./RelayObservable');
+
+import type {ExecuteFunction, FetchFunction} from './RelayNetworkTypes';
+
+/**
+ * Converts a FetchFunction into an ExecuteFunction for use by RelayNetwork.
+ */
+function convertFetch(fn: FetchFunction): ExecuteFunction {
+  return function fetch(
+    request,
+    variables,
+    cacheConfig,
+    uploadables,
+    logRequestInfo,
+  ) {
+    const result = fn(
+      request,
+      variables,
+      cacheConfig,
+      uploadables,
+      logRequestInfo,
+    );
+    // Note: We allow FetchFunction to directly return Error to indicate
+    // a failure to fetch. To avoid handling this special case throughout the
+    // Relay codebase, it is explicitly handled here.
+    if (result instanceof Error) {
+      return RelayObservable.create(sink => sink.error(result));
+    }
+    return RelayObservable.from(result);
+  };
+}
+
+module.exports = {
+  convertFetch,
+};

package/network/RelayNetwork.js.flow

@@ -0,0 +1,84 @@
+/**
+ * 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 invariant = require('invariant');
+
+const {convertFetch} = require('./ConvertToExecuteFunction');
+
+import type {RequestParameters} from '../util/RelayConcreteNode';
+import type {CacheConfig, Variables} from '../util/RelayRuntimeTypes';
+import type {
+  FetchFunction,
+  GraphQLResponse,
+  LogRequestInfoFunction,
+  INetwork,
+  SubscribeFunction,
+  UploadableMap,
+} from './RelayNetworkTypes';
+import type RelayObservable from './RelayObservable';
+
+/**
+ * Creates an implementation of the `Network` interface defined in
+ * `RelayNetworkTypes` given `fetch` and `subscribe` functions.
+ */
+function create(
+  fetchFn: FetchFunction,
+  subscribe?: SubscribeFunction,
+): INetwork {
+  // Convert to functions that returns RelayObservable.
+  const observeFetch = convertFetch(fetchFn);
+
+  function execute(
+    request: RequestParameters,
+    variables: Variables,
+    cacheConfig: CacheConfig,
+    uploadables?: ?UploadableMap,
+    logRequestInfo: ?LogRequestInfoFunction,
+  ): RelayObservable<GraphQLResponse> {
+    if (request.operationKind === 'subscription') {
+      invariant(
+        subscribe,
+        'RelayNetwork: This network layer does not support Subscriptions. ' +
+          'To use Subscriptions, provide a custom network layer.',
+      );
+
+      invariant(
+        !uploadables,
+        'RelayNetwork: Cannot provide uploadables while subscribing.',
+      );
+      return subscribe(request, variables, cacheConfig);
+    }
+
+    const pollInterval = cacheConfig.poll;
+    if (pollInterval != null) {
+      invariant(
+        !uploadables,
+        'RelayNetwork: Cannot provide uploadables while polling.',
+      );
+      return observeFetch(request, variables, {force: true}).poll(pollInterval);
+    }
+
+    return observeFetch(
+      request,
+      variables,
+      cacheConfig,
+      uploadables,
+      logRequestInfo,
+    );
+  }
+
+  return {execute};
+}
+
+module.exports = {create};

package/network/RelayNetworkTypes.js.flow

@@ -0,0 +1,145 @@
+/**
+ * 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';
+
+import type {RequestParameters} from '../util/RelayConcreteNode';
+import type {CacheConfig, Variables} from '../util/RelayRuntimeTypes';
+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 type LogRequestInfoFunction = mixed => void;
+
+export type PayloadData = {[key: string]: mixed, ...};
+
+export type PayloadError = {
+  message: string,
+  locations?: Array<{
+    line: number,
+    column: number,
+    ...
+  }>,
+  // 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)
+ */
+export type GraphQLResponseWithData = {|
+  +data: PayloadData,
+  +errors?: Array<PayloadError>,
+  +extensions?: PayloadExtensions,
+  +label?: string,
+  +path?: Array<string | number>,
+|};
+
+export type GraphQLResponseWithoutData = {|
+  +data?: ?PayloadData,
+  +errors: Array<PayloadError>,
+  +extensions?: PayloadExtensions,
+  +label?: string,
+  +path?: Array<string | number>,
+|};
+
+export type GraphQLResponseWithExtensionsOnly = {|
+  // Per https://spec.graphql.org/June2018/#sec-Errors
+  // > If the data entry in the response is not present, the errors entry
+  // > in the response must not be empty. It must contain at least one error
+  // This means a payload has to have either a data key or an errors key:
+  // but the spec leaves room for the combination of data: null plus extensions
+  // since `data: null` is a *required* output if there was an error during
+  // execution, but the inverse is not described in the sepc: `data: null`
+  // does not necessarily indicate that there was an error.
+  +data: null,
+  +extensions: PayloadExtensions,
+|};
+
+export type GraphQLSingularResponse =
+  | GraphQLResponseWithData
+  | GraphQLResponseWithExtensionsOnly
+  | GraphQLResponseWithoutData;
+
+export type GraphQLResponse =
+  | GraphQLSingularResponse
+  | $ReadOnlyArray<GraphQLSingularResponse>;
+
+/**
+ * A function that returns an Observable representing the response of executing
+ * a GraphQL operation.
+ */
+export type ExecuteFunction = (
+  request: RequestParameters,
+  variables: Variables,
+  cacheConfig: CacheConfig,
+  uploadables?: ?UploadableMap,
+  logRequestInfo?: ?LogRequestInfoFunction,
+) => RelayObservable<GraphQLResponse>;
+
+/**
+ * A function that executes a GraphQL operation with request/response semantics.
+ *
+ * May return an Observable or Promise of a plain GraphQL server response, or
+ * a composed ExecutePayload object supporting additional metadata.
+ */
+export type FetchFunction = (
+  request: RequestParameters,
+  variables: Variables,
+  cacheConfig: CacheConfig,
+  uploadables: ?UploadableMap,
+  logRequestInfo?: ?LogRequestInfoFunction,
+) => ObservableFromValue<GraphQLResponse>;
+
+/**
+ * A function that executes a GraphQL subscription operation, returning zero or
+ * more raw server responses over time.
+ */
+export type SubscribeFunction = (
+  request: RequestParameters,
+  variables: Variables,
+  cacheConfig: CacheConfig,
+) => RelayObservable<GraphQLResponse>;
+
+export type Uploadable = File | Blob;
+export type UploadableMap = {[key: string]: Uploadable, ...};
+
+/**
+ * React Flight tree created on the server.
+ */
+export type ReactFlightServerTree = mixed;
+export type ReactFlightPayloadQuery = {|
+  +id: mixed,
+  +module: mixed,
+  +response: GraphQLSingularResponse,
+  +variables: Variables,
+|};
+/**
+ * Data that is returned by a Flight compliant GraphQL server.
+ *
+ * - tree: an array of values that will be iterated and fed into
+ *     ReactFlightDOMRelayClient.
+ * - queries: an array of queries that the server preloaded for the client.
+ */
+export type ReactFlightPayloadData = {|
+  +tree: Array<ReactFlightServerTree>,
+  +queries: Array<ReactFlightPayloadQuery>,
+|};