@apollo/client 4.0.0-rc.1 → 4.0.0-rc.10

package/core/ObservableQuery.d.ts

@@ -4,53 +4,11 @@ import { Observable } from "rxjs";
 import type { Cache, MissingFieldError } from "@apollo/client/cache";
 import type { MissingTree } from "@apollo/client/cache";
 import type { MaybeMasked, Unmasked } from "@apollo/client/masking";
+import type { ApolloClient } from "./ApolloClient.js";
+import { NetworkStatus } from "./networkStatus.js";
 import type { QueryManager } from "./QueryManager.js";
-import type { ApolloQueryResult, DefaultContext, OperationVariables, QueryResult, TypedDocumentNode } from "./types.js";
-import type { ErrorPolicy, NextFetchPolicyContext, RefetchWritePolicy, SubscribeToMoreOptions, UpdateQueryMapFn, WatchQueryFetchPolicy, WatchQueryOptions } from "./watchQueryOptions.js";
-export type FetchMoreOptions<TData, TVariables extends OperationVariables, TFetchData = TData, TFetchVars extends OperationVariables = TVariables> = {
-    /**
-    * A GraphQL query string parsed into an AST with the gql template literal.
-    * 
-    * @docGroup
-    * 
-    * 1. Operation options
-    */
-    query?: DocumentNode | TypedDocumentNode<TFetchData, TFetchVars>;
-    /**
-    * An object containing all of the GraphQL variables your query requires to execute.
-    * 
-    * Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
-    * 
-    * @docGroup
-    * 
-    * 1. Operation options
-    */
-    variables?: Partial<NoInfer<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?: ErrorPolicy;
-    /**
-    * If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
-    * 
-    * @docGroup
-    * 
-    * 2. Networking options
-    */
-    context?: DefaultContext;
-    updateQuery?: (previousQueryResult: Unmasked<TData>, options: {
-        fetchMoreResult: Unmasked<TFetchData>;
-        variables: TFetchVars;
-    }) => Unmasked<TData>;
-};
+import type { DataState, DefaultContext, ErrorLike, GetDataState, OperationVariables, TypedDocumentNode } from "./types.js";
+import type { ErrorPolicy, NextFetchPolicyContext, RefetchWritePolicy, SubscribeToMoreUpdateQueryFn, UpdateQueryMapFn, WatchQueryFetchPolicy } from "./watchQueryOptions.js";
 export declare namespace ObservableQuery {
     type Options<TData = unknown, TVariables extends OperationVariables = OperationVariables> = {
         /**
@@ -60,33 +18,30 @@ export declare namespace ObservableQuery {
         * 
         * The default value is `cache-first`.
         * 
-        * @docGroup
-        * 
-        * 3. Caching options
+        * @docGroup 3. Caching options
         */
         fetchPolicy: WatchQueryFetchPolicy;
         /**
         * Specifies the `FetchPolicy` to be used after this query has completed.
         * 
-        * @docGroup
-        * 
-        * 3. Caching options
+        * @docGroup 3. Caching options
         */
-        nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy);
+        nextFetchPolicy?: WatchQueryFetchPolicy | ((this: ApolloClient.WatchQueryOptions<TData, TVariables>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy);
         /**
-        * Defaults to the initial value of options.fetchPolicy, but can be explicitly configured to specify the WatchQueryFetchPolicy to revert back to whenever variables change (unless nextFetchPolicy intervenes).
-        * 
-        * @docGroup
+        * Defaults to the initial value of options.fetchPolicy, but can be explicitly
+        * configured to specify the WatchQueryFetchPolicy to revert back to whenever
+        * variables change (unless nextFetchPolicy intervenes).
         * 
-        * 3. Caching options
+        * @docGroup 3. Caching options
         */
         initialFetchPolicy: WatchQueryFetchPolicy;
         /**
-        * Specifies whether a `NetworkStatus.refetch` operation should merge incoming field data with existing data, or overwrite the existing data. Overwriting is probably preferable, but merging is currently the default behavior, for backwards compatibility with Apollo Client 3.x.
+        * Specifies whether a `NetworkStatus.refetch` operation should merge
+        * incoming field data with existing data, or overwrite the existing data.
+        * Overwriting is probably preferable, but merging is currently the default
+        * behavior, for backwards compatibility with Apollo Client 3.x.
         * 
-        * @docGroup
-        * 
-        * 3. Caching options
+        * @docGroup 3. Caching options
         */
         refetchWritePolicy?: RefetchWritePolicy;
         /**
@@ -96,17 +51,13 @@ export declare namespace ObservableQuery {
         * 
         * The default value is `none`, meaning that the query result includes error details but not partial results.
         * 
-        * @docGroup
-        * 
-        * 1. Operation options
+        * @docGroup 1. Operation options
         */
         errorPolicy?: ErrorPolicy;
         /**
         * If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
         * 
-        * @docGroup
-        * 
-        * 2. Networking options
+        * @docGroup 2. Networking options
         */
         context?: DefaultContext;
         /**
@@ -114,9 +65,7 @@ export declare namespace ObservableQuery {
         * 
         * The default value is `0` (no polling).
         * 
-        * @docGroup
-        * 
-        * 2. Networking options
+        * @docGroup 2. Networking options
         */
         pollInterval?: number;
         /**
@@ -124,9 +73,7 @@ export declare namespace ObservableQuery {
         * 
         * The default value is `true`.
         * 
-        * @docGroup
-        * 
-        * 2. Networking options
+        * @docGroup 2. Networking options
         */
         notifyOnNetworkStatusChange?: boolean;
         /**
@@ -134,25 +81,21 @@ export declare namespace ObservableQuery {
         * 
         * The default value is `false`.
         * 
-        * @docGroup
-        * 
-        * 3. Caching options
+        * @docGroup 3. Caching options
         */
         returnPartialData?: boolean;
         /**
-        * A callback function that's called whenever a refetch attempt occurs while polling. If the function returns `true`, the refetch is skipped and not reattempted until the next poll interval.
+        * A callback function that's called whenever a refetch attempt occurs
+        * while polling. If the function returns `true`, the refetch is
+        * skipped and not reattempted until the next poll interval.
         * 
-        * @docGroup
-        * 
-        * 2. Networking options
+        * @docGroup 2. Networking options
         */
         skipPollAttempt?: () => boolean;
         /**
         * A GraphQL query string parsed into an AST with the gql template literal.
         * 
-        * @docGroup
-        * 
-        * 1. Operation options
+        * @docGroup 1. Operation options
         */
         query: DocumentNode | TypedDocumentNode<TData, TVariables>;
         /**
@@ -160,12 +103,53 @@ export declare namespace ObservableQuery {
         * 
         * Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
         * 
-        * @docGroup
-        * 
-        * 1. Operation options
+        * @docGroup 1. Operation options
         */
         variables: TVariables;
     };
+    type FetchMoreOptions<TData, TVariables extends OperationVariables, TFetchData = TData, TFetchVars extends OperationVariables = TVariables> = {
+        /**
+        * A GraphQL query string parsed into an AST with the gql template literal.
+        * 
+        * @docGroup 1. Operation options
+        */
+        query?: DocumentNode | TypedDocumentNode<TFetchData, TFetchVars>;
+        /**
+        * An object containing all of the GraphQL variables your query requires to execute.
+        * 
+        * Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value.
+        * 
+        * @docGroup 1. Operation options
+        */
+        variables?: Partial<NoInfer<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?: ErrorPolicy;
+        /**
+        * If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
+        * 
+        * @docGroup 2. Networking options
+        */
+        context?: DefaultContext;
+        updateQuery?: (previousQueryResult: Unmasked<TData>, options: {
+            fetchMoreResult: Unmasked<TFetchData>;
+            variables: TFetchVars;
+        }) => Unmasked<TData>;
+    };
+    interface SubscribeToMoreOptions<TData = unknown, TSubscriptionVariables extends OperationVariables = OperationVariables, TSubscriptionData = TData, TVariables extends OperationVariables = TSubscriptionVariables> {
+        document: DocumentNode | TypedDocumentNode<TSubscriptionData, TSubscriptionVariables>;
+        variables?: TSubscriptionVariables;
+        updateQuery?: SubscribeToMoreUpdateQueryFn<TData, TVariables, TSubscriptionData>;
+        onError?: (error: ErrorLike) => void;
+        context?: DefaultContext;
+    }
     /**
     * @internal
     * This describes the `WatchOptions` used by `ObservableQuery` to
@@ -189,6 +173,39 @@ export declare namespace ObservableQuery {
         */
         lastOwnDiff?: Cache.DiffResult<TData>;
     }
