relay-runtime 8.0.0 → 10.0.1

package/store/RelayStoreUtils.js.flow

@@ -0,0 +1,219 @@
+/**
+ * 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 getRelayHandleKey = require('../util/getRelayHandleKey');
+const invariant = require('invariant');
+const stableCopy = require('../util/stableCopy');
+
+import type {
+  NormalizationHandle,
+  NormalizationArgument,
+  NormalizationField,
+} from '../util/NormalizationNode';
+import type {ReaderArgument, ReaderField} from '../util/ReaderNode';
+import type {Variables} from '../util/RelayRuntimeTypes';
+
+export type Arguments = {+[string]: mixed, ...};
+
+const {VARIABLE, LITERAL, OBJECT_VALUE, LIST_VALUE} = RelayConcreteNode;
+
+const MODULE_COMPONENT_KEY_PREFIX = '__module_component_';
+const MODULE_OPERATION_KEY_PREFIX = '__module_operation_';
+
+function getArgumentValue(
+  arg: NormalizationArgument | ReaderArgument,
+  variables: Variables,
+): mixed {
+  if (arg.kind === VARIABLE) {
+    // Variables are provided at runtime and are not guaranteed to be stable.
+    return getStableVariableValue(arg.variableName, variables);
+  } else if (arg.kind === LITERAL) {
+    // The Relay compiler generates stable ConcreteArgument values.
+    return arg.value;
+  } else if (arg.kind === OBJECT_VALUE) {
+    const value = {};
+    arg.fields.forEach(field => {
+      value[field.name] = getArgumentValue(field, variables);
+    });
+    return value;
+  } else if (arg.kind === LIST_VALUE) {
+    const value = [];
+    arg.items.forEach(item => {
+      item != null ? value.push(getArgumentValue(item, variables)) : null;
+    });
+    return value;
+  }
+}
+
+/**
+ * Returns the values of field/fragment arguments as an object keyed by argument
+ * names. Guaranteed to return a result with stable ordered nested values.
+ */
+function getArgumentValues(
+  args: $ReadOnlyArray<NormalizationArgument | ReaderArgument>,
+  variables: Variables,
+): Arguments {
+  const values = {};
+  args.forEach(arg => {
+    values[arg.name] = getArgumentValue(arg, variables);
+  });
+  return values;
+}
+
+/**
+ * Given a handle field and variable values, returns a key that can be used to
+ * uniquely identify the combination of the handle name and argument values.
+ *
+ * Note: the word "storage" here refers to the fact this key is primarily used
+ * when writing the results of a key in a normalized graph or "store". This
+ * name was used in previous implementations of Relay internals and is also
+ * used here for consistency.
+ */
+function getHandleStorageKey(
+  handleField: NormalizationHandle,
+  variables: Variables,
+): string {
+  const {dynamicKey, handle, key, name, args, filters} = handleField;
+  const handleName = getRelayHandleKey(handle, key, name);
+  let filterArgs = null;
+  if (args && filters && args.length !== 0 && filters.length !== 0) {
+    filterArgs = args.filter(arg => filters.indexOf(arg.name) > -1);
+  }
+  if (dynamicKey) {
+    // "Sort" the arguments by argument name: this is done by the compiler for
+    // user-supplied arguments but the dynamic argument must also be in sorted
+    // order.  Note that dynamic key argument name is double-underscore-
+    // -prefixed, and a double-underscore prefix is disallowed for user-supplied
+    // argument names, so there's no need to actually sort.
+    filterArgs =
+      filterArgs != null ? [dynamicKey, ...filterArgs] : [dynamicKey];
+  }
+  if (filterArgs === null) {
+    return handleName;
+  } else {
+    return formatStorageKey(
+      handleName,
+      getArgumentValues(filterArgs, variables),
+    );
+  }
+}
+
+/**
+ * Given a field and variable values, returns a key that can be used to
+ * uniquely identify the combination of the field name and argument values.
+ *
+ * Note: the word "storage" here refers to the fact this key is primarily used
+ * when writing the results of a key in a normalized graph or "store". This
+ * name was used in previous implementations of Relay internals and is also
+ * used here for consistency.
+ */
+function getStorageKey(
+  field: NormalizationField | NormalizationHandle | ReaderField,
+  variables: Variables,
+): string {
+  if (field.storageKey) {
+    // TODO T23663664: Handle nodes do not yet define a static storageKey.
+    return (field: $FlowFixMe).storageKey;
+  }
+  const {args, name} = field;
+  return args && args.length !== 0
+    ? formatStorageKey(name, getArgumentValues(args, variables))
+    : name;
+}
+
+/**
+ * Given a `name` (eg. "foo") and an object representing argument values
+ * (eg. `{orberBy: "name", first: 10}`) returns a unique storage key
+ * (ie. `foo{"first":10,"orderBy":"name"}`).
+ *
+ * This differs from getStorageKey which requires a ConcreteNode where arguments
+ * are assumed to already be sorted into a stable order.
+ */
+function getStableStorageKey(name: string, args: ?Arguments): string {
+  return formatStorageKey(name, stableCopy(args));
+}
+
+/**
+ * Given a name and argument values, format a storage key.
+ *
+ * Arguments and the values within them are expected to be ordered in a stable
+ * alphabetical ordering.
+ */
+function formatStorageKey(name: string, argValues: ?Arguments): string {
+  if (!argValues) {
+    return name;
+  }
+  const values = [];
+  for (const argName in argValues) {
+    if (argValues.hasOwnProperty(argName)) {
+      const value = argValues[argName];
+      if (value != null) {
+        values.push(argName + ':' + (JSON.stringify(value) ?? 'undefined'));
+      }
+    }
+  }
+  return values.length === 0 ? name : name + `(${values.join(',')})`;
+}
+
+/**
+ * Given Variables and a variable name, return a variable value with
+ * all values in a stable order.
+ */
+function getStableVariableValue(name: string, variables: Variables): mixed {
+  invariant(
+    variables.hasOwnProperty(name),
+    'getVariableValue(): Undefined variable `%s`.',
+    name,
+  );
+  return stableCopy(variables[name]);
+}
+
+function getModuleComponentKey(documentName: string): string {
+  return `${MODULE_COMPONENT_KEY_PREFIX}${documentName}`;
+}
+
+function getModuleOperationKey(documentName: string): string {
+  return `${MODULE_OPERATION_KEY_PREFIX}${documentName}`;
+}
+
+/**
+ * Constants shared by all implementations of RecordSource/MutableRecordSource/etc.
+ */
+const RelayStoreUtils = {
+  FRAGMENTS_KEY: '__fragments',
+  FRAGMENT_OWNER_KEY: '__fragmentOwner',
+  FRAGMENT_PROP_NAME_KEY: '__fragmentPropName',
+  MODULE_COMPONENT_KEY: '__module_component', // alias returned by Reader
+  ID_KEY: '__id',
+  REF_KEY: '__ref',
+  REFS_KEY: '__refs',
+  ROOT_ID: 'client:root',
+  ROOT_TYPE: '__Root',
+  TYPENAME_KEY: '__typename',
+  INVALIDATED_AT_KEY: '__invalidated_at',
+  IS_WITHIN_UNMATCHED_TYPE_REFINEMENT: '__isWithinUnmatchedTypeRefinement',
+
+  formatStorageKey,
+  getArgumentValue,
+  getArgumentValues,
+  getHandleStorageKey,
+  getStorageKey,
+  getStableStorageKey,
+  getModuleComponentKey,
+  getModuleOperationKey,
+};
+
+module.exports = RelayStoreUtils;

