relay-runtime 11.0.2 → 13.0.0-rc.2

package/store/RelayConcreteVariables.js.flow

@@ -1,5 +1,5 @@
 /**
- * Copyright (c) Facebook, Inc. and its affiliates.
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
  *
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
@@ -12,12 +12,17 @@
 
 'use strict';
 
-const invariant = require('invariant');
-
-import type {NormalizationOperation} from '../util/NormalizationNode';
+import type {
+  NormalizationArgument,
+  NormalizationLocalArgumentDefinition,
+  NormalizationOperation,
+} from '../util/NormalizationNode';
 import type {ReaderFragment} from '../util/ReaderNode';
 import type {Variables} from '../util/RelayRuntimeTypes';
 
+const {getArgumentValues} = require('./RelayStoreUtils');
+const invariant = require('invariant');
+
 /**
  * Determines the variables that are in scope for a fragment given the variables
  * in scope at the root query as well as any arguments applied at the fragment
@@ -35,7 +40,6 @@ function getFragmentVariables(
     if (argumentVariables.hasOwnProperty(definition.name)) {
       return;
     }
-    // $FlowFixMe[cannot-spread-interface]
     variables = variables || {...argumentVariables};
     switch (definition.kind) {
       case 'LocalArgument':
@@ -52,12 +56,9 @@ function getFragmentVariables(
            * RelayStoreUtils.getStableVariableValue() that variable keys are all
            * present.
            */
-          // $FlowFixMe[incompatible-use]
           variables[definition.name] = undefined;
           break;
         }
-        // $FlowFixMe[incompatible-use]
-        // $FlowFixMe[cannot-write]
         variables[definition.name] = rootVariables[definition.name];
         break;
       default:
