relay-runtime 9.0.0 → 9.1.0

package/mutations/RelayRecordProxy.js.flow

@@ -0,0 +1,165 @@
+/**
+ * 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 {generateClientID} = require('../store/ClientID');
+const {getStableStorageKey} = require('../store/RelayStoreUtils');
+
+import type {RecordProxy} from '../store/RelayStoreTypes';
+import type {Arguments} from '../store/RelayStoreUtils';
+import type {DataID} from '../util/RelayRuntimeTypes';
+import type RelayRecordSourceMutator from './RelayRecordSourceMutator';
+import type RelayRecordSourceProxy from './RelayRecordSourceProxy';
+
+/**
+ * @internal
+ *
+ * A helper class for manipulating a given record from a record source via an
+ * imperative/OO-style API.
+ */
+class RelayRecordProxy implements RecordProxy {
+  _dataID: DataID;
+  _mutator: RelayRecordSourceMutator;
+  _source: RelayRecordSourceProxy;
+
+  constructor(
+    source: RelayRecordSourceProxy,
+    mutator: RelayRecordSourceMutator,
+    dataID: DataID,
+  ) {
+    this._dataID = dataID;
+    this._mutator = mutator;
+    this._source = source;
+  }
+
+  copyFieldsFrom(source: RecordProxy): void {
+    this._mutator.copyFields(source.getDataID(), this._dataID);
+  }
+
+  getDataID(): DataID {
+    return this._dataID;
+  }
+
+  getType(): string {
+    const type = this._mutator.getType(this._dataID);
+    invariant(
+      type != null,
+      'RelayRecordProxy: Cannot get the type of deleted record `%s`.',
+      this._dataID,
+    );
+    return type;
+  }
+
+  getValue(name: string, args?: ?Arguments): mixed {
+    const storageKey = getStableStorageKey(name, args);
+    return this._mutator.getValue(this._dataID, storageKey);
+  }
+
+  setValue(value: mixed, name: string, args?: ?Arguments): RecordProxy {
+    invariant(
+      isValidLeafValue(value),
+      'RelayRecordProxy#setValue(): Expected a scalar or array of scalars, ' +
+        'got `%s`.',
+      JSON.stringify(value),
+    );
+    const storageKey = getStableStorageKey(name, args);
+    this._mutator.setValue(this._dataID, storageKey, value);
+    return this;
+  }
+
+  getLinkedRecord(name: string, args?: ?Arguments): ?RecordProxy {
+    const storageKey = getStableStorageKey(name, args);
+    const linkedID = this._mutator.getLinkedRecordID(this._dataID, storageKey);
+    return linkedID != null ? this._source.get(linkedID) : linkedID;
+  }
+
+  setLinkedRecord(
+    record: RecordProxy,
+    name: string,
+    args?: ?Arguments,
+  ): RecordProxy {
+    invariant(
+      record instanceof RelayRecordProxy,
+      'RelayRecordProxy#setLinkedRecord(): Expected a record, got `%s`.',
+      record,
+    );
+    const storageKey = getStableStorageKey(name, args);
+    const linkedID = record.getDataID();
+    this._mutator.setLinkedRecordID(this._dataID, storageKey, linkedID);
+    return this;
+  }
+
+  getOrCreateLinkedRecord(
+    name: string,
+    typeName: string,
+    args?: ?Arguments,
+  ): RecordProxy {
+    let linkedRecord = this.getLinkedRecord(name, args);
+    if (!linkedRecord) {
+      const storageKey = getStableStorageKey(name, args);
+      const clientID = generateClientID(this.getDataID(), storageKey);
+      // NOTE: it's possible that a client record for this field exists
+      // but the field itself was unset.
+      linkedRecord =
+        this._source.get(clientID) ?? this._source.create(clientID, typeName);
+      this.setLinkedRecord(linkedRecord, name, args);
+    }
+    return linkedRecord;
+  }
+
+  getLinkedRecords(name: string, args?: ?Arguments): ?Array<?RecordProxy> {
+    const storageKey = getStableStorageKey(name, args);
+    const linkedIDs = this._mutator.getLinkedRecordIDs(
+      this._dataID,
+      storageKey,
+    );
+    if (linkedIDs == null) {
+      return linkedIDs;
+    }
+    return linkedIDs.map(linkedID => {
+      return linkedID != null ? this._source.get(linkedID) : linkedID;
+    });
+  }
+
+  setLinkedRecords(
+    records: Array<?RecordProxy>,
+    name: string,
+    args?: ?Arguments,
+  ): RecordProxy {
+    invariant(
+      Array.isArray(records),
+      'RelayRecordProxy#setLinkedRecords(): Expected records to be an array, got `%s`.',
+      records,
+    );
+    const storageKey = getStableStorageKey(name, args);
+    const linkedIDs = records.map(record => record && record.getDataID());
+    this._mutator.setLinkedRecordIDs(this._dataID, storageKey, linkedIDs);
+    return this;
+  }
+
+  invalidateRecord(): void {
+    this._source.markIDForInvalidation(this._dataID);
+  }
+}
+
+function isValidLeafValue(value: mixed): boolean {
+  return (
+    value == null ||
+    typeof value !== 'object' ||
+    (Array.isArray(value) && value.every(isValidLeafValue))
+  );
+}
+
+module.exports = RelayRecordProxy;

