relay-runtime 11.0.0 → 13.0.0-rc.0

package/util/RelayRuntimeTypes.js.flow

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @flow strict
+ * @flow strict-local
  * @format
  */
 
@@ -16,17 +16,20 @@
  * Basic types used throughout Relay.
  */
 
+import type {ReaderFragment, ReaderInlineDataFragment} from './ReaderNode';
+import type {ConcreteRequest} from './RelayConcreteNode';
+
 /**
  * Represents any resource that must be explicitly disposed of. The most common
  * use-case is as a return value for subscriptions, where calling `dispose()`
  * would cancel the subscription.
  */
-export type Disposable = {dispose(): void, ...};
+export type Disposable = interface {dispose(): void};
 
 export type DataID = string;
 
 // Variables
-export type Variables = {+[string]: $FlowFixMe, ...};
+export type Variables = {+[string]: $FlowFixMe};
 
 /**
  * Generated operation flow types are subtypes of this.
@@ -38,7 +41,7 @@ export type OperationType = {|
   +rawResponse?: {...},
 |};
 
-export type VariablesOf<T: OperationType> = $ElementType<T, 'variables'>;
+export type VariablesOf<T: OperationType> = T['variables'];
 
 /**
  * Settings for how a query response may be cached.
@@ -49,6 +52,7 @@ export type VariablesOf<T: OperationType> = $ElementType<T, 'variables'>;
  *   in milliseconds. (This value will be passed to setTimeout.)
  * - `liveConfigId`: causes a query to live update by calling GraphQLLiveQuery,
  *   it represents a configuration of gateway when doing live query
+ * - `onSubscribe`: Not in use.
  * - `metadata`: user-supplied metadata.
  * - `transactionId`: a user-supplied value, intended for use as a unique id for
  *   a given instance of executing an operation.
@@ -57,6 +61,7 @@ export type CacheConfig = {|
   force?: ?boolean,
   poll?: ?number,
   liveConfigId?: ?string,
+  onSubscribe?: () => void,
   metadata?: {[key: string]: mixed, ...},
   transactionId?: ?string,
 |};
@@ -67,3 +72,67 @@ export type FetchPolicy =
   | 'store-and-network'
   | 'store-only';
 export type RenderPolicy = 'full' | 'partial';
+
+/* eslint-disable no-undef */
+
+/**
+ * Return type of graphql tag literals for all operations.
+ */
+declare export opaque type Operation<
+  -TVariables: Variables,
+  +TData,
+  TRawResponse,
+>: ConcreteRequest;
+
+/**
+ * Return type of graphql tag literals for queries.
+ */
+declare export opaque type Query<
+  -TVariables: Variables,
+  +TData,
+  TRawResponse = void,
+>: Operation<TVariables, TData, TRawResponse>;
+
+/**
+ * Return type of graphql tag literals for mutations.
+ */
+declare export opaque type Mutation<
+  -TVariables: Variables,
+  +TData,
+  TRawResponse = void,
+>: Operation<TVariables, TData, TRawResponse>;
+
+/**
+ * Return type of graphql tag literals for subscriptions.
+ *
+ * NOTE: Using the GraphQL prefix here because of a naming conflict with
+ *       `RelayObservable`'s `Subscription` type.
+ */
+declare export opaque type GraphQLSubscription<
+  -TVariables: Variables,
+  +TData,
+  TRawResponse = void,
+>: Operation<TVariables, TData, TRawResponse>;
+
+/**
+ * Return type of graphql tag literals for `@inline` fragments.
+ */
+declare export opaque type InlineFragment<
+  TFragmentType,
+  +TData,
+>: ReaderInlineDataFragment;
+
+/**
+ * Return type of graphql tag literals for fragments, except `@inline`
+ * fragments.
+ */
+declare export opaque type Fragment<TFragmentType, +TData>: ReaderFragment;
+
+/**
+ * Return type of graphql tag literals for `@refetchable` fragments.
+ */
+declare export opaque type RefetchableFragment<
+  TFragmentType,
+  +TData,
+  -TVariables: Variables,
+>: Fragment<TFragmentType, TData>;

package/util/StringInterner.js.flow

