@apollo/client 4.2.0-alpha.2 → 4.2.0-alpha.4

package/__cjs/core/ApolloClient.d.cts

@@ -12,7 +12,8 @@ import type { LazyType, OptionWithFallback, SignatureStyle, VariablesOption, var
 import { getApolloClientMemoryInternals } from "@apollo/client/utilities/internal";
 import type { DeclareDefaultOptions, DefaultOptions } from "./defaultOptions.cjs";
 import type { ObservableQuery } from "./ObservableQuery.cjs";
-import type { DefaultContext, ErrorLike, InternalRefetchQueriesInclude, InternalRefetchQueriesResult, MutationQueryReducersMap, MutationUpdaterFunction, NormalizedExecutionResult, OnQueryUpdated, OperationVariables, RefetchQueriesInclude, RefetchQueriesPromiseResults, SubscriptionObservable, TypedDocumentNode } from "./types.cjs";
+import type { RefetchEventManager } from "./RefetchEventManager.cjs";
+import type { DefaultContext, ErrorLike, InternalRefetchQueriesInclude, InternalRefetchQueriesResult, MutationQueryReducersMap, MutationUpdaterFunction, NormalizedExecutionResult, OnQueryUpdated, OperationVariables, RefetchOn, RefetchQueriesInclude, RefetchQueriesPromiseResults, SubscriptionObservable, TypedDocumentNode } from "./types.cjs";
 import type { ErrorPolicy, FetchPolicy, MutationFetchPolicy, NextFetchPolicyContext, RefetchWritePolicy, WatchQueryFetchPolicy } from "./watchQueryOptions.cjs";
 /**
 * @knipignore
@@ -28,6 +29,13 @@ export interface ReferenceToAvoidDroppingImportOnBuild {
 }
 export declare namespace ApolloClient {
     export type { DeclareDefaultOptions, DefaultOptions };
+    export namespace DocumentationTypes {
+        interface DefaultOptions {
+            watchQuery?: Partial<ApolloClient.WatchQueryOptions<any, any>>;
+            query?: Partial<ApolloClient.QueryOptions<any, any>>;
+            mutate?: Partial<ApolloClient.MutateOptions<any, any, any>>;
+        }
+    }
     export interface Options extends InternalTypes.DefaultOptionsParentObject {
         /**
          * An `ApolloLink` instance to serve as Apollo Client's network layer. For more information, see [Advanced HTTP networking](https://www.apollographql.com/docs/react/networking/advanced-http-networking/).
@@ -99,6 +107,11 @@ export declare namespace ApolloClient {
          * Do not pass in experiments that are not provided by Apollo.
          */
         experiments?: ApolloClient.Experiment[];
+        /**
+         * The `RefetchEventManager` instance that manages automatic refetches for
+         * the client.
+         */
+        refetchEventManager?: RefetchEventManager;
     }
     export interface DevtoolsOptions {
         /**
@@ -216,24 +229,118 @@ export declare namespace ApolloClient {
         */
         mutation: DocumentNode | TypedDocumentNode<TData, TVariables>;
     } & VariablesOption<NoInfer<TVariables>>;
