@apollo/client 4.3.0-alpha.3 → 4.3.0-alpha.5

package/__cjs/core/ObservableQuery.d.cts

@@ -372,7 +372,18 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
     /**
      * A function that helps you fetch the next set of results for a [paginated list field](https://www.apollographql.com/docs/react/pagination/core-api/).
      */
-    fetchMore<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(options: ObservableQuery.FetchMoreOptions<TData, TVariables, TFetchData, TFetchVars>): Promise<ApolloClient.QueryResult<TFetchData>>;
+    fetchMore<TFetchData = TData, TFetchVars extends OperationVariables = TVariables, TErrorPolicy extends ErrorPolicy = "none">(options: ObservableQuery.FetchMoreOptions<TData, TVariables, TFetchData, TFetchVars> & {
+        /**
+        * Specifies how the query handles a response that returns both GraphQL errors and partial results.
+        * 
+        * For details, see [GraphQL error policies](https://www.apollographql.com/docs/react/data/error-handling/#graphql-error-policies).
+        * 
+        * The default value is `none`, meaning that the query result includes error details but not partial results.
+        * 
+        * @docGroup 1. Operation options
+        */
+        errorPolicy?: TErrorPolicy;
+    }): Promise<ApolloClient.QueryResult<TFetchData, TErrorPolicy>>;
     /**
      * A function that enables you to execute a [subscription](https://www.apollographql.com/docs/react/data/subscriptions/), usually to subscribe to specific fields that were included in the query.
      *

package/__cjs/core/QueryInfo.cjs

@@ -1,9 +1,16 @@
-"use strict";
+"use strict";;
+const {
+    __DEV__
+} = require("@apollo/client/utilities/environment");
+
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueryInfo = void 0;
 const equality_1 = require("@wry/equality");
+const trie_1 = require("@wry/trie");
+const environment_1 = require("@apollo/client/utilities/environment");
 const internal_1 = require("@apollo/client/utilities/internal");
 const invariant_1 = require("@apollo/client/utilities/invariant");
+const networkStatus_js_1 = require("./networkStatus.cjs");
 const IGNORE = {};
 const destructiveMethodCounts = new WeakMap();
 function wrapDestructiveCacheMethod(cache, methodName) {
@@ -42,10 +49,10 @@ class QueryInfo {
         this.observableQuery = observableQuery;
         this.queryManager = queryManager;
         // Track how often cache.evict is called, since we want eviction to
-        // override the feud-stopping logic in the markQueryResult method, by
-        // causing shouldWrite to return true. Wrapping the cache.evict method
-        // is a bit of a hack, but it saves us from having to make eviction
-        // counting an official part of the ApolloCache API.
+        // override the write-skipping logic in `shouldWrite`, by causing it to
+        // return true. Wrapping the cache.evict method is a bit of a hack, but it
+        // saves us from having to make eviction counting an official part of the
+        // ApolloCache API.
         if (!destructiveMethodCounts.has(cache)) {
             destructiveMethodCounts.set(cache, 0);
             wrapDestructiveCacheMethod(cache, "evict");
@@ -55,8 +62,14 @@ class QueryInfo {
     }
     /**
     * @internal
-    * For feud-preventing behaviour, `lastWrite` should be shared by all `QueryInfo` instances of an `ObservableQuery`.
-    * In the case of a standalone `QueryInfo`, we will keep a local version.
+    * Tracks the last result written to the cache so that `shouldWrite` can skip
+    * an identical write. Since a `QueryInfo` only ever represents a single
+    * network request, this is shared by all `QueryInfo` instances of an
+    * `ObservableQuery`. A standalone `QueryInfo` keeps a local version.
+    *
+    * A network result that was explicitly asked for always takes precedence over
+    * what is already cached, so `ObservableQuery.refetch` and polling clear this
+    * value before starting their request.
     * 
     * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
     */