@@ -0,0 +1,69 @@
+/**
+ * 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
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const internTable = new Map();
+let nextIndex = 1;
+const digits = initDigitTable();
+
+// Character used as the prefix for interned strings. The specific character is
+// chosen to reduce the likelihood that non-interned input strings need to be
+// escaped (choosing eg a-Z would increase the likelihood we need to escape)
+const INTERN_PREFIX = '\t';
+// Character used as the prefix of escaped strings. As above, this is also
+// chosen to be unlikely in normal input strings.
+const ESCAPE_PREFIX = '\v';
+
+function initDigitTable() {
+  // disable lint because digits isn't defined when this function is called
+  // eslint-disable-next-line no-shadow
+  const digits = new Set();
+  for (let i = 0; i < 10; ++i) {
+    digits.add(i.toString());
+  }
+  return digits;
+}
+
+// Escape a string so that it cannot conflict with an interned string
+function escape(str: string): string {
+  if (
+    // "\t<digit>..." -> "\v\t<digit>..."
+    (str[0] === INTERN_PREFIX && digits.has(str[1])) ||
+    // "\v..." -> "\v\v..."
+    str[0] === ESCAPE_PREFIX
+  ) {
+    return ESCAPE_PREFIX + str;
+  }
+  return str;
+}
+
+// Interns the input string if its length equals or exceeds the given `limit`,
+// returning a shorter replacement string that is uniquely associated with the
+// input: multiple calls to intern() for the equivalent input strings (and limit)
+// will always return the exact same string.
+// Strings shorter than the limit are not interned but are escaped if they
+// could conflict with interned strings.
+function intern(str: string, limit: ?number): string {
+  if (limit == null || str.length < limit) {
+    return escape(str);
+  }
+  let internedString = internTable.get(str);
+  if (internedString != null) {
+    return internedString;
+  }
+  internedString = INTERN_PREFIX + nextIndex++;
+  internTable.set(str, internedString);
+  return internedString;
+}
+
+module.exports = {intern};

package/util/createPayloadFor3DField.js.flow

@@ -13,14 +13,14 @@
 
 'use strict';
 
+import type {JSResourceReference} from 'JSResourceReference';
+import type {NormalizationSplitOperation} from './NormalizationNode';
+
 const {
   getModuleComponentKey,
   getModuleOperationKey,
 } = require('../store/RelayStoreUtils');
 
-import type {NormalizationSplitOperation} from './NormalizationNode';
-import type {JSResourceReference} from 'JSResourceReference';
-
 export opaque type Local3DPayload<
   +DocumentName: string,
   +Response: {...},

package/util/deepFreeze.js.flow

@@ -18,9 +18,10 @@
  * For convenience, and for consistency with the behavior of `Object.freeze`,
  * returns the now-frozen original object.
  */
