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

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

@@ -1,4 +1,4 @@
-import type { ApolloClient, DataState, DefaultContext, DocumentNode, ErrorPolicy, OperationVariables, RefetchWritePolicy, TypedDocumentNode, WatchQueryFetchPolicy } from "@apollo/client";
+import type { ApolloClient, DataState, DefaultContext, DocumentNode, ErrorPolicy, OperationVariables, RefetchOn, RefetchWritePolicy, TypedDocumentNode, WatchQueryFetchPolicy } from "@apollo/client";
 import type { SubscribeToMoreFunction } from "@apollo/client";
 import type { QueryRef } from "@apollo/client/react";
 import type { FetchMoreFunction, RefetchFunction } from "@apollo/client/react/internal";
@@ -109,113 +109,575 @@ export declare namespace useLoadableQuery {
         * @docGroup 3. Caching options
         */
         returnPartialData?: boolean;
+        /**
+        * 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;
     }
     interface DefaultOptions extends ApolloClient.DefaultOptions.WatchQuery.Calculated {
     }
     type ResultForOptions<TData, TVariables extends OperationVariables, TOptions extends Record<string, never> | Options> = Result<TData, TVariables, "complete" | "streaming" | (OptionWithFallback<TOptions, DefaultOptions, "errorPolicy"> extends ("none") ? never : "empty") | (OptionWithFallback<TOptions, DefaultOptions, "returnPartialData"> extends false ? never : "partial")>;
     namespace DocumentationTypes {
-        /**
-         * A hook for imperatively loading a query, such as responding to a user
-         * interaction.
-         *
-         * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
-         *
-         * @example
-         *
-         * ```jsx
-         * import { gql, useLoadableQuery } from "@apollo/client";
-         *
-         * const GET_GREETING = gql`
-         *   query GetGreeting($language: String!) {
-         *     greeting(language: $language) {
-         *       message
-         *     }
-         *   }
-         * `;
-         *
-         * function App() {
-         *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
-         *
-         *   return (
-         *     <>
-         *       <button onClick={() => loadGreeting({ language: "english" })}>
-         *         Load greeting
-         *       </button>
-         *       <Suspense fallback={<div>Loading...</div>}>
-         *         {queryRef && <Hello queryRef={queryRef} />}
-         *       </Suspense>
-         *     </>
-         *   );
-         * }
-         *
-         * function Hello({ queryRef }) {
-         *   const { data } = useReadQuery(queryRef);
-         *
-         *   return <div>{data.greeting.message}</div>;
-         * }
-         * ```
-         *
-         * @param query - A GraphQL query document parsed into an AST by `gql`.
-         * @param options - Options to control how the query is executed.
-         * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
-         */
         interface useLoadableQuery {
+            /**
+             * A hook for imperatively loading a query, such as responding to a user
+             * interaction.
+             *
+             * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+             *
+             * @example
+             *
+             * ```jsx
+             * import { gql, useLoadableQuery } from "@apollo/client";
+             *
+             * const GET_GREETING = gql`
+             *   query GetGreeting($language: String!) {
+             *     greeting(language: $language) {
+             *       message
+             *     }
+             *   }
+             * `;
+             *
+             * function App() {
+             *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+             *
+             *   return (
+             *     <>
+             *       <button onClick={() => loadGreeting({ language: "english" })}>
+             *         Load greeting
+             *       </button>
+             *       <Suspense fallback={<div>Loading...</div>}>
+             *         {queryRef && <Hello queryRef={queryRef} />}
+             *       </Suspense>
+             *     </>
+             *   );
+             * }
+             *
+             * function Hello({ queryRef }) {
+             *   const { data } = useReadQuery(queryRef);
+             *
+             *   return <div>{data.greeting.message}</div>;
+             * }
+             * ```
+             *
+             * @param query - A GraphQL query document parsed into an AST by `gql`.
+             * @param options - Options to control how the query is executed.
+             * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
+             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLoadableQuery.Options): useLoadableQuery.Result<TData, TVariables>;
         }
-        /**
-        * @deprecated Avoid manually specifying generics on `useLoadableQuery`.
-        * Instead, rely on TypeScript's type inference along with a correctly typed `TypedDocumentNode` to get accurate types for your query results.
-        */
         interface useLoadableQuery_Deprecated {
+            /**
+            * @deprecated Avoid manually specifying generics on `useLoadableQuery`.
+            * 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 loading a query, such as responding to a user
+            * interaction.
+            * 
+            * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql, useLoadableQuery } from "@apollo/client";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function App() {
+            *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+            * 
+            *   return (
+            *     <>
+            *       <button onClick={() => loadGreeting({ language: "english" })}>
+            *         Load greeting
+            *       </button>
+            *       <Suspense fallback={<div>Loading...</div>}>
+            *         {queryRef && <Hello queryRef={queryRef} />}
+            *       </Suspense>
+            *     </>
+            *   );
+            * }
+            * 
+            * function Hello({ queryRef }) {
+            *   const { data } = useReadQuery(queryRef);
+            * 
+            *   return <div>{data.greeting.message}</div>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Options to control how the query is executed.
+            * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
+            */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLoadableQuery.Options): useLoadableQuery.Result<TData, TVariables>;
         }
     }
     namespace Signatures {
         /**
+        * @deprecated Avoid manually specifying generics on `useLoadableQuery`.
+        * 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 loading a query, such as responding to a user
+        * interaction.
         * 
+        * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+        * 
+        * @example
+        * 
+        * ```jsx
+        * import { gql, useLoadableQuery } from "@apollo/client";
+        * 
+        * const GET_GREETING = gql`
+        *   query GetGreeting($language: String!) {
+        *     greeting(language: $language) {
+        *       message
+        *     }
+        *   }
+        * `;
+        * 
+        * function App() {
+        *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+        * 
+        *   return (
+        *     <>
+        *       <button onClick={() => loadGreeting({ language: "english" })}>
+        *         Load greeting
+        *       </button>
+        *       <Suspense fallback={<div>Loading...</div>}>
+        *         {queryRef && <Hello queryRef={queryRef} />}
+        *       </Suspense>
+        *     </>
+        *   );
+        * }
+        * 
+        * function Hello({ queryRef }) {
+        *   const { data } = useReadQuery(queryRef);
+        * 
+        *   return <div>{data.greeting.message}</div>;
+        * }
+        * ```
+        * 
+        * @param query - A GraphQL query document parsed into an AST by `gql`.
+        * @param options - Options to control how the query is executed.
+        * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
         */
         interface Classic {
             /**
+            * @deprecated Avoid manually specifying generics on `useLoadableQuery`.
+            * 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 loading a query, such as responding to a user
+            * interaction.
+            * 
+            * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql, useLoadableQuery } from "@apollo/client";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
             * 
+            * function App() {
+            *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+            * 
+            *   return (
+            *     <>
+            *       <button onClick={() => loadGreeting({ language: "english" })}>
+            *         Load greeting
+            *       </button>
+            *       <Suspense fallback={<div>Loading...</div>}>
+            *         {queryRef && <Hello queryRef={queryRef} />}
+            *       </Suspense>
+            *     </>
+            *   );
+            * }
+            * 
+            * function Hello({ queryRef }) {
+            *   const { data } = useReadQuery(queryRef);
+            * 
+            *   return <div>{data.greeting.message}</div>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Options to control how the query is executed.
+            * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLoadableQuery.Options & {
                 returnPartialData: true;
                 errorPolicy: "ignore" | "all";
             }): useLoadableQuery.Result<TData, TVariables, "complete" | "streaming" | "partial" | "empty">;
             /**
+            * @deprecated Avoid manually specifying generics on `useLoadableQuery`.
+            * 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 loading a query, such as responding to a user
+            * interaction.
+            * 
+            * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql, useLoadableQuery } from "@apollo/client";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function App() {
+            *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+            * 
+            *   return (
+            *     <>
+            *       <button onClick={() => loadGreeting({ language: "english" })}>
+            *         Load greeting
+            *       </button>
+            *       <Suspense fallback={<div>Loading...</div>}>
+            *         {queryRef && <Hello queryRef={queryRef} />}
+            *       </Suspense>
+            *     </>
+            *   );
+            * }
+            * 
+            * function Hello({ queryRef }) {
+            *   const { data } = useReadQuery(queryRef);
             * 
+            *   return <div>{data.greeting.message}</div>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Options to control how the query is executed.
+            * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLoadableQuery.Options & {
                 errorPolicy: "ignore" | "all";
             }): useLoadableQuery.Result<TData, TVariables, "complete" | "streaming" | "empty">;
             /**
+            * @deprecated Avoid manually specifying generics on `useLoadableQuery`.
+            * 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 loading a query, such as responding to a user
+            * interaction.
+            * 
+            * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql, useLoadableQuery } from "@apollo/client";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
             * 
+            * function App() {
+            *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+            * 
+            *   return (
+            *     <>
+            *       <button onClick={() => loadGreeting({ language: "english" })}>
+            *         Load greeting
+            *       </button>
+            *       <Suspense fallback={<div>Loading...</div>}>
+            *         {queryRef && <Hello queryRef={queryRef} />}
+            *       </Suspense>
+            *     </>
+            *   );
+            * }
+            * 
+            * function Hello({ queryRef }) {
+            *   const { data } = useReadQuery(queryRef);
+            * 
+            *   return <div>{data.greeting.message}</div>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Options to control how the query is executed.
+            * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLoadableQuery.Options & {
                 returnPartialData: true;
             }): useLoadableQuery.Result<TData, TVariables, "complete" | "streaming" | "partial">;
             /**
+            * @deprecated Avoid manually specifying generics on `useLoadableQuery`.
+            * 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 loading a query, such as responding to a user
+            * interaction.
+            * 
+            * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
             * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql, useLoadableQuery } from "@apollo/client";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function App() {
+            *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+            * 
+            *   return (
+            *     <>
+            *       <button onClick={() => loadGreeting({ language: "english" })}>
+            *         Load greeting
+            *       </button>
+            *       <Suspense fallback={<div>Loading...</div>}>
+            *         {queryRef && <Hello queryRef={queryRef} />}
+            *       </Suspense>
+            *     </>
+            *   );
+            * }
+            * 
+            * function Hello({ queryRef }) {
+            *   const { data } = useReadQuery(queryRef);
+            * 
+            *   return <div>{data.greeting.message}</div>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Options to control how the query is executed.
+            * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
             */
             <TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: useLoadableQuery.Options): useLoadableQuery.Result<TData, TVariables, "complete" | "streaming">;
         }
         /**
+        * A hook for imperatively loading a query, such as responding to a user
+        * interaction.
+        * 
+        * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+        * 
+        * @example
+        * 
+        * ```jsx
+        * import { gql, useLoadableQuery } from "@apollo/client";
+        * 
+        * const GET_GREETING = gql`
+        *   query GetGreeting($language: String!) {
+        *     greeting(language: $language) {
+        *       message
+        *     }
+        *   }
+        * `;
+        * 
+        * function App() {
+        *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+        * 
+        *   return (
+        *     <>
+        *       <button onClick={() => loadGreeting({ language: "english" })}>
+        *         Load greeting
+        *       </button>
+        *       <Suspense fallback={<div>Loading...</div>}>
+        *         {queryRef && <Hello queryRef={queryRef} />}
+        *       </Suspense>
+        *     </>
+        *   );
+        * }
         * 
+        * function Hello({ queryRef }) {
+        *   const { data } = useReadQuery(queryRef);
+        * 
+        *   return <div>{data.greeting.message}</div>;
+        * }
+        * ```
+        * 
+        * @param query - A GraphQL query document parsed into an AST by `gql`.
+        * @param options - Options to control how the query is executed.
+        * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
         */
         interface Modern {
             /**
+            * A hook for imperatively loading a query, such as responding to a user
+            * interaction.
+            * 
+            * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql, useLoadableQuery } from "@apollo/client";
+            * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function App() {
+            *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
             * 
+            *   return (
+            *     <>
+            *       <button onClick={() => loadGreeting({ language: "english" })}>
+            *         Load greeting
+            *       </button>
+            *       <Suspense fallback={<div>Loading...</div>}>
+            *         {queryRef && <Hello queryRef={queryRef} />}
+            *       </Suspense>
+            *     </>
+            *   );
+            * }
+            * 
+            * function Hello({ queryRef }) {
+            *   const { data } = useReadQuery(queryRef);
+            * 
+            *   return <div>{data.greeting.message}</div>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Options to control how the query is executed.
+            * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
             */
             <TData, TVariables extends OperationVariables, TOptions extends never>(query: DocumentNode | TypedDocumentNode<TData, TVariables>): useLoadableQuery.ResultForOptions<TData, TVariables, Record<string, never>>;
             /**
+            * A hook for imperatively loading a query, such as responding to a user
+            * interaction.
+            * 
+            * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+            * 
+            * @example
+            * 
+            * ```jsx
+            * import { gql, useLoadableQuery } from "@apollo/client";
             * 
+            * const GET_GREETING = gql`
+            *   query GetGreeting($language: String!) {
+            *     greeting(language: $language) {
+            *       message
+            *     }
+            *   }
+            * `;
+            * 
+            * function App() {
+            *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+            * 
+            *   return (
+            *     <>
+            *       <button onClick={() => loadGreeting({ language: "english" })}>
+            *         Load greeting
+            *       </button>
+            *       <Suspense fallback={<div>Loading...</div>}>
+            *         {queryRef && <Hello queryRef={queryRef} />}
+            *       </Suspense>
+            *     </>
+            *   );
+            * }
+            * 
+            * function Hello({ queryRef }) {
+            *   const { data } = useReadQuery(queryRef);
+            * 
+            *   return <div>{data.greeting.message}</div>;
+            * }
+            * ```
+            * 
+            * @param query - A GraphQL query document parsed into an AST by `gql`.
+            * @param options - Options to control how the query is executed.
+            * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
             */
             <TData, TVariables extends OperationVariables, TOptions extends useLoadableQuery.Options>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: TOptions): useLoadableQuery.ResultForOptions<TData, TVariables, TOptions>;
         }
         type Evaluated = SignatureStyle extends "classic" ? Classic : Modern;
     }
     /**
+    * A hook for imperatively loading a query, such as responding to a user
+    * interaction.
+    * 
+    * > Refer to the [Suspense - Fetching in response to user interaction](https://www.apollographql.com/docs/react/data/suspense#fetching-in-response-to-user-interaction) section for a more in-depth overview of `useLoadableQuery`.
+    * 
+    * @example
+    * 
+    * ```jsx
+    * import { gql, useLoadableQuery } from "@apollo/client";
+    * 
+    * const GET_GREETING = gql`
+    *   query GetGreeting($language: String!) {
+    *     greeting(language: $language) {
+    *       message
+    *     }
+    *   }
+    * `;
+    * 
+    * function App() {
+    *   const [loadGreeting, queryRef] = useLoadableQuery(GET_GREETING);
+    * 
+    *   return (
+    *     <>
+    *       <button onClick={() => loadGreeting({ language: "english" })}>
+    *         Load greeting
+    *       </button>
+    *       <Suspense fallback={<div>Loading...</div>}>
+    *         {queryRef && <Hello queryRef={queryRef} />}
+    *       </Suspense>
+    *     </>
+    *   );
+    * }
+    * 
+    * function Hello({ queryRef }) {
+    *   const { data } = useReadQuery(queryRef);
+    * 
+    *   return <div>{data.greeting.message}</div>;
+    * }
+    * ```
     * 
+    * @param query - A GraphQL query document parsed into an AST by `gql`.
+    * @param options - Options to control how the query is executed.
+    * @returns A tuple in the form of `[loadQuery, queryRef, handlers]`
     */
     interface Signature extends Signatures.Evaluated {
     }