relay-runtime 9.0.0 → 9.1.0

package/util/RelayConcreteNode.js.flow

@@ -0,0 +1,80 @@
+/**
+ * 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 {
+  NormalizationOperation,
+  NormalizationSplitOperation,
+} from './NormalizationNode';
+import type {ReaderFragment, ReaderInlineDataFragment} from './ReaderNode';
+
+/**
+ * Represents a common GraphQL request with `text` (or persisted `id`) can be
+ * used to execute it, an `operation` containing information to normalize the
+ * results, and a `fragment` derived from that operation to read the response
+ * data (masking data from child fragments).
+ */
+export type ConcreteRequest = {|
+  +kind: 'Request',
+  +fragment: ReaderFragment,
+  +operation: NormalizationOperation,
+  +params: RequestParameters,
+|};
+
+/**
+ * Contains the `text` (or persisted `id`) required for executing a common
+ * GraphQL request.
+ */
+export type RequestParameters =
+  | {|...BaseRequestParameters, +text: null, +id: string|}
+  | {|...BaseRequestParameters, +text: string, +id: null|};
+type BaseRequestParameters = {|
+  +name: string,
+  +operationKind: 'mutation' | 'query' | 'subscription',
+  +metadata: {[key: string]: mixed, ...},
+|};
+
+export type GeneratedNode =
+  | ConcreteRequest
+  | ReaderFragment
+  | ReaderInlineDataFragment
+  | NormalizationSplitOperation;
+
+const RelayConcreteNode = {
+  CONDITION: 'Condition',
+  CLIENT_EXTENSION: 'ClientExtension',
+  DEFER: 'Defer',
+  CONNECTION: 'Connection',
+  FRAGMENT: 'Fragment',
+  FRAGMENT_SPREAD: 'FragmentSpread',
+  INLINE_DATA_FRAGMENT_SPREAD: 'InlineDataFragmentSpread',
+  INLINE_DATA_FRAGMENT: 'InlineDataFragment',
+  INLINE_FRAGMENT: 'InlineFragment',
+  LINKED_FIELD: 'LinkedField',
+  LINKED_HANDLE: 'LinkedHandle',
+  LITERAL: 'Literal',
+  LIST_VALUE: 'ListValue',
+  LOCAL_ARGUMENT: 'LocalArgument',
+  MODULE_IMPORT: 'ModuleImport',
+  OBJECT_VALUE: 'ObjectValue',
+  OPERATION: 'Operation',
+  REQUEST: 'Request',
+  ROOT_ARGUMENT: 'RootArgument',
+  SCALAR_FIELD: 'ScalarField',
+  SCALAR_HANDLE: 'ScalarHandle',
+  SPLIT_OPERATION: 'SplitOperation',
+  STREAM: 'Stream',
+  VARIABLE: 'Variable',
+};
+
+module.exports = RelayConcreteNode;

package/util/RelayDefaultHandleKey.js.flow

@@ -0,0 +1,17 @@
+/**
+ * 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';
+
+module.exports = {
+  DEFAULT_HANDLE_KEY: '',
+};

package/util/RelayError.js.flow

@@ -0,0 +1,33 @@
+/**
+ * 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';
+
+/**
+ * @private
+ */
+function createError(type: string, name: string, message: string): Error {
+  const error = new Error(message);
+  error.name = name;
+  (error: any).type = type;
+  (error: any).framesToPop = 2;
+  return error;
+}
+
+module.exports = {
+  create(name: string, message: string): Error {
+    return createError('error', name, message);
+  },
+  createWarning(name: string, message: string): Error {
+    return createError('warn', name, message);
+  },
+};

package/util/RelayFeatureFlags.js.flow