-    export interface MutateResult<TData = unknown> {
-        /**
-        * The data returned from your mutation. Can be `undefined` if the `errorPolicy`
-        * is `all` or `ignore` and the server returns a GraphQL response with `errors`
-        * but not `data` or a network error is returned.
-        */
-        data: TData | undefined;
+    export namespace mutate {
+        interface DefaultOptions extends ApolloClient.DefaultOptions.Mutate.Calculated {
+        }
+        type ResultForOptions<TData, TVariables extends OperationVariables, TCache extends ApolloCache, TOptions extends Record<string, unknown> | MutateOptions<any, TVariables, TCache>> = LazyType<MutateResult<MaybeMasked<TData>, OptionWithFallback<TOptions, DefaultOptions, "errorPolicy"> & ErrorPolicy>>;
+        namespace Signatures {
+            interface Classic {
+                /**
+                * @deprecated Avoid manually specifying generics on `client.mutate`.
+                * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your mutation results.
+                *
+                *
+                * This resolves a single mutation according to the options specified and returns a
+                * Promise which is either resolved with the resulting data or rejected with an
+                * error. In some cases both `data` and `errors` might be undefined, for example
+                * when `errorPolicy` is set to `'ignore'`.
+                * 
+                * It takes options as an object with the following keys and values:
+                */
+                <TData = unknown, TVariables extends OperationVariables = OperationVariables, TCache extends ApolloCache = ApolloCache>(options: ApolloClient.MutateOptions<TData, TVariables, TCache>): Promise<ApolloClient.MutateResult<MaybeMasked<TData>>>;
+            }
+            interface Modern {
+                /**
+                * This resolves a single mutation according to the options specified and returns a
+                * Promise which is either resolved with the resulting data or rejected with an
+                * error. In some cases both `data` and `errors` might be undefined, for example
+                * when `errorPolicy` is set to `'ignore'`.
+                * 
+                * It takes options as an object with the following keys and values:
+                */
+                <TData, TVariables extends OperationVariables, TCache extends ApolloCache, TOptions extends ApolloClient.MutateOptions<NoInfer<TData>, NoInfer<TVariables>, TCache> & VariablesOption<TVariables & {
+                    [K in Exclude<keyof TOptions["variables"], keyof TVariables>]?: never;
+                }>>(options: TOptions & {
+                    mutation: TypedDocumentNode<TData, TVariables>;
+                }): Promise<ApolloClient.mutate.ResultForOptions<TData, TVariables, TCache, TOptions>>;
+            }
+            type Evaluated = SignatureStyle extends "classic" ? Classic : Modern;
+        }
         /**
-        * If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`.
+        * This resolves a single mutation according to the options specified and returns a
+        * Promise which is either resolved with the resulting data or rejected with an
+        * error. In some cases both `data` and `errors` might be undefined, for example
+        * when `errorPolicy` is set to `'ignore'`.
         * 
-        * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+        * It takes options as an object with the following keys and values:
         */
-        error?: ErrorLike;
+        interface Signature extends Signatures.Evaluated {
+        }
+    }
+    export type MutateResultMap<TData = unknown> = {
+        none: {
+            /**
+            * The data returned from your mutation. Can be `undefined` if the `errorPolicy`
+            * is `all` or `ignore` and the server returns a GraphQL response with `errors`
+            * but not `data` or a network error is returned.
+            */
+            data: TData;
+            /**
+            * If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`.
+            * 
+            * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+            */
+            error?: never;
+        };
+        all: {
+            /**
+            * The data returned from your mutation. Can be `undefined` if the `errorPolicy`
+            * is `all` or `ignore` and the server returns a GraphQL response with `errors`
+            * but not `data` or a network error is returned.
+            */
+            data: TData | undefined;
+            /**
+            * If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`.
+            * 
+            * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+            */
+            error?: ErrorLike;
+        };
+        ignore: {
+            /**
+            * The data returned from your mutation. Can be `undefined` if the `errorPolicy`
+            * is `all` or `ignore` and the server returns a GraphQL response with `errors`
+            * but not `data` or a network error is returned.
+            */
+            data: TData | undefined;
+            /**
+            * If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`.
+            * 
+            * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+            */
+            error?: never;
+        };
+        undefined: {
+            /**
+            * The data returned from your mutation. Can be `undefined` if the `errorPolicy`
+            * is `all` or `ignore` and the server returns a GraphQL response with `errors`
+            * but not `data` or a network error is returned.
+            */
+            data: TData | undefined;
+            /**
+            * If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`.
+            * 
+            * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+            */
+            error?: ErrorLike;
+        };
+    };
+    export type MutateResult<TData = unknown, TErrorPolicy extends ErrorPolicy | undefined = undefined> = MutateResultMap<TData>[`${TErrorPolicy}`] & {
         /**
         * Custom extensions returned from the GraphQL server
         */
         extensions?: Record<string, unknown>;
-    }
+    };
     /**
      * Query options.
      */
