Fragment Referencing/Query Composition

[Poincare]

We want to be able to reference a fragment definitions within our queries. The point of including this feature is to do query composition across different UI components. Each UI component can be associated with a fragment to load and a root (or, parent) UI component can then construct a query that references these fragments.

Goals

After some discussion with @stubailo, we've come up with the following goals for the design:

1. The application developer should be able to tell when he/she has used conflicting fragment names anywhere across the application (i.e. not just in a particular query). The benefit of having urging adoption of unique fragment names is that there should never be an instance where the app developer realizes six months into development that their fragment names conflict for a particular query.
2. The queries should be valid GraphQL. Apollo Client shouldn't do a bunch of magic to your query to allow you to reference fragments.
3. The graphql-tag implementation remain unaffected by this implementation.

Design

Given these goals, I'll implement the following design.

1. Each of the query-firing/mutation-firing methods inside QueryManager (e.g. watchQuery, query, mutate), etc. will take an array of GraphQL FragmentDefinitions called fragments.
2. These fragments will be merged with the query or mutation document in question.
3. The query document will be able to reference the fragments using the standard GraphQL fragment spread syntax, e.g. ...fragmentName.
4. This approach works because of goal num. 1, i.e. we should have unique fragment names.
5. All fragments must be created with a new method called client.fragment which will warn the app. developer if there are conflicting fragment names. It will also take an additional argument of fragments that the the first argument fragment depends on and fllatten all of these into a single array of FragmentDefinition values.

What this will look like

If you have a single fragment that you would like to reference within another query:

const fragments = client.fragment(gql`
  fragment authorDetails on Author {
    firstName
    lastName
  }`)
client.query({ query }, fragments)

If you have a single fragment that depends on some other fragments:

const otherFragments: FragmentDefinition[] = ... 
const fragments = client.fragment(gql`
   fragment authorDetails on Author {
      firstName
      lastName
      ...otherAuthorDetails
   }`, otherFragments)
client.query({ query }, fragments)

If you have fragments within your query document,

client.query({ query }) // these will be added through `client.fragment`

Comments/feedback appreciated!

[stubailo]

The benefit of having urging adoption of unique fragment names

Another important benefit is that this is a simple way to avoid rewriting fragment names, so that server-side debugging tools can use the fragment names meaningfully.

@Poincare one question this kinda skips.. how do I use client.fragment to create a fragment that references another fragment?

[Poincare]

To solve that issue, client.fragment will now take a second argument: an array of fragment definitions that a particular fragment depends on and there's no longer a needed for a nested array structure: client.fragment will simply return a single-dimensional array of FragmentDefinitions every time it is called.

[stubailo]

Nice! I love the detail of making sure that fragments in queries are unique as well.

[Poincare]

Closing due to #343.