@@ -0,0 +1,30 @@
+/**
+ * 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';
+
+type FeatureFlags = {|
+  ENABLE_VARIABLE_CONNECTION_KEY: boolean,
+  ENABLE_PARTIAL_RENDERING_DEFAULT: boolean,
+  ENABLE_RELAY_CONTAINERS_SUSPENSE: boolean,
+  ENABLE_UNIQUE_MUTATION_ROOT: boolean,
+|};
+
+const RelayFeatureFlags: FeatureFlags = {
+  // T45504512: new connection model
+  ENABLE_VARIABLE_CONNECTION_KEY: false,
+  ENABLE_PARTIAL_RENDERING_DEFAULT: false,
+  ENABLE_RELAY_CONTAINERS_SUSPENSE: false,
+  ENABLE_UNIQUE_MUTATION_ROOT: true,
+};
+
+module.exports = RelayFeatureFlags;

package/util/RelayProfiler.js.flow

@@ -0,0 +1,284 @@
+/**
+ * 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';
+
+type Handler = (name: string, callback: () => void) => void;
+type ProfileHandler = (name: string, state?: any) => (error?: Error) => void;
+
+function emptyFunction() {}
+
+const aggregateHandlersByName: {[name: string]: Array<Handler>, ...} = {
+  '*': [],
+};
+const profileHandlersByName: {[name: string]: Array<ProfileHandler>, ...} = {
+  '*': [],
+};
+
+const NOT_INVOKED = {};
+const defaultProfiler = {stop: emptyFunction};
+const shouldInstrument = name => {
+  if (__DEV__) {
+    return true;
+  }
+  return name.charAt(0) !== '@';
+};
+
+/**
+ * @public
+ *
+ * Instruments methods to allow profiling various parts of Relay. Profiling code
+ * in Relay consists of three steps:
+ *
+ *  - Instrument the function to be profiled.
+ *  - Attach handlers to the instrumented function.
+ *  - Run the code which triggers the handlers.
+ *
+ * Handlers attached to instrumented methods are called with an instrumentation
+ * name and a callback that must be synchronously executed:
+ *
+ *   instrumentedMethod.attachHandler(function(name, callback) {
+ *     const start = performance.now();
+ *     callback();
+ *     console.log('Duration', performance.now() - start);
+ *   });
+ *
+ * Handlers for profiles are callbacks that return a stop method:
+ *
+ *   RelayProfiler.attachProfileHandler('profileName', (name, state) => {
+ *     const start = performance.now();
+ *     return function stop(name, state) {
+ *       console.log(`Duration (${name})`, performance.now() - start);
+ *     }
+ *   });
+ *
+ * In order to reduce the impact on performance in production, instrumented
+ * methods and profilers with names that begin with `@` will only be measured
+ * if `__DEV__` is true. This should be used for very hot functions.
+ */
+const RelayProfiler = {
+  /**
+   * Instruments methods on a class or object. This re-assigns the method in
+   * order to preserve function names in stack traces (which are detected by
+   * modern debuggers via heuristics). Example usage:
+   *
+   *   const RelayStore = { primeCache: function() {...} };
+   *   RelayProfiler.instrumentMethods(RelayStore, {
+   *     primeCache: 'RelayStore.primeCache'
+   *   });
+   *
+   *   RelayStore.primeCache.attachHandler(...);
+   *
+   * As a result, the methods will be replaced by wrappers that provide the
+   * `attachHandler` and `detachHandler` methods.
+   */
+  instrumentMethods(
+    object: Function | Object,
+    names: {[key: string]: string, ...},
+  ): void {
+    for (const key in names) {
+      if (names.hasOwnProperty(key)) {
+        if (typeof object[key] === 'function') {
+          object[key] = RelayProfiler.instrument(names[key], object[key]);
+        }
+      }
+    }
+  },
+
+  /**
+   * Wraps the supplied function with one that provides the `attachHandler` and
+   * `detachHandler` methods. Example usage:
+   *
+   *   const printRelayQuery =
+   *     RelayProfiler.instrument('printRelayQuery', printRelayQuery);
+   *
+   *   printRelayQuery.attachHandler(...);
+   *
+   * NOTE: The instrumentation assumes that no handlers are attached or detached
+   * in the course of executing another handler.
+   */
+  instrument<T: Function>(name: string, originalFunction: T): T {
+    if (!shouldInstrument(name)) {
+      originalFunction.attachHandler = emptyFunction;
+      originalFunction.detachHandler = emptyFunction;
+      return originalFunction;
+    }
+    if (!aggregateHandlersByName.hasOwnProperty(name)) {
+      aggregateHandlersByName[name] = [];
+    }
+    const catchallHandlers = aggregateHandlersByName['*'];
+    const aggregateHandlers = aggregateHandlersByName[name];
+    const handlers: Array<Handler> = [];
+    const contexts: Array<[number, number, number, any, any, any]> = [];
+    const invokeHandlers = function() {
+      const context = contexts[contexts.length - 1];
+      if (context[0]) {
+        context[0]--;
+        catchallHandlers[context[0]](name, invokeHandlers);
+      } else if (context[1]) {
+        context[1]--;
+        aggregateHandlers[context[1]](name, invokeHandlers);
+      } else if (context[2]) {
+        context[2]--;
+        handlers[context[2]](name, invokeHandlers);
+      } else {
+        context[5] = originalFunction.apply(context[3], context[4]);
+      }
+    };
+    const instrumentedCallback = function() {
+      let returnValue;
+      if (
+        aggregateHandlers.length === 0 &&
+        handlers.length === 0 &&
+        catchallHandlers.length === 0
+      ) {
+        returnValue = originalFunction.apply(this, arguments);
+      } else {
+        contexts.push([
+          catchallHandlers.length,
+          aggregateHandlers.length,
+          handlers.length,
+          this,
+          arguments,
+          NOT_INVOKED,
+        ]);
+        invokeHandlers();
+        const context = contexts.pop();
+        returnValue = context[5];
+        if (returnValue === NOT_INVOKED) {
+          throw new Error(
+            'RelayProfiler: Handler did not invoke original function.',
+          );
+        }
+      }
+      return returnValue;
+    };
+    instrumentedCallback.attachHandler = function(handler: Handler): void {
+      handlers.push(handler);
+    };
+    instrumentedCallback.detachHandler = function(handler: Handler): void {
+      removeFromArray(handlers, handler);
+    };
+    instrumentedCallback.displayName = '(instrumented ' + name + ')';
+    return (instrumentedCallback: any);
+  },
+
+  /**
+   * Attaches a handler to all methods instrumented with the supplied name.
+   *
+   *   function createRenderer() {
+   *     return RelayProfiler.instrument('render', function() {...});
+   *   }
+   *   const renderA = createRenderer();
+   *   const renderB = createRenderer();
+   *
+   *   // Only profiles `renderA`.
+   *   renderA.attachHandler(...);
+   *
+   *   // Profiles both `renderA` and `renderB`.
+   *   RelayProfiler.attachAggregateHandler('render', ...);
+   *
+   */
+  attachAggregateHandler(name: string, handler: Handler): void {
+    if (shouldInstrument(name)) {
+      if (!aggregateHandlersByName.hasOwnProperty(name)) {
+        aggregateHandlersByName[name] = [];
+      }
+      aggregateHandlersByName[name].push(handler);
+    }
+  },
+
+  /**
+   * Detaches a handler attached via `attachAggregateHandler`.
+   */
+  detachAggregateHandler(name: string, handler: Handler): void {
+    if (shouldInstrument(name)) {
+      if (aggregateHandlersByName.hasOwnProperty(name)) {
+        removeFromArray(aggregateHandlersByName[name], handler);
+      }
+    }
+  },
+
+  /**
+   * Instruments profiling for arbitrarily asynchronous code by a name.
+   *
+   *   const timerProfiler = RelayProfiler.profile('timeout');
+   *   setTimeout(function() {
+   *     timerProfiler.stop();
+   *   }, 1000);
+   *
+   *   RelayProfiler.attachProfileHandler('timeout', ...);
+   *
+   * Arbitrary state can also be passed into `profile` as a second argument. The
+   * attached profile handlers will receive this as the second argument.
+   */
+  profile(name: string, state?: any): {stop: (error?: Error) => void, ...} {
+    const hasCatchAllHandlers = profileHandlersByName['*'].length > 0;
+    const hasNamedHandlers = profileHandlersByName.hasOwnProperty(name);
+    if (hasNamedHandlers || hasCatchAllHandlers) {
+      const profileHandlers =
+        hasNamedHandlers && hasCatchAllHandlers
+          ? profileHandlersByName[name].concat(profileHandlersByName['*'])
+          : hasNamedHandlers
+          ? profileHandlersByName[name]
+          : profileHandlersByName['*'];
+      let stopHandlers;
+      for (let ii = profileHandlers.length - 1; ii >= 0; ii--) {
+        const profileHandler = profileHandlers[ii];
+        const stopHandler = profileHandler(name, state);
+        stopHandlers = stopHandlers || [];
+        stopHandlers.unshift(stopHandler);
+      }
+      return {
+        stop(error?: Error): void {
+          if (stopHandlers) {
+            stopHandlers.forEach(stopHandler => stopHandler(error));
+          }
+        },
+      };
+    }
+    return defaultProfiler;
+  },
+
+  /**
+   * Attaches a handler to profiles with the supplied name. You can also
+   * attach to the special name '*' which is a catch all.
+   */
+  attachProfileHandler(name: string, handler: ProfileHandler): void {
+    if (shouldInstrument(name)) {
+      if (!profileHandlersByName.hasOwnProperty(name)) {
+        profileHandlersByName[name] = [];
+      }
+      profileHandlersByName[name].push(handler);
+    }
+  },
+
+  /**
+   * Detaches a handler attached via `attachProfileHandler`.
+   */
+  detachProfileHandler(name: string, handler: ProfileHandler): void {
+    if (shouldInstrument(name)) {
+      if (profileHandlersByName.hasOwnProperty(name)) {
+        removeFromArray(profileHandlersByName[name], handler);
+      }
+    }
+  },
+};
+
+function removeFromArray<T>(array: Array<T>, element: T): void {
+  var index = array.indexOf(element);
+  if (index !== -1) {
+    array.splice(index, 1);
+  }
+}
+
+module.exports = RelayProfiler;

