relay-runtime 9.0.0 → 9.1.0

package/network/RelayQueryResponseCache.js.flow

@@ -0,0 +1,111 @@
+/**
+ * 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 stableCopy = require('../util/stableCopy');
+
+import type {Variables} from '../util/RelayRuntimeTypes';
+import type {GraphQLSingularResponse} from './RelayNetworkTypes';
+
+type Response = {
+  fetchTime: number,
+  payload: GraphQLSingularResponse,
+  ...
+};
+
+/**
+ * A cache for storing query responses, featuring:
+ * - `get` with TTL
+ * - cache size limiting, with least-recently *updated* entries purged first
+ */
+class RelayQueryResponseCache {
+  _responses: Map<string, Response>;
+  _size: number;
+  _ttl: number;
+
+  constructor({size, ttl}: {size: number, ttl: number, ...}) {
+    invariant(
+      size > 0,
+      'RelayQueryResponseCache: Expected the max cache size to be > 0, got ' +
+        '`%s`.',
+      size,
+    );
+    invariant(
+      ttl > 0,
+      'RelayQueryResponseCache: Expected the max ttl to be > 0, got `%s`.',
+      ttl,
+    );
+    this._responses = new Map();
+    this._size = size;
+    this._ttl = ttl;
+  }
+
+  clear(): void {
+    this._responses.clear();
+  }
+
+  get(queryID: string, variables: Variables): ?GraphQLSingularResponse {
+    const cacheKey = getCacheKey(queryID, variables);
+    this._responses.forEach((response, key) => {
+      if (!isCurrent(response.fetchTime, this._ttl)) {
+        this._responses.delete(key);
+      }
+    });
+    const response = this._responses.get(cacheKey);
+    return response != null
+      ? ({
+          ...response.payload,
+          extensions: {
+            ...response.payload.extensions,
+            cacheTimestamp: response.fetchTime,
+          },
+        }: GraphQLSingularResponse)
+      : null;
+  }
+
+  set(
+    queryID: string,
+    variables: Variables,
+    payload: GraphQLSingularResponse,
+  ): void {
+    const fetchTime = Date.now();
+    const cacheKey = getCacheKey(queryID, variables);
+    this._responses.delete(cacheKey); // deletion resets key ordering
+    this._responses.set(cacheKey, {
+      fetchTime,
+      payload,
+    });
+    // Purge least-recently updated key when max size reached
+    if (this._responses.size > this._size) {
+      const firstKey = this._responses.keys().next();
+      if (!firstKey.done) {
+        this._responses.delete(firstKey.value);
+      }
+    }
+  }
+}
+
+function getCacheKey(queryID: string, variables: Variables): string {
+  return JSON.stringify(stableCopy({queryID, variables}));
+}
+
+/**
+ * Determine whether a response fetched at `fetchTime` is still valid given
+ * some `ttl`.
+ */
+function isCurrent(fetchTime: number, ttl: number): boolean {
+  return fetchTime + ttl >= Date.now();
+}
+
+module.exports = RelayQueryResponseCache;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "relay-runtime",
   "description": "A core runtime for building GraphQL-driven applications.",
