Merge remote-tracking branch 'origin/main' into release-4.0

jerelmiller · jerelmiller · commit ed3dec6d0e26 · 2025-08-20T23:23:28.000-06:00
diff --git a/.api-reports/api-report-testing_react.api.md b/.api-reports/api-report-testing_react.api.md
@@ -32,7 +32,6 @@ export interface MockedProviderProps {
     children?: any;
     // (undocumented)
     defaultOptions?: ApolloClient.DefaultOptions;
-    // (undocumented)
     devtools?: ApolloClient.Options["devtools"];
     // (undocumented)
     link?: ApolloLink;
diff --git a/.changeset/breezy-lions-rule.md b/.changeset/breezy-lions-rule.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Add deprecations and warnings to remaining APIs changed in Apollo Client 4.0.
diff --git a/.changeset/chilled-cameras-scream.md b/.changeset/chilled-cameras-scream.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Add warnings and deprecations for options and methods for all React APIs.
diff --git a/.changeset/great-jobs-fetch.md b/.changeset/great-jobs-fetch.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Add `@deprecated` tags to all properties returned from any query API (e.g. `client.query`, `observableQuery.refetch`, etc.), `client.mutate`, and `client.subscribe` that are no longer available in Apollo Client 4.0.
diff --git a/.changeset/great-suns-cover.md b/.changeset/great-suns-cover.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": patch
+---
+
+Prevent field policies from overwriting/merging into supertype field policies.
diff --git a/.changeset/perfect-donuts-roll.md b/.changeset/perfect-donuts-roll.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Add `preloadQuery.toPromise(queryRef)` as a replacement for `queryRef.toPromise()`. `queryRef.toPromise()` has been removed in Apollo Client 4.0 in favor of `preloadQuery.toPromise` and is now considered deprecated.
diff --git a/.changeset/popular-waves-drop.md b/.changeset/popular-waves-drop.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Add deprecations and deprecation warnings for `ApolloClient` options and methods.
diff --git a/.changeset/shy-boxes-exercise.md b/.changeset/shy-boxes-exercise.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Version bump only to release latest as `rc`.
diff --git a/.changeset/shy-dragons-tease.md b/.changeset/shy-dragons-tease.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Reset `addTypenameTransform` and `fragments` caches when calling `cache.gc()` only when `resetResultCache` is `true`.
diff --git a/.changeset/smooth-countries-cough.md b/.changeset/smooth-countries-cough.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Add deprecations and warnings for `addTypename` in `InMemoryCache` and `MockedProvider`.
diff --git a/.changeset/spotty-walls-repair.md b/.changeset/spotty-walls-repair.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Add deprecations and warnings for `canonizeResults`.
diff --git a/.changeset/tidy-bulldogs-exercise.md b/.changeset/tidy-bulldogs-exercise.md
@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor
+---
+
+Warn when using a `standby` fetch policy with `client.query`.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2216,6 +2216,48 @@
 
 - [#12384](https://github.com/apollographql/apollo-client/pull/12384) [`6aa6fd3`](https://github.com/apollographql/apollo-client/commit/6aa6fd316cfdb31ebbe3e3133cca2965604e7ca1) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Don't emit a partial cache result from `cache-only` queries when `returnPartialData` is `false`.
 
+## 3.14.0-rc.0
+
+### Minor Changes
+
+- [#12763](https://github.com/apollographql/apollo-client/pull/12763) [`5de6a3d`](https://github.com/apollographql/apollo-client/commit/5de6a3d3189afa2a7c3bb2eb08d3c4394ae4a16d) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Version bump only to release latest as `rc`.
+
+## 3.14.0-alpha.1
+
+### Minor Changes
+
+- [#12752](https://github.com/apollographql/apollo-client/pull/12752) [`8b779b4`](https://github.com/apollographql/apollo-client/commit/8b779b428b9dc9dad3e78f02bba6646ff415631d) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add deprecations and warnings to remaining APIs changed in Apollo Client 4.0.
+
+- [#12751](https://github.com/apollographql/apollo-client/pull/12751) [`567cad8`](https://github.com/apollographql/apollo-client/commit/567cad8fcc30ac3b82560abc24970d33f160622e) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add `@deprecated` tags to all properties returned from any query API (e.g. `client.query`, `observableQuery.refetch`, etc.), `client.mutate`, and `client.subscribe` that are no longer available in Apollo Client 4.0.
+
+- [#12751](https://github.com/apollographql/apollo-client/pull/12751) [`567cad8`](https://github.com/apollographql/apollo-client/commit/567cad8fcc30ac3b82560abc24970d33f160622e) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Warn when using a `standby` fetch policy with `client.query`.
+
+## 3.14.0-alpha.0
+
+### Minor Changes
+
+- [#12746](https://github.com/apollographql/apollo-client/pull/12746) [`0bcd2f4`](https://github.com/apollographql/apollo-client/commit/0bcd2f4ead372eb5928bbd5c00b0bd48e497a5e1) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add warnings and deprecations for options and methods for all React APIs.
+
+- [#12746](https://github.com/apollographql/apollo-client/pull/12746) [`0bcd2f4`](https://github.com/apollographql/apollo-client/commit/0bcd2f4ead372eb5928bbd5c00b0bd48e497a5e1) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add `preloadQuery.toPromise(queryRef)` as a replacement for `queryRef.toPromise()`. `queryRef.toPromise()` has been removed in Apollo Client 4.0 in favor of `preloadQuery.toPromise` and is now considered deprecated.
+
+- [#12736](https://github.com/apollographql/apollo-client/pull/12736) [`ea89440`](https://github.com/apollographql/apollo-client/commit/ea8944013278060ef87dfa4de6663a21b5204880) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add deprecations and deprecation warnings for `ApolloClient` options and methods.
+
+- [#12459](https://github.com/apollographql/apollo-client/pull/12459) [`1c5a031`](https://github.com/apollographql/apollo-client/commit/1c5a0313d388945aeda93b2c1992ad77f4416fa1) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Reset `addTypenameTransform` and `fragments` caches when calling `cache.gc()` only when `resetResultCache` is `true`.
+
+- [#12743](https://github.com/apollographql/apollo-client/pull/12743) [`92ad409`](https://github.com/apollographql/apollo-client/commit/92ad4097e5c83e0a780ede20db34e9e63fb98e8b) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add deprecations and warnings for `addTypename` in `InMemoryCache` and `MockedProvider`.
+
+- [#12743](https://github.com/apollographql/apollo-client/pull/12743) [`92ad409`](https://github.com/apollographql/apollo-client/commit/92ad4097e5c83e0a780ede20db34e9e63fb98e8b) Thanks [@jerelmiller](https://github.com/jerelmiller)! - Add deprecations and warnings for `canonizeResults`.
+
+### Patch Changes
+
+- [#12750](https://github.com/apollographql/apollo-client/pull/12750) [`ecf3de1`](https://github.com/apollographql/apollo-client/commit/ecf3de1cc9a2cf3aaeba0c945909324b9e4b478a) Thanks [@phryneas](https://github.com/phryneas)! - Prevent field policies from overwriting/merging into supertype field policies.
+
+## 3.13.9
+
+### Patch Changes
+
+- [#12804](https://github.com/apollographql/apollo-client/pull/12804) [`32c9aa9`](https://github.com/apollographql/apollo-client/commit/32c9aa9215fab72e9ab68ee71198ce242157f855) Thanks [@phryneas](https://github.com/phryneas)! - Fix a possible race condition on queries that were reobserved before they were subscribed to the first time.
+
 ## 3.13.8
 
 ### Patch Changes
diff --git a/README.md b/README.md
@@ -52,8 +52,8 @@ npm install @apollo/client graphql
 Deliver tomorrow's roadmap today with our comprehensive suite of API orchestration tools:
 
 - [**Apollo Client**](https://www.apollographql.com/docs/react?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Type-safe apps with GraphQL-powered on-device caching ([React](https://www.apollographql.com/docs/react?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme), [iOS](https://www.apollographql.com/docs/ios?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme), [Kotlin](https://www.apollographql.com/docs/kotlin?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme))
-- [**Apollo Connectors**](https://www.apollographql.com/connectors?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Compose all your GraphQL and REST APIs into one GraphQL endpoint
-- [**Apollo MCP Server**](https://www.apollographql.com/ai?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- AI needs APIs. The fastest way to ship reliable AI experiences
+- [**Apollo Connectors**](https://www.apollographql.com/graphos/apollo-connectors?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Compose all your GraphQL and REST APIs into one GraphQL endpoint
+- [**Apollo MCP Server**](https://www.apollographql.com/apollo-mcp-server?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- AI needs APIs. The fastest way to ship reliable AI experiences
 - [**Apollo Router**](https://www.apollographql.com/docs/router?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Scale your APIs seamlessly with GraphQL Federation, Security, Auth, and more
 - [**GraphOS**](https://www.apollographql.com/graphos?utm_source=github&utm_medium=apollographql_apollo-client&utm_campaign=readme) \- Deploy, manage, govern, and explore your APIs ([start for free, no credit card needed](https://www.apollographql.com/pricing?utm_medium=github&utm_source=apollographql_apollo-client&utm_campaign=readme))
 
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -1,6 +1,6 @@
 # 🔮 Apollo Client Ecosystem Roadmap
 
-**Last updated: 2025-06-25**
+**Last updated: 2025-08-20**
 
 For up to date release notes, refer to the project's [Changelog](https://github.com/apollographql/apollo-client/blob/main/CHANGELOG.md).
 
@@ -17,13 +17,15 @@ For up to date release notes, refer to the project's [Changelog](https://github.
 
 ### Apollo Client
 
-#### 3.14.0 - July 7th, 2025
+#### 3.14.0 - August 21st, 2025
 
-_Release candidate - June 27th, 2025_
+_Release candidate - July 7th, 2025_
 
 - 4.0 compatibility release/deprecations
 
-#### [4.0.0](https://github.com/apollographql/apollo-client/milestone/31) - July 31st, 2025
+To be released together with 4.0.
+
+#### [4.0.0](https://github.com/apollographql/apollo-client/milestone/31) - August 21st, 2025
 
 _Release candidate - June 18th 2025_
 
diff --git a/docs/source/caching/cache-field-behavior.mdx b/docs/source/caching/cache-field-behavior.mdx
@@ -575,22 +575,44 @@ const cache = new InMemoryCache({
 });
 ```
 
-### Disabling `merge` functions
+### Opting in to the default behavior for non-normalized fields
 
-In some cases, you might want to completely disable merge functions for certain fields. To do so, pass `merge: false` like so:
+Apollo Client replaces existing data with incoming data for non-normalized fields by default. When this happens, you will encounter console warnings like "Cache data may be lost when...", even when the default behavior is desirable. You can tell Apollo Client you want this behavior by passing `merge: false` to a field's `FieldPolicy`. By opting into this behavior, the console warning is no longer emitted:
 
-```ts {13}
+```ts {6}
 const cache = new InMemoryCache({
   typePolicies: {
-    Book: {
+    Author: {
       fields: {
-        // No longer necessary!
-        // author: {
-        //   merge: true,
-        // },
-      },
-    },
+        books: {
+          merge: false,
+        }
+      }
+    }
+  },
+});
+```
 
+In some cases, you might want the same behavior for all occurrences of a particular type. To do so, pass `merge: false` to the type policy for that type like so:
+
+```ts {19}
+const cache = new InMemoryCache({
+  typePolicies: {
+    // No longer necessary!
+    // Article: {
+    //   fields: {
+    //     author: {
+    //       merge: false,
+    //     },
+    //   },
+    // },
+    // Book: {
+    //   fields: {
+    //     author: {
+    //       merge: false,
+    //     },
+    //   },
+    // },
     Author: {
       merge: false,
     },
diff --git a/src/cache/inmemory/__tests__/policies.ts b/src/cache/inmemory/__tests__/policies.ts
@@ -669,6 +669,81 @@ describe("type policies", function () {
     ).toBe('DeathAdder:{"tagId":"LethalAbacus666"}');
   });
 
+  it("specific field policies will not override supertype policies", () => {
+    const cache = new InMemoryCache({
+      typePolicies: {
+        Named: {
+          fields: Object.freeze({
+            name: Object.freeze({
+              read(existing: any) {
+                return existing + " (Named)";
+              },
+            }),
+          }),
+        },
+        Person: {
+          fields: {
+            name: {
+              read(existing) {
+                return existing + " (Person)";
+              },
+            },
+          },
+        },
+      },
+      possibleTypes: {
+        Named: ["Person", "Pet"],
+      },
+    });
+    const query = gql`
+      {
+        me {
+          __typename
+          id
+          name
+          pets {
+            __typename
+            id
+            name
+          }
+        }
+      }
+    `;
+    cache.writeQuery({
+      query,
+      data: {
+        me: {
+          __typename: "Person",
+          id: 23,
+          name: "John Doe",
+          pets: [
+            {
+              __typename: "Pet",
+              id: 1,
+              name: "Fido",
+            },
+            {
+              __typename: "Pet",
+              id: 2,
+              name: "Whiskers",
+            },
+          ],
+        },
+      },
+    });
+    expect(cache.readQuery({ query })).toEqual({
+      me: {
+        __typename: "Person",
+        id: 23,
+        name: "John Doe (Person)",
+        pets: [
+          { __typename: "Pet", id: 1, name: "Fido (Named)" },
+          { __typename: "Pet", id: 2, name: "Whiskers (Named)" },
+        ],
+      },
+    });
+  });
+
   it("typePolicies can be inherited from supertypes with fuzzy possibleTypes", () => {
     const cache = new InMemoryCache({
       possibleTypes: {
diff --git a/src/cache/inmemory/inMemoryCache.ts b/src/cache/inmemory/inMemoryCache.ts
@@ -106,6 +106,9 @@ export class InMemoryCache extends ApolloCache {
   private resetResultCache() {
     const { fragments } = this.config;
 
+    this.addTypenameTransform.resetCache();
+    fragments?.resetCaches();
+
     // The StoreWriter is mostly stateless and so doesn't really need to be
     // reset, but it does need to have its writer.storeReader reference updated,
     // so it's simpler to update this.storeWriter as well.
@@ -297,8 +300,6 @@ export class InMemoryCache extends ApolloCache {
   }) {
     canonicalStringify.reset();
     print.reset();
-    this.addTypenameTransform.resetCache();
-    this.config.fragments?.resetCaches();
     const ids = this.optimisticData.gc();
     if (options && !this.txCount && options.resetResultCache) {
       this.resetResultCache();
diff --git a/src/cache/inmemory/policies.ts b/src/cache/inmemory/policies.ts
diff --git a/src/testing/react/MockedProvider.tsx b/src/testing/react/MockedProvider.tsx

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@apollo/client": minor
 +---
++
 +Add deprecations and warnings to remaining APIs changed in Apollo Client 4.0.