+    type Result<TData, TStates extends DataState<TData>["dataState"] = DataState<TData>["dataState"]> = {
+        /**
+        * A single ErrorLike object describing the error that occured during the latest
+        * query execution.
+        * 
+        * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+        * 
+        * @docGroup 1. Operation data
+        */
+        error?: ErrorLike;
+        /**
+        * If `true`, the query is still in flight and results have not yet been returned.
+        * 
+        * @docGroup 2. Network info
+        */
+        loading: boolean;
+        /**
+        * A number indicating the current network state of the query's associated request. [See possible values.](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/core/networkStatus.ts#L4)
+        * 
+        * Used in conjunction with the [`notifyOnNetworkStatusChange`](#notifyonnetworkstatuschange) option.
+        * 
+        * @docGroup 2. Network info
+        */
+        networkStatus: NetworkStatus;
+        /**
+        * Describes whether `data` is a complete or partial result. This flag is only
+        * set when `returnPartialData` is `true` in query options.
+        * 
+        * @deprecated This field will be removed in a future version of Apollo Client.
+        * @docGroup 1. Operation data
+        */
+        partial: boolean;
+    } & GetDataState<TData, TStates>;
     /**
      * Promise returned by `reobserve` and `refetch` methods.
      *
@@ -205,8 +222,40 @@ export declare namespace ObservableQuery {
          */
         retain(): this;
     }
