Transforms for normalizing stitched subschema deprecations

[gmac]

Adds package support and a documented approach for handling Federation-style stitching patterns that result in field oddities outside of the gateway context. While deprecation is an imperfect solution, it seems pretty reasonable as an approach. Full explanation in updated docs:

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:

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: { ... }
    },
  ],
});

@yaacovCR

TODO:

• If this PR is a new feature, reference an issue where a consensus about the design was reached (not necessary for small changes)
• Make sure all of the significant new logic is covered by tests
• Rebase your changes on master so that they can be merged easily
• Make sure all tests and linter rules pass

[gmac]

Canary is still failing... otherwise, I think this is ready for another look. I just went fully generic throughout the entire transformation chain.

[gmac]

Oh, question: is stitch the best package for these or is there a strong case for keep them generic in wrap? I’m on the fence. The remove-only behavior feels extremely specific to this stitching usecase. But, wrap is certainly more conventional.

[yaacovCR]

This is great!

Currently it does a strict equal comparison which will fail for input object types...

I do wonder if it would be better if the match directive function took the schema so that it could properly parse even custom scalars or whatever types that the directive arguments throw at it.

This could be easily implemented with getDirectives

https://github.com/ardatan/graphql-tools/blob/master/packages/utils/src/get-directives.ts#L57

Maybe two versions a la valueFromASTUntyped and valueFromAST from graphql-js?

Thoughts?

[gmac]

One note: these new transforms don’t touch input object fields. I can't think of a practical scenario where inputs should be groomed in this manner as they’re not a direct concern of the readable schema; also they don't support deprecation. Does that seem reasonable?

[gmac]

Ooooooohh... I get it now. The AST is all strings, so getDirectives casts them per the typeDef. Thanks! I'm learning a lot about GraphQL internals on this journey.

[yaacovCR]

Tests for the transforms would also be helpful.

[yaacovCR]

This is what I had in mind:

gmac#1

[gmac]

lots more tests are in.

[gmac]

OKAY – another big retooling. There are now 5 new transforms in the wrap package...

• FilterFieldDirectives
• RemoveFieldDirectives
• RemoveFieldsWithDirective
• RemoveFieldDeprecations
• RemoveFieldsWithDeprecation

Only the Deprecation transform flavors mess around with deprecationReason now (in addition to also filtering out @deprecated attributes). Seems like that covers the bases? Also, I've updated all of these transforms to accept string|RegExp inputs so that directive names/args can be pattern matched.

[yaacovCR]

Wow!

I guess the only last nit is that these transforms only work on object fields and not input object fields, so maybe they should have ObjectField in the name like FilterObjectFieldDirectives, etc

Pretty long name, but descriptive, what do you think?

And DS Store ended up in diff...

Really looks great!!!!

[gmac]

.DS_Store is the worst. Fixed, along with naming.

[theguild-bot]

The latest changes of this PR are available as alpha in npm: 6.0.19-alpha-5ba1fc22.0

Quickly update your package.json by running:

npx match-version @graphql-tools 6.0.19-alpha-5ba1fc22.0