@@ -271,7 +378,7 @@ export declare namespace ApolloClient {
         */
         fetchPolicy?: FetchPolicy;
     } & VariablesOption<NoInfer<TVariables>>;
-    export type QueryResultMap<TData = unknown, TErrorPolicy extends ErrorPolicy | undefined = undefined> = {
+    export type QueryResultMap<TData = unknown> = {
         none: {
             /**
             * An object containing the result of your GraphQL query after it completes.
@@ -349,7 +456,7 @@ export declare namespace ApolloClient {
             error?: ErrorLike;
         };
     };
-    export type QueryResult<TData = unknown, TErrorPolicy extends ErrorPolicy | undefined = undefined> = QueryResultMap<TData, TErrorPolicy>[`${TErrorPolicy}`];
+    export type QueryResult<TData = unknown, TErrorPolicy extends ErrorPolicy | undefined = undefined> = QueryResultMap<TData>[`${TErrorPolicy}`];
     export namespace query {
         interface DefaultOptions extends ApolloClient.DefaultOptions.Query.Calculated {
         }
@@ -598,6 +705,25 @@ export declare namespace ApolloClient {
         */
         query: DocumentNode | TypedDocumentNode<TData, TVariables>;
         /**
+        * Determines whether events trigger refetches for the query. Provide an
+        * object mapping each refetch event to `true` (enable), `false` (disable)
+        * or a callback function that returns `true`/`false` to control individual
+        * events. Provide `false` to disable all automatic refetch events for this
+        * query. Provide `true` to enable all automatic refetch events for this query.
+        * Provide a callback function to perform additional logic to determine
+        * whether to enable or disable a refetch for a query.
+        * 
+        * `@remarks`
+        * `refetchOn` inherits from `defaultOptions.watchQuery.refetchOn`. If
+        * `defaultOptions.watchQuery.refetchOn` is not set, all refetch events are
+        * enabled by default.
+        * 
+        * This option only has an effect when the client is configured with a
+        * `refetchEventManager`.
+        * @docGroup 1. Operation options
+        */
+        refetchOn?: RefetchOn.Option;
+        /**
         * @internal This API is meant for framework integrations only.
         * Do not use for everyday use.
         *
@@ -827,6 +953,15 @@ export declare namespace ApolloClient {
          * server at all or just resolve from the cache, etc.
          */
         function query<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.QueryOptions<TData, TVariables>): Promise<ApolloClient.QueryResult<MaybeMasked<TData>>>;
+        /**
+         * This resolves a single mutation according to the options specified and returns a
+         * Promise which is either resolved with the resulting data or rejected with an
+         * error. In some cases both `data` and `errors` might be undefined, for example
+         * when `errorPolicy` is set to `'ignore'`.
+         *
+         * It takes options as an object with the following keys and values:
+         */
+        function mutate<TData = unknown, TVariables extends OperationVariables = OperationVariables, TCache extends ApolloCache = ApolloCache>(options: ApolloClient.MutateOptions<TData, TVariables, TCache>): Promise<ApolloClient.MutateResult<MaybeMasked<TData>>>;
     }
 }
 /**
@@ -855,6 +990,7 @@ export declare class ApolloClient {
     queryDeduplication: boolean;
     defaultOptions: ApolloClient.DefaultOptions;
     readonly devtoolsConfig: ApolloClient.DevtoolsOptions;
+    readonly refetchEventManager: RefetchEventManager | undefined;
     private queryManager;
     private devToolsHookCb?;
     private resetStoreCallbacks;
@@ -907,6 +1043,7 @@ export declare class ApolloClient {
      * - Unsubscribes all active `ObservableQuery` instances by emitting a `completed` event
      * - Rejects all currently running queries with "QueryManager stopped while query was in flight"
      * - Removes all queryRefs from the suspense cache
+     * - Disconnects the `RefetchEventManager` if configured.
      */
     stop(): void;
     /**
@@ -940,14 +1077,14 @@ export declare class ApolloClient {
     */
     query: ApolloClient.query.Signature;
     /**
-     * This resolves a single mutation according to the options specified and returns a
-     * Promise which is either resolved with the resulting data or rejected with an
-     * error. In some cases both `data` and `errors` might be undefined, for example
-     * when `errorPolicy` is set to `'ignore'`.
-     *
-     * It takes options as an object with the following keys and values:
-     */
-    mutate<TData = unknown, TVariables extends OperationVariables = OperationVariables, TCache extends ApolloCache = ApolloCache>(options: ApolloClient.MutateOptions<TData, TVariables, TCache>): Promise<ApolloClient.MutateResult<MaybeMasked<TData>>>;
+    * This resolves a single mutation according to the options specified and returns a
+    * Promise which is either resolved with the resulting data or rejected with an
+    * error. In some cases both `data` and `errors` might be undefined, for example
+    * when `errorPolicy` is set to `'ignore'`.
+    * 
+    * It takes options as an object with the following keys and values:
+    */
+    mutate: ApolloClient.mutate.Signature;
     /**
      * This subscribes to a graphql subscription according to the options specified and returns an
      * `Observable` which either emits received data or an error.

package/__cjs/core/ObservableQuery.cjs

@@ -84,7 +84,7 @@ class ObservableQuery {
         // Make sure we don't store "standby" as the initialFetchPolicy.
         initialFetchPolicy = fetchPolicy === "standby" ? defaultFetchPolicy : (fetchPolicy), } = options;
         if (options[internal_1.variablesUnknownSymbol]) {
-            (0, invariant_1.invariant)(fetchPolicy === "standby", 80);
+            (0, invariant_1.invariant)(fetchPolicy === "standby", 82);
             this.variablesUnknown = true;
         }
         this.lastQuery = transformedQuery;
@@ -390,7 +390,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(81, variables, queryDef.name?.value || queryDef);
+                __DEV__ && invariant_1.invariant.warn(83, variables, queryDef.name?.value || queryDef);
             }
         }
         if (variables && !(0, equality_1.equal)(this.variables, variables)) {
@@ -406,7 +406,7 @@ class ObservableQuery {
     fetchMore({ query, variables, context, errorPolicy, updateQuery, }) {
         (0, invariant_1.invariant)(
             this.options.fetchPolicy !== "cache-only",
-            82,
+            84,
             (0, internal_1.getOperationName)(this.query, "(anonymous)")
         );
         const combinedOptions = {
@@ -440,7 +440,7 @@ class ObservableQuery {
         let wasUpdated = false;
         const isCached = this.options.fetchPolicy !== "no-cache";
         if (!isCached) {
-            (0, invariant_1.invariant)(updateQuery, 83);
+            (0, invariant_1.invariant)(updateQuery, 85);
         }
         const { finalize, pushNotification } = this.pushOperation(networkStatus_js_1.NetworkStatus.fetchMore);
         pushNotification({
@@ -616,7 +616,7 @@ class ObservableQuery {
                         onError(error);
                     }
                     else {
-                        invariant_1.invariant.error(84, error);
+                        invariant_1.invariant.error(86, error);
                     }
                     return;
                 }
@@ -867,7 +867,7 @@ class ObservableQuery {
                 if (!this.didWarnCacheOnlyPolling &&
                     pollInterval &&
                     fetchPolicy === "cache-only") {
-                    __DEV__ && invariant_1.invariant.warn(85, (0, internal_1.getOperationName)(this.query, "(anonymous)"));
+                    __DEV__ && invariant_1.invariant.warn(87, (0, internal_1.getOperationName)(this.query, "(anonymous)"));
                     this.didWarnCacheOnlyPolling = true;
                 }
             }
@@ -1367,7 +1367,7 @@ class ObservableQuery {
 exports.ObservableQuery = ObservableQuery;
 function logMissingFieldErrors(missing) {
     if (environment_1.__DEV__ && missing) {
-        __DEV__ && invariant_1.invariant.debug(86, missing);
+        __DEV__ && invariant_1.invariant.debug(88, missing);
     }
 }
 function isEqualQuery(a, b) {