Add array support to `useFragment`, `useSuspenseFragment`, and `client.watchFragment` by jerelmiller · Pull Request #12971 · apollographql/apollo-client

jerelmiller · 2025-10-13T19:42:59Z

Closes apollographql/apollo-feature-requests#452
Closes apollographql/apollo-feature-requests#358

Add support for lists with useFragment, useSuspenseFragment, and client.watchFragment.

const result = useFragment({
  fragment,
  from: [item1, item2]
});

console.log(result); // { data: [{...}, {...}], dataState: "complete", complete: true }

changeset-bot · 2025-10-13T19:43:03Z

🦋 Changeset detected

Latest commit: bc06591

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-10-13T19:43:59Z

✅ Docs preview ready

The preview is ready to be viewed. View the preview

File Changes

0 new, 11 changed, 0 removed

* (developer-tools)/react/(latest)/caching/cache-configuration.mdx
* (developer-tools)/react/(latest)/data/fragments.mdx
* (developer-tools)/react/(latest)/data/mutations.mdx
* (developer-tools)/react/(latest)/data/persisted-queries.mdx
* (developer-tools)/react/(latest)/data/queries.mdx
* (developer-tools)/react/(latest)/development-testing/testing.mdx
* (developer-tools)/react/(latest)/integrations/react-native.mdx
* (developer-tools)/react/(latest)/migrating/apollo-client-4-migration.mdx
* (developer-tools)/react/(latest)/performance/server-side-rendering.mdx
* (developer-tools)/react/(latest)/VERSIONING_POLICY.md
* (developer-tools)/react/(latest)/versioning-policy.md

Build ID: 102daf5dcb2399ff53151d2e
Build Logs: View logs

URL: https://www.apollographql.com/docs/deploy-preview/102daf5dcb2399ff53151d2e

pkg-pr-new · 2025-10-13T19:44:33Z

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

commit: 209c1f8

src/react/hooks/useFragment.ts

src/cache/core/cache.ts

jerelmiller · 2025-10-24T01:01:58Z

src/core/__tests__/client.watchFragment/general.test.ts

