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

package/react/hooks-compiled/useLazyQuery.d.ts

@@ -1,6 +1,6 @@
 import type { TypedDocumentNode } from "@graphql-typed-document-node/core";
 import type { DocumentNode } from "graphql";
-import type { ApolloClient, DataState, DefaultContext, ErrorLike, ErrorPolicy, GetDataState, InternalTypes, MaybeMasked, ObservableQuery, OperationVariables, RefetchWritePolicy, SubscribeToMoreFunction, UpdateQueryMapFn, WatchQueryFetchPolicy } from "@apollo/client";
+import type { ApolloClient, DataState, DefaultContext, ErrorLike, ErrorPolicy, GetDataState, InternalTypes, MaybeMasked, ObservableQuery, OperationVariables, RefetchOn, RefetchWritePolicy, SubscribeToMoreFunction, UpdateQueryMapFn, WatchQueryFetchPolicy } from "@apollo/client";
 import { NetworkStatus } from "@apollo/client";
 import type { DocumentationTypes as UtilityDocumentationTypes, NoInfer, OptionWithFallback, SignatureStyle, VariablesOption } from "@apollo/client/utilities/internal";
 export declare namespace useLazyQuery {
@@ -82,6 +82,25 @@ export declare namespace useLazyQuery {
         * @docGroup 1. Operation options
         */
         client?: ApolloClient;
+        /**
+        * 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;
     }
     namespace DocumentationTypes {
         namespace useLazyQuery {
@@ -286,84 +305,359 @@ export declare namespace useLazyQuery {
     }
     type ResultForOptions<TData, TVariables extends OperationVariables, TOptions extends Record<string, never> | Options<TData, TVariables>> = ResultTuple<TData, TVariables, "complete" | "streaming" | "empty" | (OptionWithFallback<TOptions, DefaultOptions, "returnPartialData"> extends false ? never : "partial")>;
     namespace DocumentationTypes {
-        /**
-         * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
-         *
-         * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
-         *
-         * @example
-         *
-         * ```jsx
-         * import { gql } from "@apollo/client";
-         * import { useLazyQuery } from "@apollo/client/react";
-         *
-         * const GET_GREETING = gql`
-         *   query GetGreeting($language: String!) {
-         *     greeting(language: $language) {
-         *       message
-         *     }
-         *   }
-         * `;
-         *
-         * function Hello() {
-         *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
-         *     variables: { language: "english" },
-         *   });
-         *   if (called && loading) return <p>Loading ...</p>;
-         *   if (!called) {
-         *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
-         *   }
-         *   return <h1>Hello {data.greeting.message}!</h1>;
-         * }
-         * ```
-         *
-         * @param query - A GraphQL query document parsed into an AST by `gql`.
-         * @param options - Default options to control how the query is executed.
-         * @returns A tuple in the form of `[execute, result]`
-         */
         interface useLazyQuery {
+            /**
+             * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+             *
+             * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
+             *
+             * @example
+             *
+             * ```jsx
+             * import { gql } from "@apollo/client";
+             * import { useLazyQuery } from "@apollo/client/react";
+             *
+             * const GET_GREETING = gql`
+             *   query GetGreeting($language: String!) {
+             *     greeting(language: $language) {
+             *       message
+             *     }
+             *   }
+             * `;
+             *
+             * function Hello() {
+             *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+             *     variables: { language: "english" },
+             *   });
+             *   if (called && loading) return <p>Loading ...</p>;
+             *   if (!called) {
+             *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+             *   }
+             *   return <h1>Hello {data.greeting.message}!</h1>;
+             * }
+             * ```
+             *
+             * @param query - A GraphQL query document parsed into an AST by `gql`.
+             * @param options - Default options to control how the query is executed.
+             * @returns A tuple in the form of `[execute, result]`
+             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLazyQuery.Options<TData, TVariables>): useLazyQuery.ResultTuple<TData, TVariables>;
         }
-        /**
-        * @deprecated Avoid manually specifying generics on `useLazyQuery`.
-        * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your query results.
-        */
         interface useLazyQuery_Deprecated {
+            /**
+            * @deprecated Avoid manually specifying generics on `useLazyQuery`.
+            * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your query results.
+            *
+            *
+            * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+            * 
+            * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql } from "@apollo/client";
+            * import { useLazyQuery } from "@apollo/client/react";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function Hello() {
+            *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+            *     variables: { language: "english" },
+            *   });
+            *   if (called && loading) return <p>Loading ...</p>;
+            *   if (!called) {
+            *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+            *   }
+            *   return <h1>Hello {data.greeting.message}!</h1>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Default options to control how the query is executed.
+            * @returns A tuple in the form of `[execute, result]`
+            */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLazyQuery.Options<TData, TVariables>): useLazyQuery.ResultTuple<TData, TVariables>;
         }
     }
     namespace Signatures {
         /**
+        * @deprecated Avoid manually specifying generics on `useLazyQuery`.
+        * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your query results.
+        * 
         * 
+        * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+        * 
+        * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
+        * 
+        * @example
+        * 
+        * ```jsx
+        * import { gql } from "@apollo/client";
+        * import { useLazyQuery } from "@apollo/client/react";
+        * 
+        * const GET_GREETING = gql`
+        *   query GetGreeting($language: String!) {
+        *     greeting(language: $language) {
+        *       message
+        *     }
+        *   }
+        * `;
+        * 
+        * function Hello() {
+        *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+        *     variables: { language: "english" },
+        *   });
+        *   if (called && loading) return <p>Loading ...</p>;
+        *   if (!called) {
+        *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+        *   }
+        *   return <h1>Hello {data.greeting.message}!</h1>;
+        * }
+        * ```
+        * 
+        * @param query - A GraphQL query document parsed into an AST by `gql`.
+        * @param options - Default options to control how the query is executed.
+        * @returns A tuple in the form of `[execute, result]`
         */
         interface Classic {
             /**
+            * @deprecated Avoid manually specifying generics on `useLazyQuery`.
+            * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your query results.
+            * 
+            * 
+            * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+            * 
+            * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
             * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql } from "@apollo/client";
+            * import { useLazyQuery } from "@apollo/client/react";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function Hello() {
+            *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+            *     variables: { language: "english" },
+            *   });
+            *   if (called && loading) return <p>Loading ...</p>;
+            *   if (!called) {
+            *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+            *   }
+            *   return <h1>Hello {data.greeting.message}!</h1>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Default options to control how the query is executed.
+            * @returns A tuple in the form of `[execute, result]`
             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLazyQuery.Options<NoInfer<TData>, NoInfer<TVariables>> & {
                 returnPartialData: true;
             }): useLazyQuery.ResultTuple<TData, TVariables, "empty" | "complete" | "streaming" | "partial">;
             /**
+            * @deprecated Avoid manually specifying generics on `useLazyQuery`.
+            * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your query results.
+            * 
+            * 
+            * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+            * 
+            * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql } from "@apollo/client";
+            * import { useLazyQuery } from "@apollo/client/react";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
             * 
+            * function Hello() {
+            *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+            *     variables: { language: "english" },
+            *   });
+            *   if (called && loading) return <p>Loading ...</p>;
+            *   if (!called) {
+            *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+            *   }
+            *   return <h1>Hello {data.greeting.message}!</h1>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Default options to control how the query is executed.
+            * @returns A tuple in the form of `[execute, result]`
             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLazyQuery.Options<NoInfer<TData>, NoInfer<TVariables>> & {
                 returnPartialData: boolean;
             }): useLazyQuery.ResultTuple<TData, TVariables, "empty" | "complete" | "streaming" | "partial">;
             /**
+            * @deprecated Avoid manually specifying generics on `useLazyQuery`.
+            * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your query results.
+            * 
+            * 
+            * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+            * 
+            * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
+            * 
+            * @example
             * 
+            * ```jsx
+            * import { gql } from "@apollo/client";
+            * import { useLazyQuery } from "@apollo/client/react";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function Hello() {
+            *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+            *     variables: { language: "english" },
+            *   });
+            *   if (called && loading) return <p>Loading ...</p>;
+            *   if (!called) {
+            *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+            *   }
+            *   return <h1>Hello {data.greeting.message}!</h1>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Default options to control how the query is executed.
+            * @returns A tuple in the form of `[execute, result]`
             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: useLazyQuery.Options<NoInfer<TData>, NoInfer<TVariables>>): useLazyQuery.ResultTuple<TData, TVariables, "empty" | "complete" | "streaming">;
         }
         /**
+        * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+        * 
+        * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
         * 
+        * @example
+        * 
+        * ```jsx
+        * import { gql } from "@apollo/client";
+        * import { useLazyQuery } from "@apollo/client/react";
+        * 
+        * const GET_GREETING = gql`
+        *   query GetGreeting($language: String!) {
+        *     greeting(language: $language) {
+        *       message
+        *     }
+        *   }
+        * `;
+        * 
+        * function Hello() {
+        *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+        *     variables: { language: "english" },
+        *   });
+        *   if (called && loading) return <p>Loading ...</p>;
+        *   if (!called) {
+        *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+        *   }
+        *   return <h1>Hello {data.greeting.message}!</h1>;
+        * }
+        * ```
+        * 
+        * @param query - A GraphQL query document parsed into an AST by `gql`.
+        * @param options - Default options to control how the query is executed.
+        * @returns A tuple in the form of `[execute, result]`
         */
         interface Modern {
             /**
+            * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+            * 
+            * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
             * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql } from "@apollo/client";
+            * import { useLazyQuery } from "@apollo/client/react";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function Hello() {
+            *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+            *     variables: { language: "english" },
+            *   });
+            *   if (called && loading) return <p>Loading ...</p>;
+            *   if (!called) {
+            *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+            *   }
+            *   return <h1>Hello {data.greeting.message}!</h1>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Default options to control how the query is executed.
+            * @returns A tuple in the form of `[execute, result]`
             */
             <TData, TVariables extends OperationVariables, TOptions extends never>(query: DocumentNode | TypedDocumentNode<TData, TVariables>): useLazyQuery.ResultForOptions<TData, TVariables, Record<string, never>>;
             /**
+            * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+            * 
+            * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
             * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql } from "@apollo/client";
+            * import { useLazyQuery } from "@apollo/client/react";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function Hello() {
+            *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+            *     variables: { language: "english" },
+            *   });
+            *   if (called && loading) return <p>Loading ...</p>;
+            *   if (!called) {
+            *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+            *   }
+            *   return <h1>Hello {data.greeting.message}!</h1>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Default options to control how the query is executed.
+            * @returns A tuple in the form of `[execute, result]`
             */
             <TData, TVariables extends OperationVariables, TOptions extends useLazyQuery.Options<NoInfer<TData>, NoInfer<TVariables>> & {
                 variables?: {
@@ -374,7 +668,39 @@ export declare namespace useLazyQuery {
         type Evaluated = SignatureStyle extends "classic" ? Classic : Modern;
     }
     /**
+    * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction.
+    * 
+    * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`.
+    * 
+    * @example
+    * 
+    * ```jsx
+    * import { gql } from "@apollo/client";
+    * import { useLazyQuery } from "@apollo/client/react";
+    * 
+    * const GET_GREETING = gql`
+    *   query GetGreeting($language: String!) {
+    *     greeting(language: $language) {
+    *       message
+    *     }
+    *   }
+    * `;
+    * 
+    * function Hello() {
+    *   const [loadGreeting, { called, loading, data }] = useLazyQuery(GET_GREETING, {
+    *     variables: { language: "english" },
+    *   });
+    *   if (called && loading) return <p>Loading ...</p>;
+    *   if (!called) {
+    *     return <button onClick={() => loadGreeting()}>Load greeting</button>;
+    *   }
+    *   return <h1>Hello {data.greeting.message}!</h1>;
+    * }
+    * ```
     * 
+    * @param query - A GraphQL query document parsed into an AST by `gql`.
+    * @param options - Default options to control how the query is executed.
+    * @returns A tuple in the form of `[execute, result]`
     */
     interface Signature extends Signatures.Evaluated {
     }

package/react/hooks-compiled/useLazyQuery.js

@@ -76,6 +76,7 @@ export const useLazyQuery = function useLazyQuery(query, options) {
         const updatedOptions = {
             query,
             errorPolicy: stableOptions?.errorPolicy,
+            refetchOn: stableOptions?.refetchOn,
             refetchWritePolicy: stableOptions?.refetchWritePolicy,
             returnPartialData: stableOptions?.returnPartialData,
             notifyOnNetworkStatusChange: stableOptions?.notifyOnNetworkStatusChange,