Transforms for normalizing stitched subschema deprecations

packages/stitch/src/index.ts

@@ -1,2 +1,4 @@
 export { stitchSchemas } from './stitchSchemas';
 export { forwardArgsToSelectionSet } from './selectionSetArgs';
+export { default as RemoveFieldDirectives } from './transforms/RemoveFieldDirectives';
+export { default as RemoveFieldsWithDirective } from './transforms/RemoveFieldsWithDirective';

packages/stitch/src/transforms/RemoveFieldDirectives.ts

@@ -0,0 +1,15 @@
+import { GraphQLSchema, DirectiveNode } from 'graphql';
+import { Transform, matchDirective } from '@graphql-tools/utils';
+import { FilterFieldDirectives } from '@graphql-tools/wrap';
+
+export default class RemoveFieldDirectives implements Transform {
+  private readonly transformer: FilterFieldDirectives;
+
+  constructor(directiveName: string, args: Record<string, any> = {}) {
+    this.transformer = new FilterFieldDirectives((dir: DirectiveNode) => !matchDirective(dir, directiveName, args));
+  }
+
+  public transformSchema(originalSchema: GraphQLSchema): GraphQLSchema {
+    return this.transformer.transformSchema(originalSchema);
+  }
+}

packages/stitch/src/transforms/RemoveFieldsWithDirective.ts

@@ -0,0 +1,19 @@
+import { GraphQLSchema, GraphQLFieldConfig } from 'graphql';
+import { Transform, matchDirective } from '@graphql-tools/utils';
+import { FilterObjectFields } from '@graphql-tools/wrap';
+
+export default class RemoveFieldsWithDirective implements Transform {
+  private readonly transformer: FilterObjectFields;
+
+  constructor(directiveName: string, args: Record<string, any> = {}) {
+    this.transformer = new FilterObjectFields(
+      (_typeName: string, _fieldName: string, fieldConfig: GraphQLFieldConfig<any, any>) => {
+        return !!fieldConfig.astNode.directives.find(dir => matchDirective(dir, directiveName, args));
+      }
+    );
+  }
+
+  public transformSchema(originalSchema: GraphQLSchema): GraphQLSchema {
+    return this.transformer.transformSchema(originalSchema);
+  }
+}

packages/stitch/tests/transformDirectives.test.ts

@@ -0,0 +1,60 @@
+import { makeExecutableSchema } from '@graphql-tools/schema';
+import { stitchSchemas } from '../src/stitchSchemas';
+import { RemoveFieldDirectives, RemoveFieldsWithDirective } from '../src/index';
+
+describe('transform deprecations', () => {
+  test('removes directives with arguments, includes deprecations', async () => {
+    const listingsSchema = makeExecutableSchema({
+      typeDefs: `
+        type Listing {
+          id: ID!
+          description: String!
+          price: Float!
+          sellerId: ID! @deprecated(reason: "stitching use only")
+          buyerId: ID  @deprecated(reason: "stitching use only")
+        }
+      `
+    });
+
+    const usersSchema = makeExecutableSchema({
+      typeDefs: `
+        type User {
+          id: ID!
+          email: String! @deprecated(reason: "other deprecation")
+        }
+        type Listing {
+          seller: User! @deprecated(reason: "gateway access only")
+          buyer: User @deprecated(reason: "gateway access only")
+        }
+      `
+    });
+
+
+
+    const gatewaySchema = stitchSchemas({
+      subschemas: [
+        {
+          schema: listingsSchema,
+          transforms: [new RemoveFieldsWithDirective('deprecated', { reason: 'gateway access only' })]
+        },
+        {
+          schema: usersSchema,
+          transforms: [new RemoveFieldDirectives('deprecated', { reason: 'gateway access only' })]
+        },
+      ],
+    });
+
+    expect(listingsSchema.getType('Listing').getFields().sellerId.deprecationReason).toBe('stitching use only');
+    expect(gatewaySchema.getType('Listing').getFields().sellerId).toBe(undefined);
+
+    expect(usersSchema.getType('Listing').getFields().seller.deprecationReason).toBe('gateway access only');
+    expect(usersSchema.getType('Listing').getFields().seller.astNode.directives.length).toEqual(1);
+    expect(gatewaySchema.getType('Listing').getFields().seller.deprecationReason).toBe(undefined);
+    expect(gatewaySchema.getType('Listing').getFields().seller.astNode.directives.length).toEqual(0);
+
+    expect(usersSchema.getType('User').getFields().email.deprecationReason).toBe('other deprecation');
+    expect(usersSchema.getType('User').getFields().email.astNode.directives.length).toEqual(1);
+    expect(gatewaySchema.getType('User').getFields().email.deprecationReason).toBe('other deprecation');
+    expect(gatewaySchema.getType('User').getFields().email.astNode.directives.length).toEqual(1);
+  });
+});

