relay-compiler 9.0.0 → 10.1.0

package/transforms/ReactFlightComponentTransform.js.flow

@@ -0,0 +1,195 @@
+/**
+ * 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
+ */
+
+'use strict';
+
+const IRTransformer = require('../core/IRTransformer');
+
+const {createUserError, createCompilerError} = require('../core/CompilerError');
+const {RelayFeatureFlags} = require('relay-runtime');
+
+import type CompilerContext from '../core/CompilerContext';
+import type {ScalarField} from '../core/IR';
+import type {TypeID, InputTypeID, ScalarFieldTypeID} from '../core/Schema';
+
+const FLIGHT_FIELD_COMPONENT_ARGUMENT_TYPE = 'String';
+const FLIGHT_FIELD_COMPONENT_ARGUMENT_NAME = 'component';
+const FLIGHT_FIELD_PROPS_ARGUMENT_NAME = 'props';
+const FLIGHT_FIELD_PROPS_TYPE = 'ReactFlightProps';
+const FLIGHT_FIELD_RETURN_TYPE = 'ReactFlightComponent';
+
+type State = {
+  parentType: TypeID,
+  types: {
+    propsType: InputTypeID,
+    componentType: ScalarFieldTypeID,
+  },
+};
+
+/**
+ * Experimental transform for React Flight.
+ */
+function reactFlightComponentTransform(
+  context: CompilerContext,
+): CompilerContext {
+  const schema = context.getSchema();
+  let propsType = schema.getTypeFromString(FLIGHT_FIELD_PROPS_TYPE);
+  propsType = propsType ? schema.asInputType(propsType) : null;
+  let componentType = schema.getTypeFromString(FLIGHT_FIELD_RETURN_TYPE);
+  componentType = componentType
+    ? schema.asScalarFieldType(componentType)
+    : null;
+  if (
+    !RelayFeatureFlags.ENABLE_REACT_FLIGHT_COMPONENT_FIELD ||
+    propsType == null ||
+    componentType == null
+  ) {
+    return context;
+  }
+  const types = {propsType, componentType};
+  return IRTransformer.transform(
+    context,
+    {
+      ScalarField: visitScalarField,
+      LinkedField: visitLinkedField,
+      InlineFragment: visitInlineFragment,
+    },
+    node => ({
+      parentType: node.type,
+      types,
+    }),
+  );
+}
+
+function visitInlineFragment(fragment, state) {
+  return this.traverse(fragment, {
+    parentType: fragment.typeCondition ?? state.parentType,
+    types: state.types,
+  });
+}
+
+function visitLinkedField(field, state) {
+  return this.traverse(field, {parentType: field.type, types: state.types});
+}
+
+function visitScalarField(field: ScalarField, state: State): ScalarField {
+  // use the return type to quickly determine if this is a flight field
+  const schema = this.getContext().getSchema();
+  if (schema.getRawType(field.type) !== state.types.componentType) {
+    return field;
+  }
+
+  // get the name of the component that provides this field
+  const clientField = schema.getFieldByName(state.parentType, field.name);
+  if (clientField == null) {
+    throw createCompilerError(
+      `Definition not found for field '${schema.getTypeString(
+        state.parentType,
+      )}.${field.name}'`,
+      [field.loc],
+    );
+  }
+  const componentDirective = clientField.directives.find(
+    directive => directive.name === 'react_flight_component',
+  );
+  const componentNameArg = componentDirective?.args.find(
+    arg => arg.name === 'name',
+  );
+  if (
+    componentNameArg == null ||
+    componentNameArg.value.kind !== 'StringValue' ||
+    typeof componentNameArg.value.value !== 'string'
+  ) {
+    throw createUserError(
+      'Invalid Flight field, expected the schema extension to specify ' +
+        "the component's module name with the '@react_flight_component' directive",
+      [field.loc],
+    );
+  }
+  const componentName = componentNameArg.value.value;
+
+  // validate that the parent type has a `flight(component, props)` field
+  const flightField = schema.getFieldByName(state.parentType, 'flight');
+  if (flightField == null) {
+    throw createUserError(
+      `Invalid Flight field, expected the parent type '${schema.getTypeString(
+        state.parentType,
+      )}' ` +
+        "to define a 'flight(component: String, props: ReactFlightProps): ReactFlightComponent' field",
+      [field.loc],
+    );
+  }
+  const componentArg = flightField.args.get(
+    FLIGHT_FIELD_COMPONENT_ARGUMENT_NAME,
+  );
+  const propsArg = flightField.args.get(FLIGHT_FIELD_PROPS_ARGUMENT_NAME);
+  if (
+    componentArg == null ||
+    propsArg == null ||
+    schema.getRawType(componentArg.type) !==
+      schema.getTypeFromString(FLIGHT_FIELD_COMPONENT_ARGUMENT_TYPE) ||
+    schema.getRawType(propsArg.type) !== state.types.propsType ||
+    schema.getRawType(flightField.type) !== state.types.componentType
+  ) {
+    throw createUserError(
+      `Invalid Flight field, expected the parent type '${schema.getTypeString(
+        state.parentType,
+      )}' ` +
+        "to define a 'flight(component: String, props: ReactFlightProps): ReactFlightComponent' field",
+      [field.loc],
+    );
+  }
+
+  return {
+    ...field,
+    name: 'flight',
+    args: [
+      {
+        kind: 'Argument',
+        loc: field.loc,
+        name: FLIGHT_FIELD_COMPONENT_ARGUMENT_NAME,
+        type: schema.getTypeFromString(FLIGHT_FIELD_COMPONENT_ARGUMENT_TYPE),
+        value: {
+          kind: 'Literal',
+          value: componentName,
+          loc: field.loc,
+        },
+      },
+      {
+        kind: 'Argument',
+        loc: field.loc,
+        name: FLIGHT_FIELD_PROPS_ARGUMENT_NAME,
+        type: state.types.propsType,
+        value: {
+          kind: 'ObjectValue',
+          fields: field.args.map(arg => {
+            return {
+              kind: 'ObjectFieldValue',
+              loc: arg.loc,
+              name: arg.name,
+              value: arg.value,
+            };
+          }),
+          loc: field.loc,
+        },
+      },
+    ],
+    metadata: {
+      ...(field.metadata || {}),
+      flight: true,
+    },
+    type: state.types.componentType,
+  };
+}
+
+module.exports = {
+  transform: reactFlightComponentTransform,
+};

