[deploy_website] enhance(stitch) canonical merged type/field definitions

.changeset/quick-masks-hang.md

@@ -0,0 +1,9 @@
+---
+"@graphql-tools/delegate": patch
+"@graphql-tools/merge": patch
+"@graphql-tools/stitch": minor
+"@graphql-tools/stitching-directives": minor
+"@graphql-tools/website": patch
+---
+
+enhance(stitch) canonical merged type and field definitions. Use the @canonical directive to promote preferred type and field descriptions into the combined gateway schema.

packages/delegate/src/types.ts

@@ -172,9 +172,10 @@ export interface SubschemaConfig<K = any, V = any, C = K> {
 
 export interface MergedTypeConfig<K = any, V = any> extends MergedTypeResolverOptions<K, V> {
   selectionSet?: string;
-  fields?: Record<string, { selectionSet?: string }>;
+  fields?: Record<string, { selectionSet?: string; canonical?: boolean }>;
   computedFields?: Record<string, { selectionSet?: string }>;
   key?: (originalResult: any) => K;
+  canonical?: boolean;
   resolve?: MergedTypeResolver;
 }
 

packages/merge/src/typedefs-mergers/enum.ts

@@ -18,7 +18,7 @@ export function mergeEnum(
           : 'EnumTypeExtension',
       loc: e1.loc,
       directives: mergeDirectives(e1.directives, e2.directives, config),
-      values: mergeEnumValues(e1.values, e2.values, config),
+      values: mergeEnumValues(e2.values, e1.values, config),
     } as any;
   }
 

packages/stitch/src/mergeCandidates.ts