package/store/StoreInspector.js.flow

@@ -0,0 +1,171 @@
+/**
+ * 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';
+
+import type {IEnvironment, RecordSource} from '../store/RelayStoreTypes';
+
+type InspectFn = (environment: IEnvironment, dataID?: ?string) => mixed;
+
+let inspect: InspectFn = () => {};
+
+if (__DEV__) {
+  let formattersInstalled = false;
+
+  /**
+   * Installs a Chrome Developer Tools custom formatter for Relay proxy objects
+   * returned by StoreInspector.inspect.
+   *
+   * bit.ly/object-formatters
+   */
+  const installDevtoolFormatters = () => {
+    if (formattersInstalled) {
+      return;
+    }
+    formattersInstalled = true;
+    if (window.devtoolsFormatters == null) {
+      window.devtoolsFormatters = [];
+    }
+    if (!Array.isArray(window.devtoolsFormatters)) {
+      return;
+    }
+    // eslint-disable-next-line no-console
+    console.info(
+      'Make sure to select "Enable custom formatters" in the Chrome ' +
+        'Developer Tools settings, tab "Preferences" under the "Console" ' +
+        'section.',
+    );
+    window.devtoolsFormatters.push(...createFormatters());
+  };
+
+  const createFormatters = () => {
+    const listStyle = {
+      style:
+        'list-style-type: none; padding: 0; margin: 0 0 0 12px; font-style: normal',
+    };
+    const keyStyle = {style: 'rgb(136, 19, 145)'};
+    const nullStyle = {style: 'color: #777'};
+
+    const reference = (object, config) => {
+      return object == null
+        ? ['span', nullStyle, 'undefined']
+        : ['object', {object, config}];
+    };
+
+    const renderRecordHeader = record => {
+      return [
+        'span',
+        {style: 'font-style: italic'},
+        record.__typename,
+        ['span', nullStyle, ' {id: "', record.__id, '", …}'],
+      ];
+    };
+
+    const isRecord = o => o != null && typeof o.__id === 'string';
+
+    class RecordEntry {
+      +key: string;
+      +value: mixed;
+      constructor(key: string, value: mixed) {
+        this.key = key;
+        this.value = value;
+      }
+    }
+
+    const renderRecordEntries = record => {
+      const children = Object.keys(record).map(key => {
+        return [
+          'li',
+          {},
+          ['object', {object: new RecordEntry(key, record[key])}],
+        ];
+      });
+      return ['ol', listStyle, ...children];
+    };
+
+    const recordFormatter = {
+      header(obj) {
+        if (!isRecord(obj)) {
+          return null;
+        }
+        return renderRecordHeader(obj);
+      },
+      hasBody(obj) {
+        return true;
+      },
+      body(obj) {
+        return renderRecordEntries(obj);
+      },
+    };
+
+    const recordEntryFormatter = {
+      header(obj) {
+        if (obj instanceof RecordEntry) {
+          const value = isRecord(obj.value)
+            ? renderRecordHeader(obj.value)
+            : reference(obj.value);
+          return ['span', keyStyle, obj.key, ': ', value];
+        }
+        return null;
+      },
+      hasBody(obj) {
+        return isRecord(obj.value);
+      },
+      body(obj) {
+        return renderRecordEntries(obj.value);
+      },
+    };
+
+    return [recordFormatter, recordEntryFormatter];
+  };
+
+  const getWrappedRecord = (source: RecordSource, dataID: string) => {
+    const record = source.get(dataID);
+    if (record == null) {
+      return record;
+    }
+    return new Proxy(
+      {...record},
+      {
+        get(target, prop) {
+          const value = target[prop];
+          if (value == null) {
+            return value;
+          }
+          if (typeof value === 'object') {
+            if (typeof value.__ref === 'string') {
+              return getWrappedRecord(source, value.__ref);
+            }
+            if (Array.isArray(value.__refs)) {
+              // $FlowFixMe[incompatible-call]
+              return value.__refs.map(ref => getWrappedRecord(source, ref));
+            }
+          }
+          return value;
+        },
+      },
+    );
+  };
+
+  inspect = (environment: IEnvironment, dataID: ?string) => {
+    installDevtoolFormatters();
+    return getWrappedRecord(
+      environment.getStore().getSource(),
+      dataID ?? 'client:root',
+    );
+  };
+}
+
+module.exports = {
+  inspect,
+};

