@apollo/client 3.9.0-alpha.4 → 3.9.0-alpha.5

package/core/QueryManager.js

@@ -1,10 +1,11 @@
 import { __assign, __awaiter, __generator } from "tslib";
 import { invariant, newInvariantError } from "../utilities/globals/index.js";
 import { equal } from "@wry/equality";
+import { WeakCache } from "@wry/caches";
 import { execute } from "../link/core/index.js";
-import { compact, hasDirectives, isExecutionPatchIncrementalResult, isExecutionPatchResult, removeDirectivesFromDocument, } from "../utilities/index.js";
+import { hasDirectives, isExecutionPatchIncrementalResult, isExecutionPatchResult, removeDirectivesFromDocument, } from "../utilities/index.js";
 import { canonicalStringify } from "../cache/index.js";
-import { getDefaultValues, getOperationDefinition, getOperationName, hasClientExports, graphQLResultHasError, getGraphQLErrorsFromResult, canUseWeakMap, Observable, asyncMap, isNonEmptyArray, Concast, makeUniqueId, isDocumentNode, isNonNullObject, DocumentTransform, } from "../utilities/index.js";
+import { getDefaultValues, getOperationDefinition, getOperationName, hasClientExports, graphQLResultHasError, getGraphQLErrorsFromResult, Observable, asyncMap, isNonEmptyArray, Concast, makeUniqueId, isDocumentNode, isNonNullObject, DocumentTransform, } from "../utilities/index.js";
 import { mergeIncrementalData } from "../utilities/common/incrementalResult.js";
 import { ApolloError, isApolloError, graphQLResultHasProtocolErrors, } from "../errors/index.js";
 import { ObservableQuery, logMissingFieldErrors } from "./ObservableQuery.js";
@@ -14,19 +15,30 @@ import { QueryInfo, shouldWriteResult, } from "./QueryInfo.js";
 import { PROTOCOL_ERRORS_SYMBOL } from "../errors/index.js";
 import { print } from "../utilities/index.js";
 var hasOwnProperty = Object.prototype.hasOwnProperty;