@@ -72,178 +85,218 @@ class QueryInfo {
     }
     shouldWrite(result, variables) {
         const { lastWrite } = this;
-        return !(lastWrite &&
+        return (!lastWrite ||
             // If cache.evict has been called since the last time we wrote this
             // data into the cache, there's a chance writing this result into
             // the cache will repair what was evicted.
-            lastWrite.dmCount === destructiveMethodCounts.get(this.cache) &&
-            (0, equality_1.equal)(variables, lastWrite.variables) &&
-            (0, equality_1.equal)(result.data, lastWrite.result.data) &&
+            lastWrite.dmCount !== destructiveMethodCounts.get(this.cache) ||
+            !(0, equality_1.equal)(variables, lastWrite.variables) ||
+            !(0, equality_1.equal)(result.data, lastWrite.result.data) ||
             // We have to compare these values because its possible the final chunk
             // emitted in the incremental result is just `hasNext: false`. This
             // ensures we trigger a cache write when we get `isLastChunk: true`.
-            result.extensions?.[internal_1.streamInfoSymbol] ===
-                lastWrite.result.extensions?.[internal_1.streamInfoSymbol]);
+            lastWrite.hasNext !== this.hasNext);
     }
     get hasNext() {
         return this.incremental ? this.incremental.hasNext : false;
     }