package/mutations/RelayRecordSourceMutator.js.flow

@@ -0,0 +1,238 @@
+/**
+ * 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 RelayModernRecord = require('../store/RelayModernRecord');
+
+const invariant = require('invariant');
+
+const {EXISTENT} = require('../store/RelayRecordState');
+
+import type {RecordState} from '../store/RelayRecordState';
+import type {
+  MutableRecordSource,
+  Record,
+  RecordSource,
+} from '../store/RelayStoreTypes';
+import type {DataID} from '../util/RelayRuntimeTypes';
+
+/**
+ * @internal
+ *
+ * Wrapper API that is an amalgam of the `RelayModernRecord` API and
+ * `MutableRecordSource` interface, implementing copy-on-write semantics for records
+ * in a record source.
+ *
+ * Modifications are applied to fresh copies of records:
+ * - Records in `base` are never modified.
+ * - Modifications cause a fresh version of a record to be created in `sink`.
+ *   These sink records contain only modified fields.
+ */
+class RelayRecordSourceMutator {
+  __sources: Array<RecordSource>;
+  _base: RecordSource;
+  _sink: MutableRecordSource;
+
+  constructor(base: RecordSource, sink: MutableRecordSource) {
+    this.__sources = [sink, base];
+    this._base = base;
+    this._sink = sink;
+  }
+
+  /**
+   * **UNSTABLE**
+   * This method is likely to be removed in an upcoming release
+   * and should not be relied upon.
+   * TODO T41593196: Remove unstable_getRawRecordWithChanges
+   */
+  unstable_getRawRecordWithChanges(dataID: DataID): ?Record {
+    const baseRecord = this._base.get(dataID);
+    const sinkRecord = this._sink.get(dataID);
+    if (sinkRecord === undefined) {
+      if (baseRecord == null) {
+        return baseRecord;
+      }
+      const nextRecord = RelayModernRecord.clone(baseRecord);
+      if (__DEV__) {
+        // Prevent mutation of a record from outside the store.
+        RelayModernRecord.freeze(nextRecord);
+      }
+      return nextRecord;
+    } else if (sinkRecord === null) {
+      return null;
+    } else if (baseRecord != null) {
+      const nextRecord = RelayModernRecord.update(baseRecord, sinkRecord);
+      if (__DEV__) {
+        if (nextRecord !== baseRecord) {
+          // Prevent mutation of a record from outside the store.
+          RelayModernRecord.freeze(nextRecord);
+        }
+      }
+      return nextRecord;
+    } else {
+      const nextRecord = RelayModernRecord.clone(sinkRecord);
+      if (__DEV__) {
+        // Prevent mutation of a record from outside the store.
+        RelayModernRecord.freeze(nextRecord);
+      }
+      return nextRecord;
+    }
+  }
+
+  _getSinkRecord(dataID: DataID): Record {
+    let sinkRecord = this._sink.get(dataID);
+    if (!sinkRecord) {
+      const baseRecord = this._base.get(dataID);
+      invariant(
+        baseRecord,
+        'RelayRecordSourceMutator: Cannot modify non-existent record `%s`.',
+        dataID,
+      );
+      sinkRecord = RelayModernRecord.create(
+        dataID,
+        RelayModernRecord.getType(baseRecord),
+      );
+      this._sink.set(dataID, sinkRecord);
+    }
+    return sinkRecord;
+  }
+
+  copyFields(sourceID: DataID, sinkID: DataID): void {
+    const sinkSource = this._sink.get(sourceID);
+    const baseSource = this._base.get(sourceID);
+    invariant(
+      sinkSource || baseSource,
+      'RelayRecordSourceMutator#copyFields(): Cannot copy fields from ' +
+        'non-existent record `%s`.',
+      sourceID,
+    );
+    const sink = this._getSinkRecord(sinkID);
+    if (baseSource) {
+      RelayModernRecord.copyFields(baseSource, sink);
+    }
+    if (sinkSource) {
+      RelayModernRecord.copyFields(sinkSource, sink);
+    }
+  }
+
+  copyFieldsFromRecord(record: Record, sinkID: DataID): void {
+    const sink = this._getSinkRecord(sinkID);
+    RelayModernRecord.copyFields(record, sink);
+  }
+
+  create(dataID: DataID, typeName: string): void {
+    invariant(
+      this._base.getStatus(dataID) !== EXISTENT &&
+        this._sink.getStatus(dataID) !== EXISTENT,
+      'RelayRecordSourceMutator#create(): Cannot create a record with id ' +
+        '`%s`, this record already exists.',
+      dataID,
+    );
+    const record = RelayModernRecord.create(dataID, typeName);
+    this._sink.set(dataID, record);
+  }
+
+  delete(dataID: DataID): void {
+    this._sink.delete(dataID);
+  }
+
+  getStatus(dataID: DataID): RecordState {
+    return this._sink.has(dataID)
+      ? this._sink.getStatus(dataID)
+      : this._base.getStatus(dataID);
+  }
+
+  getType(dataID: DataID): ?string {
+    for (let ii = 0; ii < this.__sources.length; ii++) {
+      const record = this.__sources[ii].get(dataID);
+      if (record) {
+        return RelayModernRecord.getType(record);
+      } else if (record === null) {
+        return null;
+      }
+    }
+  }
+
+  getValue(dataID: DataID, storageKey: string): mixed {
+    for (let ii = 0; ii < this.__sources.length; ii++) {
+      const record = this.__sources[ii].get(dataID);
+      if (record) {
+        const value = RelayModernRecord.getValue(record, storageKey);
+        if (value !== undefined) {
+          return value;
+        }
+      } else if (record === null) {
+        return null;
+      }
+    }
+  }
+
+  setValue(dataID: DataID, storageKey: string, value: mixed): void {
+    const sinkRecord = this._getSinkRecord(dataID);
+    RelayModernRecord.setValue(sinkRecord, storageKey, value);
+  }
+
+  getLinkedRecordID(dataID: DataID, storageKey: string): ?DataID {
+    for (let ii = 0; ii < this.__sources.length; ii++) {
+      const record = this.__sources[ii].get(dataID);
+      if (record) {
+        const linkedID = RelayModernRecord.getLinkedRecordID(
+          record,
+          storageKey,
+        );
+        if (linkedID !== undefined) {
+          return linkedID;
+        }
+      } else if (record === null) {
+        return null;
+      }
+    }
+  }
+
+  setLinkedRecordID(
+    dataID: DataID,
+    storageKey: string,
+    linkedID: DataID,
+  ): void {
+    const sinkRecord = this._getSinkRecord(dataID);
+    RelayModernRecord.setLinkedRecordID(sinkRecord, storageKey, linkedID);
+  }
+
+  getLinkedRecordIDs(dataID: DataID, storageKey: string): ?Array<?DataID> {
+    for (let ii = 0; ii < this.__sources.length; ii++) {
+      const record = this.__sources[ii].get(dataID);
+      if (record) {
+        const linkedIDs = RelayModernRecord.getLinkedRecordIDs(
+          record,
+          storageKey,
+        );
+        if (linkedIDs !== undefined) {
+          return linkedIDs;
+        }
+      } else if (record === null) {
+        return null;
+      }
+    }
+  }
+
+  setLinkedRecordIDs(
+    dataID: DataID,
+    storageKey: string,
+    linkedIDs: Array<?DataID>,
+  ): void {
+    const sinkRecord = this._getSinkRecord(dataID);
+    RelayModernRecord.setLinkedRecordIDs(sinkRecord, storageKey, linkedIDs);
+  }
+}
+
+module.exports = RelayRecordSourceMutator;

