@apollo/client 4.0.0-rc.4 → 4.0.0-rc.6

package/__cjs/core/ObservableQuery.cjs

@@ -11,7 +11,6 @@ const rxjs_1 = require("rxjs");
 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 equalByQuery_js_1 = require("./equalByQuery.cjs");
 const networkStatus_js_1 = require("./networkStatus.cjs");
 const { assign, hasOwnProperty } = Object;
 const uninitialized = {
@@ -141,7 +140,7 @@ class ObservableQuery {
                 const dataMasking = this.queryManager.dataMasking;
                 const maskedQuery = dataMasking ? documentInfo.nonReactiveQuery : query;
                 const resultIsEqual = dataMasking || documentInfo.hasNonreactiveDirective ?
-                    (0, equalByQuery_js_1.equalByQuery)(maskedQuery, previous, current, variables)
+                    (0, internal_1.equalByQuery)(maskedQuery, previous, current, variables)
                     : (0, equality_1.equal)(previous, current);
                 if (resultIsEqual && (0, equality_1.equal)(previousVariables, variables)) {
                     return;
@@ -170,7 +169,32 @@ class ObservableQuery {
     // We can't use Observable['subscribe'] here as the type as it conflicts with
     // the ability to infer T from Subscribable<T>. This limits the surface area
     // to the non-deprecated signature which works properly with type inference.
+    /**
+     * Subscribes to the `ObservableQuery`.
+     * @param observerOrNext - Either an RxJS `Observer` with some or all callback methods,
+     * or the `next` handler that is called for each value emitted from the subscribed Observable.
+     * @returns A subscription reference to the registered handlers.
+     */
     subscribe;
+    /**
+     * Used to stitch together functional operators into a chain.
+     *
+     * @example
+     *
+     * ```ts
+     * import { filter, map } from 'rxjs';
+     *
+     * observableQuery
+     *   .pipe(
+     *     filter(...),
+     *     map(...),
+     *   )
+     *   .subscribe(x => console.log(x));
+     * ```
+     *
+     * @returns The Observable result of all the operators having been called
+     * in the order they were passed in.
+     */
     pipe;
     [Symbol.observable];
     ["@@observable"];
@@ -326,6 +350,13 @@ class ObservableQuery {
      * Update the variables of this observable query, and fetch the new results.
      * This method should be preferred over `setVariables` in most use cases.
      *
+     * Returns a `ResultPromise` with an additional `.retain()` method. Calling
+     * `.retain()` keeps the network operation running even if the `ObservableQuery`
+     * no longer requires the result.
+     *
+     * Note: `refetch()` guarantees that a value will be emitted from the
+     * observable, even if the result is deep equal to the previous value.
+     *
      * @param variables - The new set of variables. If there are missing variables,
      * the previous values of those variables will be used.
      */
@@ -348,7 +379,7 @@ class ObservableQuery {
             const queryDef = (0, internal_1.getQueryDefinition)(this.query);
             const vars = queryDef.variableDefinitions;
             if (!vars || !vars.some((v) => v.variable.name.value === "variables")) {
-                __DEV__ && invariant_1.invariant.warn(78, variables, queryDef.name?.value || queryDef);
+                __DEV__ && invariant_1.invariant.warn(77, variables, queryDef.name?.value || queryDef);
             }
         }
         if (variables && !(0, equality_1.equal)(this.variables, variables)) {
@@ -361,13 +392,10 @@ class ObservableQuery {
             newNetworkStatus: networkStatus_js_1.NetworkStatus.refetch,
         });
     }
-    /**
-     * 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({ query, variables, context, errorPolicy, updateQuery, }) {
         (0, invariant_1.invariant)(
             this.options.fetchPolicy !== "cache-only",
-            79,
+            78,
             (0, internal_1.getOperationName)(this.query, "(anonymous)")
         );
         const combinedOptions = {
@@ -401,7 +429,7 @@ class ObservableQuery {
         let wasUpdated = false;
         const isCached = this.options.fetchPolicy !== "no-cache";
         if (!isCached) {
-            (0, invariant_1.invariant)(updateQuery, 80);
+            (0, invariant_1.invariant)(updateQuery, 79);
         }
         const { finalize, pushNotification } = this.pushOperation(networkStatus_js_1.NetworkStatus.fetchMore);
         pushNotification({
@@ -533,7 +561,7 @@ class ObservableQuery {
                         onError(error);
                     }
                     else {
-                        __DEV__ && invariant_1.invariant.error(81, error);
+                        __DEV__ && invariant_1.invariant.error(80, error);
                     }
                     return;
                 }
@@ -568,14 +596,12 @@ class ObservableQuery {
      * `setVariables` in order to to be properly notified of results even when
      * they come from the cache.
      *
-     * Note: the `next` callback will *not* fire if the variables have not changed
-     * or if the result is coming from cache.
-     *
-     * Note: the promise will return the old results immediately if the variables
-     * have not changed.
+     * Note: `setVariables()` guarantees that a value will be emitted from the
+     * observable, even if the result is deeply equal to the previous value.
      *
-     * Note: the promise will return the last result immediately if the query is not active
-     * (there are no subscribers).
+     * Note: the promise will resolve with the last emitted result
+     * when either the variables match the current variables or there
+     * are no subscribers to the query.
      *
      * @param variables - The new set of variables. If there are missing variables,
      * the previous values of those variables will be used.
@@ -779,7 +805,7 @@ class ObservableQuery {
                 if (!this.didWarnCacheOnlyPolling &&
                     pollInterval &&
                     fetchPolicy === "cache-only") {
-                    __DEV__ && invariant_1.invariant.warn(82, (0, internal_1.getOperationName)(this.query, "(anonymous)"));
+                    __DEV__ && invariant_1.invariant.warn(81, (0, internal_1.getOperationName)(this.query, "(anonymous)"));
                     this.didWarnCacheOnlyPolling = true;
                 }
             }
@@ -831,6 +857,9 @@ class ObservableQuery {
     /**
      * Reevaluate the query, optionally against new options. New options will be
      * merged with the current options when given.
+     *
+     * Note: `variables` can be reset back to their defaults (typically empty) by calling `reobserve` with
+     * `variables: undefined`.
      */
     reobserve(newOptions) {
         return this._reobserve(newOptions);
@@ -1137,8 +1166,9 @@ class ObservableQuery {
     /**
     * @internal
     * Called from `clearStore`.
-    * * resets the query to its initial state
-    * * cancels all active operations and their subscriptions
+    *
+    * - resets the query to its initial state
+    * - cancels all active operations and their subscriptions
     * 
     * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
     */
@@ -1272,7 +1302,7 @@ class ObservableQuery {
 exports.ObservableQuery = ObservableQuery;
 function logMissingFieldErrors(missing) {
     if (environment_1.__DEV__ && missing) {
-        __DEV__ && invariant_1.invariant.debug(83, missing);
+        __DEV__ && invariant_1.invariant.debug(82, missing);
     }
 }
 function isEqualQuery(a, b) {