+    get incrementalHandler() {
+        return this.queryManager.incrementalHandler;
+    }
     maybeHandleIncrementalResult(cacheData, incoming, query) {
-        const { incrementalHandler } = this.queryManager;
-        if (incrementalHandler.isIncrementalResult(incoming)) {
-            this.incremental ||= incrementalHandler.startRequest({
+        if (this.incrementalHandler.isIncrementalResult(incoming)) {
+            this.incremental ||= this.incrementalHandler.startRequest({
                 query,
             });
             return this.incremental.handle(cacheData, incoming);
         }
         return incoming;
     }
-    markQueryResult(incoming, { document: query, variables, errorPolicy, cacheWriteBehavior, returnPartialData, }) {
+    markQueryResult(incoming, { document: query, variables, errorPolicy, cacheWriteBehavior, returnPartialData, fetchPolicy, networkStatus, prunePendingDeferFragments: prune, }) {
         const diffOptions = {
             query,
             variables,
-            returnPartialData: true,
             optimistic: true,
         };
         // Cancel the pending notify timeout (if it exists) to prevent extraneous network
         // requests. To allow future notify timeouts, diff and dirty are reset as well.
         this.observableQuery?.["resetNotifications"]();
         const skipCache = cacheWriteBehavior === 0 /* CacheWriteBehavior.FORBID */;
-        const lastDiff = skipCache ? undefined : this.cache.diff(diffOptions);
-        const incrementalResult = this.maybeHandleIncrementalResult(lastDiff?.result, incoming, query);
+        const diff = skipCache ? undefined : (this.getDiff({
+            ...diffOptions,
+            // We usually request partial data to ensure the network incremental
+            // result is merged with all existing data (especially true to
+            // maintain @stream arrays with partial list items in the right order
+            // or when chunk might otherwise replace a partial non-normalized
+            // object), but if we are about to throw away the result anyways due
+            // to the error policy (which early returns below), prune any
+            // pending boundaries so that CombinedGraphQLErrors contains the
+            // right `data` value.
+            returnPartialData: errorPolicy !== "none" ||
+                !this.incrementalHandler.extractErrors(incoming)?.length,
+        }, this.getIncrementalInfo({ prune })));
+        const incrementalResult = this.maybeHandleIncrementalResult(diff?.result, incoming, query);
         let result = {
             ...incrementalResult,
-            dataState: incrementalResult.data == null ? "empty"
-                : this.hasNext ? "streaming"
-                    : "complete",
+            dataState: incrementalResult.data == null ? "empty" : "complete",
         };
-        if (skipCache) {
-            return {
-                ...result,
-                dataState: result.data == null ? "empty"
-                    // Ww can simplify the checks for no-cache queries because the
-                    // result is purely server driven which means we can assume a
-                    // well-formed GraphQL response. In this case, `streaming` only
-                    // makes sense if we are using the `@defer` directive and there are
-                    // more chunks still streaming (i.e. this.hasNext is true). Purely
-                    // `@stream` queries should always be complete.
-                    : this.hasNext && (0, internal_1.hasDirectives)(["defer"], query) ? "streaming"
-                        : "complete",
-            };
+        const hasPendingDefer = this.incremental
+            ?.getPendingWithInfo?.()
+            .some((pending) => pending.type === "defer" && !pending.delivered);
+        if (hasPendingDefer ||
+            // The Defer20220824Handler cannot track pending/completed incremental
+            // chunks due to its data format so we naively set dataState to
+            // streaming if we are still processing chunks. The only case where
+            // streaming is incorrect and should actually be complete is when
+            // both a @defer and @stream boundary is present and the @defer chunk
+            // has completed before the `@stream` array.
+            //
+            // Assigning the naive "streaming" value avoids a much more expensive
+            // pass over `result.data` that would otherwise need to traverse the
+            // selection sets and evaluate the data object at each defer boundary
+            // to see if it fulfills the selection set. For such a narrow case where
+            // its incorrect on a format that is now outdated is not worth the
+            // fix so we are ok with reporting a `streaming` here.
+            (!this.incremental?.getPendingWithInfo &&
+                this.hasNext &&
+                (0, internal_1.hasDirectives)(["defer"], query))) {
+            result.dataState = "streaming";
         }
-        if (shouldWriteResult(result, errorPolicy)) {
-            // Using a transaction here so we have a chance to read the result
-            // back from the cache before the watch callback fires as a result
-            // of writeQuery, so we can store the new diff quietly and ignore
-            // it when we receive it redundantly from the watch callback.
-            this.cache.batch({
-                onWatchUpdated: (
-                // all additional options on ObservableQuery.CacheWatchOptions are
-                // optional so we can use the type here
-                watch, diff) => {
-                    if (watch.watcher === this.observableQuery) {
-                        // see comment on `lastOwnDiff` for explanation
-                        watch.lastOwnDiff = diff;
-                    }
-                },
-                update: (cache) => {
-                    if (this.shouldWrite(result, variables)) {
-                        cache.writeQuery({
-                            query,
-                            data: result.data,
-                            variables,
-                            overwrite: cacheWriteBehavior === 1 /* CacheWriteBehavior.OVERWRITE */,
-                            extensions: result.extensions,
-                        });
-                        this.lastWrite = {
-                            result,
-                            variables,
-                            dmCount: destructiveMethodCounts.get(this.cache),
-                        };
-                    }
-                    else {
-                        // If result is the same as the last result we received from
-                        // the network (and the variables match too), avoid writing
-                        // result into the cache again. The wisdom of skipping this
-                        // cache write is far from obvious, since any cache write
-                        // could be the one that puts the cache back into a desired
-                        // state, fixing corruption or missing data. However, if we
-                        // always write every network result into the cache, we enable
-                        // feuds between queries competing to update the same data in
-                        // incompatible ways, which can lead to an endless cycle of
-                        // cache broadcasts and useless network requests. As with any
-                        // feud, eventually one side must step back from the brink,
-                        // letting the other side(s) have the last word(s). There may
-                        // be other points where we could break this cycle, such as
-                        // silencing the broadcast for cache.writeQuery (not a good
-                        // idea, since it just delays the feud a bit) or somehow
-                        // avoiding the network request that just happened (also bad,
-                        // because the server could return useful new data). All
-                        // options considered, skipping this cache write seems to be
-                        // the least damaging place to break the cycle, because it
-                        // reflects the intuition that we recently wrote this exact
-                        // result into the cache, so the cache *should* already/still
-                        // contain this data. If some other query has clobbered that
-                        // data in the meantime, that's too bad, but there will be no
-                        // winners if every query blindly reverts to its own version
-                        // of the data. This approach also gives the network a chance
-                        // to return new data, which will be written into the cache as
-                        // usual, notifying only those queries that are directly
-                        // affected by the cache updates, as usual. In the future, an
-                        // even more sophisticated cache could perhaps prevent or
-                        // mitigate the clobbering somehow, but that would make this
-                        // particular cache write even less important, and thus
-                        // skipping it would be even safer than it is today.
-                        if (lastDiff && lastDiff.complete) {
-                            // Reuse data from the last good (complete) diff that we
-                            // received, when possible.
-                            result = {
-                                ...result,
-                                data: lastDiff.result,
-                                dataState: "complete",
-                            };
-                            return;
-                        }
-                        // If the previous this.diff was incomplete, fall through to
-                        // re-reading the latest data with cache.diff, below.
-                    }
-                    const diff = cache.diff(diffOptions);
-                    // If we're allowed to write to the cache, and we can read a
-                    // complete result from the cache, update result.data to be the
-                    // result from the cache, rather than the raw network result.
-                    // Set without setDiff to avoid triggering a notify call, since
-                    // we have other ways of notifying for this result.
-                    if (diff.complete) {
-                        result = {
-                            ...result,
-                            data: diff.result,
-                            dataState: "complete",
-                        };
-                    }
-                    else if (this.hasNext && diff.result !== null) {
-                        const isPartial = isStreamingPartial(diff, query, variables);
-                        // If we tolerate partial results always apply `diff.result` to
-                        // ensure we return the result of any transforms in cache read
-                        // functions or custom scalars. If we don't tolerate partial
-                        // results, we only want to apply the diff result if the only hole
-                        // in the data is at a defer boundary (e.g.
-                        // `diff.complete === false && isStreamingPartial === false`)
-                        if (returnPartialData || !isPartial) {
-                            result = {
-                                ...result,
-                                data: diff.result,
-                                dataState: isPartial ? "partial" : "streaming",
-                            };
-                        }
-                    }
-                },
-            });
+        if (skipCache) {
+            return result;
         }
-        else {
+        if (!shouldWriteResult(result, errorPolicy)) {
             this.lastWrite = void 0;
+            return result;
         }
+        let written = false;
+        // Using a transaction here so we have a chance to read the result
+        // back from the cache before the watch callback fires as a result
+        // of writeQuery, so we can store the new diff quietly and ignore
+        // it when we receive it redundantly from the watch callback.
+        this.cache.batch({
+            onWatchUpdated: (
+            // all additional options on ObservableQuery.CacheWatchOptions are
+            // optional so we can use the type here
+            watch, diff) => {
+                if (watch.watcher === this.observableQuery) {
+                    // see comment on `lastOwnDiff` for explanation
+                    watch.lastOwnDiff = diff;
+                }
+            },
+            update: (cache) => {
+                const shouldWrite = this.shouldWrite(result, variables);
+                // If result is the same as the last result we received from
+                // the network (and the variables match too), avoid writing
+                // result into the cache again. The wisdom of skipping this
+                // cache write is far from obvious, since any cache write
+                // could be the one that puts the cache back into a desired
+                // state, fixing corruption or missing data. However, if we
+                // always write every network result into the cache, we enable
+                // feuds between queries competing to update the same data in
+                // incompatible ways, which can lead to an endless cycle of
+                // cache broadcasts and useless network requests. As with any
+                // feud, eventually one side must step back from the brink,
+                // letting the other side(s) have the last word(s). There may
+                // be other points where we could break this cycle, such as
+                // silencing the broadcast for cache.writeQuery (not a good
+                // idea, since it just delays the feud a bit) or somehow
+                // avoiding the network request that just happened (also bad,
+                // because the server could return useful new data). All
+                // options considered, skipping this cache write seems to be
+                // the least damaging place to break the cycle, because it
+                // reflects the intuition that we recently wrote this exact
+                // result into the cache, so the cache *should* already/still
+                // contain this data. If some other query has clobbered that
+                // data in the meantime, that's too bad, but there will be no
+                // winners if every query blindly reverts to its own version
+                // of the data. This approach also gives the network a chance
+                // to return new data, which will be written into the cache as
+                // usual, notifying only those queries that are directly
+                // affected by the cache updates, as usual. In the future, an
+                // even more sophisticated cache could perhaps prevent or
+                // mitigate the clobbering somehow, but that would make this
+                // particular cache write even less important, and thus
+                // skipping it would be even safer than it is today.
+                if (shouldWrite) {
+                    cache.writeQuery({
+                        query,
+                        data: result.data,
+                        variables,
+                        overwrite: cacheWriteBehavior === 1 /* CacheWriteBehavior.OVERWRITE */,
+                        extensions: result.extensions,
+                    });
+                    this.lastWrite = {
+                        result,
+                        variables,
+                        dmCount: destructiveMethodCounts.get(this.cache),
+                        hasNext: this.hasNext,
+                    };
+                    written = true;
+                }
+                const { dataState, result: diffResult } = this.getDiff({
+                    ...diffOptions,
+                    returnPartialData: returnPartialData &&
+                        // Never deliver partial data for network-only requests
+                        (fetchPolicy !== "network-only" ||
+                            networkStatus === networkStatus_js_1.NetworkStatus.refetch),
+                }, this.getIncrementalInfo({ prune }));
+                if (dataState === "complete" ||
+                    dataState === "streaming" ||
+                    (returnPartialData && dataState === "partial" && shouldWrite)) {
+                    result = { ...result, data: diffResult, dataState };
+                }
+                else if (environment_1.__DEV__ &&
+                    written &&
+                    // A result that is still streaming is expected to read back
+                    // incomplete until the remaining chunks arrive.
+                    !this.hasNext) {
+                    warnAboutPartialCacheResult(query, result.data, 
+                    // Always show the partial result for debugging, otherwise the user
+                    // sees `null` when `returnPartialData` is false which isn't helpful
+                    // for figuring out where the problem is.
+                    cache.diff({ ...diffOptions, returnPartialData: true }));
+                }
+            },
+        });
         return result;
     }
+    getIncrementalInfo({ prune }) {
+        const pending = this.incremental?.getPendingWithInfo?.() ?? [];
+        const streamInfo = this.incremental?.streamInfo;
+        const incrementalInfo = { streamInfo };
+        // We don't want to deliver stream items or complete defer boundaries
+        // for a network-only request if they haven't yet streamed from the
+        // network. We record all the still-pending paths so that cache.diff
+        // can prune complete defer/stream boundaries at those paths.
+        if (prune) {
+            for (const item of pending) {
+                if (item.type === "defer" && !item.delivered) {
+                    incrementalInfo.deferInfo ||= new trie_1.Trie(true, () => true);
+                    incrementalInfo.deferInfo.lookupArray(item.path.concat(item.label || []));
+                }
+                else if (streamInfo && item.type === "stream") {
+                    streamInfo.lookupArray(item.path).state.truncate = true;
+                }
+            }
+        }
+        return incrementalInfo;
+    }
+    getDiff(options, incrementalInfo) {
+        const diff = this.cache.diff({
+            ...options,
+            [internal_1.handleIncrementalSymbol]: incrementalInfo,
+        });
+        if ("dataState" in diff) {
+            return diff;
+        }
+        return {
+            ...diff,
+            dataState: diff.complete ? "complete"
+                : diff.result === null ? "empty"
+                    : "partial",
+        };
+    }
     markMutationResult(incoming, mutation, cache = this.cache) {
         const cacheWrites = [];
         const skipCache = mutation.cacheWriteBehavior === 0 /* CacheWriteBehavior.FORBID */;
@@ -439,6 +492,15 @@ class QueryInfo {
     }
 }
 exports.QueryInfo = QueryInfo;
+function warnAboutPartialCacheResult(query, networkResult, diff) {
+    __DEV__ && invariant_1.invariant.warn(
+        89,
+        (0, internal_1.getOperationName)(query, "(anonymous)"),
+        diff.missing?.missing,
+        networkResult,
+        diff.result
+    );
+}
 function shouldWriteResult(result, errorPolicy = "none") {
     const ignoreErrors = errorPolicy === "ignore" || errorPolicy === "all";
     let writeWithErrors = !(0, internal_1.graphQLResultHasError)(result);
@@ -447,129 +509,4 @@ function shouldWriteResult(result, errorPolicy = "none") {
     }
     return writeWithErrors;
 }
-function isStreamingPartial(diff, document, variables) {
-    if (!diff.missing)
-        return false;
-    const fragmentMap = (0, internal_1.createFragmentMap)((0, internal_1.getFragmentDefinitions)(document));
-    return isPartialInSelectionSet((0, internal_1.getMainDefinition)(document).selectionSet, diff.missing.missing, { fragmentMap, variables });
-}
-function isPartialInSelectionSet(selectionSet, missingTree, context) {
-    if (typeof missingTree === "string")
-        return true;
-    if (missingTree === undefined)
-        return false;
-    const missingKeys = Object.keys(missingTree);
-    if (missingKeys.length > 0 && missingKeys.every(isArrayIndex)) {
-        return missingKeys.some((key) => {
-            if (typeof missingTree[key] === "string")
-                return true;
-            return isPartialInSelectionSet(selectionSet, missingTree[key], context);
-        });
-    }
-    const { fragmentMap, variables } = context;
-    for (const selection of selectionSet.selections) {
-        if ((0, internal_1.isField)(selection)) {
-            if ((0, internal_1.isTypenameField)(selection))
-                continue;
-            const missing = missingTree[(0, internal_1.resultKeyNameFromField)(selection)];
-            // If a missing entry is absent, we have a value for this field
-            if (missing === undefined)
-                continue;
-            if (!selection.selectionSet ||
-                isPartialInSelectionSet(selection.selectionSet, missing, context)) {
-                return true;
-            }
-        }
-        else {
-            const fragment = (0, internal_1.getFragmentFromSelection)(selection, fragmentMap);
-            if (!fragment)
-                continue;
-            if ((0, internal_1.isDeferredFragment)(selection, variables)) {
-                // We need to know the non-deferred fields that might overlap with the
-                // deferred selection set so that we accurately report the right
-                // dataState when all the non-deferred fields are satisfied and only the
-                // selections inside the fragment are missing.
-                // For example:
-                //
-                // {
-                //   recipient {
-                //     name
-                //   }
-                //   ... @defer {
-                //     recipient {
-                //       name
-                //       email
-                //     }
-                //   }
-                // }
-                //
-                // dataState should be `streaming`, not `partial` if `name` is present,
-                // but `email` is absent since `name` is not deferred.
-                if (isPartialDeferBoundary(fragment.selectionSet, missingTree, (0, internal_1.collectSiblingFields)(selectionSet, {
-                    ...context,
-                    exclude: selection,
-                }), fragmentMap)) {
-                    return true;
-                }
-            }
-            else if (isPartialInSelectionSet(fragment.selectionSet, missingTree, context)) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-function isPartialDeferBoundary(selectionSet, missing, nonDeferredFields, fragmentMap) {
-    // This flag tracks whether all fields in this selection set should contain
-    // values or should all be missing. A defer boundary is only partial if some
-    // fields are missing. The first selection node will set this value and all
-    // sibling fields should match after that. As soon as we get a mismatch, we
-    // have a partial defer boundary.
-    let shouldContainValues;
-    for (const selection of selectionSet.selections) {
-        if ((0, internal_1.isField)(selection)) {
-            if ((0, internal_1.isTypenameField)(selection))
-                continue;
-            const name = (0, internal_1.resultKeyNameFromField)(selection);
-            const nonDeferredField = nonDeferredFields?.[name];
-            // If this field is not exclusive to this selection set, we don't care
-            // what the value is as far as the defer boundary is concerned. Ignore it
-            // and continue checking other siblings.
-            if (nonDeferredField === true)
-                continue;
-            // The value of missing means different things:
-            // - undefined: The field is fully satisfied (i.e. it has a value for the field)
-            // - string: the field is fully unsatisfied (no scalar value, or object is
-            //   missing all fields)
-            // - object: The field has a selection set and is partially satisfied.
-            const missingField = missing[name];
-            if (typeof missingField !== "object") {
-                const hasValue = missingField === undefined;
-                if (shouldContainValues === undefined) {
-                    shouldContainValues = hasValue;
-                }
-                if (hasValue !== shouldContainValues) {
-                    return true;
-                }
-                continue;
-            }
-            if (selection.selectionSet &&
-                isPartialDeferBoundary(selection.selectionSet, missingField, nonDeferredField, fragmentMap)) {
-                return true;
-            }
-        }
-        else {
-            const fragment = (0, internal_1.getFragmentFromSelection)(selection, fragmentMap);
-            if (!fragment)
-                continue;
-            if (isPartialDeferBoundary(fragment.selectionSet, missing, nonDeferredFields, fragmentMap)) {
-                return true;
-            }
-        }
-    }
-    return false;
-}
-function isArrayIndex(key) {
-    return /^\d+$/.test(key);
-}
 //# sourceMappingURL=QueryInfo.cjs.map