fix(masking): preserve referential equality of masked data on refetch

When `dataMasking: true` is configured, `maskOperation` always creates new
object references for masked data (since fragment fields are stripped). This
breaks referential equality on refetch with identical results, causing
unnecessary useEffect callbacks and re-renders.

Memoize the masked output in `ObservableQuery.maskResult` so that if the
input data reference is unchanged or the masked result is deeply equal to
the previous one, the previous masked reference is reused.

Fixes #13181

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: audrius-sav

.changeset/fix-masked-data-referential-equality.md

@@ -0,0 +1,5 @@
+---
+"@apollo/client": patch
+---
+
+fix(masking): preserve referential equality of masked data on refetch with identical results

src/core/ObservableQuery.ts

@@ -1723,6 +1723,13 @@ Did you mean to call refetch(variables) instead of refetch({ variables })?`,
     return this.queryManager.transform(document);
   }
 
+  /** The `result.data` input from the last `maskResult` call, used to
+   * short-circuit re-masking when the cache returns the same reference. */
+  private lastMaskedInput: any = undefined;
+  /** The masked output from the last `maskResult` call, reused when the new
+   * masked result is deeply equal to preserve referential equality. */
+  private lastMaskedResult: any = undefined;
+
   private maskResult<T extends { data: any }>(result: T): T {
     const masked = this.queryManager.maskOperation({
       document: this.query,
@@ -1732,7 +1739,22 @@ Did you mean to call refetch(variables) instead of refetch({ variables })?`,
     });
 
     // Maintain object identity as much as possible
-    return masked === result.data ? result : { ...result, data: masked };
+    if (masked === result.data) return result;
+
+    // Preserve referential equality of masked data when the underlying
+    // cache data hasn't changed (same reference) or when the masked
+    // output is deeply equal to the previous one.
+    if (
+      this.lastMaskedResult !== undefined &&
+      (result.data === this.lastMaskedInput ||
+        equal(masked, this.lastMaskedResult))
+    ) {
+      return { ...result, data: this.lastMaskedResult };
+    }
+
+    this.lastMaskedInput = result.data;
+    this.lastMaskedResult = masked;
+    return { ...result, data: masked };
   }
 
   private dirty: boolean = false;

src/react/hooks/__tests__/useQuery.test.tsx

@@ -11871,6 +11871,122 @@ describe("useQuery Hook", () => {
         });
       }
     });
+
+    // https://github.com/apollographql/apollo-client/issues/13181
+    it("preserves referential equality of masked data on refetch with identical results", async () => {
+      type UserFieldsFragment = {
+        __typename: "User";
+        age: number;
+      } & { " $fragmentName"?: "UserFieldsFragment" };
+
+      interface Query {
+        currentUser: {
+          __typename: "User";
+          id: number;
+          name: string;
+        } & { " $fragmentRefs"?: { UserFieldsFragment: UserFieldsFragment } };
+      }
+
+      const query: TypedDocumentNode<Query, Record<string, never>> = gql`
+        query MaskedQuery {
+          currentUser {
+            id
+            name
+            ...UserFields
+          }
+        }
+
+        fragment UserFields on User {
+          age
+        }
+      `;
+
+      const mocks = [
+        {
+          request: { query },
+          result: {
+            data: {
+              currentUser: {
+                __typename: "User",
+                id: 1,
+                name: "Test User",
+                age: 30,
+              },
+            },
+          },
+        },
+        {
+          request: { query },
+          result: {
+            data: {
+              currentUser: {
+                __typename: "User",
+                id: 1,
+                name: "Test User",
+                age: 30,
+              },
+            },
+          },
+        },
+      ];
+
+      const client = new ApolloClient({
+        dataMasking: true,
+        cache: new InMemoryCache(),
+        link: new MockLink(mocks),
+      });
+
+      const renderStream =
+        createRenderStream<useQuery.Result<Query, Record<string, never>>>();
+
+      function App() {
+        const result = useQuery(query);
+
+        renderStream.replaceSnapshot(result);
+
+        return null;
+      }
+
+      using _disabledAct = disableActEnvironment();
+      await renderStream.render(<App />, {
+        wrapper: ({ children }) => (
+          <ApolloProvider client={client}>{children}</ApolloProvider>
+        ),
+      });
+
+      // loading
+      await renderStream.takeRender();
+
+      const { snapshot: initialSnapshot } = await renderStream.takeRender();
+
+      expect(initialSnapshot.data).toStrictEqual({
+        currentUser: {
+          __typename: "User",
+          id: 1,
+          name: "Test User",
+        },
+      });
+
+      // Trigger refetch with identical result
+      await initialSnapshot.refetch();
+
+      // Skip intermediate renders (e.g. NetworkStatus.refetch) and find
+      // the settled result
+      let refetchSnapshot;
+      while (true) {
+        const { snapshot } = await renderStream.takeRender();
+        if (snapshot.networkStatus === NetworkStatus.ready) {
+          refetchSnapshot = snapshot;
+          break;
+        }
+      }
+
+      // The masked data should be the same reference since the underlying
+      // data hasn't changed
+      expect(refetchSnapshot.data).toBe(initialSnapshot.data);
+
+      await expect(renderStream).not.toRerender();
+    });
   });
 
   // https://github.com/apollographql/apollo-client/issues/12229