Fix partial/complete data values for incremental responses, especially when combined with returnPartialData

.api-reports/api-report-utilities_internal.api.md

@@ -14,6 +14,7 @@ import { ErrorLike } from '@apollo/client';
 import type { FieldNode } from 'graphql';
 import type { FormattedExecutionResult } from 'graphql';
 import type { FragmentDefinitionNode } from 'graphql';
+import type { FragmentSpreadNode } from 'graphql';
 import type { GraphQLFormattedError } from 'graphql';
 import type { HKT } from '@apollo/client/utilities';
 import type { Incremental } from '@apollo/client/incremental';
@@ -85,6 +86,21 @@ export type ClassicSignature = SignatureStyle extends "classic" ? unknown : neve
 // @internal @deprecated
 export function cloneDeep<T>(value: T): T;
 
+// @public (undocumented)
+interface CollectionContext {
+    // (undocumented)
+    exclude: SelectionNode;
+    // Warning: (ae-incompatible-release-tags) The symbol "fragmentMap" is marked as @public, but its signature references "FragmentMap" which is marked as @internal
+    //
+    // (undocumented)
+    fragmentMap: FragmentMap;
+}
+
+// Warning: (ae-forgotten-export) The symbol "CollectionContext" needs to be exported by the entry point index.d.ts
+//
+// @internal @deprecated
+export function collectSiblingFields(selectionSet: SelectionSetNode, context: CollectionContext, visitedFragments?: Map<string, FieldMap>): FieldMap;
+
 // @public
 export function combineLatestBatched<T>(observables: Array<Observable<T> & {
     dirty?: boolean;
@@ -221,6 +237,11 @@ export interface ExtensionsWithStreamInfo extends Record<string, unknown> {
     };
 }
 
+// @public (undocumented)
+export type FieldMap = {
+    [fieldName: string]: FieldMap | true;
+};
+
 // @public (undocumented)
 export function filterMap<T, R>(fn: (value: T, context: undefined) => R | undefined): OperatorFunction<T, R>;
 
@@ -368,6 +389,9 @@ export type IsAny<T> = 0 extends 1 & T ? true : false;
 // @internal @deprecated
 export const isArray: (a: any) => a is any[] | readonly any[];
 
+// @public (undocumented)
+export function isDeferredFragment(fragmentSelection: InlineFragmentNode | FragmentSpreadNode, variables: OperationVariables): boolean;
+
 // @internal @deprecated (undocumented)
 export function isDocumentNode(value: unknown): value is DocumentNode;
 
@@ -390,6 +414,9 @@ export function isNonNullObject(obj: unknown): obj is Record<string | number, an
 // @internal @deprecated (undocumented)
 export function isPlainObject(obj: unknown): obj is Record<string | number, any>;
 
+// @public (undocumented)
+export function isTypenameField(field: FieldNode): boolean;
+
 // @public
 export type LazyType<T> = T & {
     [K in "" as never]: LazyType<never>;

.changeset/angry-baboons-decide.md

@@ -0,0 +1,97 @@
+---
+"@apollo/client": minor
+---
+
+Fix the accuracy of `dataState` in complex incremental streaming scenarios, especially when combined with `returnPartialData: true`.
+
+Prior to this change, all intermediate chunks used for both `@defer` and `@stream` directives returned a `dataState` of `streaming`, regardless of whether the actual data shape fit the definition of the `streaming` data state. The `streaming` data state represents an incomplete incremental response where the only holes in the data occur at `@defer` boundaries.
+
+Let's use the following example of where the previous `dataState` fell down when combined with `returnPartialData`.
+
+```gql
+query GreetingQuery {
+  greeting {
+    message
+    ... @defer {
+      recipient {
+        name
+        email
+      }
+    }
+  }
+}
+```
+
+1. Scenario 1: partial data inside a `@defer` boundary written to the cache
+
+Let's say the cache contained the following partial data:
+
+```ts
+{
+  greeting: {
+    __typename: "Greeting",
+    recipient: {
+      __typename: "Person",
+      name: "John Doe",
+    },
+  },
+};
+```
+
+After the first chunk arrives from the server, the data looks like the following:
+
+```ts
+{
+  greeting: {
+    __typename: "Greeting",
+    message: "Hello, John",
+    recipient: {
+      __typename: "Person",
+      name: "John Doe",
+    },
+  },
+};
+```
+
+This data is not `complete` because `recipient.email` is missing. This data is also not `streaming` because the data requirements in the `@defer` boundary are partially fulfilled due to the existence of `recipient`. This could lead to runtime crashes on `recipient.email` if you use the existence of `recipient` to detect whether data in the `@defer` boundary has streamed in or not. This change now accurately reports this as `partial` to ensure the field is marked as a partial field in `recipient`.
+
+2. Scenario 2: partial data written to the cache that fulfills the data requirements of the `@defer` boundary
+
+Let's say the cache contained the following partial data:
+
+```ts
+{
+  greeting: {
+    __typename: "Greeting",
+    recipient: {
+      __typename: "Person",
+      name: "John Doe",
+      email: "john@example.com",
+    },
+  },
+};
+```
+
+After the first chunk arrives from the server, the data looks like the following:
+
+```ts
+{
+  greeting: {
+    __typename: "Greeting",
+    message: "Hello, John",
+    recipient: {
+      __typename: "Person",
+      name: "John Doe",
+      email: "john@example.com",
+    },
+  },
+};
+```
+
+In this case, the combination of the first chunk and the partial data in the cache now fulfills the data requirements of the query. Even though the server is still streaming data (`NetworkStatus.streaming`), we can report this as `dataState: "complete"` since it is safe to access data on all fields.
+
+This change also means `@stream` queries by definition fulfill the data requirements of the query after the first chunk arrives since `@stream` operates on lists and contains no data holes. `@stream` queries now accurately report `dataState` as `complete` or `partial`, depending on whether the list mixes partial data with streamed list items.
+
+As a result of this change, some cases where you'd previously see `dataState` reported as `"streaming"` are now reported as `partial` or `complete`.
+
+If you use `dataState` to determine whether an incremental request is still in-flight, please use `networkStatus` instead to check for `NetworkStatus.streaming`. `dataState` is type narrowing feature and not intended to report the network status.

.changeset/fast-geckos-help.md

@@ -0,0 +1,34 @@
+---
+"@apollo/client": patch
+---
+
+Fix an issue where field `read` functions were not applied to intermediate results while streaming `@defer` responses. `cache.diff` ran the `read` functions, but the transformed values were only applied to the emitted result when the updated cache result was considered complete. Intermediate chunks whose only holes were at `@defer` boundaries now correctly return the result of field `read` functions.
+
+```ts
+new InMemoryCache({
+  typePolicies: {
+    Greeting: {
+      fields: {
+        message: {
+          read: (message) => message.toUpperCase(),
+        },
+      },
+    },
+  },
+});
+
+// query GreetingQuery {
+//   greeting {
+//     message
+//     ... @defer {
+//       recipient { name }
+//     }
+//   }
+// }
+
+// First chunk previously returned:
+// { greeting: { message: "Hello world" } }
+//
+// Now correctly returns while still streaming:
+// { greeting: { message: "HELLO WORLD" } }
+```

.changeset/serious-bugs-move.md

@@ -0,0 +1,7 @@
+---
+"@apollo/client": patch
+---
+
+Fix an issue with `@stream` queries when using `returnPartialData: true` where the streamed list was truncated after the first incremental chunk when the list contained partial cache data. The list is no longer truncated and partial list items are now retained as incremental chunks arrive. The `dataState` is now reported as `partial` until the server has streamed enough of the list so that each list item fully satisfies the query.
+
+This change also updates `@stream` queries so that they reported with `dataState: "complete` instead of `"streaming"` since it is safe to access all fields in the response.

.size-limits.json

@@ -1,6 +1,6 @@
 {
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 48863,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 43151,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 36730,
-  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 30145
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (CJS)": 49697,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production) (CJS)": 43842,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\"": 37288,
+  "import { ApolloClient, InMemoryCache, HttpLink } from \"@apollo/client\" (production)": 30735
 }

src/__tests__/__snapshots__/exports.ts.snap

@@ -445,6 +445,7 @@ Array [
   "canonicalStringify",
   "checkDocument",
   "cloneDeep",
+  "collectSiblingFields",
   "combineLatestBatched",
   "compact",
   "createFragmentMap",
@@ -474,11 +475,13 @@ Array [
   "hasDirectives",
   "hasForcedResolvers",
   "isArray",
+  "isDeferredFragment",
   "isDocumentNode",
   "isField",
   "isNonEmptyArray",
   "isNonNullObject",
   "isPlainObject",
+  "isTypenameField",
   "makeReference",
   "makeUniqueId",
   "mapObservableFragmentMemoized",

src/core/ObservableQuery.ts

@@ -1009,10 +1009,7 @@ Did you mean to call refetch(variables) instead of refetch({ variables })?`,
                         // will be overwritten anyways, just here for types sake
                         loading: false,
                         data: diff.result,
-                        dataState:
-                          fetchMoreResult.dataState === "streaming" ?
-                            "streaming"
-                          : "complete",
+                        dataState: diff.complete ? "complete" : "streaming",
                       },
                     });
                   }