Apollo-client: Outstanding AC3 documentation

[hwillson]

This issue tracks the docs items that weren't completed in https://github.com/apollographql/apollo-client/pull/6429.

TODO:

• [ ] Refactor all pagination documentation
  
  
  
  • [x] Overhaul https://www.apollographql.com/docs/react/data/pagination/
  
  
  • https://github.com/apollographql/apollo-client/pull/7175
  
  
  • [ ] Document new pagination helpers (https://github.com/apollographql/apollo-client/pull/6464 and https://github.com/apollographql/apollo-client/pull/6465)
  
  
• [ ] Deprecate fetchMode's updateQuery, replacing with field policies (https://github.com/apollographql/apollo-client/pull/6464)
• [x] Explain what keyArgs: false does
  
  
  
  • See https://deploy-preview-7175--apollo-client-docs.netlify.app/docs/react/pagination/key-args/
  
  
• [ ] Remaining local state updates
  
  
  
  • [ ] add a mutation example
  
  
  • [ ] add a merge function example
  
  
  • [ ] Handling async operations with field policies (https://github.com/apollographql/apollo-client/issues/6852#issuecomment-674984235)
  
  
  • [ ] Rewrite the 2.6 code splitting content, showing how to do the same thing with client.cache.policies.addTypePolicies(typePolicies)
  
  
• [ ] @apollo/client/core, @apollo/client/utilities, @apollo/client/testing, @apollo/client/cache, etc. entry points
• [ ] Explain new cache console.log warnings, what they mean, how to resolve them
• [ ] Fall back to cache-first after cache-and-network or network-only (8ce2b4f7c8e631a46ed41cd205c34ede38f202c9)
• [ ] Update all read / merge docs to make sure they reflect the final version of the API
• [ ] Consider updating the intro path to mutations to replace the new default approach of using cache.modify with a readQuery / writeQuery approach instead (then briefly mention cache.modify as a more advanced alternative
• [ ] Update https://www.apollographql.com/docs/react/development-testing/client-schema-mocking/ to leverage field policies instead of local resolvers
• [ ] Properly explain how cache.writeQuery/Fragment broadcasting can be silenced using the broadcast option (and what the advantages are to doing so - reference: https://github.com/apollographql/apollo-client/pull/6288)
  
  
  
  • [ ] Also explain how to use cache.performTransaction() to batch writes without broadcasting until they've all finished
  
  
• [ ] Document merge: false (e.g. https://github.com/apollographql/apollo-client/pull/6372#issuecomment-670593650)
• [ ] Document useReactiveVar (https://github.com/apollographql/apollo-client/pull/6867)
• [ ] Document type policy inheritance, using possibleTypes (https://github.com/apollographql/apollo-client/pull/7065)
• [x] Document custom merge function support in type policies (https://github.com/apollographql/apollo-client/pull/7070)
• [ ] Explain how to properly test local state using MockedProvider, by passing a configured cache into MockedProvider itself (https://github.com/apollographql/apollo-client/issues/4532)

If anyone notices other AC3 docs items that are wrong/missing, please let us know. Thanks!

[Jamesdinnes]

Would be good to get some more clarification around testing especially around client directives and reactive variables.

[abdonrd]

Meanwhile where we can find information about pagination? Thanks!

[hwillson]

@abdonrd We're working on overhauling the main pagination section of the docs, but in the meantime you can find some details here: https://www.apollographql.com/docs/react/caching/cache-field-behavior/#handling-pagination

[tsnieman]

Regardless of whether #6619 is a bug or intended behavior, this comment indicates a section of the documentation that could use some love to clarify intention WRT merging variables on mutate calls. Similarly, information about the change (if intentional) should also be conveyed in migration guides, changelogs, etc.

[JesseZomer]

I'm looking for documentation for local-only mutations. I see there's still a checkbox missing with the mutation example, but if someone could explain to me what I'm doing wrong, that would be great.

Our application makes use of the old local resolvers. Now I want to 'update' them to typePolicies. My old resolver looked like:

resolvers: {
         ....
        Mutation: {
           createCategorie(...)
        }
}

Now I changed it to this typePolicy:

const inMemoryCache = new InMemoryCache({
    typePolicies: {
        Query: {
            fields: {
                ....
            },
        },
        Mutation: {
            fields: {
                createCategorie(...) {
                    console.log('in create');
                }
            }
        },
       ...

the mutation gets called like this:

gql`
 mutation createCategorie(...) {
 createCategorie(...) @client
}`,

However the console.log never gets called. Is there something I'm missing?

edit: found my answer here: https://spectrum.chat/apollo/apollo-client/ac3-client-mutation~a0f064bf-731b-4129-8016-601217d45971

[tsnieman]

I think this issue about undefined old data when loading new data could use some love in the documentation / migration guides too.

[dmitry]

@JesseZomer I've stuck with the same problem. Probably you can help me with migration from local resolver mutation -> reactive variable?
Another problem related to this issue: https://github.com/apollographql/apollo-client/issues/6247 and comment https://github.com/apollographql/apollo-client/issues/6711#issuecomment-671838312

[JesseZomer]

@dmitry I didn't migrate from local mutation resolvers to reactive variables, but I threw away the local mutations and just did direct cache updates with read/writeQuery.

[lorensr]

@apollo/client/core, @apollo/client/utilities, @apollo/client/testing, @apollo/client/cache, etc. entry points

Also link entry points. These imports are out of date: https://www.apollographql.com/docs/link/

[gbiryukov]

Example with apollo cache reset to initial state also needs to be updated because it uses deprecated apollo-link-state to write defaults