Missing AC3 documentation improvements ☔

[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)~
  • https://github.com/apollographql/apollo-client/issues/8915#issuecomment-1133021058
• [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
• [x] ~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) 👉 https://github.com/apollographql/apollo-client/pull/9978~
• [x] ~Explain how to use cache.performTransaction() to batch writes without broadcasting until they've all finished. cache.batch (introduced in https://github.com/apollographql/apollo-client/pull/7819) provides a better API and essentially wraps performTransaction, so it’s the one we should recommend people use. 👉 https://github.com/apollographql/apollo-client/pull/9987~
• [x] ~Document merge: false (e.g. https://github.com/apollographql/apollo-client/pull/6372#issuecomment-670593650) 👉 https://github.com/apollographql/apollo-client/pull/9969~
• [x] ~Document useReactiveVar (https://github.com/apollographql/apollo-client/pull/6867) 👉 #9906~
• [x] ~Document type policy inheritance, using possibleTypes (https://github.com/apollographql/apollo-client/pull/7065) 👉 #9905~
• [x] ~Document custom merge function support in type policies (https://github.com/apollographql/apollo-client/pull/7070)~
• [x] ~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) PR https://github.com/apollographql/apollo-client/pull/9867~
• [x] ~Remove deprecated language from dataIdFromObject #9817~
• [x] updateQuery documentation error #9832
• [ ] Missing docs about aborted requests for V3 #9882
• [ ] Potential Missing docs for MyQueryInterface #9946
• [ ] Allow registering named fragments with InMemoryCache to support using ...FragmentName in queries without redeclaring FragmentName in every query #9764
• [ ] Avoid letting defaultDataIdFromObject normalize objects with nullish ids #9862

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

[JimboFromLimbo]

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

[tyler-dot-earth]

Regardless of whether apollographql/apollo-client#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

[tyler-dot-earth]

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

[jpvajda]

If anyone is interested in helping update our documentation for these different features or improvements please feel free to submit a PR. Thank you!

[jpvajda]

Our next steps with this issue will be to:

1. Validate if these changes still need to be made, or if we've subsequently made changes later on that nullified these older changes.
2. Confirm which docs updates are still required.
3. Work with the docs team on the improvements that need to be made.

The best way to validate these changes are still accurate and haven't been modified by a later PR would be to search our changelog by a common term, to see if we have since pushed any code that would have nullified these original changes.

Alternatively you could look at the individual file changed and review the commit history.

For example: apollographql/apollo-client#7065 was a change to support inheritance of type and field policies, according to possibleTypes. so by searching the change log with possibleTypes you can validate this was the most recent change in apollographql/apollo-client#7065 , and that is OK to document. The file history also shows the recent commit

[jpvajda]

We decided we'll break this issue up in a few weeks where we can have low effort, medium effort and larger effort docs changes in separate issues instead of one larger issue.

[jpvajda]

I'll work on breaking this out into separate tickets.

[jpvajda]

Issues I broke out for the remaining docs improvement work:

• https://github.com/apollographql/apollo-client/issues/10176
• https://github.com/apollographql/apollo-client/issues/10177
• https://github.com/apollographql/apollo-client/issues/10178
• https://github.com/apollographql/apollo-client/issues/10179
• https://github.com/apollographql/apollo-client/issues/10180
• https://github.com/apollographql/apollo-client/issues/10181
• https://github.com/apollographql/apollo-client/issues/10182
• https://github.com/apollographql/apollo-client/issues/10183
• https://github.com/apollographql/apollo-client/issues/10184
• https://github.com/apollographql/apollo-client/issues/10185
• https://github.com/apollographql/apollo-client/issues/10186

So we can close out this umbrella issue now and focus on these independent issues.