package/store/TypeID.js.flow

@@ -0,0 +1,28 @@
+/**
+ * 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';
+
+import type {DataID} from '../util/RelayRuntimeTypes';
+
+const PREFIX = 'client:__type:';
+const TYPE_SCHEMA_TYPE = '__TypeSchema';
+
+function generateTypeID(typeName: string): DataID {
+  return PREFIX + typeName;
+}
+
+function isTypeID(id: DataID): boolean {
+  return id.indexOf(PREFIX) === 0;
+}
+
+module.exports = {generateTypeID, isTypeID, TYPE_SCHEMA_TYPE};

package/store/ViewerPattern.js.flow

@@ -0,0 +1,26 @@
+/**
+ * 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 {generateClientID} = require('./ClientID');
+const {ROOT_ID} = require('./RelayStoreUtils');
+
+import type {DataID} from 'relay-runtime/util/RelayRuntimeTypes';
+
+const VIEWER_ID: DataID = generateClientID(ROOT_ID, 'viewer');
+const VIEWER_TYPE = 'Viewer';
+
+module.exports = {
+  VIEWER_ID,
+  VIEWER_TYPE,
+};

package/store/cloneRelayHandleSourceField.js.flow

@@ -0,0 +1,66 @@
+/**
+ * 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 areEqual = require('areEqual');
+const invariant = require('invariant');
+
+const {LINKED_FIELD} = require('../util/RelayConcreteNode');
+const {getHandleStorageKey} = require('./RelayStoreUtils');
+
+import type {
+  NormalizationLinkedField,
+  NormalizationSelection,
+} from '../util/NormalizationNode';
+import type {NormalizationLinkedHandle} from '../util/NormalizationNode';
+import type {Variables} from '../util/RelayRuntimeTypes';
+
+/**
+ * @private
+ *
+ * Creates a clone of the supplied `handleField` by finding the original linked
+ * field (on which the handle was declared) among the sibling `selections`, and
+ * copying its selections into the clone.
+ */
+function cloneRelayHandleSourceField(
+  handleField: NormalizationLinkedHandle,
+  selections: $ReadOnlyArray<NormalizationSelection>,
+  variables: Variables,
+): NormalizationLinkedField {
+  const sourceField = selections.find(
+    source =>
+      source.kind === LINKED_FIELD &&
+      source.name === handleField.name &&
+      source.alias === handleField.alias &&
+      areEqual(source.args, handleField.args),
+  );
+  invariant(
+    sourceField && sourceField.kind === LINKED_FIELD,
+    'cloneRelayHandleSourceField: Expected a corresponding source field for ' +
+      'handle `%s`.',
+    handleField.handle,
+  );
+  const handleKey = getHandleStorageKey(handleField, variables);
+  return {
+    kind: 'LinkedField',
+    alias: sourceField.alias,
+    name: handleKey,
+    storageKey: handleKey,
+    args: null,
+    concreteType: sourceField.concreteType,
+    plural: sourceField.plural,
+    selections: sourceField.selections,
+  };
+}
+
+module.exports = cloneRelayHandleSourceField;