package/transforms/RefetchableFragmentTransform.js.flow

@@ -0,0 +1,272 @@
+/**
+ * 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 IRVisitor = require('../core/IRVisitor');
+
+const getLiteralArgumentValues = require('../core/getLiteralArgumentValues');
+const inferRootArgumentDefinitions = require('../core/inferRootArgumentDefinitions');
+
+const {
+  createUserError,
+  eachWithCombinedError,
+} = require('../core/CompilerError');
+const {buildRefetchOperation} = require('./query-generators');
+
+import type CompilerContext from '../core/CompilerContext';
+import type {Argument, Field, Fragment} from '../core/IR';
+import type {Schema} from '../core/Schema';
+import type {ReaderPaginationMetadata} from 'relay-runtime';
+
+const SCHEMA_EXTENSION = `
+  directive @refetchable(
+    queryName: String!
+  ) on FRAGMENT_DEFINITION
+`;
+
+/**
+ * This transform synthesizes "refetch" queries for fragments that
+ * are trivially refetchable. This is comprised of three main stages:
+ *
+ * 1. Validating that fragments marked with @refetchable qualify for
+ *    refetch query generation; mainly this means that the fragment
+ *    type is able to be refetched in some canonical way.
+ * 2. Determining the variable definitions to use for each generated
+ *    query. GraphQL does not have a notion of fragment-local variables
+ *    at all, and although Relay adds this concept developers are still
+ *    allowed to reference global variables. This necessitates a
+ *    visiting all reachable fragments for each @refetchable fragment,
+ *    and finding the union of all global variables expceted to be defined.
+ * 3. Building the refetch queries, a straightforward copying transform from
+ *    Fragment to Root IR nodes.
+ */
+function refetchableFragmentTransform(
+  context: CompilerContext,
+): CompilerContext {
+  const schema = context.getSchema();
+
+  const refetchOperations = buildRefetchMap(context);
+  let nextContext = context;
+  eachWithCombinedError(refetchOperations, ([refetchName, fragment]) => {
+    const {
+      identifierField,
+      path,
+      node,
+      transformedFragment,
+    } = buildRefetchOperation(schema, fragment, refetchName);
+    const connectionMetadata = extractConnectionMetadata(
+      context.getSchema(),
+      transformedFragment,
+    );
+    nextContext = nextContext.replace({
+      ...transformedFragment,
+      metadata: {
+        ...(transformedFragment.metadata || {}),
+        refetch: {
+          connection: connectionMetadata ?? null,
+          operation: refetchName,
+          fragmentPathInResult: path,
+          identifierField,
+        },
+      },
+    });
+    nextContext = nextContext.add({
+      ...node,
+      metadata: {
+        ...(node.metadata || {}),
+        derivedFrom: transformedFragment.name,
+        isRefetchableQuery: true,
+      },
+    });
+  });
+  return nextContext;
+}
+
+/**
+ * Walk the documents of a compiler context and create a mapping of
+ * refetch operation names to the source fragment from which the refetch
+ * operation should be derived.
+ */
+function buildRefetchMap(context: CompilerContext): Map<string, Fragment> {
+  const refetchOperations = new Map();
+  eachWithCombinedError(context.documents(), node => {
+    if (node.kind !== 'Fragment') {
+      return;
+    }
+    const refetchName = getRefetchQueryName(node);
+    if (refetchName === null) {
+      return;
+    }
+    const previousOperation = refetchOperations.get(refetchName);
+    if (previousOperation != null) {
+      throw createUserError(
+        `Duplicate definition for @refetchable operation '${refetchName}' from fragments '${node.name}' and '${previousOperation.name}'`,
+        [node.loc, previousOperation.loc],
+      );
+    }
+    refetchOperations.set(refetchName, node);
+  });
+  const transformed = inferRootArgumentDefinitions(context);
+  return new Map(
+    Array.from(refetchOperations.entries(), ([name, fragment]) => {
+      return [name, transformed.getFragment(fragment.name)];
+    }),
+  );
+}
+
+/**
+ * Validate that any @connection usage is valid for refetching:
+ * - Variables are used for both the "count" and "cursor" arguments
+ *   (after/first or before/last)
+ * - Exactly one connection
+ * - Has a stable path to the connection data
+ *
+ * Returns connection metadata to add to the transformed fragment or undefined
+ * if there is no connection.
+ */
+function extractConnectionMetadata(
+  schema: Schema,
+  fragment: Fragment,
+): ReaderPaginationMetadata | void {
+  const fields = [];
+  let connectionField = null;
+  let path = null;
+  IRVisitor.visit(fragment, {
+    LinkedField: {
+      enter(field) {
+        fields.push(field);
+        if (
+          field.connection === true ||
+          (field.handles &&
+            field.handles.some(handle => handle.name === 'connection'))
+        ) {
+          // Disallow multiple @connections
+          if (connectionField != null) {
+            throw createUserError(
+              `Invalid use of @refetchable with @connection in fragment '${fragment.name}', at most once @connection can appear in a refetchable fragment.`,
+              [field.loc],
+            );
+          }
+          // Disallow connections within plurals
+          const pluralOnPath = fields.find(pathField =>
+            schema.isList(schema.getNullableType(pathField.type)),
+          );
+          if (pluralOnPath) {
+            throw createUserError(
+              `Invalid use of @refetchable with @connection in fragment '${fragment.name}', refetchable connections cannot appear inside plural fields.`,
+              [field.loc, pluralOnPath.loc],
+            );
+          }
+          connectionField = field;
+          path = fields.map(pathField => pathField.alias);
+        }
+      },
+      leave() {
+        fields.pop();
+      },
+    },
+  });
+  if (connectionField == null || path == null) {
+    return;
+  }
+  // Validate arguments: if either of before/last appear they must both appear
+  // and use variables (not scalar values)
+  let backward = null;
+  const before = findArgument(connectionField, 'before');
+  const last = findArgument(connectionField, 'last');
+  if (before || last) {
+    if (
+      !before ||
+      !last ||
+      before.value.kind !== 'Variable' ||
+      last.value.kind !== 'Variable'
+    ) {
+      throw createUserError(
+        `Invalid use of @refetchable with @connection in fragment '${fragment.name}', refetchable connections must use variables for the before and last arguments.`,
+        [
+          connectionField.loc,
+          before && before.value.kind !== 'Variable' ? before.value.loc : null,
+          last && last.value.kind !== 'Variable' ? last.value.loc : null,
+        ].filter(Boolean),
+      );
+    }
+    backward = {
+      count: last.value.variableName,
+      cursor: before.value.variableName,
+    };
+  }
+  // Validate arguments: if either of after/first appear they must both appear
+  // and use variables (not scalar values)
+  let forward = null;
+  const after = findArgument(connectionField, 'after');
+  const first = findArgument(connectionField, 'first');
+  if (after || first) {
+    if (
+      !after ||
+      !first ||
+      after.value.kind !== 'Variable' ||
+      first.value.kind !== 'Variable'
+    ) {
+      throw createUserError(
+        `Invalid use of @refetchable with @connection in fragment '${fragment.name}', refetchable connections must use variables for the after and first arguments.`,
+        [
+          connectionField.loc,
+          after && after.value.kind !== 'Variable' ? after.value.loc : null,
+          first && first.value.kind !== 'Variable' ? first.value.loc : null,
+        ].filter(Boolean),
+      );
+    }
+    forward = {
+      count: first.value.variableName,
+      cursor: after.value.variableName,
+    };
+  }
+  return {forward, backward, path};
+}
+
+function getRefetchQueryName(fragment: Fragment): string | null {
+  const refetchableDirective = fragment.directives.find(
+    directive => directive.name === 'refetchable',
+  );
+  if (refetchableDirective == null) {
+    return null;
+  }
+  const refetchArguments = getLiteralArgumentValues(refetchableDirective.args);
+  const queryName = refetchArguments.queryName;
+  if (queryName == null) {
+    throw createUserError(
+      "Expected the 'queryName' argument of @refetchable to be provided",
+      [refetchableDirective.loc],
+    );
+  } else if (typeof queryName !== 'string') {
+    const queryNameArg = refetchableDirective.args.find(
+      arg => arg.name === 'queryName',
+    );
+    throw createUserError(
+      `Expected the 'queryName' argument of @refetchable to be a string, got '${String(
+        queryName,
+      )}'.`,
+      [queryNameArg?.loc ?? refetchableDirective.loc],
+    );
+  }
+  return queryName;
+}
+
+function findArgument(field: Field, argumentName: string): Argument | null {
+  return field.args.find(arg => arg.name === argumentName) ?? null;
+}
+
+module.exports = {
+  SCHEMA_EXTENSION,
+  transform: refetchableFragmentTransform,
+};

