Implement minimal useFragment hook

[benjamn]

Initial implementation of the idea I sketched in #8236 (comment) (though without previousData for now).

This API is still in development and is very much subject to change (hence the [WIP] tag). Watch this space for more details and examples in the coming days/week.

[trevor-scheer]

I wanted this ~2 weeks ago, love to see it!

[jayy-lmao]

Super excited for this!

Part of a team of ~10 devs who are currently using my very-disfunctional useFragment 😅
Thanks for all your work on this, and looking forward to having a play around with it when it lands on the beta

[benjamn]

Since we are postponing useSyncExternalStore support until v3.7 (or whenever React 18 ships), I removed my commit that made useFragment leverage useSyncExternalStore.

A rebased-and-ready-to-cherry-pick version of that commit (35ccbd7) can still be found on this branch.

[Lalitha-Iyer]

Hi @benjamn ,
Stoked to see this work in progress.
Could you please expand on what is intentionally out of scope in the first version.
I am mostly interested in understanding, the steady state useFragment capabilities.
For example would we support paginated fragments.

[Lalitha-Iyer]

what is optimistic used for.

[benjamn]

InMemoryCache can temporarily have additional layers during mutations that use optimisticResponse, which then get discarded once the real data have been written to the root/non-optimistic layer of the cache.

When you're using useFragment, you can control whether it reads data from these optimistic layers (optimistic: true, the default), or just the root layer (optimistic: false). Reading from optimistic data is a good default because it's the same as reading non-optimistic data when there are no active optimistic updates, and reading optimistic data allows the optimisticResponse to be rendered immediately, and then the real response only needs to trigger a UI update if the optimisticResponse was wrong/incomplete.

[Lalitha-Iyer]

Why do we need to specify "from", since we already specify 'fragment`. I am guessing because we don't know which query it is bound to at runtime, and the 'id' of the type.

[benjamn]

The options.from value represents the specific entity object (with some __typename that matches the fragment type condition, and some unique ID field(s)) against which the options.fragment should be applied/executed.

When you execute a query rather than a fragment, there's no mystery about which object to start with, since there's only one singleton ROOT_QUERY object. Fragments don't have that luxury, and always need to know the starting object. Occasionally it might be possible to guess the object based on the fragment's type condition; for example, fragment QueryFrag on Query {...} is always going to be a fragment that starts executing against the ROOT_QUERY object, but I'm not sure those special cases are worth exploiting, since they are not the common case.

The options.from argument is similar to the options.id field for cache.readFragment and cache.writeFragment, but a little more flexible (in case you don't know the string ID).

[benjamn]

@Lalitha-Iyer Thanks for the review!

My two biggest open questions are:

• How can we associate useFragment calls with the queries that support them, so they can share variables and display warnings when/if the query is removed or stops providing the data useFragment expects?
  • There's a possibility this belongs on the query side, as an option to useBackgroundQuery, but my current thinking is that useFragment can bear most of the burden.
• Since GraphQL errors are not currently stored in InMemoryCache (a promising but tricky idea), and since useFragment is a direct binding to the InMemoryCache, how can consumers of useFragment find out about relevant errors that might impact the data they (don't) receive?
  • If useFragment had a reliable way to name the queries it depends on, we might also be able to expose those queries' latest errors in the useFragment result. This is appealing because it's not blocked on caching errors, and reuses the existing error logic in the client (outside of the cache).

When you asked about paginated fragments, were you thinking of something like putting a fetchMore function in the useFragment result object?

[Lalitha-Iyer]

Thanks for the clarifications @benjamn !

When you asked about paginated fragments, were you thinking of something like putting a fetchMore function in the useFragment result object?

I didn't mean to suggest any implementation, I was curious to know the breadth of capabilities we plan to make available long term. As a contrived example, one way to think abt the scope would be: what is the lifecycle of a fragment and what controls will be available to manage fragments ( accessing already cached data -> subscribing to changes -> refetching/pagination -> garbage collection).

With the lifecycle/capabilities listed, we could then try to model fragments either in the current way ( loosely coupled from queries ) or a stricter 1:1 mapping or a 1:many ( depending on whichever approach solves our usecases).

[Lalitha-Iyer]

@benjamn ignore my previous comment, I probably misunderstood fragments. Reading the Graphql spec if fragments are a reusable set of fields that can be applied to any query then your approach of not binding to a query makes senss. Your open questions around error handling and at runtime mapping fragment to one/more queries seem reasonable. Thanks again for taking time to clarify.