package/store/cloneRelayScalarHandleSourceField.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.
+ *
+ * @flow strict-local
+ * @format
+ */
+
+// flowlint ambiguous-object-type:error
+
+'use strict';
+
+const areEqual = require('areEqual');
+const invariant = require('invariant');
+
+const {SCALAR_FIELD} = require('../util/RelayConcreteNode');
+const {getHandleStorageKey} = require('./RelayStoreUtils');
+
+import type {
+  NormalizationScalarField,
+  NormalizationSelection,
+} from '../util/NormalizationNode';
+import type {NormalizationScalarHandle} from '../util/NormalizationNode';
+import type {Variables} from '../util/RelayRuntimeTypes';
+
+/**
+ * @private
+ *
+ * Creates a clone of the supplied `handleField` by finding the original scalar
+ * field (on which the handle was declared) among the sibling `selections`.
+ */
+function cloneRelayScalarHandleSourceField(
+  handleField: NormalizationScalarHandle,
+  selections: $ReadOnlyArray<NormalizationSelection>,
+  variables: Variables,
+): NormalizationScalarField {
+  const sourceField = selections.find(
+    source =>
+      source.kind === SCALAR_FIELD &&
+      source.name === handleField.name &&
+      source.alias === handleField.alias &&
+      areEqual(source.args, handleField.args),
+  );
+  invariant(
+    sourceField && sourceField.kind === SCALAR_FIELD,
+    'cloneRelayScalarHandleSourceField: Expected a corresponding source field for ' +
+      'handle `%s`.',
+    handleField.handle,
+  );
+  const handleKey = getHandleStorageKey(handleField, variables);
+  return {
+    kind: 'ScalarField',
+    alias: sourceField.alias,
+    name: handleKey,
+    storageKey: handleKey,
+    args: null,
+  };
+}
+
+module.exports = cloneRelayScalarHandleSourceField;