@@ -86,7 +87,6 @@ function getOperationVariables(
   const operationVariables = {};
   operation.argumentDefinitions.forEach(def => {
     let value = def.defaultValue;
-    // $FlowFixMe[cannot-write]
     if (variables[def.name] != null) {
       value = variables[def.name];
     }
@@ -95,7 +95,26 @@ function getOperationVariables(
   return operationVariables;
 }
 
+function getLocalVariables(
+  currentVariables: Variables,
+  argumentDefinitions: ?$ReadOnlyArray<NormalizationLocalArgumentDefinition>,
+  args: ?$ReadOnlyArray<NormalizationArgument>,
+): Variables {
+  if (argumentDefinitions == null) {
+    return currentVariables;
+  }
+  const nextVariables = {...currentVariables};
+  const nextArgs = args ? getArgumentValues(args, currentVariables) : {};
+  argumentDefinitions.forEach(def => {
+    // $FlowFixMe[cannot-write]
+    const value = nextArgs[def.name] ?? def.defaultValue;
+    nextVariables[def.name] = value;
+  });
+  return nextVariables;
+}
+
 module.exports = {
+  getLocalVariables,
   getFragmentVariables,
   getOperationVariables,
 };

package/store/RelayExperimentalGraphResponseHandler.js.flow

@@ -0,0 +1,121 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and 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
+ * @format
+ */
+
+import type {
+  DataChunk,
+  GraphModeResponse,
+  RecordChunk,
+} from './RelayExperimentalGraphResponseTransform';
+import type {MutableRecordSource, Record} from './RelayStoreTypes';
+
+const RelayModernRecord = require('./RelayModernRecord');
+const invariant = require('invariant');
+
+/**
+ * Given a stream of GraphMode chunks, populate a MutableRecordSource.
+ */
+export function handleGraphModeResponse(
+  recordSource: MutableRecordSource,
+  response: GraphModeResponse,
+): MutableRecordSource {
+  const handler = new GraphModeHandler(recordSource);
+  return handler.populateRecordSource(response);
+}
+
+class GraphModeHandler {
+  _recordSource: MutableRecordSource;
+  _streamIdToCacheKey: Map<number, string>;
+  constructor(recordSource: MutableRecordSource) {
+    this._recordSource = recordSource;
+    this._streamIdToCacheKey = new Map();
+  }
+  populateRecordSource(response: GraphModeResponse): MutableRecordSource {
+    for (const chunk of response) {
+      switch (chunk.$kind) {
+        case 'Record':
+          this._handleRecordChunk(chunk);
+          break;
+        case 'Extend': {
+          const cacheKey = this._lookupCacheKey(chunk.$streamID);
+          const record = this._recordSource.get(cacheKey);
+          invariant(
+            record != null,
+            `Expected to have a record for cache key ${cacheKey}`,
+          );
+          this._populateRecord(record, chunk);
+          break;
+        }
+        case 'Complete':
+          this._streamIdToCacheKey.clear();
+          break;
+        default:
+          (chunk.$kind: empty);
+      }
+    }
+    return this._recordSource;
+  }
+
+  _handleRecordChunk(chunk: RecordChunk) {
+    const cacheKey = chunk.__id;
+    let record = this._recordSource.get(cacheKey);
+    if (record == null) {
+      record = RelayModernRecord.create(cacheKey, chunk.__typename);
+      this._recordSource.set(cacheKey, record);
+    }
+
+    this._streamIdToCacheKey.set(chunk.$streamID, cacheKey);
+    this._populateRecord(record, chunk);
+  }
+
+  _populateRecord(parentRecord: Record, chunk: DataChunk) {
+    for (const [key, value] of Object.entries(chunk)) {
+      switch (key) {
+        case '$streamID':
+        case '$kind':
+        case '__typename':
+          break;
+        default:
+          if (
+            typeof value !== 'object' ||
+            value == null ||
+            Array.isArray(value)
+          ) {
+            RelayModernRecord.setValue(parentRecord, key, value);
+          } else {
+            if (value.hasOwnProperty('__id')) {
+              // Singular
+              const streamID = ((value.__id: any): number);
+              const id = this._lookupCacheKey(streamID);
+              RelayModernRecord.setLinkedRecordID(parentRecord, key, id);
+            } else if (value.hasOwnProperty('__ids')) {
+              // Plural
+              const streamIDs = ((value.__ids: any): Array<number | null>);
+              const ids = streamIDs.map(sID => {
+                return sID == null ? null : this._lookupCacheKey(sID);
+              });
+              RelayModernRecord.setLinkedRecordIDs(parentRecord, key, ids);
+            } else {
+              invariant(false, 'Expected object to have either __id or __ids.');
+            }
+          }
+      }
+    }
+  }
+
+  _lookupCacheKey(streamID: number): string {
+    const cacheKey = this._streamIdToCacheKey.get(streamID);
+    invariant(
+      cacheKey != null,
+      `Expected to have a cacheKey for $streamID ${streamID}`,
+    );
+    return cacheKey;
+  }
+}

package/store/RelayExperimentalGraphResponseTransform.js.flow

@@ -0,0 +1,470 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and 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
+ * @format
+ */
+
+import type {ActorIdentifier} from '../multi-actor-environment/ActorIdentifier';
+import type {PayloadData} from '../network/RelayNetworkTypes';
+import type {
+  NormalizationField,
+  NormalizationLinkedField,
+  NormalizationNode,
+} from '../util/NormalizationNode';
+import type {DataID, Variables} from '../util/RelayRuntimeTypes';
+import type {NormalizationOptions} from './RelayResponseNormalizer';
+import type {GetDataID} from './RelayResponseNormalizer';
+import type {
+  IncrementalDataPlaceholder,
+  NormalizationSelector,
+} from './RelayStoreTypes';
+
+const {
+  CLIENT_EXTENSION,
+  CONDITION,
+  DEFER,
+  FRAGMENT_SPREAD,
+  INLINE_FRAGMENT,
+  LINKED_FIELD,
+  SCALAR_FIELD,
+} = require('../util/RelayConcreteNode');
+const {getLocalVariables} = require('./RelayConcreteVariables');
+const {createNormalizationSelector} = require('./RelayModernSelector');
+const {ROOT_TYPE, TYPENAME_KEY, getStorageKey} = require('./RelayStoreUtils');
+const invariant = require('invariant');
+const {generateClientID} = require('relay-runtime');
+
+/**
+ * This module is an experiment to explore a proposal normalized response format for GraphQL.
+ * See the Quip document: Canonical Normalized Response Format (“GraphMode”) Proposal
+ */
+
+/**
+ * # TODO
+ *
+ * - [ ] Compute storage keys using method outlined in the proposal
+ * - [ ] Plural fields
+ * - [ ] Write a utility to populate the store using a GraphMode response.
+ */
+
+export type ScalarField = string | number | null;
+export type LinkedField =
+  | {
+      __id: number,
+    }
+  | {
+      __ids: Array<number | null>,
+    };
+
+export type ChunkField = ScalarField | Array<ScalarField> | LinkedField;
+
+export type ChunkFields = {
+  [string]: ChunkField,
+};
+
+export type RecordChunk = {
+  $kind: 'Record',
+  $streamID: number,
+  __id: string,
+  __typename: string,
+  [string]: ChunkField,
+};
+
+export type ExtendChunk = {
+  $kind: 'Extend',
+  $streamID: number,
+  [string]: ChunkField,
+};
+
+export type CompleteChunk = {
+  $kind: 'Complete',
+};
+
+export type DataChunk = RecordChunk | ExtendChunk;
+
+export type GraphModeChunk = DataChunk | CompleteChunk;
+
+export type GraphModeResponse = Iterable<GraphModeChunk>;
+
+/**
+ * Converts a JSON response (and Normalization AST) into a stream of GraphMode chunks
+ *
+ * The stream is modeled as a Generator in order to highlight the streaming
+ * nature of the response. Once a chunk is generated, it can be immediately flushed
+ * to the client.
+ *
+ * The response is traversed depth-first, meaning children are emitted before
+ * the parent. This allows parent objects to reference children using their
+ * `$streamID`.
+ *
+ * After each object is traversed, a chunk is emitted. The first time an object
+ * -- identified by its strong ID -- is encountered we emit a `Record`, and its
+ * `$streamID` is recorded. If that same object is encountered again later in
+ * the response, an `Extend` chunk is emitted, which includes any previously
+ * unsent fields. If no unsent fields are present in the second appearance of
+ * the new object, no chunk is emitted.
+ *
+ * ## State
+ *
+ * As we traverse we must maintain some state:
+ *
+ * - The next streamID
+ * - A mapping of cache keys to streamIDs
+ * - The set of fields which we've sent for each streamID. This allows us to
+ *   avoid sending fields twice.
+ */
+export function normalizeResponse(
+  response: PayloadData,
+  selector: NormalizationSelector,
+  options: NormalizationOptions,
+): GraphModeResponse {
+  const {node, variables, dataID} = selector;
+  const normalizer = new GraphModeNormalizer(variables, options);
+  return normalizer.normalizeResponse(node, dataID, response);
+}
+
+class GraphModeNormalizer {
+  _cacheKeyToStreamID: Map<string, number>;
+  _sentFields: Map<string, Set<string>>;
+  _getDataId: GetDataID;
+  _nextStreamID: number;
+  _getDataID: GetDataID;
+  _variables: Variables;
+  _path: Array<string>;
+  _incrementalPlaceholders: Array<IncrementalDataPlaceholder>;
+  _actorIdentifier: ?ActorIdentifier;
+  constructor(variables: Variables, options: NormalizationOptions) {
+    this._actorIdentifier = options.actorIdentifier;
+    this._path = options.path ? [...options.path] : [];
+    this._getDataID = options.getDataID;
+    this._cacheKeyToStreamID = new Map();
+    this._sentFields = new Map();
+    this._nextStreamID = 0;
+    this._variables = variables;
+  }
+
+  _getStreamID() {
+    return this._nextStreamID++;
+  }
+
+  _getSentFields(cacheKey: string): Set<string> {
+    const maybeSent = this._sentFields.get(cacheKey);
+    if (maybeSent != null) {
+      return maybeSent;
+    }
+    const sent = new Set();
+    this._sentFields.set(cacheKey, sent);
+    return sent;
+  }
+
+  _getObjectType(data: PayloadData): string {
+    const typeName = (data: any)[TYPENAME_KEY];
+    invariant(
+      typeName != null,
+      'Expected a typename for record `%s`.',
+      JSON.stringify(data, null, 2),
+    );
+    return typeName;
+  }
+
+  // TODO: The GraphMode proposal outlines different approachs to derive keys. We
+  // can expriment with different approaches here.
+  _getStorageKey(selection: NormalizationField) {
+    return getStorageKey(selection, this._variables);
+  }
+
+  _getVariableValue(name: string): mixed {
+    invariant(
+      this._variables.hasOwnProperty(name),
+      'Unexpected undefined variable `%s`.',
+      name,
+    );
+    return this._variables[name];
+  }
+
+  *normalizeResponse(
+    node: NormalizationNode,
+    dataID: DataID,
+    data: PayloadData,
+  ): Generator<GraphModeChunk, void, void> {
+    const rootFields: ChunkFields = {};
+    yield* this._traverseSelections(node, data, rootFields, dataID, new Set());
+
+    const $streamID = this._getStreamID();
+    yield {
+      ...rootFields,
+      $kind: 'Record',
+      $streamID,
+      __id: dataID,
+      __typename: ROOT_TYPE,
+    };
+    yield {
+      $kind: 'Complete',
+    };
+  }
+
+  *_flushFields(
+    cacheKey: string,
+    typename: string,
+    fields: ChunkFields,
+  ): Generator<GraphModeChunk, number, void> {
+    const maybeStreamID = this._cacheKeyToStreamID.get(cacheKey);
+    const $streamID = maybeStreamID ?? this._getStreamID();
+    if (maybeStreamID == null) {
+      this._cacheKeyToStreamID.set(cacheKey, $streamID);
+      // TODO: We could mutate `fields` rather than constructing a new
+      // chunk object, but it's hard to convince Flow that we've
+      // constructed a valid Chunk, and perf is not important for this
+      // experimental transform
+      yield {
+        ...fields,
+        $kind: 'Record',
+        __typename: typename,
+        __id: cacheKey,
+        $streamID,
+      };
+    } else if (Object.keys(fields).length > 0) {
+      yield {...fields, $kind: 'Extend', $streamID};
+    }
+    return $streamID;
+  }
+
+  *_traverseSelections(
+    node: NormalizationNode,
+    data: PayloadData,
+    parentFields: ChunkFields,
+    parentID: string,
+    sentFields: Set<string>,
+  ): Generator<GraphModeChunk, void, void> {
+    const selections = node.selections;
+
+    for (const selection of selections) {
+      switch (selection.kind) {
+        case LINKED_FIELD: {
+          const responseKey = selection.alias ?? selection.name;
+          const fieldData = ((data[responseKey]: any): PayloadData);
+
+          const storageKey = this._getStorageKey(selection);
+
+          this._path.push(responseKey);
+
+          const fieldValue = yield* this._traverseLinkedField(
+            selection.plural,
+            fieldData,
+            storageKey,
+            selection,
+            parentID,
+          );
+
+          this._path.pop();
+
+          // TODO: We could also opt to confirm that this matches the previously
+          // seen value.
+          if (sentFields.has(storageKey)) {
+            break;
+          }
+
+          parentFields[storageKey] = fieldValue;
+          sentFields.add(storageKey);
+          break;
+        }
+        case SCALAR_FIELD: {
+          const responseKey = selection.alias ?? selection.name;
+
+          const storageKey = this._getStorageKey(selection);
+
+          // TODO: We could also opt to confirm that this matches the previously
+          // seen value.
+          if (sentFields.has(storageKey)) {
+            break;
+          }
+          const fieldData = ((data[responseKey]: any): ChunkField);
+
+          parentFields[storageKey] = fieldData;
+          sentFields.add(storageKey);
+          break;
+        }
+        case INLINE_FRAGMENT: {
+          const objType = this._getObjectType(data);
+          const {abstractKey} = selection;
+          if (abstractKey == null) {
+            if (objType !== selection.type) {
+              break;
+            }
+          } else if (!data.hasOwnProperty(abstractKey)) {
+            break;
+          }
+          yield* this._traverseSelections(
+            selection,
+            data,
+            parentFields,
+            parentID,
+            sentFields,
+          );
+          break;
+        }
+        case FRAGMENT_SPREAD: {
+          const prevVariables = this._variables;
+          this._variables = getLocalVariables(
+            this._variables,
+            selection.fragment.argumentDefinitions,
+            selection.args,
+          );
+          yield* this._traverseSelections(
+            selection.fragment,
+            data,
+            parentFields,
+            parentID,
+            sentFields,
+          );
+          this._variables = prevVariables;
+          break;
+        }
+        case CONDITION:
+          const conditionValue = Boolean(
+            this._getVariableValue(selection.condition),
+          );
+          if (conditionValue === selection.passingValue) {
+            yield* this._traverseSelections(
+              selection,
+              data,
+              parentFields,
+              parentID,
+              sentFields,
+            );
+          }
+          break;
+        case DEFER:
+          const isDeferred =
+            selection.if === null || this._getVariableValue(selection.if);
+          if (isDeferred === false) {
+            // If defer is disabled there will be no additional response chunk:
+            // normalize the data already present.
+            yield* this._traverseSelections(
+              selection,
+              data,
+              parentFields,
+              parentID,
+              sentFields,
+            );
+          } else {
+            // Otherwise data *for this selection* should not be present: enqueue
+            // metadata to process the subsequent response chunk.
+            this._incrementalPlaceholders.push({
+              kind: 'defer',
+              data,
+              label: selection.label,
+              path: [...this._path],
+              selector: createNormalizationSelector(
+                selection,
+                parentID,
+                this._variables,
+              ),
+              typeName: this._getObjectType(data),
+              actorIdentifier: this._actorIdentifier,
+            });
+          }
+          break;
+        case CLIENT_EXTENSION:
+          // Since we are only expecting to handle server responses, we can skip
+          // over client extensions.
+          break;
+        default:
+          throw new Error(`Unexpected selection type: ${selection.kind}`);
+      }
+    }
+  }
+
+  *_traverseLinkedField(
+    plural: boolean,
+    fieldData: PayloadData,
+    storageKey: string,
+    selection: NormalizationLinkedField,
+    parentID: string,
+    index?: number,
+  ): Generator<GraphModeChunk, ChunkField, void> {
+    if (fieldData == null) {
+      return null;
+    }
+
+    if (plural) {
+      invariant(
+        Array.isArray(fieldData),
+        `Expected fieldData to be an array. Got ${JSON.stringify(fieldData)}`,
+      );
+
+      const fieldValue = [];
+      for (const [i, itemData] of fieldData.entries()) {
+        this._path.push(String(i));
+        const itemValue = yield* this._traverseLinkedField(
+          false,
+          itemData,
+          storageKey,
+          selection,
+          parentID,
+          i,
+        );
+        this._path.pop();
+        fieldValue.push(itemValue);
+      }
+
+      const ids = fieldValue.map(value => {
+        if (value == null) {
+          return null;
+        }
+        invariant(
+          typeof value.__id === 'number',
+          'Expected objects in a plural linked field to have an __id.',
+        );
+        return value.__id;
+      });
+
+      return {__ids: ids};
+    }
+
+    invariant(
+      typeof fieldData === 'object',
+      'Expected data for field `%s` to be an object.',
+      storageKey,
+    );
+
+    const objType = selection.concreteType ?? this._getObjectType(fieldData);
+
+    const nextID =
+      this._getDataID(fieldData, objType) ||
+      // Note: In RelayResponseNormalizer we try to access a cached
+      // version of the key before generating a new one. I'm not clear if
+      // that's a performance optimization (which would not be important
+      // here) or important for stable ids.
+
+      // TODO: The proposal does not yet specify how we handle objects
+      // without strong ids.
+      generateClientID(parentID, storageKey, index);
+
+    invariant(
+      typeof nextID === 'string',
+      'Expected id on field `%s` to be a string.',
+      storageKey,
+    );
+
+    const fields: ChunkFields = {};
+
+    // Yield any decendent record chunks, and mutatively populate direct fields.
+    yield* this._traverseSelections(
+      selection,
+      fieldData,
+      fields,
+      nextID,
+      this._getSentFields(nextID),
+    );
+
+    const $streamID = yield* this._flushFields(nextID, objType, fields);
+
+    return {__id: $streamID};
+  }
+}