Feature: useFragment hook

This issue will track the development of a useFragment hook.

Description

useFragment is a read-only reactive/live binding into the cache, providing an always-up-to-date view of whatever data the cache currently contains for a given fragment.

[benjamn]

@smikula I’m still working on a more official proposal, but what do you think of the following sketch?

const {
  data,     // Whatever data the cache can provide right now for this fragment
  complete, // True if no missing fields. Useful with returnPartialData: true
  errors,   // Provides any MissingFieldErrors from the cache
  // Last complete result read by this useFragment, in case data is undefined
  // and displaying stale data is acceptable
  previousData,
} = useFragment({
  // DocumentNode containing the fragment
  fragment,
  // Name of the fragment you want to use, in case the document contains multiple fragments
  fragmentName,
  // Minimal representation of the entity to read the fragment from
  // Can also be a Reference or an ID string, if you have that handy
  from: { __typename: "SomeType", id },
  // Various options shared by cache.diff and cache.read
  variables,
  returnPartialData,
  optimistic,
  canonizeResults,
});

As this sketch suggests, useFragment is a read-only reactive/live binding into the cache, providing an always-up-to-date view of whatever data the cache currently contains for a given fragment.

This architecture means Apollo Client can broadcast extremely specific fragment results to individual components that use useFragment, simply by dumping the results of all incoming queries into the cache. Relay works this way, and I’m very much coming around to it. Perhaps more importantly, Apollo Client has always been capable of this, so I don’t want to leave these capabilities unused.

It’s possible to implement something like this already (see https://github.com/apollographql/apollo-client/issues/7072#issuecomment-810611537 for one version), but there are some remaining questions to answer around who (what code) is responsible for issuing the queries, in this new world of only/mostly fragments.

Reusing useQuery is certainly an option, but then the component gets subscribed to all changes in the query data, when it probably only cares about some small fragment of the query’s data. I think a new kind of query hook will be necessary, or perhaps an additional sub-section within the useFragment options.

Let me know if/how that matches your hopes/expectations!

[hwillson]

This work was completed (https://github.com/apollographql/apollo-client/pull/8782) and will be released in Apollo Client 3.7.