-  "version": "9.0.0",
+  "version": "9.1.0",
   "keywords": [
     "graphql",
     "relay"

package/query/GraphQLTag.js.flow

@@ -0,0 +1,166 @@
+/**
+ * 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 RelayConcreteNode = require('../util/RelayConcreteNode');
+
+const invariant = require('invariant');
+const warning = require('warning');
+
+import type {
+  ReaderFragment,
+  ReaderRefetchableFragment,
+  ReaderPaginationFragment,
+  ReaderInlineDataFragment,
+} from '../util/ReaderNode';
+import type {ConcreteRequest} from '../util/RelayConcreteNode';
+
+// The type of a graphql`...` tagged template expression.
+export type GraphQLTaggedNode =
+  | ReaderFragment
+  | ConcreteRequest
+  | {
+      // This is this case when we `require()` a generated ES6 module
+      default: ReaderFragment | ConcreteRequest,
+      ...
+    };
+
+/**
+ * Runtime function to correspond to the `graphql` tagged template function.
+ * All calls to this function should be transformed by the plugin.
+ */
+function graphql(strings: Array<string>): GraphQLTaggedNode {
+  invariant(
+    false,
+    'graphql: Unexpected invocation at runtime. Either the Babel transform ' +
+      'was not set up, or it failed to identify this call site. Make sure it ' +
+      'is being used verbatim as `graphql`.',
+  );
+}
+
+function getNode(
+  taggedNode: GraphQLTaggedNode,
+): ReaderFragment | ConcreteRequest {
+  let node = taggedNode;
+  if (typeof node === 'function') {
+    node = (node(): ReaderFragment | ConcreteRequest);
+    warning(
+      false,
+      'RelayGraphQLTag: node `%s` unexpectedly wrapped in a function.',
+      node.kind === 'Fragment' ? node.name : node.operation.name,
+    );
+  } else if (node.default) {
+    // Support for languages that work (best) with ES6 modules, such as TypeScript.
+    node = node.default;
+  }
+  return node;
+}
+
+function isFragment(node: GraphQLTaggedNode): boolean {
+  const fragment = getNode(node);
+  return (
+    typeof fragment === 'object' &&
+    fragment !== null &&
+    fragment.kind === RelayConcreteNode.FRAGMENT
+  );
+}
+
+function isRequest(node: GraphQLTaggedNode): boolean {
+  const request = getNode(node);
+  return (
+    typeof request === 'object' &&
+    request !== null &&
+    request.kind === RelayConcreteNode.REQUEST
+  );
+}
+
+function isInlineDataFragment(node: GraphQLTaggedNode): boolean {
+  const fragment = getNode(node);
+  return (
+    typeof fragment === 'object' &&
+    fragment !== null &&
+    fragment.kind === RelayConcreteNode.INLINE_DATA_FRAGMENT
+  );
+}
+
+function getFragment(taggedNode: GraphQLTaggedNode): ReaderFragment {
+  const fragment = getNode(taggedNode);
+  invariant(
+    isFragment(fragment),
+    'GraphQLTag: Expected a fragment, got `%s`.',
+    JSON.stringify(fragment),
+  );
+  return (fragment: any);
+}
+
+function getPaginationFragment(
+  taggedNode: GraphQLTaggedNode,
+): ReaderPaginationFragment | null {
+  const fragment = getFragment(taggedNode);
+  const refetch = fragment.metadata?.refetch;
+  const connection = refetch?.connection;
+  if (
+    refetch === null ||
+    typeof refetch !== 'object' ||
+    connection === null ||
+    typeof connection !== 'object'
+  ) {
+    return null;
+  }
+  return (fragment: any);
+}
+
+function getRefetchableFragment(
+  taggedNode: GraphQLTaggedNode,
+): ReaderRefetchableFragment | null {
+  const fragment = getFragment(taggedNode);
+  const refetch = fragment.metadata?.refetch;
+  if (refetch === null || typeof refetch !== 'object') {
+    return null;
+  }
+  return (fragment: any);
+}
+
+function getRequest(taggedNode: GraphQLTaggedNode): ConcreteRequest {
+  const request = getNode(taggedNode);
+  invariant(
+    isRequest(request),
+    'GraphQLTag: Expected a request, got `%s`.',
+    JSON.stringify(request),
+  );
+  return (request: any);
+}
+
+function getInlineDataFragment(
+  taggedNode: GraphQLTaggedNode,
+): ReaderInlineDataFragment {
+  const fragment = getNode(taggedNode);
+  invariant(
+    isInlineDataFragment(fragment),
+    'GraphQLTag: Expected an inline data fragment, got `%s`.',
+    JSON.stringify(fragment),
+  );
+  return (fragment: any);
+}
+
+module.exports = {
+  getFragment,
+  getPaginationFragment,
+  getRefetchableFragment,
+  getRequest,
+  getInlineDataFragment,
+  graphql,
+  isFragment,
+  isRequest,
+  isInlineDataFragment,
+};

package/query/fetchQuery.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<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);
+  return environment
+    .execute({operation, cacheConfig})
+    .map(() => environment.lookup(operation.fragment).data)
+    .toPromise();
+}
+
+module.exports = fetchQuery;

package/query/fetchQueryInternal.js.flow

