cache.modify: less strict types & dev runtime warnings

[phryneas]

Checklist:

• If this PR contains changes to the library itself (not necessary for e.g. docs updates), please include a changeset (see CONTRIBUTING.md)
• If this PR is a new feature, please reference an issue where a consensus about the design was reached (not necessary for small changes)
• Make sure all of the significant new logic is covered by tests

This fixes #11171.
While technically it is correct that the modify function should always return an array of only objects or only references, this is very annoying to be used with TypeScript - and also never enforced by us on Runtime.

So instead, this PR relaxes the strictness of the modify arguments from Obj[] | Reference[] to (Obj | Reference)[], and does the same for the return value.

Additionally, it adds a runtime warning if the modify function returns a mixed array, where at least one of the non-Reference-objects could be represented by a Reference.

Also, there was a footgun of only calling toReference(obj) where obj was not part of the store yet. In that case, it would not write obj to the store and create a "dead" reference. I also added a DEV-level warning for those cases.

---

⚠️ This PR uses #11177, so it should only be merged after that - but it can already be reviewed.

[changeset-bot]

🦋 Changeset detected

Latest commit: dba00aa

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	Patch

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

[github-actions]

size-limit report 📦

Path	Size
dist/apollo-client.min.cjs	37.07 KB (0%)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs"	43.52 KB (+0.29% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/main.cjs" (production)	42.01 KB (+0.12% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js"	32.6 KB (+0.4% 🔺)
import { ApolloClient, InMemoryCache, HttpLink } from "dist/index.js" (production)	31.27 KB (+0.15% 🔺)
import { ApolloProvider } from "dist/react/index.js"	1.22 KB (0%)
import { ApolloProvider } from "dist/react/index.js" (production)	1.21 KB (0%)
import { useQuery } from "dist/react/index.js"	4.28 KB (-0.03% 🔽)
import { useQuery } from "dist/react/index.js" (production)	4.1 KB (+0.03% 🔺)
import { useLazyQuery } from "dist/react/index.js"	4.59 KB (-0.03% 🔽)
import { useLazyQuery } from "dist/react/index.js" (production)	4.41 KB (0%)
import { useMutation } from "dist/react/index.js"	2.54 KB (-0.04% 🔽)
import { useMutation } from "dist/react/index.js" (production)	2.52 KB (-0.04% 🔽)
import { useSubscription } from "dist/react/index.js"	2.24 KB (-0.09% 🔽)
import { useSubscription } from "dist/react/index.js" (production)	2.2 KB (-0.05% 🔽)
import { useSuspenseQuery } from "dist/react/index.js"	4.62 KB (-0.03% 🔽)
import { useSuspenseQuery } from "dist/react/index.js" (production)	4.05 KB (+0.03% 🔺)
import { useBackgroundQuery } from "dist/react/index.js"	4.14 KB (-0.05% 🔽)
import { useBackgroundQuery } from "dist/react/index.js" (production)	3.56 KB (+0.03% 🔺)
import { useReadQuery } from "dist/react/index.js"	3 KB (0%)
import { useReadQuery } from "dist/react/index.js" (production)	2.94 KB (-0.04% 🔽)
import { useFragment } from "dist/react/index.js"	2.09 KB (0%)
import { useFragment } from "dist/react/index.js" (production)	2.04 KB (0%)

[phryneas]

/release:pr

[github-actions]

A new release has been made for this PR. You can install it with npm i @apollo/[email protected].

[alessbell]

The dev warning is really well worded - this will be a great improvement!

[jmoore9j]

In my angular 14 projects, compilation fails at this point with the changes in the 3.8.1 patch. Is there a workaround or documentation so I can fix it?

`Error: node_modules/@apollo/client/cache/core/types/common.d.ts:52:110 - error TS1005: '?' expected.

52 type StoreObjectValueMaybeReference = StoreVal extends Array<infer Item extends Record<string, any>> ? ReadonlyArray<AsStoreObject | Reference> : StoreVal extends Record<string, any> ? AsStoreObject | Reference : StoreVal;
`

[phryneas]

@jmoore9j what TypeScript version are you on?

[jmoore9j]

@phryneas currently its at ~4.6.4. Is there a recommended version?

[phryneas]

@jmoore9j Preferrably a recent one - TypeScript moves quite fast, and I would almost bet that you wouldn't have that problem with 5.1 or 5.2.

[phryneas]

The specific notion that's giving you problems here (infer X extends Y) seems to have been added with TS 4.8