-var QueryManager = (function () {
+import { Trie } from "@wry/trie";
+var QueryManager = /** @class */ (function () {
     function QueryManager(_a) {
-        var _this = this;
         var cache = _a.cache, link = _a.link, defaultOptions = _a.defaultOptions, documentTransform = _a.documentTransform, _b = _a.queryDeduplication, queryDeduplication = _b === void 0 ? false : _b, onBroadcast = _a.onBroadcast, _c = _a.ssrMode, ssrMode = _c === void 0 ? false : _c, _d = _a.clientAwareness, clientAwareness = _d === void 0 ? {} : _d, localState = _a.localState, _e = _a.assumeImmutableResults, assumeImmutableResults = _e === void 0 ? !!cache.assumeImmutableResults : _e, defaultContext = _a.defaultContext;
+        var _this = this;
         this.clientAwareness = {};
+        // All the queries that the QueryManager is currently managing (not
+        // including mutations and subscriptions).
         this.queries = new Map();
+        // Maps from queryId strings to Promise rejection functions for
+        // currently active queries and fetches.
+        // Use protected instead of private field so
+        // @apollo/experimental-nextjs-app-support can access type info.
         this.fetchCancelFns = new Map();
-        this.transformCache = new (canUseWeakMap ? WeakMap : Map)();
+        this.transformCache = new WeakCache( /** TODO: decide on a maximum size (will do all max sizes in a combined separate PR) */);
         this.queryIdCounter = 1;
         this.requestIdCounter = 1;
         this.mutationIdCounter = 1;
-        this.inFlightLinkObservables = new Map();
-        var defaultDocumentTransform = new DocumentTransform(function (document) { return _this.cache.transformDocument(document); }, { cache: false });
+        // Use protected instead of private field so
+        // @apollo/experimental-nextjs-app-support can access type info.
+        this.inFlightLinkObservables = new Trie(false);
+        var defaultDocumentTransform = new DocumentTransform(function (document) { return _this.cache.transformDocument(document); }, 
+        // Allow the apollo cache to manage its own transform caches
+        { cache: false });
         this.cache = cache;
         this.link = link;
         this.defaultOptions = defaultOptions || Object.create(null);
@@ -35,16 +47,31 @@ var QueryManager = (function () {
         this.localState = localState || new LocalState({ cache: cache });
         this.ssrMode = ssrMode;
         this.assumeImmutableResults = assumeImmutableResults;
-        this.documentTransform = documentTransform
-            ? defaultDocumentTransform
-                .concat(documentTransform)
-                .concat(defaultDocumentTransform)
-            : defaultDocumentTransform;
+        this.documentTransform =
+            documentTransform ?
+                defaultDocumentTransform
+                    .concat(documentTransform)
+                    // The custom document transform may add new fragment spreads or new
+                    // field selections, so we want to give the cache a chance to run
+                    // again. For example, the InMemoryCache adds __typename to field
+                    // selections and fragments from the fragment registry.
+                    .concat(defaultDocumentTransform)
+                : defaultDocumentTransform;
         this.defaultContext = defaultContext || Object.create(null);
         if ((this.onBroadcast = onBroadcast)) {
             this.mutationStore = Object.create(null);
         }
+        // TODO: remove before we release 3.9
+        Object.defineProperty(this.inFlightLinkObservables, "get", {
+            value: function () {
+                throw new Error("This version of Apollo Client requires at least @apollo/experimental-nextjs-app-support version 0.5.2.");
+            },
+        });
     }
+    /**
+     * Call this method to terminate any active query processes, making it safe
+     * to dispose of this QueryManager instance.
+     */
     QueryManager.prototype.stop = function () {
         var _this = this;
         this.queries.forEach(function (_info, queryId) {
@@ -70,8 +97,8 @@ var QueryManager = (function () {
                         mutation = this.cache.transformForLink(this.transform(mutation));
                         hasClientExports = this.getDocumentInfo(mutation).hasClientExports;
                         variables = this.getVariables(mutation, variables);
-                        if (!hasClientExports) return [3, 2];
-                        return [4, this.localState.addExportedVariables(mutation, variables, context)];
+                        if (!hasClientExports) return [3 /*break*/, 2];
+                        return [4 /*yield*/, this.localState.addExportedVariables(mutation, variables, context)];
                     case 1:
                         variables = (_h.sent());
                         _h.label = 2;
@@ -98,7 +125,7 @@ var QueryManager = (function () {
                         }
                         this.broadcastQueries();
                         self = this;
-                        return [2, new Promise(function (resolve, reject) {
+                        return [2 /*return*/, new Promise(function (resolve, reject) {
                                 return asyncMap(self.getObservableFromLink(mutation, __assign(__assign({}, context), { optimisticResponse: optimisticResponse }), variables, false), function (result) {
                                     if (graphQLResultHasError(result) && errorPolicy === "none") {
                                         throw new ApolloError({
@@ -135,6 +162,11 @@ var QueryManager = (function () {
                                 }).subscribe({
                                     next: function (storeResult) {
                                         self.broadcastQueries();
+                                        // Since mutations might receive multiple payloads from the
+                                        // ApolloLink chain (e.g. when used with @defer),
+                                        // we resolve with a SingleExecutionResult or after the final
+                                        // ExecutionPatchResult has arrived and we have assembled the
+                                        // multipart response into a single result.
                                         if (!("hasNext" in storeResult) || storeResult.hasNext === false) {
                                             resolve(storeResult);
                                         }
@@ -148,11 +180,9 @@ var QueryManager = (function () {
                                             self.cache.removeOptimistic(mutationId);
                                         }
                                         self.broadcastQueries();
-                                        reject(err instanceof ApolloError
-                                            ? err
-                                            : new ApolloError({
-                                                networkError: err,
-                                            }));
+                                        reject(err instanceof ApolloError ? err : (new ApolloError({
+                                            networkError: err,
+                                        })));
                                     },
                                 });
                             })];
@@ -179,6 +209,9 @@ var QueryManager = (function () {
                 isNonEmptyArray(result.incremental)) {
                 var diff = cache.diff({
                     id: "ROOT_MUTATION",
+                    // The cache complains if passed a mutation where it expects a
+                    // query, so we transform mutations and subscriptions to queries
+                    // (only once, thanks to this.transformCache).
                     query: this.getDocumentInfo(mutation.document).asQuery,
                     variables: mutation.variables,
                     optimistic: false,
@@ -189,6 +222,8 @@ var QueryManager = (function () {
                     mergedData = mergeIncrementalData(diff.result, result);
                 }
                 if (typeof mergedData !== "undefined") {
+                    // cast the ExecutionPatchResult to FetchResult here since
+                    // ExecutionPatchResult never has `data` when returned from the server
                     result.data = mergedData;
                     cacheWrites.push({
                         result: mergedData,
@@ -208,6 +243,7 @@ var QueryManager = (function () {
                     }
                     var updater = updateQueries_1[queryName];
                     var _b = _this.queries.get(queryId), document = _b.document, variables = _b.variables;
+                    // Read the current query result from the store.
                     var _c = cache.diff({
                         query: document,
                         variables: variables,
@@ -215,11 +251,13 @@ var QueryManager = (function () {
                         optimistic: false,
                     }), currentQueryResult = _c.result, complete = _c.complete;
                     if (complete && currentQueryResult) {
+                        // Run our reducer using the current query result and the mutation result.
                         var nextQueryResult = updater(currentQueryResult, {
                             mutationResult: result,
                             queryName: (document && getOperationName(document)) || void 0,
                             queryVariables: variables,
                         });
+                        // Write the modified result back into the store if we got a new result.
                         if (nextQueryResult) {
                             cacheWrites.push({
                                 result: nextQueryResult,
@@ -243,13 +281,25 @@ var QueryManager = (function () {
                     if (!skipCache) {
                         cacheWrites.forEach(function (write) { return cache.write(write); });
                     }
+                    // If the mutation has some writes associated with it then we need to
+                    // apply those writes to the store by running this reducer again with
+                    // a write action.
                     var update = mutation.update;
+                    // Determine whether result is a SingleExecutionResult,
+                    // or the final ExecutionPatchResult.
                     var isFinalResult = !isExecutionPatchResult(result) ||
                         (isExecutionPatchIncrementalResult(result) && !result.hasNext);
                     if (update) {
                         if (!skipCache) {
+                            // Re-read the ROOT_MUTATION data we just wrote into the cache
+                            // (the first cache.write call in the cacheWrites.forEach loop
+                            // above), so field read functions have a chance to run for
+                            // fields within mutation result objects.
                             var diff = cache.diff({
                                 id: "ROOT_MUTATION",
+                                // The cache complains if passed a mutation where it expects a
+                                // query, so we transform mutations and subscriptions to queries
+                                // (only once, thanks to this.transformCache).
                                 query: _this.getDocumentInfo(mutation.document).asQuery,
                                 variables: mutation.variables,
                                 optimistic: false,
@@ -265,6 +315,9 @@ var QueryManager = (function () {
                                 }
                             }
                         }
+                        // If we've received the whole response,
+                        // either a SingleExecutionResult or the final ExecutionPatchResult,
+                        // call the update function.
                         if (isFinalResult) {
                             update(cache, result, {
                                 context: mutation.context,
@@ -272,6 +325,8 @@ var QueryManager = (function () {
                             });
                         }
                     }
+                    // TODO Do this with cache.evict({ id: 'ROOT_MUTATION' }) but make it
+                    // shallow to allow rolling back optimistic evictions.
                     if (!skipCache && !mutation.keepRootFields && isFinalResult) {
                         cache.modify({
                             id: "ROOT_MUTATION",
@@ -283,11 +338,21 @@ var QueryManager = (function () {
                     }
                 },
                 include: mutation.refetchQueries,
+                // Write the final mutation.result to the root layer of the cache.
                 optimistic: false,
+                // Remove the corresponding optimistic layer at the same time as we
+                // write the final non-optimistic result.
                 removeOptimistic: mutation.removeOptimistic,
+                // Let the caller of client.mutate optionally determine the refetching
+                // behavior for watched queries after the mutation.update function runs.
+                // If no onQueryUpdated function was provided for this mutation, pass
+                // null instead of undefined to disable the default refetching behavior.
                 onQueryUpdated: mutation.onQueryUpdated || null,
             }).forEach(function (result) { return results_1.push(result); });
             if (mutation.awaitRefetchQueries || mutation.onQueryUpdated) {
+                // Returning a promise here makes the mutation await that promise, so we
+                // include results in that promise's work if awaitRefetchQueries or an
+                // onQueryUpdated function was specified.
                 return Promise.all(results_1).then(function () { return result; });
             }
         }
@@ -295,8 +360,8 @@ var QueryManager = (function () {
     };
     QueryManager.prototype.markMutationOptimistic = function (optimisticResponse, mutation) {
         var _this = this;
-        var data = typeof optimisticResponse === "function"
-            ? optimisticResponse(mutation.variables)
+        var data = typeof optimisticResponse === "function" ?
+            optimisticResponse(mutation.variables)
             : optimisticResponse;
         return this.cache.recordOptimisticTransaction(function (cache) {
             try {
@@ -337,6 +402,11 @@ var QueryManager = (function () {
         var transformCache = this.transformCache;
         if (!transformCache.has(document)) {
             var cacheEntry = {
+                // TODO These three calls (hasClientExports, shouldForceResolvers, and
+                // usesNonreactiveDirective) are performing independent full traversals
+                // of the transformed document. We should consider merging these
+                // traversals into a single pass in the future, though the work is
+                // cached after the first time.
                 hasClientExports: hasClientExports(document),
                 hasForcedResolvers: this.localState.shouldForceResolvers(document),
                 hasNonreactiveDirective: hasDirectives(["nonreactive"], document),
@@ -347,6 +417,8 @@ var QueryManager = (function () {
                     { name: "nonreactive" },
                 ], document),
                 defaultVars: getDefaultValues(getOperationDefinition(document)),
+                // Transform any mutation or subscription operations to query operations
+                // so we can read/write them from/to the cache.
                 asQuery: __assign(__assign({}, document), { definitions: document.definitions.map(function (def) {
                         if (def.kind === "OperationDefinition" &&
                             def.operation !== "query") {
@@ -364,6 +436,9 @@ var QueryManager = (function () {
     };
     QueryManager.prototype.watchQuery = function (options) {
         var query = this.transform(options.query);
+        // assign variable default values if supplied
+        // NOTE: We don't modify options.query here with the transformed query to
+        // ensure observable.options.query is set to the raw untransformed query.
         options = __assign(__assign({}, options), { variables: this.getVariables(query, options.variables) });
         if (typeof options.notifyOnNetworkStatusChange === "undefined") {
             options.notifyOnNetworkStatusChange = false;
@@ -376,6 +451,8 @@ var QueryManager = (function () {
         });
         observable["lastQuery"] = query;
         this.queries.set(observable.queryId, queryInfo);
+        // We give queryInfo the transformed query to ensure the first cache diff
+        // uses the transformed query instead of the raw query
         queryInfo.init({
             document: query,
             observableQuery: observable,
@@ -414,9 +491,16 @@ var QueryManager = (function () {
         if (options === void 0) { options = {
             discardWatches: true,
         }; }
+        // Before we have sent the reset action to the store, we can no longer
+        // rely on the results returned by in-flight requests since these may
+        // depend on values that previously existed in the data portion of the
+        // store. So, we cancel the promises and observers that we have issued
+        // so far and not yet resolved (in the case of queries).
         this.cancelPendingFetches(newInvariantError(32));
         this.queries.forEach(function (queryInfo) {
             if (queryInfo.observableQuery) {
+                // Set loading to true so listeners don't trigger unless they want
+                // results with partial data.
                 queryInfo.networkStatus = NetworkStatus.loading;
             }
             else {
@@ -426,6 +510,7 @@ var QueryManager = (function () {
         if (this.mutationStore) {
             this.mutationStore = Object.create(null);
         }
+        // begin removing data from the store
         return this.cache.reset(options);
     };
     QueryManager.prototype.getObservableQueries = function (include) {
@@ -472,6 +557,9 @@ var QueryManager = (function () {
         });
         if (legacyQueryOptions.size) {
             legacyQueryOptions.forEach(function (options) {
+                // We will be issuing a fresh network request for this query, so we
+                // pre-allocate a new query ID here, using a special prefix to enable
+                // cleaning up these temporary queries later, after fetching.
                 var queryId = makeUniqueId("legacyOneTimeQuery");
                 var queryInfo = _this.getQuery(queryId).init({
                     document: options.query,
@@ -523,6 +611,8 @@ var QueryManager = (function () {
         var makeObservable = function (variables) {
             return _this.getObservableFromLink(query, context, variables).map(function (result) {
                 if (fetchPolicy !== "no-cache") {
+                    // the subscription interface should handle not sending us results we no longer subscribe to.
+                    // XXX I don't think we ever send in an object with errors, but we might in the future...
                     if (shouldWriteResult(result, errorPolicy)) {
                         _this.cache.write({
                             query: query,
@@ -543,6 +633,9 @@ var QueryManager = (function () {
                     if (hasProtocolErrors) {
                         errors.protocolErrors = result.extensions[PROTOCOL_ERRORS_SYMBOL];
                     }
+                    // `errorPolicy` is a mechanism for handling GraphQL errors, according
+                    // to our documentation, so we throw protocol errors regardless of the
+                    // set error policy.
                     if (errorPolicy === "none" || hasProtocolErrors) {
                         throw new ApolloError(errors);
                     }
@@ -574,6 +667,11 @@ var QueryManager = (function () {
         this.removeQuery(queryId);
     };
     QueryManager.prototype.removeQuery = function (queryId) {
+        // teardown all links
+        // Both `QueryManager.fetchRequest` and `QueryManager.query` create separate promises
+        // that each add their reject functions to fetchCancelFns.
+        // A query created with `QueryManager.query()` could trigger a `QueryManager.fetchRequest`.
+        // The same queryId could have two rejection fns for two promises
         this.fetchCancelFns.delete(queryId);
         if (this.queries.has(queryId)) {
             this.getQuery(queryId).stop();
@@ -588,7 +686,9 @@ var QueryManager = (function () {
     QueryManager.prototype.getLocalState = function () {
         return this.localState;
     };
-    QueryManager.prototype.getObservableFromLink = function (query, context, variables, deduplication) {
+    QueryManager.prototype.getObservableFromLink = function (query, context, variables, 
+    // Prefer context.queryDeduplication if specified.
+    deduplication) {
         var _this = this;
         var _a;
         if (deduplication === void 0) { deduplication = (_a = context === null || context === void 0 ? void 0 : context.queryDeduplication) !== null && _a !== void 0 ? _a : this.queryDeduplication; }
@@ -605,19 +705,16 @@ var QueryManager = (function () {
             context = operation.context;
             if (deduplication) {
                 var printedServerQuery_1 = print(serverQuery);
-                var byVariables_1 = inFlightLinkObservables_1.get(printedServerQuery_1) || new Map();
-                inFlightLinkObservables_1.set(printedServerQuery_1, byVariables_1);
                 var varJson_1 = canonicalStringify(variables);
-                observable = byVariables_1.get(varJson_1);
+                var entry = inFlightLinkObservables_1.lookup(printedServerQuery_1, varJson_1);
+                observable = entry.observable;
                 if (!observable) {
                     var concast = new Concast([
                         execute(link, operation),
                     ]);
-                    byVariables_1.set(varJson_1, (observable = concast));
+                    observable = entry.observable = concast;
                     concast.beforeNext(function () {
-                        if (byVariables_1.delete(varJson_1) && byVariables_1.size < 1) {
-                            inFlightLinkObservables_1.delete(printedServerQuery_1);
-                        }
+                        inFlightLinkObservables_1.remove(printedServerQuery_1, varJson_1);
                     });
                 }
             }
@@ -645,16 +742,25 @@ var QueryManager = (function () {
     };
     QueryManager.prototype.getResultsFromLink = function (queryInfo, cacheWriteBehavior, options) {
         var requestId = (queryInfo.lastRequestId = this.generateRequestId());
+        // Performing transformForLink here gives this.cache a chance to fill in
+        // missing fragment definitions (for example) before sending this document
+        // through the link chain.
         var linkDocument = this.cache.transformForLink(options.query);
-        return asyncMap(this.getObservableFromLink(linkDocument, compact(this.defaultContext, options.context), options.variables), function (result) {
+        return asyncMap(this.getObservableFromLink(linkDocument, options.context, options.variables), function (result) {
             var graphQLErrors = getGraphQLErrorsFromResult(result);
             var hasErrors = graphQLErrors.length > 0;
+            // If we interrupted this request by calling getResultsFromLink again
+            // with the same QueryInfo object, we ignore the old results.
             if (requestId >= queryInfo.lastRequestId) {
                 if (hasErrors && options.errorPolicy === "none") {
+                    // Throwing here effectively calls observer.error.
                     throw queryInfo.markError(new ApolloError({
                         graphQLErrors: graphQLErrors,
                     }));
                 }
+                // Use linkDocument rather than queryInfo.document so the
+                // operation/fragments used to write the result are the same as the
+                // ones used to obtain it from the link.
                 result = queryInfo.markResult(result, linkDocument, options, cacheWriteBehavior);
                 queryInfo.markReady();
             }
@@ -669,16 +775,19 @@ var QueryManager = (function () {
             }
             return aqr;
         }, function (networkError) {
-            var error = isApolloError(networkError)
-                ? networkError
-                : new ApolloError({ networkError: networkError });
+            var error = isApolloError(networkError) ? networkError : (new ApolloError({ networkError: networkError }));
+            // Avoid storing errors from older interrupted queries.
             if (requestId >= queryInfo.lastRequestId) {
                 queryInfo.markError(error);
             }
             throw error;
         });
     };
-    QueryManager.prototype.fetchConcastWithInfo = function (queryId, options, networkStatus, query) {
+    QueryManager.prototype.fetchConcastWithInfo = function (queryId, options, 
+    // The initial networkStatus for this fetch, most often
+    // NetworkStatus.loading, but also possibly fetchMore, poll, refetch,
+    // or setVariables.
+    networkStatus, query) {
         var _this = this;
         if (networkStatus === void 0) { networkStatus = NetworkStatus.loading; }
         if (query === void 0) { query = options.query; }
@@ -696,26 +805,49 @@ var QueryManager = (function () {
             context: context,
         });
         var fromVariables = function (variables) {
+            // Since normalized is always a fresh copy of options, it's safe to
+            // modify its properties here, rather than creating yet another new
+            // WatchQueryOptions object.
             normalized.variables = variables;
             var sourcesWithInfo = _this.fetchQueryByPolicy(queryInfo, normalized, networkStatus);
-            if (normalized.fetchPolicy !== "standby" &&
+            if (
+            // If we're in standby, postpone advancing options.fetchPolicy using
+            // applyNextFetchPolicy.
+            normalized.fetchPolicy !== "standby" &&
+                // The "standby" policy currently returns [] from fetchQueryByPolicy, so
+                // this is another way to detect when nothing was done/fetched.
                 sourcesWithInfo.sources.length > 0 &&
                 queryInfo.observableQuery) {
                 queryInfo.observableQuery["applyNextFetchPolicy"]("after-fetch", options);
             }
             return sourcesWithInfo;
         };
+        // This cancel function needs to be set before the concast is created,
+        // in case concast creation synchronously cancels the request.
         var cleanupCancelFn = function () { return _this.fetchCancelFns.delete(queryId); };
         this.fetchCancelFns.set(queryId, function (reason) {
             cleanupCancelFn();
+            // This delay ensures the concast variable has been initialized.
             setTimeout(function () { return concast.cancel(reason); });
         });
         var concast, containsDataFromLink;
+        // If the query has @export(as: ...) directives, then we need to
+        // process those directives asynchronously. When there are no
+        // @export directives (the common case), we deliberately avoid
+        // wrapping the result of this.fetchQueryByPolicy in a Promise,
+        // since the timing of result delivery is (unfortunately) important
+        // for backwards compatibility. TODO This code could be simpler if
+        // we deprecated and removed LocalState.
         if (this.getDocumentInfo(normalized.query).hasClientExports) {
             concast = new Concast(this.localState
                 .addExportedVariables(normalized.query, normalized.variables, normalized.context)
                 .then(fromVariables)
                 .then(function (sourcesWithInfo) { return sourcesWithInfo.sources; }));
+            // there is just no way we can synchronously get the *right* value here,
+            // so we will assume `true`, which is the behaviour before the bug fix in
+            // #10597. This means that bug is not fixed in that case, and is probably
+            // un-fixable with reasonable effort for the edge case of @export as
+            // directives.
             containsDataFromLink = true;
         }
         else {
@@ -745,23 +877,71 @@ var QueryManager = (function () {
         if (updateCache) {
             this.cache.batch({
                 update: updateCache,
+                // Since you can perform any combination of cache reads and/or writes in
+                // the cache.batch update function, its optimistic option can be either
+                // a boolean or a string, representing three distinct modes of
+                // operation:
+                //
+                // * false: read/write only the root layer
+                // * true: read/write the topmost layer
+                // * string: read/write a fresh optimistic layer with that ID string
+                //
+                // When typeof optimistic === "string", a new optimistic layer will be
+                // temporarily created within cache.batch with that string as its ID. If
+                // we then pass that same string as the removeOptimistic option, we can
+                // make cache.batch immediately remove the optimistic layer after
+                // running the updateCache function, triggering only one broadcast.
+                //
+                // However, the refetchQueries method accepts only true or false for its
+                // optimistic option (not string). We interpret true to mean a temporary
+                // optimistic layer should be created, to allow efficiently rolling back
+                // the effect of the updateCache function, which involves passing a
+                // string instead of true as the optimistic option to cache.batch, when
+                // refetchQueries receives optimistic: true.
+                //
+                // In other words, we are deliberately not supporting the use case of
+                // writing to an *existing* optimistic layer (using the refetchQueries
+                // updateCache function), since that would potentially interfere with
+                // other optimistic updates in progress. Instead, you can read/write
+                // only the root layer by passing optimistic: false to refetchQueries,
+                // or you can read/write a brand new optimistic layer that will be
+                // automatically removed by passing optimistic: true.
                 optimistic: (optimistic && removeOptimistic) || false,
+                // The removeOptimistic option can also be provided by itself, even if
+                // optimistic === false, to remove some previously-added optimistic
+                // layer safely and efficiently, like we do in markMutationResult.
+                //
+                // If an explicit removeOptimistic string is provided with optimistic:
+                // true, the removeOptimistic string will determine the ID of the
+                // temporary optimistic layer, in case that ever matters.
                 removeOptimistic: removeOptimistic,
                 onWatchUpdated: function (watch, diff, lastDiff) {
                     var oq = watch.watcher instanceof QueryInfo && watch.watcher.observableQuery;
                     if (oq) {
                         if (onQueryUpdated) {
+                            // Since we're about to handle this query now, remove it from
+                            // includedQueriesById, in case it was added earlier because of
+                            // options.include.
                             includedQueriesById.delete(oq.queryId);
                             var result = onQueryUpdated(oq, diff, lastDiff);
                             if (result === true) {
+                                // The onQueryUpdated function requested the default refetching
+                                // behavior by returning true.
                                 result = oq.refetch();
                             }
+                            // Record the result in the results Map, as long as onQueryUpdated
+                            // did not return false to skip/ignore this result.
                             if (result !== false) {
                                 results.set(oq, result);
                             }
+                            // Allow the default cache broadcast to happen, except when
+                            // onQueryUpdated returns false.
                             return result;
                         }
                         if (onQueryUpdated !== null) {
+                            // If we don't have an onQueryUpdated function, and onQueryUpdated
+                            // was not disabled by passing null, make sure this query is
+                            // "included" like any other options.include-specified query.
                             includedQueriesById.set(oq.queryId, { oq: oq, lastDiff: lastDiff, diff: diff });
                         }
                     }
@@ -772,14 +952,17 @@ var QueryManager = (function () {
             includedQueriesById.forEach(function (_a, queryId) {
                 var oq = _a.oq, lastDiff = _a.lastDiff, diff = _a.diff;
                 var result;
+                // If onQueryUpdated is provided, we want to use it for all included
+                // queries, even the QueryOptions ones.
                 if (onQueryUpdated) {
                     if (!diff) {
                         var info = oq["queryInfo"];
-                        info.reset();
+                        info.reset(); // Force info.getDiff() to read from cache.
                         diff = info.getDiff();
                     }
                     result = onQueryUpdated(oq, diff, lastDiff);
                 }
+                // Otherwise, we fall back to refetching.
                 if (!onQueryUpdated || result === true) {
                     result = oq.refetch();
                 }
@@ -792,11 +975,22 @@ var QueryManager = (function () {
             });
         }
         if (removeOptimistic) {
+            // In case no updateCache callback was provided (so cache.batch was not
+            // called above, and thus did not already remove the optimistic layer),
+            // remove it here. Since this is a no-op when the layer has already been
+            // removed, we do it even if we called cache.batch above, since it's
+            // possible this.cache is an instance of some ApolloCache subclass other
+            // than InMemoryCache, and does not fully support the removeOptimistic
+            // option for cache.batch.
             this.cache.removeOptimistic(removeOptimistic);
         }
         return results;
     };
-    QueryManager.prototype.fetchQueryByPolicy = function (queryInfo, _a, networkStatus) {
+    QueryManager.prototype.fetchQueryByPolicy = function (queryInfo, _a, 
+    // The initial networkStatus for this fetch, most often
+    // NetworkStatus.loading, but also possibly fetchMore, poll, refetch,
+    // or setVariables.
+    networkStatus) {
         var _this = this;
         var query = _a.query, variables = _a.variables, fetchPolicy = _a.fetchPolicy, refetchWritePolicy = _a.refetchWritePolicy, errorPolicy = _a.errorPolicy, returnPartialData = _a.returnPartialData, context = _a.context, notifyOnNetworkStatusChange = _a.notifyOnNetworkStatusChange;
         var oldNetworkStatus = queryInfo.networkStatus;
@@ -826,6 +1020,10 @@ var QueryManager = (function () {
                 })
                     .then(function (resolved) { return fromData(resolved.data || void 0); });
             }
+            // Resolves https://github.com/apollographql/apollo-client/issues/10317.
+            // If errorPolicy is 'none' and notifyOnNetworkStatusChange is true,
+            // data was incorrectly returned from the cache on refetch:
+            // if diff.missing exists, we should not return cache data.
             if (errorPolicy === "none" &&
                 networkStatus === NetworkStatus.refetch &&
                 Array.isArray(diff.missing)) {
@@ -833,13 +1031,13 @@ var QueryManager = (function () {
             }
             return fromData(data);
         };
-        var cacheWriteBehavior = fetchPolicy === "no-cache"
-            ? 0
-            :
-                networkStatus === NetworkStatus.refetch &&
-                    refetchWritePolicy !== "merge"
-                    ? 1
-                    : 2;
+        var cacheWriteBehavior = fetchPolicy === "no-cache" ? 0 /* CacheWriteBehavior.FORBID */
+            // Watched queries must opt into overwriting existing data on refetch,
+            // by passing refetchWritePolicy: "overwrite" in their WatchQueryOptions.
+            : (networkStatus === NetworkStatus.refetch &&
+                refetchWritePolicy !== "merge") ?
+                1 /* CacheWriteBehavior.OVERWRITE */
+                : 2 /* CacheWriteBehavior.MERGE */;
         var resultsFromLink = function () {
             return _this.getResultsFromLink(queryInfo, cacheWriteBehavior, {
                 query: query,
@@ -898,6 +1096,9 @@ var QueryManager = (function () {
                 if (shouldNotify) {
                     return {
                         fromLink: true,
+                        // Note that queryInfo.getDiff() for no-cache queries does not call
+                        // cache.diff, but instead returns a { complete: false } stub result
+                        // when there is no queryInfo.diff already defined.
                         sources: [resultsFromCache(queryInfo.getDiff()), resultsFromLink()],
                     };
                 }
@@ -915,7 +1116,7 @@ var QueryManager = (function () {
     QueryManager.prototype.prepareContext = function (context) {
         if (context === void 0) { context = {}; }
         var newContext = this.localState.prepareContext(context);
-        return __assign(__assign({}, newContext), { clientAwareness: this.clientAwareness });
+        return __assign(__assign(__assign({}, this.defaultContext), newContext), { clientAwareness: this.clientAwareness });
     };
     return QueryManager;
 }());