@@ -0,0 +1,349 @@
+/**
+ * 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 Observable = require('../network/RelayObservable');
+const RelayReplaySubject = require('../util/RelayReplaySubject');
+
+const invariant = require('invariant');
+
+import type {GraphQLResponse} from '../network/RelayNetworkTypes';
+import type {Subscription} from '../network/RelayObservable';
+import type {
+  IEnvironment,
+  OperationDescriptor,
+  RequestDescriptor,
+} from '../store/RelayStoreTypes';
+import type {CacheConfig} from '../util/RelayRuntimeTypes';
+import type {RequestIdentifier} from '../util/getRequestIdentifier';
+
+type RequestCacheEntry = {|
+  +identifier: RequestIdentifier,
+  +subject: RelayReplaySubject<GraphQLResponse>,
+  +subjectForInFlightStatus: RelayReplaySubject<GraphQLResponse>,
+  +subscription: Subscription,
+|};
+
+const WEAKMAP_SUPPORTED = typeof WeakMap === 'function';
+
+const requestCachesByEnvironment = WEAKMAP_SUPPORTED
+  ? new WeakMap()
+  : new Map();
+
+/**
+ * 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() takes an Observer, which you can provide to
+ * observe network events:
+ *
+ * ```
+ * fetchQuery(environment, query, variables).subscribe({
+ *   // Called when network requests starts
+ *   start: (subscription) => {},
+ *
+ *   // 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) => {},
+ * });
+ * ```
+ *
+ * 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 any query data outside the scope of the
+ * request, which means it is not guaranteed that it won't be garbage
+ * collected after the request completes.
+ * If you need to retain data, you can do so manually with environment.retain().
+ *
+ * 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.
+ *
+ * ```
+ * const subscription = fetchQuery(...).subscribe(...);
+ *
+ * // This will cancel the request if it is in-flight.
+ * subscription.unsubscribe();
+ * ```
+ */
+function fetchQuery(
+  environment: IEnvironment,
+  operation: OperationDescriptor,
+  options?: {|
+    networkCacheConfig?: CacheConfig,
+  |},
+): Observable<GraphQLResponse> {
+  return fetchQueryDeduped(environment, operation.request, () =>
+    environment.execute({
+      operation,
+      cacheConfig: options?.networkCacheConfig,
+    }),
+  );
+}
+
+/**
+ * Low-level implementation details of `fetchQuery`.
+ *
+ * `fetchQueryDeduped` can also be used to share a single cache for
+ * requests that aren't using `fetchQuery` directly (e.g. because they don't
+ * have an `OperationDescriptor` when they are called).
+ */
+function fetchQueryDeduped(
+  environment: IEnvironment,
+  request: RequestDescriptor,
+  fetchFn: () => Observable<GraphQLResponse>,
+): Observable<GraphQLResponse> {
+  return Observable.create(sink => {
+    const requestCache = getRequestCache(environment);
+    const identifier = request.identifier;
+    let cachedRequest = requestCache.get(identifier);
+
+    if (!cachedRequest) {
+      fetchFn()
+        .finally(() => requestCache.delete(identifier))
+        .subscribe({
+          start: subscription => {
+            cachedRequest = {
+              identifier,
+              subject: new RelayReplaySubject(),
+              subjectForInFlightStatus: new RelayReplaySubject(),
+              subscription: subscription,
+            };
+            requestCache.set(identifier, cachedRequest);
+          },
+          next: response => {
+            const cachedReq = getCachedRequest(requestCache, identifier);
+            cachedReq.subject.next(response);
+            cachedReq.subjectForInFlightStatus.next(response);
+          },
+          error: error => {
+            const cachedReq = getCachedRequest(requestCache, identifier);
+            cachedReq.subject.error(error);
+            cachedReq.subjectForInFlightStatus.error(error);
+          },
+          complete: () => {
+            const cachedReq = getCachedRequest(requestCache, identifier);
+            cachedReq.subject.complete();
+            cachedReq.subjectForInFlightStatus.complete();
+          },
+          unsubscribe: subscription => {
+            const cachedReq = getCachedRequest(requestCache, identifier);
+            cachedReq.subject.unsubscribe();
+            cachedReq.subjectForInFlightStatus.unsubscribe();
+          },
+        });
+    }
+
+    invariant(
+      cachedRequest != null,
+      '[fetchQueryInternal] fetchQueryDeduped: Expected `start` to be ' +
+        'called synchronously',
+    );
+    return getObservableForCachedRequest(requestCache, cachedRequest).subscribe(
+      sink,
+    );
+  });
+}
+
+/**
+ * @private
+ */
+function getObservableForCachedRequest(
+  requestCache: Map<RequestIdentifier, RequestCacheEntry>,
+  cachedRequest: RequestCacheEntry,
+): Observable<GraphQLResponse> {
+  return Observable.create(sink => {
+    const subscription = cachedRequest.subject.subscribe(sink);
+
+    return () => {
+      subscription.unsubscribe();
+      const cachedRequestInstance = requestCache.get(cachedRequest.identifier);
+      if (cachedRequestInstance) {
+        const requestSubscription = cachedRequestInstance.subscription;
+        if (
+          requestSubscription != null &&
+          cachedRequestInstance.subject.getObserverCount() === 0
+        ) {
+          requestSubscription.unsubscribe();
+          requestCache.delete(cachedRequest.identifier);
+        }
+      }
+    };
+  });
+}
+
+/**
+ * @private
+ */
+function getActiveStatusObservableForCachedRequest(
+  environment: IEnvironment,
+  requestCache: Map<RequestIdentifier, RequestCacheEntry>,
+  cachedRequest: RequestCacheEntry,
+): Observable<void> {
+  return Observable.create(sink => {
+    const subscription = cachedRequest.subjectForInFlightStatus.subscribe({
+      error: sink.error,
+      next: response => {
+        if (!environment.isRequestActive(cachedRequest.identifier)) {
+          sink.complete();
+          return;
+        }
+        sink.next();
+      },
+      complete: sink.complete,
+      unsubscribe: sink.complete,
+    });
+
+    return () => {
+      subscription.unsubscribe();
+    };
+  });
+}
+
+/**
+ * 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
+ * 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
+ */
+function getPromiseForActiveRequest(
+  environment: IEnvironment,
+  request: RequestDescriptor,
+): Promise<void> | null {
+  const requestCache = getRequestCache(environment);
+  const cachedRequest = requestCache.get(request.identifier);
+  if (!cachedRequest) {
+    return null;
+  }
+  if (!environment.isRequestActive(cachedRequest.identifier)) {
+    return null;
+  }
+
+  return new Promise((resolve, reject) => {
+    let resolveOnNext = false;
+    getActiveStatusObservableForCachedRequest(
+      environment,
+      requestCache,
+      cachedRequest,
+    ).subscribe({
+      complete: resolve,
+      error: reject,
+      next: response => {
+        /*
+         * The underlying `RelayReplaySubject` will synchronously replay events
+         * as soon as we subscribe, but since we want the *next* asynchronous
+         * one, we'll ignore them until the replay finishes.
+         */
+        if (resolveOnNext) {
+          resolve(response);
+        }
+      },
+    });
+    resolveOnNext = true;
+  });
+}
+
+/**
+ * If there is a pending request for the given query, returns an Observable of
+ * *all* its responses. Existing responses are published synchronously and
+ * subsequent responses are published asynchronously. Returns null if there is
+ * no pending request. This is similar to fetchQuery() except that it will not
+ * issue a fetch if there isn't already one pending.
+ */
+function getObservableForActiveRequest(
+  environment: IEnvironment,
+  request: RequestDescriptor,
+): Observable<void> | null {
+  const requestCache = getRequestCache(environment);
+  const cachedRequest = requestCache.get(request.identifier);
+  if (!cachedRequest) {
+    return null;
+  }
+  if (!environment.isRequestActive(cachedRequest.identifier)) {
+    return null;
+  }
+
+  return getActiveStatusObservableForCachedRequest(
+    environment,
+    requestCache,
+    cachedRequest,
+  );
+}
+
+/**
+ * @private
+ */
+function getRequestCache(
+  environment: IEnvironment,
+): Map<RequestIdentifier, RequestCacheEntry> {
+  const cached: ?Map<
+    RequestIdentifier,
+    RequestCacheEntry,
+  > = requestCachesByEnvironment.get(environment);
+  if (cached != null) {
+    return cached;
+  }
+  const requestCache: Map<RequestIdentifier, RequestCacheEntry> = new Map();
+  requestCachesByEnvironment.set(environment, requestCache);
+  return requestCache;
+}
+
+/**
+ * @private
+ */
+function getCachedRequest(
+  requestCache: Map<RequestIdentifier, RequestCacheEntry>,
+  identifier: RequestIdentifier,
+) {
+  const cached = requestCache.get(identifier);
+  invariant(
+    cached != null,
+    '[fetchQueryInternal] getCachedRequest: Expected request to be cached',
+  );
+  return cached;
+}
+
+module.exports = {
+  fetchQuery,
+  fetchQueryDeduped,
+  getPromiseForActiveRequest,
+  getObservableForActiveRequest,
+};