Missing AC3 documentation improvements ☔

[hwillson]

This issue tracks the docs items that weren't completed in #6429.

TODO:

• Refactor all pagination documentation
  • Overhaul https://www.apollographql.com/docs/react/data/pagination/
    • Rewrite documentation for custom pagination with field policies #7175
• Deprecate fetchMode's updateQuery, replacing with field policies (Deprecate fetchMore updateQuery function, and provide basic field policy helper functions #6464)
  • Please don't remove updateQuery. #8915 (comment)
• Explain what keyArgs: false does
  • See https://deploy-preview-7175--apollo-client-docs.netlify.app/docs/react/pagination/key-args/
    /6852#issuecomment-674984235)
• @apollo/client/core, @apollo/client/utilities, @apollo/client/testing, @apollo/client/cache, etc. entry points
• Properly explain how cache.writeQuery/Fragment broadcasting can be silenced using the broadcast option (and what the advantages are to doing so - reference: Allow silencing broadcast for cache update methods. #6288) 👉 adds broadcast false details #9978
• Explain how to use cache.performTransaction() to batch writes without broadcasting until they've all finished. cache.batch (introduced in Introduce new cache.batch(options) method for InMemoryCache. #7819) provides a better API and essentially wraps performTransaction, so it’s the one we should recommend people use. 👉 Cache.batch docs #9987
• Document merge: false (e.g. Warn when clobbering non-normalized data in the cache. #6372 (comment)) 👉 Field policy merge docs #9969
• Document useReactiveVar (Implement useReactiveVar hook for consuming reactive variables in React components. #6867) 👉 Use reactive var hook #9906
• Document type policy inheritance, using possibleTypes (Support inheritance of typePolicies, according to possibleTypes. #7065) 👉 Type policy inheritance #9905
• Document custom merge function support in type policies (Allow custom merge functions (including merge:true and merge:false) in type policies. #7070)
• Explain how to properly test local state using MockedProvider, by passing a configured cache into MockedProvider itself (MockedProvider not returning data when @client is specified #4532) PR Mockprovider docs updates #9867
• Remove deprecated language from dataIdFromObject Remove deprecated language from dataIdFromObject  #9817
• updateQuery documentation error updateQuery documentation error #9832
• Missing docs about aborted requests for V3 Missing docs about aborted requests for V3 #9882
• Potential Missing docs for MyQueryInterface (typescript): Request for adding different types(interfaces) for the query data from useQuery and subscribeToMore data #9946
• Allow registering named fragments with InMemoryCache to support using ...FragmentName in queries without redeclaring FragmentName in every query 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 Avoid letting defaultDataIdFromObject normalize objects with nullish ids #9862

[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 #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: #6247 and comment #6711 (comment)

[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: #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 #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:

• AC 3 Docs Make remaining local state updates to Docs #10176
• AC 3 Docs Document new pagination helpers #10177
• AC 3 Docs Rewrite the 2.6 code splitting content #10178
• AC 3 Docs Explain new cache console.log warnings, what they mean, how to resolve them #10179
• AC 3 Docs Fall back to cache-first after cache-and-network or network-only  #10180
• AC 3 Docs Update all read / merge docs to make sure they reflect the final version of the API #10181
• AC 3 Docs Update the intro path to mutations to replace the new default approach  #10182
• AC 3 Docs Update missing docs about aborted requests  #10183
• AC 3 Docs Update missing docs defining data type for subscribeToMore #10184
• Add createFragmentRegistry documentation #10185
• AC 3 Docs Improve docs for defaultDataIdFromObject and nullish ids #10186

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