package/mutations/RelayRecordSourceProxy.js.flow

@@ -0,0 +1,164 @@
+/**
+ * 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 RelayModernRecord = require('../store/RelayModernRecord');
+const RelayRecordProxy = require('./RelayRecordProxy');
+
+const invariant = require('invariant');
+
+const {EXISTENT, NONEXISTENT} = require('../store/RelayRecordState');
+const {ROOT_ID, ROOT_TYPE} = require('../store/RelayStoreUtils');
+
+import type {HandlerProvider} from '../handlers/RelayDefaultHandlerProvider';
+import type {GetDataID} from '../store/RelayResponseNormalizer';
+import type {
+  HandleFieldPayload,
+  RecordSource,
+  RecordProxy,
+  RecordSourceProxy,
+} from '../store/RelayStoreTypes';
+import type {DataID} from '../util/RelayRuntimeTypes';
+import type RelayRecordSourceMutator from './RelayRecordSourceMutator';
+
+/**
+ * @internal
+ *
+ * A helper for manipulating a `RecordSource` via an imperative/OO-style API.
+ */
+class RelayRecordSourceProxy implements RecordSourceProxy {
+  _handlerProvider: ?HandlerProvider;
+  __mutator: RelayRecordSourceMutator;
+  _proxies: {[dataID: DataID]: ?RelayRecordProxy, ...};
+  _getDataID: GetDataID;
+  _invalidatedStore: boolean;
+  _idsMarkedForInvalidation: Set<DataID>;
+
+  constructor(
+    mutator: RelayRecordSourceMutator,
+    getDataID: GetDataID,
+    handlerProvider?: ?HandlerProvider,
+  ) {
+    this.__mutator = mutator;
+    this._handlerProvider = handlerProvider || null;
+    this._proxies = {};
+    this._getDataID = getDataID;
+    this._invalidatedStore = false;
+    this._idsMarkedForInvalidation = new Set();
+  }
+
+  publishSource(
+    source: RecordSource,
+    fieldPayloads?: ?Array<HandleFieldPayload>,
+  ): void {
+    const dataIDs = source.getRecordIDs();
+    dataIDs.forEach(dataID => {
+      const status = source.getStatus(dataID);
+      if (status === EXISTENT) {
+        const sourceRecord = source.get(dataID);
+        if (sourceRecord) {
+          if (this.__mutator.getStatus(dataID) !== EXISTENT) {
+            this.create(dataID, RelayModernRecord.getType(sourceRecord));
+          }
+          this.__mutator.copyFieldsFromRecord(sourceRecord, dataID);
+        }
+      } else if (status === NONEXISTENT) {
+        this.delete(dataID);
+      }
+    });
+
+    if (fieldPayloads && fieldPayloads.length) {
+      fieldPayloads.forEach(fieldPayload => {
+        const handler =
+          this._handlerProvider && this._handlerProvider(fieldPayload.handle);
+        invariant(
+          handler,
+          'RelayModernEnvironment: Expected a handler to be provided for handle `%s`.',
+          fieldPayload.handle,
+        );
+        handler.update(this, fieldPayload);
+      });
+    }
+  }
+
+  create(dataID: DataID, typeName: string): RecordProxy {
+    this.__mutator.create(dataID, typeName);
+    delete this._proxies[dataID];
+    const record = this.get(dataID);
+    // For flow
+    invariant(
+      record,
+      'RelayRecordSourceProxy#create(): Expected the created record to exist.',
+    );
+    return record;
+  }
+
+  delete(dataID: DataID): void {
+    invariant(
+      dataID !== ROOT_ID,
+      'RelayRecordSourceProxy#delete(): Cannot delete the root record.',
+    );
+    delete this._proxies[dataID];
+    this.__mutator.delete(dataID);
+  }
+
+  get(dataID: DataID): ?RecordProxy {
+    if (!this._proxies.hasOwnProperty(dataID)) {
+      const status = this.__mutator.getStatus(dataID);
+      if (status === EXISTENT) {
+        this._proxies[dataID] = new RelayRecordProxy(
+          this,
+          this.__mutator,
+          dataID,
+        );
+      } else {
+        this._proxies[dataID] = status === NONEXISTENT ? null : undefined;
+      }
+    }
+    return this._proxies[dataID];
+  }
+
+  getRoot(): RecordProxy {
+    let root = this.get(ROOT_ID);
+    if (!root) {
+      root = this.create(ROOT_ID, ROOT_TYPE);
+    }
+    invariant(
+      root && root.getType() === ROOT_TYPE,
+      'RelayRecordSourceProxy#getRoot(): Expected the source to contain a ' +
+        'root record, %s.',
+      root == null
+        ? 'no root record found'
+        : `found a root record of type \`${root.getType()}\``,
+    );
+    return root;
+  }
+
+  invalidateStore(): void {
+    this._invalidatedStore = true;
+  }
+
+  isStoreMarkedForInvalidation(): boolean {
+    return this._invalidatedStore;
+  }
+
+  markIDForInvalidation(dataID: DataID): void {
+    this._idsMarkedForInvalidation.add(dataID);
+  }
+
+  getIDsMarkedForInvalidation(): Set<DataID> {
+    return this._idsMarkedForInvalidation;
+  }
+}
+
+module.exports = RelayRecordSourceProxy;

