Feature: add onSubscriptionData callback to <Subscription>

[jedwards1211]

For most of what I do with GraphQL subscriptions, I find myself wishing I could just use ApolloClient.writeQuery to update the cache, rather than the subscribeToMore/updateQuery approach. The new <Subscription> components alleviates the pain of unsubscribing and resubscribing in my own code when I need to change variables, but it doesn't currently provide any way of updating the cache, so it's fairly useless for my needs.

But with this PR, I get a callback from <Subscription> with the ApolloClient and the subscription data, so I can use writeQuery to update the cache:

// subscribes to multiple items; each response will be a single item
const subscription = gql`subscription ($ids: [Int!]!) {
  Item: Items(ids: $ids) {
    name
  }
}`

// query for writing a single item
const query = gql`query ($id: Int!) {
  Item(id: $id) {
    name
  }
}`

const App = ({itemsToShow}) => (
  <Subscription
    subscription={RepoSubscription}
    variables={{ids: itemsToShow}}
    onSubscriptionData={({client, subscriptionData}) => {
      if (subscriptionData.data) {
        const {Item} = subscriptionData.data
        client.writeQuery({
          query: RepoQuery,
          variables: {id: Item.id},
          data: {Item},
        })
      }
    }}
  />
)

[hwillson]

Thanks for this PR @jedwards1211. What are your main concerns / complaints about the subscribeToMore / updateQuery approach?

[jedwards1211]

@hwillson for one, sometimes doing an initial query is completely unnecessary. For another, it pushes all of the work of unsubscribing and resubscribing when relevant variables change onto the developer.

Sometimes subscriptions can be decoupled: there are some things my app always needs to be subscribed to, so it is better to manage that subscription with a single component, even though multiple views query the data that is updated by the subscription.

It is more awkward to make cache update logic reusable with updateQuery than with writeQuery.

But the chief problem with the query-then-subscribe paradigm is that updates can be lost if changes occur between the time the server responds to the initial query and the client initiates a subscription. I explain that in more detail here: apollographql/apollo-client#2892

[hwillson]

Thanks for working on this @jedwards1211 - LGTM! 👍