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

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> = {
         /**
@@ -72,7 +30,7 @@ export declare namespace ObservableQuery {
         * 
         * 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).
         * 
@@ -166,6 +124,57 @@ export declare namespace ObservableQuery {
         */
         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 +198,48 @@ 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 +256,39 @@ 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.
+            * 
+            * @returns The Observable result of all the operators having been called in the order they were passed in.
+            * 
+            * @example
+            * ```ts
+            * import { filter, map } from 'rxjs';
+            * 
+            * observableQuery
+            *   .pipe(
+            *     filter(...),
+            *     map(...),
+            *   )
+            *   .subscribe(x => console.log(x));
+            * ```
+            */
+            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 +320,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 +365,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 +403,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 +436,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 +477,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);
+                        __DEV__ && 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) {