package/util/RelayReplaySubject.js.flow

@@ -0,0 +1,134 @@
+/**
+ * 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('../network/RelayObservable');
+
+const invariant = require('invariant');
+
+import type {Observer, Sink, Subscription} from '../network/RelayObservable';
+
+type Event<T> =
+  | {
+      kind: 'next',
+      data: T,
+      ...
+    }
+  | {
+      kind: 'error',
+      error: Error,
+      ...
+    }
+  | {kind: 'complete', ...};
+
+/**
+ * An implementation of a `ReplaySubject` for Relay Observables.
+ *
+ * Records events provided and synchronously plays them back to new subscribers,
+ * as well as forwarding new asynchronous events.
+ */
+class RelayReplaySubject<T> {
+  _complete: boolean = false;
+  _events: Array<Event<T>> = [];
+  _sinks: Set<Sink<T>> = new Set();
+  _observable: RelayObservable<T>;
+  _subscription: ?Subscription = null;
+
+  constructor() {
+    this._observable = RelayObservable.create(sink => {
+      this._sinks.add(sink);
+
+      const events = this._events;
+      for (let i = 0; i < events.length; i++) {
+        if (sink.closed) {
+          // Bail if an event made the observer unsubscribe.
+          break;
+        }
+        const event = events[i];
+        switch (event.kind) {
+          case 'complete':
+            sink.complete();
+            break;
+          case 'error':
+            sink.error(event.error);
+            break;
+          case 'next':
+            sink.next(event.data);
+            break;
+          default:
+            (event.kind: empty);
+            invariant(
+              false,
+              'RelayReplaySubject: Unknown event kind `%s`.',
+              event.kind,
+            );
+        }
+      }
+
+      return () => {
+        this._sinks.delete(sink);
+      };
+    });
+  }
+
+  complete(): void {
+    if (this._complete === true) {
+      return;
+    }
+    this._complete = true;
+    this._events.push({
+      kind: 'complete',
+    });
+    this._sinks.forEach(sink => sink.complete());
+  }
+
+  error(error: Error): void {
+    if (this._complete === true) {
+      return;
+    }
+    this._complete = true;
+    this._events.push({
+      kind: 'error',
+      error,
+    });
+    this._sinks.forEach(sink => sink.error(error));
+  }
+
+  next(data: T): void {
+    if (this._complete === true) {
+      return;
+    }
+    this._events.push({
+      kind: 'next',
+      data,
+    });
+    this._sinks.forEach(sink => sink.next(data));
+  }
+
+  subscribe(observer: Observer<T> | Sink<T>): Subscription {
+    this._subscription = this._observable.subscribe(observer);
+    return this._subscription;
+  }
+
+  unsubscribe() {
+    if (this._subscription) {
+      this._subscription.unsubscribe();
+    }
+  }
+
+  getObserverCount(): number {
+    return this._sinks.size;
+  }
+}
+
+module.exports = RelayReplaySubject;