-function deepFreeze<T: {...}>(object: T): T {
+function deepFreeze<T: interface {}>(object: T): T {
   Object.freeze(object);
   Object.getOwnPropertyNames(object).forEach(name => {
+    // $FlowFixMe[prop-missing]
     const property = object[name];
     if (
       property &&

package/util/getFragmentIdentifier.js.flow

@@ -13,18 +13,17 @@
 
 'use strict';
 
-const RelayFeatureFlags = require('./RelayFeatureFlags');
-
-const isEmptyObject = require('./isEmptyObject');
-const stableCopy = require('./stableCopy');
+import type {ReaderFragment} from './ReaderNode';
 
 const {
   getDataIDsFromFragment,
-  getVariablesFromFragment,
   getSelector,
+  getVariablesFromFragment,
 } = require('../store/RelayModernSelector');
-
-import type {ReaderFragment} from './ReaderNode';
+const isEmptyObject = require('./isEmptyObject');
+const RelayFeatureFlags = require('./RelayFeatureFlags');
+const stableCopy = require('./stableCopy');
+const {intern} = require('./StringInterner');
 
 function getFragmentIdentifier(
   fragmentNode: ReaderFragment,
@@ -43,6 +42,19 @@ function getFragmentIdentifier(
   const dataIDs = getDataIDsFromFragment(fragmentNode, fragmentRef);
 
   if (RelayFeatureFlags.ENABLE_GETFRAGMENTIDENTIFIER_OPTIMIZATION) {
+    let ids =
+      typeof dataIDs === 'undefined'
+        ? 'missing'
+        : dataIDs == null
+        ? 'null'
+        : Array.isArray(dataIDs)
+        ? '[' + dataIDs.join(',') + ']'
+        : dataIDs;
+    ids =
+      RelayFeatureFlags.STRING_INTERN_LEVEL <= 1
+        ? ids
+        : intern(ids, RelayFeatureFlags.MAX_DATA_ID_LENGTH);
+
     return (
       fragmentOwnerIdentifier +
       '/' +
@@ -52,15 +64,15 @@ function getFragmentIdentifier(
         ? '{}'
         : JSON.stringify(stableCopy(fragmentVariables))) +
       '/' +
-      (typeof dataIDs === 'undefined'
-        ? 'missing'
-        : dataIDs == null
-        ? 'null'
-        : Array.isArray(dataIDs)
-        ? '[' + dataIDs.join(',') + ']'
-        : dataIDs)
+      ids
     );
   } else {
+    let ids = JSON.stringify(dataIDs) ?? 'missing';
+    ids =
+      RelayFeatureFlags.STRING_INTERN_LEVEL <= 1
+        ? ids
+        : intern(ids, RelayFeatureFlags.MAX_DATA_ID_LENGTH);
+
     return (
       fragmentOwnerIdentifier +
       '/' +
@@ -68,7 +80,7 @@ function getFragmentIdentifier(
       '/' +
       JSON.stringify(stableCopy(fragmentVariables)) +
       '/' +
-      (JSON.stringify(dataIDs) ?? 'missing')
+      ids
     );
   }
 }

package/util/getOperation.js.flow

@@ -13,14 +13,14 @@
 
 'use strict';
 
-const {REQUEST, SPLIT_OPERATION} = require('./RelayConcreteNode');
-
 import type {
   NormalizationOperation,
   NormalizationRootNode,
   NormalizationSplitOperation,
 } from './NormalizationNode';
 
+const {REQUEST, SPLIT_OPERATION} = require('./RelayConcreteNode');
+
 /**
  * OperationLoaders can return either a NormalizationSplitOperation or
  * ConcreteRequest.

package/util/getPaginationMetadata.js.flow

@@ -0,0 +1,72 @@
+/**
+ * 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
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+import type {
+  ConcreteRequest,
+  ReaderFragment,
+  ReaderPaginationMetadata,
+} from 'relay-runtime';
+
+const getRefetchMetadata = require('./getRefetchMetadata');
+const invariant = require('invariant');
+
+function getPaginationMetadata(
+  fragmentNode: ReaderFragment,
+  componentDisplayName: string,
+): {|
+  connectionPathInFragmentData: $ReadOnlyArray<string | number>,
+  identifierField: ?string,
+  paginationRequest: ConcreteRequest,
+  paginationMetadata: ReaderPaginationMetadata,
+  stream: boolean,
+|} {
+  const {refetchableRequest: paginationRequest, refetchMetadata} =
+    getRefetchMetadata(fragmentNode, componentDisplayName);
+
+  const paginationMetadata = refetchMetadata.connection;
+  invariant(
+    paginationMetadata != null,
+    'Relay: getPaginationMetadata(): Expected fragment `%s` to include a ' +
+      'connection when using `%s`. Did you forget to add a @connection ' +
+      'directive to the connection field in the fragment?',
+    componentDisplayName,
+    fragmentNode.name,
+  );
+  const connectionPathInFragmentData = paginationMetadata.path;
+
+  const connectionMetadata = (fragmentNode.metadata?.connection ?? [])[0];
+  invariant(
+    connectionMetadata != null,
+    'Relay: getPaginationMetadata(): Expected fragment `%s` to include a ' +
+      'connection when using `%s`. Did you forget to add a @connection ' +
+      'directive to the connection field in the fragment?',
+    componentDisplayName,
+    fragmentNode.name,
+  );
+  const identifierField = refetchMetadata.identifierField;
+  invariant(
+    identifierField == null || typeof identifierField === 'string',
+    'Relay: getRefetchMetadata(): Expected `identifierField` to be a string.',
+  );
+  return {
+    connectionPathInFragmentData,
+    identifierField,
+    paginationRequest,
+    paginationMetadata,
+    stream: connectionMetadata.stream === true,
+  };
+}
+
+module.exports = getPaginationMetadata;

package/util/getPaginationVariables.js.flow

@@ -0,0 +1,108 @@
+/**
+ * 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
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+import type {ReaderPaginationMetadata} from './ReaderNode';
+import type {Variables} from './RelayRuntimeTypes';
+
+const invariant = require('invariant');
+const warning = require('warning');
+
+export type Direction = 'forward' | 'backward';
+
+function getPaginationVariables(
+  direction: Direction,
+  count: number,
+  cursor: ?string,
+  baseVariables: Variables,
+  extraVariables: Variables,
+  paginationMetadata: ReaderPaginationMetadata,
+): {[string]: mixed, ...} {
+  const {backward: backwardMetadata, forward: forwardMetadata} =
+    paginationMetadata;
+
+  if (direction === 'backward') {
+    invariant(
+      backwardMetadata != null &&
+        backwardMetadata.count != null &&
+        backwardMetadata.cursor != null,
+      'Relay: Expected backward pagination metadata to be available. ' +
+        "If you're seeing this, this is likely a bug in Relay.",
+    );
+    warning(
+      !extraVariables.hasOwnProperty(backwardMetadata.cursor),
+      'Relay: `UNSTABLE_extraVariables` provided by caller should not ' +
+        'contain cursor variable `%s`. This variable is automatically ' +
+        'determined by Relay.',
+      backwardMetadata.cursor,
+    );
+    warning(
+      !extraVariables.hasOwnProperty(backwardMetadata.count),
+      'Relay: `UNSTABLE_extraVariables` provided by caller should not ' +
+        'contain count variable `%s`. This variable is automatically ' +
+        'determined by Relay.',
+      backwardMetadata.count,
+    );
+    const paginationVariables = {
+      ...baseVariables,
+      ...extraVariables,
+      [backwardMetadata.cursor]: cursor,
+      [backwardMetadata.count]: count,
+    };
+    if (forwardMetadata && forwardMetadata.cursor) {
+      paginationVariables[forwardMetadata.cursor] = null;
+    }
+    if (forwardMetadata && forwardMetadata.count) {
+      paginationVariables[forwardMetadata.count] = null;
+    }
+    return paginationVariables;
+  }
+
+  invariant(
+    forwardMetadata != null &&
+      forwardMetadata.count != null &&
+      forwardMetadata.cursor != null,
+    'Relay: Expected forward pagination metadata to be available. ' +
+      "If you're seeing this, this is likely a bug in Relay.",
+  );
+  warning(
+    !extraVariables.hasOwnProperty(forwardMetadata.cursor),
+    'Relay: `UNSTABLE_extraVariables` provided by caller should not ' +
+      'contain cursor variable `%s`. This variable is automatically ' +
+      'determined by Relay.',
+    forwardMetadata.cursor,
+  );
+  warning(
+    !extraVariables.hasOwnProperty(forwardMetadata.count),
+    'Relay: `UNSTABLE_extraVariables` provided by caller should not ' +
+      'contain count variable `%s`. This variable is automatically ' +
+      'determined by Relay.',
+    forwardMetadata.count,
+  );
+  const paginationVariables = {
+    ...baseVariables,
+    ...extraVariables,
+    [forwardMetadata.cursor]: cursor,
+    [forwardMetadata.count]: count,
+  };
+  if (backwardMetadata && backwardMetadata.cursor) {
+    paginationVariables[backwardMetadata.cursor] = null;
+  }
+  if (backwardMetadata && backwardMetadata.count) {
+    paginationVariables[backwardMetadata.count] = null;
+  }
+  return paginationVariables;
+}
+
+module.exports = getPaginationVariables;

package/util/getPendingOperationsForFragment.js.flow

@@ -0,0 +1,62 @@
+/**
+ * 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
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+import type {IEnvironment, RequestDescriptor} from '../store/RelayStoreTypes';
+import type {ReaderFragment} from './ReaderNode';
+
+const {getPromiseForActiveRequest} = require('../query/fetchQueryInternal');
+
+function getPendingOperationsForFragment(
+  environment: IEnvironment,
+  fragmentNode: ReaderFragment,
+  fragmentOwner: RequestDescriptor,
+): {|
+  promise: Promise<void>,
+  pendingOperations: $ReadOnlyArray<RequestDescriptor>,
+|} | null {
+  let pendingOperations: $ReadOnlyArray<RequestDescriptor> = [];
+  let promise = getPromiseForActiveRequest(environment, fragmentOwner);
+
+  if (promise != null) {
+    pendingOperations = [fragmentOwner];
+  } else {
+    const result = environment
+      .getOperationTracker()
+      .getPendingOperationsAffectingOwner(fragmentOwner);
+
+    pendingOperations = result?.pendingOperations ?? [];
+    promise = result?.promise ?? null;
+  }
+
+  if (!promise) {
+    return null;
+  }
+
+  let pendingOperationName =
+    pendingOperations?.map(op => op.node.params.name).join(',') ?? null;
+  if (pendingOperationName == null || pendingOperationName.length === 0) {
+    pendingOperationName = 'Unknown pending operation';
+  }
+  const fragmentName = fragmentNode.name;
+  const promiseDisplayName =
+    pendingOperationName === fragmentName
+      ? `Relay(${pendingOperationName})`
+      : `Relay(${pendingOperationName}:${fragmentName})`;
+  // $FlowExpectedError[prop-missing] Expando to annotate Promises.
+  promise.displayName = promiseDisplayName;
+  return {promise, pendingOperations};
+}
+
+module.exports = getPendingOperationsForFragment;

package/util/getRefetchMetadata.js.flow

@@ -0,0 +1,79 @@
+/**
+ * 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
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+import type {
+  ConcreteRequest,
+  ReaderFragment,
+  ReaderRefetchMetadata,
+} from 'relay-runtime';
+
+const invariant = require('invariant');
+
+function getRefetchMetadata(
+  fragmentNode: ReaderFragment,
+  componentDisplayName: string,
+): {|
+  fragmentRefPathInResponse: $ReadOnlyArray<string | number>,
+  identifierField: ?string,
+  refetchableRequest: ConcreteRequest,
+  refetchMetadata: ReaderRefetchMetadata,
+|} {
+  invariant(
+    fragmentNode.metadata?.plural !== true,
+    'Relay: getRefetchMetadata(): Expected fragment `%s` not to be plural when using ' +
+      '`%s`. Remove `@relay(plural: true)` from fragment `%s` ' +
+      'in order to use it with `%s`.',
+    fragmentNode.name,
+    componentDisplayName,
+    fragmentNode.name,
+    componentDisplayName,
+  );
+
+  const refetchMetadata = fragmentNode.metadata?.refetch;
+  invariant(
+    refetchMetadata != null,
+    'Relay: getRefetchMetadata(): Expected fragment `%s` to be refetchable when using `%s`. ' +
+      'Did you forget to add a @refetchable directive to the fragment?',
+    componentDisplayName,
+    fragmentNode.name,
+  );
+
+  // handle both commonjs and es modules
+  const refetchableRequest: ConcreteRequest | string =
+    (refetchMetadata: $FlowFixMe).operation.default
+      ? (refetchMetadata: $FlowFixMe).operation.default
+      : refetchMetadata.operation;
+  const fragmentRefPathInResponse = refetchMetadata.fragmentPathInResult;
+  invariant(
+    typeof refetchableRequest !== 'string',
+    'Relay: getRefetchMetadata(): Expected refetch query to be an ' +
+      "operation and not a string when using `%s`. If you're seeing this, " +
+      'this is likely a bug in Relay.',
+    componentDisplayName,
+  );
+  const identifierField = refetchMetadata.identifierField;
+  invariant(
+    identifierField == null || typeof identifierField === 'string',
+    'Relay: getRefetchMetadata(): Expected `identifierField` to be a string.',
+  );
+  return {
+    fragmentRefPathInResponse,
+    identifierField,
+    refetchableRequest,
+    refetchMetadata,
+  };
+}
+
+module.exports = getRefetchMetadata;

package/util/getRelayHandleKey.js.flow

@@ -12,9 +12,8 @@
 
 'use strict';
 
-const invariant = require('invariant');
-
 const {DEFAULT_HANDLE_KEY} = require('./RelayDefaultHandleKey');
+const invariant = require('invariant');
 
 /**
  * @internal

package/util/getRequestIdentifier.js.flow

@@ -12,12 +12,12 @@
 
 'use strict';
 
-const invariant = require('invariant');
-const stableCopy = require('./stableCopy');
-
 import type {RequestParameters} from './RelayConcreteNode';
 import type {Variables} from './RelayRuntimeTypes';
 
+const stableCopy = require('./stableCopy');
+const invariant = require('invariant');
+
 export type RequestIdentifier = string;
 
 /**