perf: defer MissingFieldError construction and avoid JSON.stringify in cache diff (#13329)

Fixes #13305.
## Problem
Two expensive operations run eagerly on the cache-diff hot path even
when the caller only checks `diff.complete` (a cheap boolean):
1. **`JSON.stringify(objectOrReference, null, 2)`** — pretty-prints the
full parent object for every missing-field message, scaling with object
size.
2. **`new MissingFieldError(...)`** — constructs an `Error` subclass
(paying V8 stack capture) per incomplete diff, even though
`diff.missing` is only consumed in `__DEV__`-guarded logging on most
call paths.
## Solution
- **Cheap messages:** Replaced the `JSON.stringify` with a `__typename`
lookup. Embedded parents now produce `"object Profile"` instead of the
full pretty-printed object dump.
- **Lazy errors:** `diffQueryAgainstStore` now derives `diff.complete`
from the raw `execResult.missing` tree (a `MissingTree`). The
`MissingFieldError` is built lazily via a getter, only when
`diff.missing` is actually accessed. The getter caches the result so
repeated access is cheap.
All three consumers of `diff.missing` are safe — two are
`__DEV__`-guarded, one is a legitimate `watchFragment` consumer. The hot
`broadcastWatch` path only compares `diff.result` with `equal()`, so the
getter is never triggered by property enumeration.
## Changes
| File | Change |
|------|--------|
| `src/cache/inmemory/readFromStore.ts` | Cheap missing-field message +
lazy `MissingFieldError` getter |
| `src/cache/inmemory/__tests__/readFromStore.ts` | 2 new tests + 3
existing assertions updated |
| `src/cache/inmemory/__tests__/diffAgainstStore.ts` | 1 assertion
updated |
| `src/cache/inmemory/__tests__/policies.ts` | 1 assertion updated |
| `.changeset/lazy-diff-diagnostics.md` | Patch-level changeset |
### Checklist:
- [x] Includes a changeset
- [x] Significant new logic is covered by tests
- [ ] ~~New feature~~ (not applicable — performance fix for existing
behavior)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Performance**
- Improved cache diff performance by avoiding unnecessary serialization
of stored objects.
  - Missing-field diagnostics are now generated only when requested.

- **Bug Fixes**
- Improved missing-field error messages with shorter, more relevant
object descriptions.
- Cache completeness is now reported accurately without requiring full
error construction.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: DeepSeek V4 Pro agent <agent@atlarix.dev>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Jerel Miller <jerelmiller@gmail.com>

Author: 4 people

.changeset/lazy-diff-diagnostics.md

@@ -0,0 +1,7 @@
+---
+"@apollo/client": patch
+---
+
+Cache diffs for incomplete queries no longer pay the cost of building a full `MissingFieldError` when the `missing` property is not accessed. The error object is now only constructed when the `missing` property is accessed the first time. This improves performance by avoiding a V8 stack capture when `missing` is ignored entirely.
+
+As an additional small performance improvement, `JSON.stringify` is no longer used in the error message on objects whose cache ID is known. `JSON.stringify` is only used for non-normalized objects.

src/cache/inmemory/__tests__/readFromStore.ts

@@ -1612,12 +1612,12 @@ describe("reading from the store", () => {
         ],
       },
       missing: new MissingFieldError(
-        "Can't find field 'id' on object undefined",
+        "Can't find field 'id' on object {}",
         {
           ducks: {
             2: {
-              id: "Can't find field 'id' on object undefined",
-              quacking: "Can't find field 'quacking' on object undefined",
+              id: "Can't find field 'id' on object {}",
+              quacking: "Can't find field 'quacking' on object {}",
             },
           },
         },
@@ -2178,3 +2178,125 @@ describe("reading from the store", () => {
     expect(result2.abc).toBe(abc);
   });
 });
