AC 3 Docs Make remaining local state updates to Docs

[jpvajda]

• AC 3 Docs Make remaining local state updates to Docs #10176
  • add a mutation example
  • Handling async operations with field policies (read method on field's TypePolicy should allow async behaviour apollo-feature-requests#383)

[bignimbus]

Notes and questions

Please do feel free to weigh in on these ideas!

Add a mutation example

Regarding local state, I think #6711 (comment) summarizes the example we'll want to add to managing-state-with-field-policies (with a corresponding blurb in local-state-management.mdx?

Add a merge function example

The following documents demonstrate the merge function in some fashion:

• https://github.com/apollographql/apollo-client/blob/main/docs/source/pagination/cursor-based.mdx
• https://github.com/apollographql/apollo-client/blob/main/docs/source/pagination/core-api.mdx
• https://github.com/apollographql/apollo-client/blob/main/docs/source/pagination/key-args.mdx
• https://github.com/apollographql/apollo-client/blob/main/docs/source/caching/cache-field-behavior.mdx
• https://github.com/apollographql/apollo-client/blob/main/docs/source/caching/advanced-topics.mdx

There's nothing in the local-state directory though, so I'll plan on targeting that directory, maybe in managing-state-with-field-policies.mdx (with a corresponding high-level blurb in local-state-management.mdx?)

Handling async operations with field policies

Since #9274 is still open, let's use @benjamn's example in apollographql/apollo-feature-requests#383 as a template. We should explain more about why reads are synchronous out of the box and how to implement your own asynchronous read function.

[hwillson]

@bignimbus this looks great!

Mutations with field policies are definitely different than the older local state resolver mutation capabilities, and our docs are sorely lacking details on this, so that section will probably require the most attention. The main point to get across is that the newer type/field policy API is all about the cache and working with cache fields, not about running resolvers (and mutations). The new API gives read/write hooks into the cache that can be combined with GraphQL operations using @client, but it's not meant to be a GraphQL aware resolver layer. If the local cache needs to be updated without firing a remote mutation, we recommend using writeQuery / writeFragment directly. We should also call out that Reactive Variables can help address a lot of the previous local resolver mutation usage patterns as well. E.g. if you were using a local resolver + mutation to handle updating a shopping cart entity in the cache, you could consider storing the cart in a reactive variable, wiring the reading of the cart up in field policies using @client, then just update the cart reactive variable directly any time you want to change it without needing to fire a mutation.

Thanks for working on this!