packages/utils/src/index.ts

@@ -48,3 +48,4 @@ export * from './errors';
 export * from './toConfig';
 export * from './observableToAsyncIterable';
 export * from './visitResult';
+export * from './matchDirective';

packages/utils/src/matchDirective.ts

@@ -0,0 +1,21 @@
+import { DirectiveNode, ArgumentNode } from 'graphql';
+
+export function matchDirective(
+  directive: DirectiveNode,
+  requiredName: string,
+  requiredArgs: Record<string, any> = {}
+): boolean {
+  if (directive.name.value === requiredName) {
+    const requiredArgNames = Object.keys(requiredArgs);
+
+    if (requiredArgNames.length) {
+      const argsMap: Record<string, any> = Object.create(null);
+      directive.arguments.forEach((arg: ArgumentNode) => {
+        argsMap[arg.name.value] = 'value' in arg.value ? arg.value.value : undefined;
+      });
+      return requiredArgNames.every(name => requiredArgs[name] === argsMap[name]);
+    }
+    return true;
+  }
+  return false;
+}

packages/utils/tests/matchDirective.test.ts

@@ -0,0 +1,34 @@
+import { matchDirective } from '../src/matchDirective';
+
+describe('matchDirective', () => {
+  test('matches a directive node based on flexible criteria', () => {
+    const dir = {
+      kind: 'Directive',
+      name: { kind: 'Name', value: 'deprecated' },
+      arguments: [{
+        kind: 'Argument',
+        name: { kind: 'Name', value: 'reason' },
+        value: {
+          kind: 'StringValue',
+          value: 'reason',
+          block: false,
+        }
+      }, {
+        kind: 'Argument',
+        name: { kind: 'Name', value: 'also' },
+        value: {
+          kind: 'StringValue',
+          value: 'also',
+          block: false,
+        }
+      }]
+    };
+
+    expect(matchDirective(dir, 'notthis')).toBe(false);
+    expect(matchDirective(dir, 'deprecated')).toBe(true);
+    expect(matchDirective(dir, 'deprecated', { reason: 'reason' })).toBe(true);
+    expect(matchDirective(dir, 'deprecated', { reason: 'reason', also: 'also' })).toBe(true);
+    expect(matchDirective(dir, 'deprecated', { reason: 'reason', and: 'and' })).toBe(false);
+    expect(matchDirective(dir, 'deprecated', { this: 'this' })).toBe(false);
+  });
+});

packages/wrap/src/transforms/FilterFieldDirectives.ts

@@ -0,0 +1,34 @@
+import { GraphQLSchema, GraphQLFieldConfig, DirectiveNode } from 'graphql';
+import { Transform } from '@graphql-tools/utils';
+import TransformObjectFields from './TransformObjectFields';
+
+export default class FilterFieldDirectives implements Transform {
+  private readonly transformer: TransformObjectFields;
+
+  constructor(filter: (dir: DirectiveNode) => boolean) {
+    this.transformer = new TransformObjectFields(
+      (_typeName: string, _fieldName: string, fieldConfig: GraphQLFieldConfig<any, any>) => {
+        const keepDirectives = fieldConfig.astNode.directives.filter(dir => filter(dir));
+
+        if (keepDirectives.length !== fieldConfig.astNode.directives.length) {
+          fieldConfig = {
+            ...fieldConfig,
+            astNode: {
+              ...fieldConfig.astNode,
+              directives: keepDirectives,
+            },
+          };
+
+          if (fieldConfig.deprecationReason && !keepDirectives.some(dir => dir.name.value === 'deprecated')) {
+            delete fieldConfig.deprecationReason;
+          }
+          return fieldConfig;
+        }
+      }
+    );
+  }
+
+  public transformSchema(originalSchema: GraphQLSchema): GraphQLSchema {
+    return this.transformer.transformSchema(originalSchema);
+  }
+}

