relay-runtime 10.1.3 → 11.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "relay-runtime",
   "description": "A core runtime for building GraphQL-driven applications.",
-  "version": "10.1.3",
+  "version": "11.0.2",
   "keywords": [
     "graphql",
     "relay"
@@ -12,7 +12,8 @@
   "repository": "facebook/relay",
   "dependencies": {
     "@babel/runtime": "^7.0.0",
-    "fbjs": "^3.0.0"
+    "fbjs": "^3.0.0",
+    "invariant": "^2.2.4"
   },
   "directories": {
     "": "./"

package/query/fetchQuery.js.flow

@@ -4,6 +4,7 @@
  * 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
  */
@@ -12,36 +13,162 @@
 
 'use strict';
 
+const RelayObservable = require('../network/RelayObservable');
+
+const fetchQueryInternal = require('./fetchQueryInternal');
+const invariant = require('invariant');
+const reportMissingRequiredFields = require('../util/reportMissingRequiredFields');
+
 const {
   createOperationDescriptor,
 } = require('../store/RelayModernOperationDescriptor');
 const {getRequest} = require('./GraphQLTag');
 
-import type {IEnvironment} from '../store/RelayStoreTypes';
-import type {CacheConfig, OperationType} from '../util/RelayRuntimeTypes';
-import type {GraphQLTaggedNode} from './GraphQLTag';
+import type {
+  CacheConfig,
+  FetchQueryFetchPolicy,
+  GraphQLTaggedNode,
+  IEnvironment,
+  OperationDescriptor,
+  OperationType,
+  Snapshot,
+  VariablesOf,
+} from 'relay-runtime';
 
 /**
- * A helper function to fetch the results of a query. Note that results for
- * fragment spreads are masked: fields must be explicitly listed in the query in
- * order to be accessible in the result object.
+ * Fetches the given query and variables on the provided environment,
+ * and de-dupes identical in-flight requests.
+ *
+ * Observing a request:
+ * ====================
+ * fetchQuery returns an Observable which you can call .subscribe()
+ * on. Subscribe optionally takes an Observer, which you can provide to
+ * observe network events:
+ *
+ * ```
+ * fetchQuery(environment, query, variables).subscribe({
+ *   // Called when network requests starts
+ *   start: (subsctiption) => {},
+ *
+ *   // Called after a payload is received and written to the local store
+ *   next: (payload) => {},
+ *
+ *   // Called when network requests errors
+ *   error: (error) => {},
+ *
+ *   // Called when network requests fully completes
+ *   complete: () => {},
+ *
+ *   // Called when network request is unsubscribed
+ *   unsubscribe: (subscription) => {},
+ * });
+ * ```
+ *
+ * Request Promise:
+ * ================
+ * The obervable can be converted to a Promise with .toPromise(), which will
+ * resolve to a snapshot of the query data when the first response is received
+ * from the server.
+ *
+ * ```
+ * fetchQuery(environment, query, variables).toPromise().then((data) => {
+ *   // ...
+ * });
+ * ```
+ *
+ * In-flight request de-duping:
+ * ============================
+ * By default, calling fetchQuery multiple times with the same
+ * environment, query and variables will not initiate a new request if a request
+ * for those same parameters is already in flight.
+ *
+ * A request is marked in-flight from the moment it starts until the moment it
+ * fully completes, regardless of error or successful completion.
+ *
+ * NOTE: If the request completes _synchronously_, calling fetchQuery
+ * a second time with the same arguments in the same tick will _NOT_ de-dupe
+ * the request given that it will no longer be in-flight.
+ *
+ *
+ * Data Retention:
+ * ===============
+ * This function will NOT retain query data, meaning that it is not guaranteed
+ * that the fetched data will remain in the Relay store after the request has
+ * completed.
+ * If you need to retain the query data outside of the network request,
+ * you need to use `environment.retain()`.
+ *
+ *
+ * Cancelling requests:
+ * ====================
+ * If the disposable returned by subscribe is called while the
+ * request is in-flight, the request will be cancelled.
+ *
+ * ```
+ * const disposable = fetchQuery(...).subscribe(...);
+ *
+ * // This will cancel the request if it is in-flight.
+ * disposable.dispose();
+ * ```
+ * NOTE: When using .toPromise(), the request cannot be cancelled.
  */
-
-function fetchQuery<T: OperationType>(
+function fetchQuery<TQuery: OperationType>(
   environment: IEnvironment,
-  taggedNode: GraphQLTaggedNode,
-  variables: $PropertyType<T, 'variables'>,
-  cacheConfig?: ?CacheConfig,
-): Promise<$PropertyType<T, 'response'>> {
-  const query = getRequest(taggedNode);
-  if (query.params.operationKind !== 'query') {
-    throw new Error('fetchQuery: Expected query operation');
+  query: GraphQLTaggedNode,
+  variables: VariablesOf<TQuery>,
+  options?: $ReadOnly<{|
+    fetchPolicy?: FetchQueryFetchPolicy,
+    networkCacheConfig?: CacheConfig,
+  |}>,
+): RelayObservable<$ElementType<TQuery, 'response'>> {
+  const queryNode = getRequest(query);
+  invariant(
+    queryNode.params.operationKind === 'query',
+    'fetchQuery: Expected query operation',
+  );
+  const networkCacheConfig = {
+    force: true,
+    ...options?.networkCacheConfig,
+  };
+  const operation = createOperationDescriptor(
+    queryNode,
+    variables,
+    networkCacheConfig,
+  );
+  const fetchPolicy = options?.fetchPolicy ?? 'network-only';
+
+  function readData(snapshot: Snapshot) {
+    if (snapshot.missingRequiredFields != null) {
+      reportMissingRequiredFields(environment, snapshot.missingRequiredFields);
+    }
+    return snapshot.data;
+  }
+
+  switch (fetchPolicy) {
+    case 'network-only': {
+      return getNetworkObservable(environment, operation).map(readData);
+    }
+    case 'store-or-network': {
+      if (environment.check(operation).status === 'available') {
+        return RelayObservable.from(environment.lookup(operation.fragment)).map(
+          readData,
+        );
+      }
+      return getNetworkObservable(environment, operation).map(readData);
+    }
+    default:
+      (fetchPolicy: empty);
+      throw new Error('fetchQuery: Invalid fetchPolicy ' + fetchPolicy);
   }
-  const operation = createOperationDescriptor(query, variables, cacheConfig);
-  return environment
-    .execute({operation})
-    .map(() => environment.lookup(operation.fragment).data)
-    .toPromise();
+}
+
+function getNetworkObservable<TQuery: OperationType>(
+  environment: IEnvironment,
+  operation: OperationDescriptor,
+): RelayObservable<$ElementType<TQuery, 'response'>> {
+  return fetchQueryInternal
+    .fetchQuery(environment, operation)
+    .map(() => environment.lookup(operation.fragment));
 }
 
 module.exports = fetchQuery;

package/query/fetchQueryInternal.js.flow

@@ -92,8 +92,7 @@ const requestCachesByEnvironment = WEAKMAP_SUPPORTED
  * Cancelling requests:
  * ====================
  * If the subscription returned by subscribe is called while the
- * request is in-flight, apart from releasing retained data, the request will
- * also be cancelled.
+ * request is in-flight, the request will be cancelled.
  *
  * ```
  * const subscription = fetchQuery(...).subscribe(...);
@@ -233,7 +232,7 @@ function getActiveStatusObservableForCachedRequest(
 
 /**
  * If a request is active for the given query, variables and environment,
- * this function will return a Promise that will resolve when that request has
+ * this function will return a Promise that will resolve when that request
  * stops being active (receives a final payload), and the data has been saved
  * to the store.
  * If no request is active, null will be returned

package/query/fetchQuery_DEPRECATED.js.flow

@@ -0,0 +1,47 @@
+/**
+ * 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 {
+  createOperationDescriptor,
+} = require('../store/RelayModernOperationDescriptor');
+const {getRequest} = require('./GraphQLTag');
+
+import type {IEnvironment} from '../store/RelayStoreTypes';
+import type {CacheConfig, OperationType} from '../util/RelayRuntimeTypes';
+import type {GraphQLTaggedNode} from './GraphQLTag';
+
+/**
+ * A helper function to fetch the results of a query. Note that results for
+ * fragment spreads are masked: fields must be explicitly listed in the query in
+ * order to be accessible in the result object.
+ */
+
+function fetchQuery_DEPRECATED<T: OperationType>(
+  environment: IEnvironment,
+  taggedNode: GraphQLTaggedNode,
+  variables: $PropertyType<T, 'variables'>,
+  cacheConfig?: ?CacheConfig,
+): Promise<$PropertyType<T, 'response'>> {
+  const query = getRequest(taggedNode);
+  if (query.params.operationKind !== 'query') {
+    throw new Error('fetchQuery: Expected query operation');
+  }
+  const operation = createOperationDescriptor(query, variables, cacheConfig);
+  return environment
+    .execute({operation})
+    .map(() => environment.lookup(operation.fragment).data)
+    .toPromise();
+}
+
+module.exports = fetchQuery_DEPRECATED;