Feature: useFragment hook

[hwillson]

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.

[smikula]

@hwillson, is there any further documentation about the useFragment hook anywhere — what it does, or what problems it is intended to solve? If it is what it sounds like, it's a feature I'm very interested in.

[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 #7072 (comment) 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!

[smikula]

@benjamn Yes, this is exactly what I was hoping for. When can I have it? :)

I'll take a look at the comment you linked — maybe something like that will work for me in the meantime.