relay-runtime 9.0.0 → 10.1.0

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,135 @@
+/**
+ * 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();
+      this._subscription = null;
+    }
+  }
+
+  getObserverCount(): number {
+    return this._sinks.size;
+  }
+}
+
+module.exports = RelayReplaySubject;

package/util/RelayRuntimeTypes.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.
+ *
+ * @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?: {...},
+|};
+
+export type VariablesOf<T: OperationType> = $ElementType<T, 'variables'>;
+
+/**
+ * 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;

package/util/deepFreeze.js.flow

@@ -0,0 +1,36 @@
+/**
+ * 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';
+
+/**
+ * Recursively "deep" freezes the supplied object.
+ *
+ * For convenience, and for consistency with the behavior of `Object.freeze`,
+ * returns the now-frozen original object.
+ */
+function deepFreeze<T: {...}>(object: T): T {
+  Object.freeze(object);
+  Object.getOwnPropertyNames(object).forEach(name => {
+    const property = object[name];
+    if (
+      property &&
+      typeof property === 'object' &&
+      !Object.isFrozen(property)
+    ) {
+      deepFreeze(property);
+    }
+  });
+  return object;
+}
+
+module.exports = deepFreeze;

package/util/generateID.js.flow

@@ -0,0 +1,21 @@
+/**
+ * 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';
+
+let id = 100000;
+
+function generateID(): number {
+  return id++;
+}
+
+module.exports = generateID;

package/util/getFragmentIdentifier.js.flow

@@ -0,0 +1,76 @@
+/**
+ * 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
+ * @emails oncall+relay
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const RelayFeatureFlags = require('./RelayFeatureFlags');
+
+const isEmptyObject = require('./isEmptyObject');
+const stableCopy = require('./stableCopy');
+
+const {
+  getDataIDsFromFragment,
+  getVariablesFromFragment,
+  getSelector,
+} = require('../store/RelayModernSelector');
+
+import type {ReaderFragment} from './ReaderNode';
+
+function getFragmentIdentifier(
+  fragmentNode: ReaderFragment,
+  fragmentRef: mixed,
+): string {
+  const selector = getSelector(fragmentNode, fragmentRef);
+  const fragmentOwnerIdentifier =
+    selector == null
+      ? 'null'
+      : selector.kind === 'SingularReaderSelector'
+      ? selector.owner.identifier
+      : '[' +
+        selector.selectors.map(sel => sel.owner.identifier).join(',') +
+        ']';
+  const fragmentVariables = getVariablesFromFragment(fragmentNode, fragmentRef);
+  const dataIDs = getDataIDsFromFragment(fragmentNode, fragmentRef);
+
+  if (RelayFeatureFlags.ENABLE_GETFRAGMENTIDENTIFIER_OPTIMIZATION) {
+    return (
+      fragmentOwnerIdentifier +
+      '/' +
+      fragmentNode.name +
+      '/' +
+      (fragmentVariables == null || isEmptyObject(fragmentVariables)
+        ? '{}'
+        : JSON.stringify(stableCopy(fragmentVariables))) +
+      '/' +
+      (typeof dataIDs === 'undefined'
+        ? 'missing'
+        : dataIDs == null
+        ? 'null'
+        : Array.isArray(dataIDs)
+        ? '[' + dataIDs.join(',') + ']'
+        : dataIDs)
+    );
+  } else {
+    return (
+      fragmentOwnerIdentifier +
+      '/' +
+      fragmentNode.name +
+      '/' +
+      JSON.stringify(stableCopy(fragmentVariables)) +
+      '/' +
+      (JSON.stringify(dataIDs) ?? 'missing')
+    );
+  }
+}
+
+module.exports = getFragmentIdentifier;

package/util/getOperation.js.flow

@@ -0,0 +1,40 @@
+/**
+ * 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
+ * @emails oncall+relay
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const {REQUEST, SPLIT_OPERATION} = require('./RelayConcreteNode');
+
+import type {
+  NormalizationOperation,
+  NormalizationRootNode,
+  NormalizationSplitOperation,
+} from './NormalizationNode';
+
+/**
+ * OperationLoaders can return either a NormalizationSplitOperation or
+ * ConcreteRequest.
+ */
+function getOperation(
+  node: NormalizationRootNode,
+): NormalizationSplitOperation | NormalizationOperation {
+  switch (node.kind) {
+    case REQUEST:
+      return node.operation;
+    case SPLIT_OPERATION:
+    default:
+      return node;
+  }
+}
+
+module.exports = getOperation;