@@ -10,8 +10,10 @@ import {
   isUnionType,
   isEnumType,
   isInputObjectType,
+  GraphQLFieldConfig,
   GraphQLFieldConfigMap,
   GraphQLInputObjectType,
+  GraphQLInputFieldConfig,
   GraphQLInputFieldConfigMap,
   ObjectTypeDefinitionNode,
   InputObjectTypeDefinitionNode,
@@ -33,8 +35,10 @@ import {
   TypeMergingOptions,
   MergeFieldConfigCandidate,
   MergeInputFieldConfigCandidate,
+  MergeEnumValueConfigCandidate,
 } from './types';
 import { fieldToFieldConfig, inputFieldToFieldConfig } from '@graphql-tools/utils';
+import { isSubschemaConfig } from '@graphql-tools/delegate';
 
 export function mergeCandidates(
   typeName: string,
@@ -68,6 +72,8 @@ function mergeObjectTypeCandidates(
   candidates: Array<MergeTypeCandidate>,
   typeMergingOptions: TypeMergingOptions
 ): GraphQLObjectType<any, any> {
+  candidates = orderedTypeCandidates(candidates, typeMergingOptions);
+
   const description = mergeTypeDescriptions(candidates, typeMergingOptions);
   const fields = fieldConfigMapFromTypeCandidates(candidates, typeMergingOptions);
   const typeConfigs = candidates.map(candidate => (candidate.type as GraphQLObjectType).toConfig());
@@ -84,6 +90,17 @@ function mergeObjectTypeCandidates(
   const interfaces = Object.keys(interfaceMap).map(interfaceName => interfaceMap[interfaceName]);
 
   const astNodes = pluck<ObjectTypeDefinitionNode>('astNode', candidates);
+  const fieldAstNodes = canonicalFieldNamesForType(candidates)
+    .map(fieldName => fields[fieldName]?.astNode)
+    .filter(n => n != null);
+
+  if (astNodes.length > 1 && fieldAstNodes.length) {
+    astNodes.push({
+      ...astNodes[astNodes.length - 1],
+      fields: JSON.parse(JSON.stringify(fieldAstNodes)),
+    });
+  }
+
   const astNode = astNodes
     .slice(1)
     .reduce(
@@ -113,10 +130,23 @@ function mergeInputObjectTypeCandidates(
   candidates: Array<MergeTypeCandidate>,
   typeMergingOptions: TypeMergingOptions
 ): GraphQLInputObjectType {
+  candidates = orderedTypeCandidates(candidates, typeMergingOptions);
+
   const description = mergeTypeDescriptions(candidates, typeMergingOptions);
   const fields = inputFieldConfigMapFromTypeCandidates(candidates, typeMergingOptions);
 
   const astNodes = pluck<InputObjectTypeDefinitionNode>('astNode', candidates);
+  const fieldAstNodes = canonicalFieldNamesForType(candidates)
+    .map(fieldName => fields[fieldName]?.astNode)
+    .filter(n => n != null);
+
+  if (astNodes.length > 1 && fieldAstNodes.length) {
+    astNodes.push({
+      ...astNodes[astNodes.length - 1],
+      fields: JSON.parse(JSON.stringify(fieldAstNodes)),
+    });
+  }
+
   const astNode = astNodes
     .slice(1)
     .reduce(
@@ -149,6 +179,8 @@ function mergeInterfaceTypeCandidates(
   candidates: Array<MergeTypeCandidate>,
   typeMergingOptions: TypeMergingOptions
 ): GraphQLInterfaceType {
+  candidates = orderedTypeCandidates(candidates, typeMergingOptions);
+
   const description = mergeTypeDescriptions(candidates, typeMergingOptions);
   const fields = fieldConfigMapFromTypeCandidates(candidates, typeMergingOptions);
   const typeConfigs = candidates.map(candidate => (candidate.type as GraphQLInterfaceType).toConfig());
@@ -165,6 +197,17 @@ function mergeInterfaceTypeCandidates(
   const interfaces = Object.keys(interfaceMap).map(interfaceName => interfaceMap[interfaceName]);
 
   const astNodes = pluck<InterfaceTypeDefinitionNode>('astNode', candidates);
+  const fieldAstNodes = canonicalFieldNamesForType(candidates)
+    .map(fieldName => fields[fieldName]?.astNode)
+    .filter(n => n != null);
+
+  if (astNodes.length > 1 && fieldAstNodes.length) {
+    astNodes.push({
+      ...astNodes[astNodes.length - 1],
+      fields: JSON.parse(JSON.stringify(fieldAstNodes)),
+    });
+  }
+
   const astNode = astNodes
     .slice(1)
     .reduce(
@@ -194,6 +237,7 @@ function mergeUnionTypeCandidates(
   candidates: Array<MergeTypeCandidate>,
   typeMergingOptions: TypeMergingOptions
 ): GraphQLUnionType {
+  candidates = orderedTypeCandidates(candidates, typeMergingOptions);
   const description = mergeTypeDescriptions(candidates, typeMergingOptions);
 
   const typeConfigs = candidates.map(candidate => (candidate.type as GraphQLUnionType).toConfig());
@@ -234,16 +278,10 @@ function mergeEnumTypeCandidates(
   candidates: Array<MergeTypeCandidate>,
   typeMergingOptions: TypeMergingOptions
 ): GraphQLEnumType {
-  const description = mergeTypeDescriptions(candidates, typeMergingOptions);
+  candidates = orderedTypeCandidates(candidates, typeMergingOptions);
 
-  const typeConfigs = candidates.map(candidate => (candidate.type as GraphQLEnumType).toConfig());
-  const values = typeConfigs.reduce<GraphQLEnumValueConfigMap>(
-    (acc, typeConfig) => ({
-      ...acc,
-      ...typeConfig.values,
-    }),
-    {}
-  );
+  const description = mergeTypeDescriptions(candidates, typeMergingOptions);
+  const values = enumValueConfigMapFromTypeCandidates(candidates, typeMergingOptions);
 
   const astNodes = pluck<EnumTypeDefinitionNode>('astNode', candidates);
   const astNode = astNodes
@@ -266,13 +304,56 @@ function mergeEnumTypeCandidates(
   return new GraphQLEnumType(typeConfig);
 }
 
+function enumValueConfigMapFromTypeCandidates(
+  candidates: Array<MergeTypeCandidate>,
+  typeMergingOptions: TypeMergingOptions
+): GraphQLEnumValueConfigMap {
+  const enumValueConfigCandidatesMap: Record<string, Array<MergeEnumValueConfigCandidate>> = Object.create(null);
+
+  candidates.forEach(candidate => {
+    const valueMap = (candidate.type as GraphQLEnumType).toConfig().values;
+    Object.keys(valueMap).forEach(enumValue => {
+      const enumValueConfigCandidate = {
+        enumValueConfig: valueMap[enumValue],
+        enumValue,
+        type: candidate.type as GraphQLEnumType,
+        subschema: candidate.subschema,
+        transformedSubschema: candidate.transformedSubschema,
+      };
+
+      if (enumValue in enumValueConfigCandidatesMap) {
+        enumValueConfigCandidatesMap[enumValue].push(enumValueConfigCandidate);
+      } else {
+        enumValueConfigCandidatesMap[enumValue] = [enumValueConfigCandidate];
+      }
+    });
+  });
+
+  const enumValueConfigMap = Object.create(null);
+
+  Object.keys(enumValueConfigCandidatesMap).forEach(enumValue => {
+    const enumValueConfigMerger = typeMergingOptions?.enumValueConfigMerger ?? defaultEnumValueConfigMerger;
+    enumValueConfigMap[enumValue] = enumValueConfigMerger(enumValueConfigCandidatesMap[enumValue]);
+  });
+
+  return enumValueConfigMap;
+}
+
+function defaultEnumValueConfigMerger(candidates: Array<MergeEnumValueConfigCandidate>) {
+  const preferred = candidates.find(
+    ({ type, subschema }) => isSubschemaConfig(subschema) && subschema.merge?.[type.name]?.canonical
+  );
+  return (preferred || candidates[candidates.length - 1]).enumValueConfig;
+}
+
 function mergeScalarTypeCandidates(
   typeName: string,
   candidates: Array<MergeTypeCandidate>,
   typeMergingOptions: TypeMergingOptions
 ): GraphQLScalarType {
-  const description = mergeTypeDescriptions(candidates, typeMergingOptions);
+  candidates = orderedTypeCandidates(candidates, typeMergingOptions);
 
+  const description = mergeTypeDescriptions(candidates, typeMergingOptions);
   const serializeFns = pluck<GraphQLScalarSerializer<any>>('serialize', candidates);
   const serialize = serializeFns[serializeFns.length - 1];
 
@@ -285,7 +366,10 @@ function mergeScalarTypeCandidates(
   const astNodes = pluck<ScalarTypeDefinitionNode>('astNode', candidates);
   const astNode = astNodes
     .slice(1)
-    .reduce((acc, astNode) => mergeScalar(acc, astNode), astNodes[0]) as ScalarTypeDefinitionNode;
+    .reduce(
+      (acc, astNode) => mergeScalar(astNode, acc as ScalarTypeDefinitionNode) as ScalarTypeDefinitionNode,
+      astNodes[0]
+    );
 
   const extensionASTNodes = [].concat(pluck<Record<string, any>>('extensionASTNodes', candidates));
 
@@ -305,6 +389,29 @@ function mergeScalarTypeCandidates(
   return new GraphQLScalarType(typeConfig);
 }
 
+function orderedTypeCandidates(
+  candidates: Array<MergeTypeCandidate>,
+  typeMergingOptions: TypeMergingOptions
+): Array<MergeTypeCandidate> {
+  const typeCandidateMerger = typeMergingOptions?.typeCandidateMerger ?? defaultTypeCandidateMerger;
+  const candidate = typeCandidateMerger(candidates);
+  return candidates.filter(c => c !== candidate).concat([candidate]);
+}
+
+function defaultTypeCandidateMerger(candidates: Array<MergeTypeCandidate>): MergeTypeCandidate {
+  const canonical: Array<MergeTypeCandidate> = candidates.filter(({ type, subschema }) =>
+    isSubschemaConfig(subschema) ? subschema.merge?.[type.name]?.canonical : false
+  );
+
+  if (canonical.length > 1) {
+    throw new Error(`Multiple canonical definitions for "${canonical[0].type.name}"`);
+  } else if (canonical.length) {
+    return canonical[0];
+  }
+
+  return candidates[candidates.length - 1];
+}
+
 function mergeTypeDescriptions(candidates: Array<MergeTypeCandidate>, typeMergingOptions: TypeMergingOptions): string {
   const typeDescriptionsMerger = typeMergingOptions?.typeDescriptionsMerger ?? defaultTypeDescriptionMerger;
   return typeDescriptionsMerger(candidates);
@@ -354,6 +461,26 @@ function mergeFieldConfigs(candidates: Array<MergeFieldConfigCandidate>, typeMer
 }
 
 function defaultFieldConfigMerger(candidates: Array<MergeFieldConfigCandidate>) {
+  const canonicalByField: Array<GraphQLFieldConfig<any, any>> = [];
+  const canonicalByType: Array<GraphQLFieldConfig<any, any>> = [];
+
+  candidates.forEach(({ type, fieldName, fieldConfig, subschema }) => {
+    if (!isSubschemaConfig(subschema)) return;
+    if (subschema.merge?.[type.name]?.fields?.[fieldName]?.canonical) {
+      canonicalByField.push(fieldConfig);
+    } else if (subschema.merge?.[type.name]?.canonical) {
+      canonicalByType.push(fieldConfig);
+    }
+  });
+
+  if (canonicalByField.length > 1) {
+    throw new Error(`Multiple canonical definitions for "${candidates[0].type.name}.${candidates[0].fieldName}"`);
+  } else if (canonicalByField.length) {
+    return canonicalByField[0];
+  } else if (canonicalByType.length) {
+    return canonicalByType[0];
+  }
+
   return candidates[candidates.length - 1].fieldConfig;
 }
 
@@ -385,23 +512,49 @@ function inputFieldConfigMapFromTypeCandidates(
   const inputFieldConfigMap = Object.create(null);
 
   Object.keys(inputFieldConfigCandidatesMap).forEach(fieldName => {
-    inputFieldConfigMap[fieldName] = mergeInputFieldConfigs(
-      inputFieldConfigCandidatesMap[fieldName],
-      typeMergingOptions
-    );
+    const inputFieldConfigMerger = typeMergingOptions?.inputFieldConfigMerger ?? defaultInputFieldConfigMerger;
+    inputFieldConfigMap[fieldName] = inputFieldConfigMerger(inputFieldConfigCandidatesMap[fieldName]);
   });
 
   return inputFieldConfigMap;
 }
 
-function mergeInputFieldConfigs(
-  candidates: Array<MergeInputFieldConfigCandidate>,
-  typeMergingOptions: TypeMergingOptions
-) {
-  const inputFieldConfigMerger = typeMergingOptions?.inputFieldConfigMerger ?? defaultInputFieldConfigMerger;
-  return inputFieldConfigMerger(candidates);
-}
-
 function defaultInputFieldConfigMerger(candidates: Array<MergeInputFieldConfigCandidate>) {
+  const canonicalByField: Array<GraphQLInputFieldConfig> = [];
+  const canonicalByType: Array<GraphQLInputFieldConfig> = [];
+
+  candidates.forEach(({ type, fieldName, inputFieldConfig, subschema }) => {
+    if (!isSubschemaConfig(subschema)) return;
+    if (subschema.merge?.[type.name]?.fields?.[fieldName]?.canonical) {
+      canonicalByField.push(inputFieldConfig);
+    } else if (subschema.merge?.[type.name]?.canonical) {
+      canonicalByType.push(inputFieldConfig);
+    }
+  });
+
+  if (canonicalByField.length > 1) {
+    throw new Error(`Multiple canonical definitions for "${candidates[0].type.name}.${candidates[0].fieldName}"`);
+  } else if (canonicalByField.length) {
+    return canonicalByField[0];
+  } else if (canonicalByType.length) {
+    return canonicalByType[0];
+  }
+
   return candidates[candidates.length - 1].inputFieldConfig;
 }
+
+function canonicalFieldNamesForType(candidates: Array<MergeTypeCandidate>): Array<string> {
+  const canonicalFieldNames: Record<string, boolean> = Object.create(null);
+
+  candidates.forEach(({ type, subschema }) => {
+    if (isSubschemaConfig(subschema) && subschema.merge?.[type.name]?.fields && !subschema.merge[type.name].canonical) {
+      Object.entries(subschema.merge[type.name].fields).forEach(([fieldName, mergedFieldConfig]) => {
+        if (mergedFieldConfig.canonical) {
+          canonicalFieldNames[fieldName] = true;
+        }
+      });
+    }
+  });
+
+  return Object.keys(canonicalFieldNames);
+}

packages/stitch/src/types.ts

@@ -8,6 +8,8 @@ import {
   GraphQLInterfaceType,
   GraphQLInputFieldConfig,
   GraphQLInputObjectType,
+  GraphQLEnumValueConfig,
+  GraphQLEnumType,
 } from 'graphql';
 import { ITypeDefinitions, TypeMap } from '@graphql-tools/utils';
 import { MergedTypeResolver, Subschema, SubschemaConfig } from '@graphql-tools/delegate';
@@ -35,6 +37,14 @@ export interface MergeInputFieldConfigCandidate {
   transformedSubschema?: Subschema;
 }
 
+export interface MergeEnumValueConfigCandidate {
+  enumValueConfig: GraphQLEnumValueConfig;
+  enumValue: string;
+  type: GraphQLEnumType;
+  subschema?: GraphQLSchema | SubschemaConfig;
+  transformedSubschema?: Subschema;
+}
+
 export type MergeTypeFilter = (mergeTypeCandidates: Array<MergeTypeCandidate>, typeName: string) => boolean;
 
 export interface MergedTypeInfo {
@@ -70,9 +80,11 @@ export interface IStitchSchemasOptions<TContext = any> extends Omit<IExecutableS
 export type SubschemaConfigTransform = (subschemaConfig: SubschemaConfig) => SubschemaConfig;
 
 export interface TypeMergingOptions {
+  typeCandidateMerger?: (candidates: Array<MergeTypeCandidate>) => MergeTypeCandidate;
   typeDescriptionsMerger?: (candidates: Array<MergeTypeCandidate>) => string;
   fieldConfigMerger?: (candidates: Array<MergeFieldConfigCandidate>) => GraphQLFieldConfig<any, any>;
   inputFieldConfigMerger?: (candidates: Array<MergeInputFieldConfigCandidate>) => GraphQLInputFieldConfig;
+  enumValueConfigMerger?: (candidates: Array<MergeEnumValueConfigCandidate>) => GraphQLEnumValueConfig;
 }
 
 export type OnTypeConflict = (