Improve handling of arrays in `@defer` and `@stream` payloads #12923

jerelmiller · 2025-09-15T22:04:18Z

Fixes issues where arrays returned in @defer payloads would maintain cached items when the defer array was shorter than the cached array. This change also affects @stream arrays so that when a @stream chunk is processed, it truncates the array to the length of the stream payload. This ensures the length of the final result equals the length of the server array, much like it would if a plain refetch were issued.

…rge behavior

…rging

…d/streamed lists

changeset-bot · 2025-09-15T22:04:22Z

🦋 Changeset detected

Latest commit: 059426e

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

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

apollo-librarian · 2025-09-15T22:05:16Z

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: 65998f1ed1f52cf86e6a07cb
Build Logs: View logs

pkg-pr-new · 2025-09-15T22:05:49Z

npm i https://pkg.pr.new/apollographql/apollo-client/@apollo/client@12923

commit: c496039

jerelmiller · 2025-09-15T22:07:18Z

.changeset/cold-kiwis-give.md

@@ -0,0 +1,5 @@
+---
+"@apollo/client": minor


I'm marking this as a minor change. While it does fix the array merging behavior, it's a big enough difference to warrant a minor.

jerelmiller · 2025-09-15T22:08:10Z

src/core/__tests__/client.watchQuery/defer20220824.test.ts

  expect(outgoingRequestSpy).toHaveBeenCalledTimes(2);
 });
+
+it.each([["cache-first"], ["no-cache"]] as const)(


These were added from #11374 (with some tweaks)

jerelmiller · 2025-09-15T22:08:27Z

src/core/__tests__/client.watchQuery/deferGraphQL17Alpha9.test.ts

  expect(outgoingRequestSpy).toHaveBeenCalledTimes(2);
 });