package/mutations/RelayRecordSourceSelectorProxy.js.flow

@@ -0,0 +1,119 @@
+/**
+ * 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 {getStorageKey, ROOT_TYPE} = require('../store/RelayStoreUtils');
+
+import type {
+  RecordProxy,
+  RecordSourceProxy,
+  RecordSourceSelectorProxy,
+  SingularReaderSelector,
+} from '../store/RelayStoreTypes';
+import type {ReaderLinkedField} from '../util/ReaderNode';
+import type {DataID} from '../util/RelayRuntimeTypes';
+import type RelayRecordSourceMutator from './RelayRecordSourceMutator';
+
+/**
+ * @internal
+ *
+ * A subclass of RecordSourceProxy that provides convenience methods for
+ * accessing the root fields of a given query/mutation. These fields accept
+ * complex arguments and it can be tedious to re-construct the correct sets of
+ * arguments to pass to e.g. `getRoot().getLinkedRecord()`.
+ */
+class RelayRecordSourceSelectorProxy implements RecordSourceSelectorProxy {
+  __mutator: RelayRecordSourceMutator;
+  __recordSource: RecordSourceProxy;
+  _readSelector: SingularReaderSelector;
+
+  constructor(
+    mutator: RelayRecordSourceMutator,
+    recordSource: RecordSourceProxy,
+    readSelector: SingularReaderSelector,
+  ) {
+    this.__mutator = mutator;
+    this.__recordSource = recordSource;
+    this._readSelector = readSelector;
+  }
+
+  create(dataID: DataID, typeName: string): RecordProxy {
+    return this.__recordSource.create(dataID, typeName);
+  }
+
+  delete(dataID: DataID): void {
+    this.__recordSource.delete(dataID);
+  }
+
+  get(dataID: DataID): ?RecordProxy {
+    return this.__recordSource.get(dataID);
+  }
+
+  getRoot(): RecordProxy {
+    return this.__recordSource.getRoot();
+  }
+
+  getOperationRoot(): RecordProxy {
+    let root = this.__recordSource.get(this._readSelector.dataID);
+    if (!root) {
+      root = this.__recordSource.create(this._readSelector.dataID, ROOT_TYPE);
+    }
+    return root;
+  }
+
+  _getRootField(
+    selector: SingularReaderSelector,
+    fieldName: string,
+    plural: boolean,
+  ): ReaderLinkedField {
+    const field = selector.node.selections.find(
+      selection =>
+        selection.kind === 'LinkedField' && selection.name === fieldName,
+    );
+    invariant(
+      field && field.kind === 'LinkedField',
+      'RelayRecordSourceSelectorProxy#getRootField(): Cannot find root ' +
+        'field `%s`, no such field is defined on GraphQL document `%s`.',
+      fieldName,
+      selector.node.name,
+    );
+    invariant(
+      field.plural === plural,
+      'RelayRecordSourceSelectorProxy#getRootField(): Expected root field ' +
+        '`%s` to be %s.',
+      fieldName,
+      plural ? 'plural' : 'singular',
+    );
+    return field;
+  }
+
+  getRootField(fieldName: string): ?RecordProxy {
+    const field = this._getRootField(this._readSelector, fieldName, false);
+    const storageKey = getStorageKey(field, this._readSelector.variables);
+    return this.getOperationRoot().getLinkedRecord(storageKey);
+  }
+
+  getPluralRootField(fieldName: string): ?Array<?RecordProxy> {
+    const field = this._getRootField(this._readSelector, fieldName, true);
+    const storageKey = getStorageKey(field, this._readSelector.variables);
+    return this.getOperationRoot().getLinkedRecords(storageKey);
+  }
+
+  invalidateStore(): void {
+    this.__recordSource.invalidateStore();
+  }
+}
+
+module.exports = RelayRecordSourceSelectorProxy;