packages/wrap/src/transforms/index.ts

@@ -14,6 +14,7 @@ export { default as FilterInterfaceFields } from './FilterInterfaceFields';
 export { default as TransformInputObjectFields } from './TransformInputObjectFields';
 export { default as RenameInputObjectFields } from './RenameInputObjectFields';
 export { default as FilterInputObjectFields } from './FilterInputObjectFields';
+export { default as FilterFieldDirectives } from './FilterFieldDirectives';
 export { default as MapLeafValues } from './MapLeafValues';
 export { default as TransformEnumValues } from './TransformEnumValues';
 export { default as TransformQuery } from './TransformQuery';

website/docs/stitch-type-merging.md

@@ -341,7 +341,7 @@ Some important features to notice in the above schema:
 - Users service `Listing` now _only_ provides `buyer` and `seller` associations without any need for a shared `id`.
 - Users service defines a `ListingRepresentation` input for external keys, and a `_listingsByReps` query that recieves them.
 
-To bring this all together, the gateway orchestrates collecting plain keys from the listing service, and then injecting them as representations of external records into the users service... from which they return as a complete type:
+To bring this all together, the gateway orchestrates collecting plain keys from the listing service, and then injects them as representations of external records into the users service...
 
 ```js
 const gatewaySchema = stitchSchemas({
@@ -373,9 +373,9 @@ const gatewaySchema = stitchSchemas({
 });
 ```
 
-In summary, the gateway had selected `buyerId` and `sellerId` fields from the listings services, sent those keys as input over to the users service, and then recieved back a complete type resolved with multiple fields of any type and selection. Neat!
+To recap, the gateway has selected `buyerId` and `sellerId` fields from the listings services, sent those keys as input over to the users service, and then recieved back a complete type resolved with multiple fields of any type and selection. Neat!
 
-However, you may notice that both `sellerId` and `buyerId` keys are _always_ requested from the listing service, even though they are only needed when resolving their respective associations. If we were sensitive to costs associated with keys, then we could judiciously select only the keys needed for the query with a field-level selectionSet mapping:
+However, you may notice that both `buyerId` and `sellerId` keys are _always_ requested from the listing service, even though they are only needed when resolving their respective associations. If we were sensitive to costs associated with keys, then we could judiciously select only the keys needed for the query with a field-level selectionSet mapping:
 
 ```js
 {
@@ -394,7 +394,52 @@ However, you may notice that both `sellerId` and `buyerId` keys are _always_ req
 }
 ```
 
-One minor disadvantage of this pattern is that the listings service includes ugly `sellerId` and `buyerId` fields. There's no harm in marking these IDs as `@deprecated`, or they may be removed completely from the gateway schema using a [transform](/docs/stitch-combining-schemas#adding-transforms).
+One disadvantage of this pattern is that we end up with clutter—`buyerId`/`sellerId` are extra fields, and `buyer`/`seller` fields have gateway dependencies. To tidy things up, we can aggressively deprecate these fields in subschemas and then remove/normalize their behavior in the gateway using available transforms:
+
+```js
+import { RemoveFieldsWithDirective, RemoveFieldDirectives } from '@graphql-tools/stitch';
+
+const listingsSchema = makeExecutableSchema({
+  typeDefs: `
+    type Listing {
+      id: ID!
+      description: String!
+      price: Float!
+      sellerId: ID! @deprecated(reason: "stitching use only")
+      buyerId: ID  @deprecated(reason: "stitching use only")
+    }
+  `
+});
+
+const usersSchema = makeExecutableSchema({
+  typeDefs: `
+    type User {
+      id: ID!
+      email: String!
+    }
+
+    type Listing {
+      seller: User! @deprecated(reason: "gateway access only")
+      buyer: User @deprecated(reason: "gateway access only")
+    }
+  `
+});
+
+const gatewaySchema = stitchSchemas({
+  subschemas: [
+    {
+      schema: listingsSchema,
+      transforms: [new RemoveFieldsWithDirective('deprecated', { reason: 'stitching use only' })],
+      merge: { ... }
+    },
+    {
+      schema: usersSchema,
+      transforms: [new RemoveFieldDirectives('deprecated', { reason: 'gateway access only' })],
+      merge: { ... }
+    },
+  ],
+});
+```
 
 ### Federation services