+
+describe("lazy MissingFieldError diagnostics", () => {
+  it("only constructs MissingFieldError when diff.missing is accessed", () => {
+    const cache = new InMemoryCache();
+
+    const fullQuery = gql`
+      query {
+        customer {
+          id
+          name
+          address {
+            street
+            city
+          }
+        }
+      }
+    `;
+
+    const partialQuery = gql`
+      query {
+        customer {
+          id
+        }
+      }
+    `;
+
+    cache.writeQuery({
+      query: partialQuery,
+      data: {
+        customer: {
+          __typename: "Customer",
+          id: "c1",
+        },
+      },
+    });
+
+    const diff = cache.diff({
+      query: fullQuery,
+      returnPartialData: true,
+      optimistic: true,
+    });
+
+    // @ts-ignore
+    const missingSpy = jest.spyOn(diff, "missing", "get");
+    expect(missingSpy).not.toHaveBeenCalled();
+
+    // diff.missing should be lazily constructed only when accessed
+    expect(diff.missing).toEqual(
+      new MissingFieldError(
+        "Can't find field 'name' on Customer:c1 object",
+        {
+          customer: {
+            name: "Can't find field 'name' on Customer:c1 object",
+            address: "Can't find field 'address' on Customer:c1 object",
+          },
+        },
+        fullQuery,
+        {}
+      )
+    );
+
+    expect(missingSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it("missing message uses JSON.stringify for non-normalized embedded parents", () => {
+    const cache = new InMemoryCache();
+
+    const query = gql`
+      query {
+        profile {
+          bio
+          largeField
+        }
+      }
+    `;
+
+    cache.writeQuery({
+      query: gql`
+        query {
+          profile {
+            bio
+          }
+        }
+      `,
+      data: {
+        profile: {
+          __typename: "Profile",
+          bio: "a".repeat(10),
+        },
+      },
+    });
+
+    const diff = cache.diff({
+      query,
+      returnPartialData: true,
+      optimistic: true,
+    });
+
+    const message = `Can't find field 'largeField' on object ${JSON.stringify(
+      { __typename: "Profile", bio: "a".repeat(10) },
+      null,
+      2
+    )}`;
+
+    expect(diff).toStrictEqualTyped({
+      result: {
+        profile: { __typename: "Profile", bio: "a".repeat(10) },
+      },
+      complete: false,
+      missing: new MissingFieldError(
+        message,
+        {
+          profile: {
+            largeField: message,
+          },
+        },
+        query,
+        {}
+      ),
+    });
+  });
+});

src/cache/inmemory/readFromStore.ts

@@ -224,18 +224,10 @@ export class StoreReader {
       },
     });
 
-    let missing: MissingFieldError | undefined;
-    if (execResult.missing) {
-      missing = new MissingFieldError(
-        firstMissing(execResult.missing)!,
-        execResult.missing,
-        query,
-        variables
-      );
-    }
+    const { result, missing: rawMissing } = execResult;
+    const complete = !rawMissing;
 
-    const complete = !missing;
-    const { result } = execResult;
+    let missingError: MissingFieldError | undefined;
 
     return {
       result:
@@ -246,7 +238,17 @@ export class StoreReader {
           : result
         : null,
       complete,
-      missing,
+      get missing() {
+        if (missingError === void 0 && rawMissing) {
+          missingError = new MissingFieldError(
+            firstMissing(rawMissing)!,
+            rawMissing,
+            query,
+            variables
+          );
+        }
+        return missingError;
+      },
     } as Cache.DiffResult<T>;
   }
 
@@ -338,11 +340,16 @@ export class StoreReader {
 
         if (fieldValue === void 0) {
           if (!addTypenameToDocument.added(selection)) {
+            const id =
+              isReference(objectOrReference) ? objectOrReference.__ref
+              : objectOrReference ? policies.identify(objectOrReference)[0]
+              : undefined;
+
             missing = missingMerger.merge(missing, {
               [resultName]: `Can't find field '${selection.name.value}' on ${
-                isReference(objectOrReference) ?
-                  objectOrReference.__ref + " object"
-                : "object " + JSON.stringify(objectOrReference, null, 2)
+                id ?
+                  `${id} object`
+                : `object ${JSON.stringify(objectOrReference || {}, null, 2)}`
               }`,
             });
           }