package/transforms/RelayDirectiveTransform.js.flow

@@ -0,0 +1,97 @@
+/**
+ * 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 IRTransformer = require('../core/IRTransformer');
+
+const getLiteralArgumentValues = require('../core/getLiteralArgumentValues');
+const invariant = require('invariant');
+
+import type CompilerContext from '../core/CompilerContext';
+import type {Fragment, FragmentSpread} from '../core/IR';
+
+const RELAY = 'relay';
+const SCHEMA_EXTENSION = `
+directive @relay(
+  # Marks a fragment as being backed by a GraphQLList.
+  plural: Boolean,
+
+  # Marks a fragment spread which should be unmasked if provided false
+  mask: Boolean = true,
+) on FRAGMENT_DEFINITION | FRAGMENT_SPREAD
+`;
+
+/**
+ * A transform that extracts `@relay(plural: Boolean)` directives and converts
+ * them to metadata that can be accessed at runtime.
+ */
+function relayDirectiveTransform(context: CompilerContext): CompilerContext {
+  return IRTransformer.transform(context, {
+    Fragment: visitRelayMetadata(fragmentMetadata),
+    FragmentSpread: visitRelayMetadata(fragmentSpreadMetadata),
+  });
+}
+
+type MixedObj = {[key: string]: mixed, ...};
+function visitRelayMetadata<T: Fragment | FragmentSpread>(
+  metadataFn: MixedObj => MixedObj,
+): T => T {
+  return function(node) {
+    const relayDirective = node.directives.find(({name}) => name === RELAY);
+    if (!relayDirective) {
+      return this.traverse(node);
+    }
+    const argValues = getLiteralArgumentValues(relayDirective.args);
+    const metadata = metadataFn(argValues);
+    return this.traverse({
+      ...node,
+      directives: node.directives.filter(
+        directive => directive !== relayDirective,
+      ),
+      // $FlowFixMe[cannot-spread-indexer]
+      metadata: {
+        ...(node.metadata || {}),
+        ...metadata,
+      },
+    });
+  };
+}
+
+function fragmentMetadata({mask, plural}): MixedObj {
+  invariant(
+    plural === undefined || typeof plural === 'boolean',
+    'RelayDirectiveTransform: Expected the "plural" argument to @relay ' +
+      'to be a boolean literal if specified.',
+  );
+  invariant(
+    mask === undefined || typeof mask === 'boolean',
+    'RelayDirectiveTransform: Expected the "mask" argument to @relay ' +
+      'to be a boolean literal if specified.',
+  );
+  return {mask, plural};
+}
+
+function fragmentSpreadMetadata({mask}): MixedObj {
+  invariant(
+    mask === undefined || typeof mask === 'boolean',
+    'RelayDirectiveTransform: Expected the "mask" argument to @relay ' +
+      'to be a boolean literal if specified.',
+  );
+  return {mask};
+}
+
+module.exports = {
+  RELAY,
+  SCHEMA_EXTENSION,
+  transform: relayDirectiveTransform,
+};