package/util/RelayRuntimeTypes.js.flow

@@ -0,0 +1,70 @@
+/**
+ * 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';
+
+/**
+ * Basic types used throughout Relay.
+ */
+
+/**
+ * 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 DataID = string;
+
+// Variables
+export type Variables = {+[string]: $FlowFixMe, ...};
+
+/**
+ * Generated operation flow types are subtypes of this.
+ */
+export type OperationType = {|
+  // TODO(T33395812) Make this an open object type
+  +variables: Variables,
+  +response: mixed,
+  +rawResponse?: {...},
+|};
+
+/**
+ * Settings for how a query response may be cached.
+ *
+ * - `force`: causes a query to be issued unconditionally, irrespective of the
+ *   state of any configured response cache.
+ * - `poll`: causes a query to live update by polling at the specified interval
+ *   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
+ * - `metadata`: user-supplied metadata.
+ * - `transactionId`: a user-supplied value, intended for use as a unique id for
+ *   a given instance of executing an operation.
+ */
+export type CacheConfig = {|
+  force?: ?boolean,
+  poll?: ?number,
+  liveConfigId?: ?string,
+  metadata?: {[key: string]: mixed, ...},
+  transactionId?: ?string,
+|};
+
+/**
+ * Experimental
+ */
+export type FetchQueryFetchPolicy = 'store-or-network' | 'network-only';
+export type FetchPolicy =
+  | FetchQueryFetchPolicy
+  | 'store-and-network'
+  | 'store-only';
+export type RenderPolicy = 'full' | 'partial';

package/util/createPayloadFor3DField.js.flow

@@ -0,0 +1,43 @@
+/**
+ * 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';
+
+const {
+  getModuleComponentKey,
+  getModuleOperationKey,
+} = require('../store/RelayStoreUtils');
+
+import type {NormalizationSplitOperation} from './NormalizationNode';
+import type {JSResourceReference} from 'JSResourceReference';
+
+export opaque type Local3DPayload<
+  +DocumentName: string,
+  +Response: {...},
+> = Response;
+
+function createPayloadFor3DField<+DocumentName: string, +Response: {...}>(
+  name: DocumentName,
+  operation: JSResourceReference<NormalizationSplitOperation>,
+  component: JSResourceReference<mixed>,
+  response: Response,
+): Local3DPayload<DocumentName, Response> {
+  const data = {
+    ...response,
+  };
+  data[getModuleComponentKey(name)] = component;
+  data[getModuleOperationKey(name)] = operation;
+  return data;
+}
+
+module.exports = createPayloadFor3DField;