+
+it.each([["cache-first"], ["no-cache"]] as const)(


Added from #11374 (with some tweaks)

jerelmiller · 2025-09-15T22:10:33Z

src/core/__tests__/client.watchQuery/streamDefer20220824.test.ts

+      Query: {
+        fields: {
+          friendList: {
+            merge: (existing = [], incoming, { field }) => {


Should we consider exposing a utility function or helper of some kind to do this kind of thing? At the very least, we probably want to put something in our docs along with @stream that describes how to do this in your own code. This demonstrates that you can maintain the original cached items when using stream instead of default overwriting the array.

Let's document it first and figure out the perfect helper later.

jerelmiller · 2025-09-15T22:11:21Z

src/incremental/handlers/__tests__/defer20220824/stream.test.ts

        friendList: [
          { name: "Luke", id: "1" },
          { name: "Han", id: "2" },
-          { name: "Leia Cached", id: "3" },


This behavior will now rely on a merge function to keep the cached item if the user wishes.

jerelmiller · 2025-09-15T22:24:53Z

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

+        Query: {
+          fields: {
+            friendList: {
+              merge: (_, incoming) => incoming,


I added this here to silence the warning about data loss, but I think this might happen a lot with @stream since fetches against a @stream field will naturally return a shorter list than already-cached lists since the list is streamed in over time.

Should we consider muting the warning for @stream fields like we do for @defer? Or should we recommend adding these type policies to explicitly opt into the @stream behavior?

I'm more confused as why this would warrant a data loss warning in the first place, at least with the output we have here. It's just overwriting a reference array with a shorter reference array, without any real data loss?

console.warn Cache data may be lost when replacing the friendList field of a Query object. This could cause additional (usually avoidable) network requests to fetch data that were otherwise cached. To address this problem (which is not a bug in Apollo Client), define a custom merge function for the Query.friendList field, so InMemoryCache can safely merge these objects: existing: [ { __ref: 'Friend:1' }, { __ref: 'Friend:2' }, { __ref: 'Friend:3' }, [length]: 3 ] incoming: [ { __ref: 'Friend:1' }, [length]: 1 ] For more information about these options, please refer to the documentation: * Ensuring entity objects have IDs: https://go.apollo.dev/c/generating-unique-identifiers * Defining custom merge functions: https://go.apollo.dev/c/merging-non-normalized-objects

Discussed in person. We want to silence the warning if the field has an @stream directive on it, otherwise every @stream field will require a field policy which feels broken.

Let's put this on the table to discuss when you're back. Discovered something in the comments that make me think this might make sense. See

apollo-client/src/cache/inmemory/writeToStore.ts

Lines 863 to 864 in 6914a97

// Arrays do not have __typename fields, and always need a custom merge

// function, even if their elements are normalized entities.

Seems custom merge functions are always expected for array fields (something we should at least document). Again, let's discuss when you're back to get a final decision. For now I'm going to leave this as-is.

jerelmiller · 2025-09-15T22:51:47Z

src/utilities/internal/DeepMerger.ts

+export class DeepMerger<TContextArgs extends any[] = any[]> {
  constructor(
-    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>
+    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>,


Since this is an internal class, I know we are free to update the API so with that in mind... should reconciler be moved to options instead? Its a bit awkward in places where we need arrayMerge but not reconciler since you have to pass undefined as the first argument.

Thoughts on changing it so we can do:

new DeepMerger({ arrayMerge: 'truncate' });

?

We use reconciler exactly once in the codebase, so it won't change things around a lot. What do you think about just making it an option?

.changeset/cold-kiwis-give.md

phryneas · 2025-11-12T12:01:23Z

src/utilities/internal/DeepMerger.ts

+export class DeepMerger<TContextArgs extends any[] = any[]> {
  constructor(
-    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>
+    private reconciler: ReconcilerFunction<TContextArgs> = defaultReconciler as any as ReconcilerFunction<TContextArgs>,


We use reconciler exactly once in the codebase, so it won't change things around a lot. What do you think about just making it an option?

phryneas · 2025-11-12T12:27:54Z

src/incremental/handlers/defer20220824.ts

+            if (isNumericKey) {
+              arrayMerge = "combine";
+            }


This feels like a workaround that might explode into our face in some way at some point - e.g. when we'd want to truncate deeply nested, but a parent is an array.

Alternative suggestion: WDTY about adding an atPath option into DeepMerger?
The arrayMerge strategy should then only apply at the exact level where the new source is being inserted, with everything else always being treated as combine - and we would also save creating all these deeply nested objects just for the sake of merging, which will be thrown away after the merge anyways.

phryneas · 2025-11-12T13:44:23Z

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

+        Query: {
+          fields: {
+            friendList: {
+              merge: (_, incoming) => incoming,


I'm more confused as why this would warrant a data loss warning in the first place, at least with the output we have here. It's just overwriting a reference array with a shorter reference array, without any real data loss?

console.warn Cache data may be lost when replacing the friendList field of a Query object. This could cause additional (usually avoidable) network requests to fetch data that were otherwise cached. To address this problem (which is not a bug in Apollo Client), define a custom merge function for the Query.friendList field, so InMemoryCache can safely merge these objects: existing: [ { __ref: 'Friend:1' }, { __ref: 'Friend:2' }, { __ref: 'Friend:3' }, [length]: 3 ] incoming: [ { __ref: 'Friend:1' }, [length]: 1 ] For more information about these options, please refer to the documentation: * Ensuring entity objects have IDs: https://go.apollo.dev/c/generating-unique-identifiers * Defining custom merge functions: https://go.apollo.dev/c/merging-non-normalized-objects

phryneas · 2025-11-12T13:47:52Z

src/react/hooks/__tests__/useSuspenseQuery/streamDefer20220824.test.tsx

-          { __typename: "Friend", id: "2", name: "Han" },
-          { __typename: "Friend", id: "3", name: "Leia" },
-        ],
+        friendList: [{ __typename: "Friend", id: "1", name: "Luke (refetch)" }],


Tbh, for a refetch it feels as if it should be merged, not truncated. Or even better, truncated on the last chunk, not the first one. But I don't have a good idea on how to make that distinction.

For now I'm going to leave this, but let's make a final decision when you get back.

phryneas · 2025-11-12T13:51:14Z

src/core/__tests__/client.watchQuery/streamDefer20220824.test.ts

+      Query: {
+        fields: {
+          friendList: {
+            merge: (existing = [], incoming, { field }) => {


Let's document it first and figure out the perfect helper later.

Co-authored-by: Lenz Weber-Tronic <[email protected]>

jerelmiller added 23 commits September 12, 2025 17:12

Add array merge strategy to deep merger

0d96e4b

Default DeepMerger generic argument

ee7da21

WIP truncate merge arrays

6da0221

Check length before truncating

f9b8772

Add another test for truncate merge

108acd2

Add past copies instead of copying twice

bd60f05

Inline new merger

b156bef

Move type to namespace

138a110

Use dynamic array merge strategies

2c8180f

Use property type for array merge

b62fe24

Truncate arrays in defer20220824 handler

6a39f32

Update useBackgroundQuery tests to reflect updated nature on lists

43791bc

Combine array items if merging defer arrays

2cb8e98

Make graphql17Alpha9 more like Defer20220824 when determining arrayMe…

4bc8dd9

…rge behavior

Update useSuspenseQuery stream tests with updated behavior of list me…

121a646

…rging

Update spyOnConsole statement

e5cb816

Remove todo in useBackgroundQuery tests

0857af7

Update useQuery stream tests

cc80296

Remove unneeded arg

37979b9

Add test to ensure custom merge function can be used to combine cache…

34a29d2

…d/streamed lists

Add changeset

c826bc3

Update size limits

a506a89

Add tests for refetches with defer arrays

ff289b7

jerelmiller requested a review from phryneas September 15, 2025 22:04

jerelmiller mentioned this pull request Sep 15, 2025

Add test that shows a bug when merging deferred results for arrays. #11374

Closed

3 tasks

Fix changeset version type

c558fe5

jerelmiller commented Sep 15, 2025

View reviewed changes

jerelmiller mentioned this pull request Sep 15, 2025

Add support for @stream #12918

Merged

jerelmiller commented Sep 15, 2025

View reviewed changes

jerelmiller added 4 commits September 15, 2025 16:31

Print object as array in warning

04dbe02

Add changeset

1becedf

Update api report

0c156f1

Fix tag mix in api report

dd5eccb

jerelmiller commented Sep 15, 2025

View reviewed changes

This was referenced Sep 16, 2025

[3.9.5 but reproducible on latest] DeepMerger returns incorrect results when merging incremental arrays into existing data #12660

Open

Merging array in DeepMerger #11704

Open

jerelmiller force-pushed the jerel/stream-support branch from d071a61 to 096db02 Compare September 16, 2025 15:57

jerelmiller force-pushed the jerel/array-merge-strategy branch from 2a2fbc5 to 9b9d8aa Compare September 16, 2025 15:58

jerelmiller force-pushed the jerel/stream-support branch from 096db02 to b05df03 Compare September 16, 2025 16:02

jerelmiller force-pushed the jerel/array-merge-strategy branch 2 times, most recently from b41de5f to c496039 Compare September 16, 2025 16:32

github-actions bot mentioned this pull request Sep 17, 2025

Version Packages (alpha) #12928

Merged

phryneas reviewed Nov 12, 2025

View reviewed changes

jerelmiller force-pushed the jerel/stream-support branch from b05df03 to c785cc5 Compare November 14, 2025 22:34

jerelmiller force-pushed the jerel/array-merge-strategy branch 2 times, most recently from c8c950b to dd5eccb Compare November 14, 2025 22:45

jerelmiller changed the base branch from jerel/stream-support to release-4.1-baseline November 14, 2025 22:45

Fix typo

059426e

Co-authored-by: Lenz Weber-Tronic <[email protected]>

jerelmiller merged commit 94ea3e3 into release-4.1-baseline Nov 14, 2025
34 of 40 checks passed

jerelmiller deleted the jerel/array-merge-strategy branch November 17, 2025 21:45

	// Arrays do not have __typename fields, and always need a custom merge
	// function, even if their elements are normalized entities.

Improve handling of arrays in @defer and @stream payloads #12923

Improve handling of arrays in @defer and @stream payloads #12923

Uh oh!

Conversation

jerelmiller commented Sep 15, 2025

Uh oh!

changeset-bot bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

apollo-librarian bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview has no changes

Uh oh!

pkg-pr-new bot commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Improve handling of arrays in `@defer` and `@stream` payloads #12923

Improve handling of arrays in `@defer` and `@stream` payloads #12923

changeset-bot bot commented Sep 15, 2025 •

edited

Loading

apollo-librarian bot commented Sep 15, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 15, 2025 •

edited

Loading