+    namespace DocumentationTypes {
+        type OperatorFunctionChain<From, To> = [];
+        interface ObservableMethods<TData, OperatorResult> {
+            /**
+            * 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(...operators: OperatorFunctionChain<ObservableQuery.Result<TData>, OperatorResult>): Observable<OperatorResult>;
+            /**
+            * 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(observerOrNext: Partial<Observer<ObservableQuery.Result<MaybeMasked<TData>>>> | ((value: ObservableQuery.Result<MaybeMasked<TData>>) => void)): Subscription;
+        }
+    }
 }
-export declare class ObservableQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables> implements Subscribable<ApolloQueryResult<MaybeMasked<TData>>>, InteropObservable<ApolloQueryResult<MaybeMasked<TData>>> {
+export declare class ObservableQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables> implements Subscribable<ObservableQuery.Result<MaybeMasked<TData>>>, InteropObservable<ObservableQuery.Result<MaybeMasked<TData>>> {
     readonly options: ObservableQuery.Options<TData, TVariables>;
     readonly queryName?: string;
     /**
@@ -238,15 +287,40 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
     private get networkStatus();
     constructor({ queryManager, options, transformedQuery, }: {
         queryManager: QueryManager;
-        options: WatchQueryOptions<TVariables, TData>;
+        options: ApolloClient.WatchQueryOptions<TData, TVariables>;
         transformedQuery?: DocumentNode | TypedDocumentNode<TData, TVariables>;
         queryId?: string;
     });
     private initializeObservablesQueue;
-    subscribe: (observer: Partial<Observer<ApolloQueryResult<MaybeMasked<TData>>>> | ((value: ApolloQueryResult<MaybeMasked<TData>>) => void)) => Subscription;
-    pipe: Observable<ApolloQueryResult<MaybeMasked<TData>>>["pipe"];
-    [Symbol.observable]: () => Subscribable<ApolloQueryResult<MaybeMasked<TData>>>;
-    ["@@observable"]: () => Subscribable<ApolloQueryResult<MaybeMasked<TData>>>;
+    /**
+     * 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: (observerOrNext: Partial<Observer<ObservableQuery.Result<MaybeMasked<TData>>>> | ((value: ObservableQuery.Result<MaybeMasked<TData>>) => void)) => Subscription;
+    /**
+     * 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: Observable<ObservableQuery.Result<MaybeMasked<TData>>>["pipe"];
+    [Symbol.observable]: () => Subscribable<ObservableQuery.Result<MaybeMasked<TData>>>;
+    ["@@observable"]: () => Subscribable<ObservableQuery.Result<MaybeMasked<TData>>>;
     /**
     * @internal
     * 
@@ -258,25 +332,32 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
     private getInitialResult;
     private resubscribeCache;
     private stableLastResult?;
-    getCurrentResult(): ApolloQueryResult<MaybeMasked<TData>>;
+    getCurrentResult(): ObservableQuery.Result<MaybeMasked<TData>>;
     /**
      * 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.
      */
-    refetch(variables?: Partial<TVariables>): ObservableQuery.ResultPromise<QueryResult<TData>>;
+    refetch(variables?: Partial<TVariables>): ObservableQuery.ResultPromise<ApolloClient.QueryResult<TData>>;
     /**
      * 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>({ query, variables, context, errorPolicy, updateQuery, }: FetchMoreOptions<TData, TVariables, TFetchData, TFetchVars>): Promise<QueryResult<TFetchData>>;
+    fetchMore<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(options: ObservableQuery.FetchMoreOptions<TData, TVariables, TFetchData, TFetchVars>): Promise<ApolloClient.QueryResult<TFetchData>>;
     /**
      * 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.
      *
      * This function returns _another_ function that you can call to terminate the subscription.
      */
-    subscribeToMore<TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables>(options: SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData, TVariables>): () => void;
+    subscribeToMore<TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables>(options: ObservableQuery.SubscribeToMoreOptions<TData, TSubscriptionVariables, TSubscriptionData, TVariables>): () => void;
     /**
     * @internal
     * 
@@ -289,19 +370,17 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
      * `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: `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 old results immediately if the variables
-     * have not changed.
-     *
-     * 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.
      */
-    setVariables(variables: TVariables): Promise<QueryResult<TData>>;
+    setVariables(variables: TVariables): Promise<ApolloClient.QueryResult<TData>>;
     /**
      * A function that enables you to update the query's cached result without executing a followup GraphQL operation.
      *
@@ -324,8 +403,11 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
     /**
      * 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?: Partial<ObservableQuery.Options<TData, TVariables>>): ObservableQuery.ResultPromise<QueryResult<MaybeMasked<TData>>>;
+    reobserve(newOptions?: Partial<ObservableQuery.Options<TData, TVariables>>): ObservableQuery.ResultPromise<ApolloClient.QueryResult<MaybeMasked<TData>>>;
     private _reobserve;
     hasObservers(): boolean;
     /**
@@ -362,8 +444,9 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
     /**
     * @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.
     */

package/core/ObservableQuery.js

@@ -1,9 +1,8 @@
 import { equal } from "@wry/equality";
 import { BehaviorSubject, Observable, share, Subject, tap } from "rxjs";
 import { __DEV__ } from "@apollo/client/utilities/environment";
-import { compact, filterMap, getOperationDefinition, getOperationName, getQueryDefinition, preventUnhandledRejection, toQueryResult, } from "@apollo/client/utilities/internal";
+import { compact, equalByQuery, filterMap, getOperationDefinition, getOperationName, getQueryDefinition, preventUnhandledRejection, toQueryResult, } from "@apollo/client/utilities/internal";
 import { invariant } from "@apollo/client/utilities/invariant";
-import { equalByQuery } from "./equalByQuery.js";
 import { isNetworkRequestInFlight, NetworkStatus } from "./networkStatus.js";
 const { assign, hasOwnProperty } = Object;
 const uninitialized = {
@@ -162,7 +161,32 @@ export 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"];
@@ -318,6 +342,13 @@ export 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.
      */
@@ -340,7 +371,7 @@ export class ObservableQuery {
             const queryDef = getQueryDefinition(this.query);
             const vars = queryDef.variableDefinitions;
             if (!vars || !vars.some((v) => v.variable.name.value === "variables")) {
-                __DEV__ && invariant.warn(78, variables, queryDef.name?.value || queryDef);
+                __DEV__ && invariant.warn(77, variables, queryDef.name?.value || queryDef);
             }
         }
         if (variables && !equal(this.variables, variables)) {
@@ -353,13 +384,10 @@ export class ObservableQuery {
             newNetworkStatus: 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, }) {
         invariant(
             this.options.fetchPolicy !== "cache-only",
-            79,
+            78,
             getOperationName(this.query, "(anonymous)")
         );
         const combinedOptions = {
@@ -393,7 +421,7 @@ export class ObservableQuery {
         let wasUpdated = false;
         const isCached = this.options.fetchPolicy !== "no-cache";
         if (!isCached) {
-            invariant(updateQuery, 80);
+            invariant(updateQuery, 79);
         }
         const { finalize, pushNotification } = this.pushOperation(NetworkStatus.fetchMore);
         pushNotification({
@@ -525,7 +553,7 @@ export class ObservableQuery {
                         onError(error);
                     }
                     else {
-                        __DEV__ && invariant.error(81, error);
+                        invariant.error(80, error);
                     }
                     return;
                 }
@@ -560,14 +588,12 @@ export 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.
@@ -771,7 +797,7 @@ export class ObservableQuery {
                 if (!this.didWarnCacheOnlyPolling &&
                     pollInterval &&
                     fetchPolicy === "cache-only") {
-                    __DEV__ && invariant.warn(82, getOperationName(this.query, "(anonymous)"));
+                    __DEV__ && invariant.warn(81, getOperationName(this.query, "(anonymous)"));
                     this.didWarnCacheOnlyPolling = true;
                 }
             }
@@ -823,6 +849,9 @@ export 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);
@@ -1129,8 +1158,9 @@ export 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.
     */
@@ -1263,7 +1293,7 @@ export class ObservableQuery {
 }
 export function logMissingFieldErrors(missing) {
     if (__DEV__ && missing) {
-        __DEV__ && invariant.debug(83, missing);
+        __DEV__ && invariant.debug(82, missing);
     }
 }
 function isEqualQuery(a, b) {