@apollo/client 4.0.0-alpha.8 → 4.0.0-rc.0

package/__cjs/core/ObservableQuery.d.cts

@@ -1,67 +1,264 @@
+import type { DocumentNode } from "graphql";
 import type { InteropObservable, Observer, Subscribable, Subscription } from "rxjs";
-import type { Observable } from "rxjs";
-import type { MissingFieldError } from "@apollo/client/cache";
+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 { QueryInfo } from "./QueryInfo.cjs";
 import type { QueryManager } from "./QueryManager.cjs";
-import type { ApolloQueryResult, ErrorLike, OperationVariables, QueryResult, TypedDocumentNode } from "./types.cjs";
-import type { FetchMoreQueryOptions, SubscribeToMoreOptions, UpdateQueryMapFn, WatchQueryOptions } from "./watchQueryOptions.cjs";
-export interface FetchMoreOptions<TData = unknown, TVariables = OperationVariables> {
-    updateQuery?: (previousQueryResult: TData, options: {
-        fetchMoreResult?: TData;
-        variables?: TVariables;
-    }) => TData;
-}
-export declare class ObservableQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables> implements Subscribable<ApolloQueryResult<MaybeMasked<TData>>>, InteropObservable<ApolloQueryResult<MaybeMasked<TData>>> {
+import type { ApolloQueryResult, DefaultContext, OperationVariables, QueryResult, TypedDocumentNode } from "./types.cjs";
+import type { ErrorPolicy, NextFetchPolicyContext, RefetchWritePolicy, SubscribeToMoreOptions, UpdateQueryMapFn, WatchQueryFetchPolicy, WatchQueryOptions } from "./watchQueryOptions.cjs";
+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>;
+};
+export declare namespace ObservableQuery {
+    type Options<TData = unknown, TVariables extends OperationVariables = OperationVariables> = {
+        /**
+        * Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server).
+        * 
+        * For details, see [Setting a fetch policy](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy).
+        * 
+        * The default value is `cache-first`.
+        * 
+        * @docGroup
+        * 
+        * 3. Caching options
+        */
+        fetchPolicy: WatchQueryFetchPolicy;
+        /**
+        * Specifies the `FetchPolicy` to be used after this query has completed.
+        * 
+        * @docGroup
+        * 
+        * 3. Caching options
+        */
+        nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, 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
+        * 
+        * 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.
+        * 
+        * @docGroup
+        * 
+        * 3. Caching options
+        */
+        refetchWritePolicy?: RefetchWritePolicy;
+        /**
+        * 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;
+        /**
+        * Specifies the interval (in milliseconds) at which the query polls for updated results.
+        * 
+        * The default value is `0` (no polling).
+        * 
+        * @docGroup
+        * 
+        * 2. Networking options
+        */
+        pollInterval?: number;
+        /**
+        * If `true`, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs.
+        * 
+        * The default value is `true`.
+        * 
+        * @docGroup
+        * 
+        * 2. Networking options
+        */
+        notifyOnNetworkStatusChange?: boolean;
+        /**
+        * If `true`, the query can return partial results from the cache if the cache doesn't contain results for all queried fields.
+        * 
+        * The default value is `false`.
+        * 
+        * @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.
+        * 
+        * @docGroup
+        * 
+        * 2. Networking options
+        */
+        skipPollAttempt?: () => boolean;
+        /**
+        * A GraphQL query string parsed into an AST with the gql template literal.
+        * 
+        * @docGroup
+        * 
+        * 1. Operation options
+        */
+        query: DocumentNode | TypedDocumentNode<TData, TVariables>;
+        /**
+        * 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: TVariables;
+    };
     /**
-     * @internal
-     * A slot used by the `useQuery` hook to indicate that `client.watchQuery`
-     * should not register the query immediately, but instead wait for the query to
-     * be started registered with the `QueryManager` when `useSyncExternalStore`
-     * actively subscribes to it.
+    * @internal
+    * This describes the `WatchOptions` used by `ObservableQuery` to
+    * subscribe to the cache.
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    interface CacheWatchOptions<TData = unknown, TVariables extends OperationVariables = OperationVariables> extends Cache.WatchOptions<TData, TVariables> {
+        /**
+        * @internal
+        * We cannot suppress the broadcast completely, since that would
+        * result in external updates to be lost if we go from
+        * (external A) -> (own B) -> (external C) when A and C have the same
+        * value.
+        * Without the `own B` being broadcast, the `cache.watch` would swallow
+        * C.
+        * So instead we track the last "own diff" and suppress further processing
+        * in the callback.
+        * 
+        * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+        */
+        lastOwnDiff?: Cache.DiffResult<TData>;
+    }
+    /**
+     * Promise returned by `reobserve` and `refetch` methods.
+     *
+     * By default, if the `ObservableQuery` is not interested in the result
+     * of this operation anymore, the network operation will be cancelled.
+     *
+     * This has an additional `retain` method that can be used to keep the
+     * network operation running until it is finished nonetheless.
      */
-    private static inactiveOnCreation;
-    readonly options: WatchQueryOptions<TVariables, TData>;
-    readonly queryId: string;
+    interface ResultPromise<T> extends Promise<T> {
+        /**
+         * Kepp the network operation running until it is finished, even if
+         * `ObservableQuery` unsubscribed from the operation.
+         */
+        retain(): this;
+    }
+}
+export declare class ObservableQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables> implements Subscribable<ApolloQueryResult<MaybeMasked<TData>>>, InteropObservable<ApolloQueryResult<MaybeMasked<TData>>> {
+    readonly options: ObservableQuery.Options<TData, TVariables>;
     readonly queryName?: string;
+    /**
+    * @internal will be read and written from `QueryInfo`
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    _lastWrite?: unknown;
     get query(): TypedDocumentNode<TData, TVariables>;
     /**
      * An object containing the variables that were provided for the query.
      */
-    get variables(): TVariables | undefined;
+    get variables(): TVariables;
+    private unsubscribeFromCache?;
+    private input;
     private subject;
-    private readonly observable;
-    private initialResult;
     private isTornDown;
     private queryManager;
     private subscriptions;
-    private waitForOwnResult;
-    private last?;
-    private lastQuery?;
-    private queryInfo;
+    /**
+     * If an `ObservableQuery` is created with a `network-only` fetch policy,
+     * it should actually start receiving cache updates, but not before it has
+     * received the first result from the network.
+     */
+    private waitForNetworkResult;
+    private lastQuery;
     private linkSubscription?;
-    private linkObservable?;
     private pollingInfo?;
-    private networkStatus;
-    constructor({ queryManager, queryInfo, options, }: {
+    private get networkStatus();
+    constructor({ queryManager, options, transformedQuery, }: {
         queryManager: QueryManager;
-        queryInfo: QueryInfo;
         options: WatchQueryOptions<TVariables, TData>;
+        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>>>;
-    /** @internal */
-    resetDiff(): void;
-    private getCurrentFullResult;
-    getCurrentResult(saveAsLastResult?: boolean): ApolloQueryResult<MaybeMasked<TData>>;
-    isDifferentFromLastResult(newResult: ApolloQueryResult<TData>, variables?: TVariables): boolean | undefined;
-    private getLast;
-    getLastResult(variablesMustMatch?: boolean): ApolloQueryResult<TData> | undefined;
-    getLastError(variablesMustMatch?: boolean): ErrorLike | undefined;
-    resetLastResults(): void;
+    /**
+    * @internal
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    getCacheDiff({ optimistic }?: {
+        optimistic?: boolean | undefined;
+    }): Cache.DiffResult<TData>;
+    private getInitialResult;
+    private resubscribeCache;
+    private stableLastResult?;
+    getCurrentResult(): ApolloQueryResult<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.
@@ -69,24 +266,23 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
      * @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>): Promise<QueryResult<TData>>;
+    refetch(variables?: Partial<TVariables>): ObservableQuery.ResultPromise<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>(fetchMoreOptions: FetchMoreQueryOptions<TFetchVars, TFetchData> & {
-        updateQuery?: (previousQueryResult: Unmasked<TData>, options: {
-            fetchMoreResult: Unmasked<TFetchData>;
-            variables: TFetchVars;
-        }) => Unmasked<TData>;
-    }): Promise<QueryResult<TFetchData>>;
+    fetchMore<TFetchData = TData, TFetchVars extends OperationVariables = TVariables>({ query, variables, context, errorPolicy, updateQuery, }: FetchMoreOptions<TData, TVariables, TFetchData, TFetchVars>): Promise<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;
-    /** @internal */
-    silentSetOptions(newOptions: Partial<WatchQueryOptions<TVariables, TData>>): void;
+    /**
+    * @internal
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    applyOptions(newOptions: Partial<ObservableQuery.Options<TData, TVariables>>): void;
     /**
      * Update the variables of this observable query, and fetch the new results
      * if they've changed. Most users should prefer `refetch` instead of
@@ -122,30 +318,65 @@ export declare class ObservableQuery<TData = unknown, TVariables extends Operati
     stopPolling(): void;
     private applyNextFetchPolicy;
     private fetch;
+    private didWarnCacheOnlyPolling;
     private updatePolling;
-    private updateLastResult;
+    private cancelPolling;
     /**
      * Reevaluate the query, optionally against new options. New options will be
      * merged with the current options when given.
      */
-    reobserve(newOptions?: Partial<WatchQueryOptions<TVariables, TData>>): Promise<QueryResult<MaybeMasked<TData>>>;
-    private observe;
-    private reportResult;
-    private reportError;
+    reobserve(newOptions?: Partial<ObservableQuery.Options<TData, TVariables>>): ObservableQuery.ResultPromise<QueryResult<MaybeMasked<TData>>>;
+    private _reobserve;
     hasObservers(): boolean;
+    /**
+     * Tears down the `ObservableQuery` and stops all active operations by sending a `complete` notification.
+     */
+    stop(): void;
     private tearDownQuery;
     private transformDocument;
     private maskResult;
     private dirty;
     private notifyTimeout?;
-    /** @internal */
-    protected resetNotifications(): void;
-    private cancelNotifyTimeout;
-    /** @internal */
-    protected scheduleNotify(): void;
-    /** @internal */
-    protected notify(): void;
+    /**
+    * @internal
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    private resetNotifications;
+    /**
+    * @internal
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    private scheduleNotify;
+    /**
+    * @internal
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    notify(scheduled?: boolean): void;
+    private activeOperations;
+    private pushOperation;
+    private calculateNetworkStatus;
+    private abortActiveOperations;
+    /**
+    * @internal
+    * Called from `clearStore`.
+    * * 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.
+    */
+    reset(): void;
+    /**
+    * @internal
+    * 
+    * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+    */
+    private setResult;
+    private operator;
     private reobserveCacheFirst;
+    private getVariablesWithDefaults;
 }
 export declare function logMissingFieldErrors(missing: MissingFieldError | MissingTree | undefined): void;
 //# sourceMappingURL=ObservableQuery.d.cts.map