(docs) - elaborate on graphcache documentation (#950)

* clarify some graphcache documentation

* Apply suggestions from code review

Co-authored-by: Phil Pluckthun <phil@kitten.sh>
Co-authored-by: Will Golledge <35961363+wgolledge@users.noreply.github.com>

* update wording

* consistent mentions

Co-authored-by: Phil Pluckthun <phil@kitten.sh>
Co-authored-by: Will Golledge <35961363+wgolledge@users.noreply.github.com>

authored by

Jovi De Croock

Phil Pluckthun

Will Golledge and committed by

GitHub 5 years ago 34181a3a 6d4e4012

+19 -6

2 changed files

expand all

docs

graphcache

custom-updates.md

normalized-caching.md

+9 -6

docs/graphcache/custom-updates.md

··· 5 5 6 6 # Custom Updates 7 7 8 - _Graphcache_ will attempt to automatically react to your mutations' and subscriptions' results 9 - but sometimes this isn't possible. While it will update all normalized entities that it finds in 10 - those results, it can't for instance tell whether a new item should be appended or removed from a 11 - list. 8 + Every time Graphcache sees a result from the API for a `subscription` or a `mutation` it will look at the response and traverse it. 9 + This process is the same as for queries but instead of starting at the Query root type, 10 + it will start searching for keyable entities, where an object's `__typename` and `id` or `_id` fields (or a custom keys config) 11 + are provided, so it can write normalized entities to the cache. 12 12 13 - Specifically, a normalized cache can't automatically assume that unrelated links have changed due to 13 + A normalized cache can't automatically assume that unrelated links have changed due to 14 14 a mutation, since this is server-side specific logic. Instead, we may use the `updates` 15 15 configuration to set up manual updates that react to mutations or subscriptions. 16 16 ··· 257 257 Rather than use `cache.inspectFields('Query')`, which would give us all queried `todo` fields with their arguments, we can instead provide an object as the argument to `inspectFields` asking for all `Todo` types for a given id. 258 258 259 259 ```js 260 - cache.inspectFields({ __typename: 'Todo', id: args.id }) 260 + cache.inspectFields({ __typename: 'Todo', id: args.id }); 261 261 ``` 262 262 263 263 Now we'll get all fields for the given `todo` and can freely update the `authors`. ··· 267 267 If we know what result a mutation may return, why wait for the GraphQL API to fulfill our mutations? 268 268 The _Optimistic Updates_ configuration allows us to set up "temporary" results for mutations, which 269 269 will be applied immediately. This is a great solution to reduce the waiting time for the user. 270 + 271 + > Note that an optimistic response is meant to be a temporary update to an entity until the server responds to your mutation. 272 + > This means that what you return here should reflect the shape of what the server will return. 270 273 271 274 This technique is often used with one-off mutations that are assumed to succeed, like starring a 272 275 repository, or liking a tweet. In such cases it's often desirable to make the interaction feel

+10

docs/graphcache/normalized-caching.md

··· 62 62 later on in the app. This would automatically cause _Graphcache_ to update any related queries in 63 63 the entire app, because all references to each each entity are shared. 64 64 65 + ## Terminology 66 + 67 + A few terms that will be used throughout the _Graphcache_ documentation that are important to understand in order to get a full understanding. 68 + 69 + - **Entity**, this is an object for which the cache can generate a key, like `Todo:1`. 70 + - **Record**, this is a property that relate to an entity, in the above case this would be `title`, ... 71 + internally these will be represented as `Todo:1.title`. 72 + - **Link**, This is the connection between entities or the base `Query` field, this will link an entity key (ex: `Query`/`Todo:1`) to a single or an array 73 + of keys 74 + 65 75 ## Key Generation 66 76 67 77 As we saw in the previous example, by default _Graphcache_ will attempt to generate a key by

Configure Feed

Configure Feed