Add deprecations and warnings to ApolloClient options and methods

[jerelmiller]

Adds @deprecated tags to options and methods on the ApolloClient constructor that are no longer supported. Adds runtime warnings for other change.

[changeset-bot]

🦋 Changeset detected

Latest commit: c1929fd

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@apollo/client	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

npm i https://pkg.pr.new/@apollo/client@12736

commit: c1929fd

[github-actions]

size-limit report 📦

Path	Size
dist/apollo-client.min.cjs	41.4 KB (+0.18% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (CJS)	50.92 KB (+0.26% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (production) (CJS)	47.94 KB (+0.17% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client"	36.46 KB (+0.38% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "@apollo/client" (production)	33.78 KB (+0.18% 🔺)
import { ApolloProvider } from "@apollo/client/react"	1.26 KB (0%)
import { ApolloProvider } from "@apollo/client/react" (production)	1.24 KB (-0.16% 🔽)
import { useQuery } from "@apollo/client/react"	10.1 KB (+0.04% 🔺)
import { useQuery } from "@apollo/client/react" (production)	9.02 KB (0%)
import { useLazyQuery } from "@apollo/client/react"	9.48 KB (+0.02% 🔺)
import { useMutation } from "@apollo/client/react"	3.62 KB (+0.06% 🔺)
import { useMutation } from "@apollo/client/react" (production)	2.84 KB (+0.04% 🔺)
import { useSubscription } from "@apollo/client/react"	4.43 KB (+0.03% 🔺)
import { useSubscription } from "@apollo/client/react" (production)	3.48 KB (+0.06% 🔺)
import { useSuspenseQuery } from "@apollo/client/react"	5.89 KB (+0.02% 🔺)
import { useSuspenseQuery } from "@apollo/client/react" (production)	4.56 KB (+0.03% 🔺)
import { useBackgroundQuery } from "@apollo/client/react"	5.38 KB (+0.02% 🔺)
import { useBackgroundQuery } from "@apollo/client/react" (production)	4.04 KB (0%)
import { useLoadableQuery } from "@apollo/client/react"	5.47 KB (0%)
import { useLoadableQuery } from "@apollo/client/react" (production)	4.12 KB (0%)
import { useReadQuery } from "@apollo/client/react"	3.44 KB (+0.03% 🔺)
import { useReadQuery } from "@apollo/client/react" (production)	3.38 KB (+0.06% 🔺)
import { useFragment } from "@apollo/client/react"	2.36 KB (0%)
import { useFragment } from "@apollo/client/react" (production)	2.31 KB (-0.05% 🔽)

[jerelmiller]

Do we also want runtime warnings when using these functions or just leave it as an @deprecated tag?

[jerelmiller]

Suggestions welcome on wording here. I don't know how best to communicate "this will change, but only works as resolvers until 4.0"

[phryneas]

Suggested change

	* @deprecated `resolvers` has been changed in Apollo Client 4.0 and will no
	* longer be provided as an option directly to `ApolloClient`. `resolvers`
	* should continue to be used until upgrading to 4.0.
	* @deprecated in preparation to the Apollo Client 4.0:
	* `resolvers` will change in Apollo Client 4.0 and will no longer be provided as an option directly to `ApolloClient`.
	* It is safe to keep using this option with Apollo Client 3.x.

Maybe something like this?

[apollo-librarian]

❌ Docs preview failed

The preview failed to build.

Build ID: 9cfb15a263f39791129092a0

Errors

General: other side closed

[phryneas]

I'm missing a bit of a common structure for all of these deprecation comments.

Maybe we should have a common "template" for all of these comments?

Something like this:

   * @deprecated in preparation of a migation to Apollo Client 4.0. It is safe to keep using this in Apollo Client 3.x.
| Description  | This option will be renamed in Apollo Client 4.0. |
| ------------- | ------------- |
| On Migration  | pass `prioritizeCacheValues` instead of `disableNetworkFetches` to the `ApolloClient` constructor  |
| Recommended now  | no action needed  |
   */

Note that it's very difficult to get VSCode to display any structured data - there's no "nested list" support, so a table seems like the best option.

[phryneas]

Suggested change

	* @deprecated `resolvers` has been changed in Apollo Client 4.0 and will no
	* longer be provided as an option directly to `ApolloClient`. `resolvers`
	* should continue to be used until upgrading to 4.0.
	* @deprecated in preparation to the Apollo Client 4.0:
	* `resolvers` will change in Apollo Client 4.0 and will no longer be provided as an option directly to `ApolloClient`.
	* It is safe to keep using this option with Apollo Client 3.x.

Maybe something like this?

[jerelmiller]

The table idea is interesting. It looks though like this only really formats well in VSCode.

Here is neovim with the same text:

I'll keep trying different format options but I like the idea of having some sort of template that defines what you should do now vs later.

[jerelmiller]

@phryneas take a look at the latest and see if you like that format.

[jerelmiller]

I avoided a warning for resolvers and fragmentMatcher in here since there is nothing actionable that can be done until the upgrade to 4.0. Having a warning that you can't get rid of I think would be too annoying.