package/store/createFragmentSpecResolver.js.flow

@@ -0,0 +1,55 @@
+/**
+ * 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 RelayModernFragmentSpecResolver = require('./RelayModernFragmentSpecResolver');
+
+const warning = require('warning');
+
+import type {
+  FragmentMap,
+  FragmentSpecResolver,
+  Props,
+  RelayContext,
+} from './RelayStoreTypes';
+
+function createFragmentSpecResolver(
+  context: RelayContext,
+  containerName: string,
+  fragments: FragmentMap,
+  props: Props,
+  callback?: () => void,
+): FragmentSpecResolver {
+  if (__DEV__) {
+    const fragmentNames = Object.keys(fragments);
+    fragmentNames.forEach(fragmentName => {
+      const propValue = props[fragmentName];
+      warning(
+        propValue !== undefined,
+        'createFragmentSpecResolver: Expected prop `%s` to be supplied to `%s`, but ' +
+          'got `undefined`. Pass an explicit `null` if this is intentional.',
+        fragmentName,
+        containerName,
+      );
+    });
+  }
+
+  return new RelayModernFragmentSpecResolver(
+    context,
+    fragments,
+    props,
+    callback,
+  );
+}
+
+module.exports = createFragmentSpecResolver;

package/store/createRelayContext.js.flow

@@ -0,0 +1,44 @@
+/**
+ * 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');
+
+import type {RelayContext} from './RelayStoreTypes.js';
+import typeof {createContext} from 'react';
+
+// Ideally, we'd just import the type of the react module, but this causes Flow
+// problems.
+type React = {
+  createContext: createContext<RelayContext | null>,
+  version: string,
+  ...
+};
+
+let relayContext: ?React$Context<RelayContext | null>;
+let firstReact: ?React;
+
+function createRelayContext(react: React): React$Context<RelayContext | null> {
+  if (!relayContext) {
+    relayContext = react.createContext(null);
+    firstReact = react;
+  }
+  invariant(
+    react === firstReact,
+    '[createRelayContext]: You passing a different instance of React',
+    react.version,
+  );
+  return relayContext;
+}
+
+module.exports = createRelayContext;

package/store/defaultGetDataID.js.flow

@@ -0,0 +1,27 @@
+/**
+ * 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 {VIEWER_ID, VIEWER_TYPE} = require('./ViewerPattern');
+
+function defaultGetDataID(
+  fieldValue: {[string]: mixed, ...},
+  typeName: string,
+): mixed {
+  if (typeName === VIEWER_TYPE) {
+    return fieldValue.id == null ? VIEWER_ID : fieldValue.id;
+  }
+  return fieldValue.id;
+}
+
+module.exports = defaultGetDataID;