+    link: ApolloLink.empty(),
+  });
+
+  const observable = client.watchFragment({


Should we complete the observable if its the from: null observable?

I think we should keep it the same for all calls to watchFragment, so never-completing. I can imagine someone resubscribing in an infinite loop or something similar otherwise.

Copilot

Pull Request Overview

This PR adds array support to useFragment, useSuspenseFragment, and client.watchFragment, allowing developers to watch multiple fragment entities simultaneously. The from option now accepts arrays, returning an array of data where each index corresponds to the from array index.

Key changes:

Added combineLatestBatched utility for efficient Observable batching
Enhanced fragment watching to support arrays with proper type inference
Added getCurrentResult method to fragment observables

Reviewed Changes

Copilot reviewed 38 out of 39 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/utilities/internal/combineLatestBatched.ts	New utility for batching observable updates from array items sharing the same observable
src/utilities/DeepPartial.ts	Removed `undefined` from array item types in `DeepPartial`
src/cache/core/cache.ts	Core implementation of array support for `watchFragment` with deduplication and batching
src/core/ApolloClient.ts	Added overloads and `getCurrentResult` method for `watchFragment`
src/react/hooks/useFragment.ts	Refactored to use `watchFragment` observable with array support
src/react/hooks/useSuspenseFragment.ts	Added array support with suspense behavior
src/testing/matchers/*.ts	New test matchers for fragment watches validation
docs/source/data/fragments.mdx	Documentation updates for array support

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/utilities/internal/combineLatestBatched.ts

Copilot · 2025-10-24T09:05:00Z

src/cache/core/cache.ts

+          // Unfortunately we forgot to allow for `null` on watchFragment in 4.0
+          // when `from` is a single record. As such, we need to fallback to {}
+          // when diff.result is null to maintain backwards compatibility. We
+          // should plan to change this in v5. We do howeever support `null` if
+          // `from` is explicitly `null`.
+          //
+          // NOTE: Using `from` with an array will maintain `null` properly
+          // without the need for a similar fallback since watchFragment with
+          // arrays is new functionality in v4.


[nitpick] The backwards compatibility fallback (?? {}) for non-null from values deserves a more prominent comment explaining why this behavior differs from the array case and when it can be removed (v5).

Suggested change

// Unfortunately we forgot to allow for `null` on watchFragment in 4.0

// when `from` is a single record. As such, we need to fallback to {}

// when diff.result is null to maintain backwards compatibility. We

// should plan to change this in v5. We do howeever support `null` if

// `from` is explicitly `null`.

//

// NOTE: Using `from` with an array will maintain `null` properly

// without the need for a similar fallback since watchFragment with

// arrays is new functionality in v4.

// TODO(v5): Remove backwards compatibility fallback for non-null `from` values.

// In Apollo Client v4, we did not allow `null` for watchFragment when `from` is a single record.

// To maintain backwards compatibility, we fallback to `{}` when `diff.result` is `null` and `from` is not `null`.

// This differs from the array case (new in v4), which properly supports `null` values and does not require this fallback.

// The fallback can be removed in v5, at which point `null` will be returned for `diff.result` when appropriate.

// If `from` is explicitly `null`, we do support returning `null` as the result.

phryneas · 2025-10-24T09:21:40Z

src/core/ApolloClient.ts

+    let currentResult: ApolloClient.WatchFragmentResult<any>;
+    let stableMaskedResult: ApolloClient.WatchFragmentResult<any>;
+
+    return Object.assign(observable.pipe(map(mask)), {


Could it be that we need another distinctUntilChanged here?
In dev, something could change upstream and then be filtered out, resulting in a "no change" situation.
In that case, the tracking of currentResult below might also not be enough.

something could change upstream and then be filtered out, resulting in a "no change" situation.

Just to clarify, by "upstream" do you mean data that changes in a nested fragment that would otherwise be masked?

I think this is covered by the document transform we apply to the fragment document before passing it to cache.watchFragment. That transform removes any fragment spreads without @unmask from the fragment document, resulting in only a document that includes fields that we care to watch. The maskFragment in __DEV__ is only to handle @unmask(mode: "migrate") where we want to apply warnings on field access.

Ah, good call. For some reason I had assumed that we would only filter down the fragment in non-DEV mode 🤦

src/utilities/internal/combineLatestBatched.ts

phryneas · 2025-10-24T10:03:38Z

src/core/__tests__/client.watchFragment/getCurrentResult.test.ts

+  });
+
+  // ensure it changes identity when a new value is emitted
+  expect(observable.getCurrentResult()).not.toBe(lastResult);


Can we have a test the other direction, too? Emit first, then call getCurrentResult, check for referential equality.

Do lines 209-214 cover that, or are you looking to check the value after its changed?

No, not covered yet. A bit unfortunate that the comment is only attached to this line, it was more a comment for the whole test :)

This test is "call getCurrentResult, subscribe, check referential equality". I'd like to have "subscribe, call getCurrentResult, check referential equality", too - doing things in the other direction and seeing them be referentially equal, too - both starting from a "new, unsubscribed" observable.

Added some more assertions to check that this 2nd emitted result is referentially stable with the value emitted from the observable: e677cfd

I tweaked the order of assertions in 6a2dc58 that get the result from the observable, then check it against getCurrentResult. I think this covers it?

src/core/__tests__/client.watchFragment/arrays.test.ts

phryneas

Looks good to me, let's get this out there 🚀

…t.watchFragment` (#12971) Co-authored-by: Lenz Weber-Tronic <[email protected]> Co-authored-by: jerelmiller <[email protected]>

jerelmiller added 6 commits October 13, 2025 12:54

Add failing tests for useFragment with lists

ae66ac9

Add initial pass implementation for useFragment with list

9f2e982

Update type test

1d52bea

Remove unneeded null return

ce739a5

Fix incorrect assertions

e5f722b

Ensure array changes identities to rerender updated data

314c248

jerelmiller commented Oct 13, 2025

View reviewed changes

src/react/hooks/useFragment.ts Outdated Show resolved Hide resolved

jerelmiller added 17 commits October 13, 2025 15:28

Add overloads for client/cache.watchFragment

93d3876

Handle masking

a29e004

Add failing list tests for watchFragment

87c09f0

Add first implementation in core

607d149

Don't allow for reobserve

4906e6a

Fix incorrect application of data masking in client.watchFragment

c73fb8f

Warn on invalid id sooner

456c372

Allow from as null internally in client.watchFragment

e9bb759

Switch to client.watchFragment with from array in useFragment

6b3d53d

Add tests for getCurrentResult

bb76dbe

Add getCurrentResult to watchFragment result

e5ef39e

Update test

7b6701e

Move comment down

326c76a

Use observable.getCurrentResult in useFragment

39a5300

Emit stable value to maintain referential equality

57a26f0

Move observable to useMemo

28ab461

Combine useDeepMemos

290c497

phryneas reviewed Oct 14, 2025

View reviewed changes

src/cache/core/cache.ts Show resolved Hide resolved

jerelmiller added 2 commits October 14, 2025 12:27

Rename lastResult to currentResult

6472131

Cast to any for now

ffbecf4

jerelmiller added 6 commits October 23, 2025 18:28

Update api report

2a71d7a

Remove some type casts

5f19e33

Remove another type cast

a323f05

Add doc blocks

3d671d3

Tweak changeset

8336a20

Add changeset

ca42b1f

jerelmiller commented Oct 24, 2025

View reviewed changes

phryneas requested a review from Copilot October 24, 2025 09:04

Copilot AI reviewed Oct 24, 2025

View reviewed changes

jerelmiller added the auto-cleanup 🤖 label Oct 24, 2025

phryneas and others added 2 commits October 24, 2025 09:29

batch array watchFragment notifications (#12980)

d7176be

Clean up Prettier, Size-limit, and Api-Extractor

40379c5

phryneas reviewed Oct 24, 2025

View reviewed changes

jerelmiller and others added 9 commits October 24, 2025 09:48

Make dirty an optional property with combineLatestBatched

e3ee16b

Fix typo

8f37ffa

Add more assertions

e677cfd

Tweak order of assertions

6a2dc58

Simplify math

9f56fa7

Use new Array(length)

56a372e

Clean up Prettier, Size-limit, and Api-Extractor

7b6e884

Add changeset

7ce25b3

Clean up Prettier, Size-limit, and Api-Extractor

3da2aed

phryneas approved these changes Oct 27, 2025

View reviewed changes

jerelmiller and others added 2 commits October 27, 2025 09:20

Merge branch 'release-4.1' into jerel/use-fragment-list

209c1f8

Clean up Prettier, Size-limit, and Api-Extractor

bc06591

jerelmiller merged commit d11eb40 into release-4.1 Oct 27, 2025
31 of 33 checks passed

jerelmiller deleted the jerel/use-fragment-list branch October 27, 2025 15:35

github-actions bot mentioned this pull request Oct 27, 2025

Version Packages (alpha) #12977

Merged

jerelmiller added a commit that referenced this pull request Nov 17, 2025

Add array support to useFragment, useSuspenseFragment, and `clien…

45ebb52

…t.watchFragment` (#12971) Co-authored-by: Lenz Weber-Tronic <[email protected]> Co-authored-by: jerelmiller <[email protected]>

github-actions bot locked as resolved and limited conversation to collaborators Nov 27, 2025

Conversation

jerelmiller commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Oct 13, 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 Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Docs preview ready

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Copilot AI Oct 24, 2025

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!

phryneas Oct 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

phryneas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jerelmiller commented Oct 13, 2025 •

edited

Loading

changeset-bot bot commented Oct 13, 2025 •

edited

Loading

apollo-librarian bot commented Oct 13, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 13, 2025 •

edited

Loading

phryneas Oct 24, 2025 •

edited

Loading