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

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

@@ -1,4 +1,4 @@
-import type { ApolloClient, DataState, DefaultContext, DocumentNode, ErrorLike, ErrorPolicy, GetDataState, MaybeMasked, OperationVariables, RefetchWritePolicy, TypedDocumentNode, WatchQueryFetchPolicy, WatchQueryOptions } from "@apollo/client";
+import type { ApolloClient, DataState, DefaultContext, DocumentNode, ErrorLike, ErrorPolicy, GetDataState, MaybeMasked, OperationVariables, RefetchWritePolicy, TypedDocumentNode, WatchQueryFetchPolicy } from "@apollo/client";
 import type { SubscribeToMoreFunction } from "@apollo/client";
 import { NetworkStatus } from "@apollo/client";
 import type { FetchMoreFunction, RefetchFunction } from "@apollo/client/react/internal";
@@ -87,7 +87,7 @@ export declare namespace useSuspenseQuery {
             * 
             * We recommend using `skipToken` in place of the `skip` option as it is more type-safe.
             * 
-            * This option is deprecated and only supported to ease the migration from useQuery. It will be removed in a future release.
+            * This option is deprecated and only supported to ease the migration from `useQuery`. It will be removed in a future release. Please use [`skipToken`](https://www.apollographql.com/docs/react/api/react/hooks#skiptoken) instead of the `skip` option as it is more type-safe.
             * 
             * @docGroup
             * 
@@ -95,10 +95,14 @@ export declare namespace useSuspenseQuery {
             * 
             *
             * @example Recommended usage of `skipToken`:
+            *
             * ```ts
-            * import { skipToken, useSuspenseQuery } from '@apollo/client';
+            * import { skipToken, useSuspenseQuery } from "@apollo/client";
             *
-            * const { data } = useSuspenseQuery(query, id ? { variables: { id } } : skipToken);
+            * const { data } = useSuspenseQuery(
+            *   query,
+            *   id ? { variables: { id } } : skipToken
+            * );
             * ```
             */
             skip?: boolean;
@@ -106,17 +110,9 @@ export declare namespace useSuspenseQuery {
     }
     type Options<TVariables extends OperationVariables = OperationVariables> = Base.Options<TVariables> & VariablesOption<TVariables>;
     namespace DocumentationTypes {
-        interface Options<TVariables extends OperationVariables = OperationVariables> extends Base.Options<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;
+        namespace useSuspenseQuery {
+            interface Options<TVariables extends OperationVariables = OperationVariables> extends Base.Options<TVariables>, UtilityDocumentationTypes.VariableOptions<TVariables> {
+            }
         }
     }
     namespace Base {
@@ -148,6 +144,10 @@ export declare namespace useSuspenseQuery {
             * @docGroup
             * 
             * 3. Helper functions
+            * 
+            *
+            * @remarks
+            * Calling this function will cause the component to re-suspend, unless the call site is wrapped in [`startTransition`](https://react.dev/reference/react/startTransition).
             */
             fetchMore: FetchMoreFunction<TData, TVariables>;
             /**
@@ -167,9 +167,15 @@ export declare namespace useSuspenseQuery {
             * 
             * See also [Refetching](https://www.apollographql.com/docs/react/data/queries/#refetching).
             * 
+            * Returns a `ResultPromise` with an additional `.retain()` method. Calling `.retain()` keeps the network operation running even if the `ObservableQuery` no longer requires the result.
+            * 
             * @docGroup
             * 
             * 3. Helper functions
+            * 
+            *
+            * @remarks
+            * Calling this function will cause the component to re-suspend, unless the call site is wrapped in [`startTransition`](https://react.dev/reference/react/startTransition).
             */
             refetch: RefetchFunction<TData, TVariables>;
             /**
@@ -187,42 +193,457 @@ export declare namespace useSuspenseQuery {
     }
     type Result<TData = unknown, TVariables extends OperationVariables = OperationVariables, TStates extends DataState<TData>["dataState"] = DataState<TData>["dataState"]> = Base.Result<TData, TVariables> & GetDataState<MaybeMasked<TData>, TStates>;
     namespace DocumentationTypes {
-        interface Result<TData = unknown, TVariables extends OperationVariables = OperationVariables> extends Base.Result<TData, TVariables>, UtilityDocumentationTypes.DataState<TData> {
+        namespace useSuspenseQuery {
+            interface Result<TData = unknown, TVariables extends OperationVariables = OperationVariables> extends Base.Result<TData, TVariables>, UtilityDocumentationTypes.DataState<TData> {
+            }
         }
     }
+    namespace DocumentationTypes {
+        /**
+        * Test For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+        * 
+        * @param query - A GraphQL query document parsed into an AST by `gql`.
+        * 
+        * @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+        * 
+        * @example
+        * ```jsx
+        * import { Suspense } from "react";
+        * import { useSuspenseQuery } from "@apollo/client";
+        * 
+        * const listQuery = gql`
+        *   query {
+        *     list {
+        *       id
+        *     }
+        *   }
+        * `;
+        * 
+        * function App() {
+        *   return (
+        *     <Suspense fallback={<Spinner />}>
+        *       <List />
+        *     </Suspense>
+        *   );
+        * }
+        * 
+        * function List() {
+        *   const { data } = useSuspenseQuery(listQuery);
+        * 
+        *   return (
+        *     <ol>
+        *       {data.list.map((item) => (
+        *         <Item key={item.id} id={item.id} />
+        *       ))}
+        *     </ol>
+        *   );
+        * }
+        * ```
+        */
+        function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: useSuspenseQuery.Options<TVariables>): useSuspenseQuery.Result<TData, TVariables>;
+    }
 }
+/**
+ * For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+ *
+ * @example
+ *
+ * ```jsx
+ * import { Suspense } from "react";
+ * import { useSuspenseQuery } from "@apollo/client";
+ *
+ * const listQuery = gql`
+ *   query {
+ *     list {
+ *       id
+ *     }
+ *   }
+ * `;
+ *
+ * function App() {
+ *   return (
+ *     <Suspense fallback={<Spinner />}>
+ *       <List />
+ *     </Suspense>
+ *   );
+ * }
+ *
+ * function List() {
+ *   const { data } = useSuspenseQuery(listQuery);
+ *
+ *   return (
+ *     <ol>
+ *       {data.list.map((item) => (
+ *         <Item key={item.id} id={item.id} />
+ *       ))}
+ *     </ol>
+ *   );
+ * }
+ * ```
+ *
+ * @param query - A GraphQL query document parsed into an AST by `gql`.
+ * @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+ */
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useSuspenseQuery.Options<NoInfer<TVariables>> & {
     returnPartialData: true;
     errorPolicy: "ignore" | "all";
 }): useSuspenseQuery.Result<TData, TVariables, "complete" | "streaming" | "partial" | "empty">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useSuspenseQuery.Options<NoInfer<TVariables>> & {
     errorPolicy: "ignore" | "all";
 }): useSuspenseQuery.Result<TData, TVariables, "complete" | "streaming" | "empty">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useSuspenseQuery.Options<NoInfer<TVariables>> & {
     skip: boolean;
     returnPartialData: true;
 }): useSuspenseQuery.Result<TData, TVariables, "complete" | "empty" | "streaming" | "partial">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useSuspenseQuery.Options<NoInfer<TVariables>> & {
     returnPartialData: true;
 }): useSuspenseQuery.Result<TData, TVariables, "partial" | "streaming" | "complete">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useSuspenseQuery.Options<NoInfer<TVariables>> & {
     skip: boolean;
 }): useSuspenseQuery.Result<TData, TVariables, "complete" | "streaming" | "empty">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: SkipToken | (useSuspenseQuery.Options<NoInfer<TVariables>> & {
     returnPartialData: true;
 })): useSuspenseQuery.Result<TData, TVariables, "empty" | "streaming" | "complete" | "partial">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, ...[options]: {} extends TVariables ? [
     options?: useSuspenseQuery.Options<NoInfer<TVariables>>
 ] : [options: useSuspenseQuery.Options<NoInfer<TVariables>>]): useSuspenseQuery.Result<TData, TVariables, "complete" | "streaming">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, ...[options]: {} extends TVariables ? [
     options?: SkipToken | useSuspenseQuery.Options<NoInfer<TVariables>>
 ] : [options: SkipToken | useSuspenseQuery.Options<NoInfer<TVariables>>]): useSuspenseQuery.Result<TData, TVariables, "complete" | "streaming" | "empty">;
+/**
+* For a detailed explanation of `useSuspenseQuery`, see the [fetching with Suspense reference](https://www.apollographql.com/docs/react/data/suspense).
+* 
+* @param query - A GraphQL query document parsed into an AST by `gql`.
+* 
+* @param options - An optional object containing options for the query. Instead of passing a `useSuspenseQuery.Options` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending.
+* 
+* @example
+* ```jsx
+* import { Suspense } from "react";
+* import { useSuspenseQuery } from "@apollo/client";
+* 
+* const listQuery = gql`
+*   query {
+*     list {
+*       id
+*     }
+*   }
+* `;
+* 
+* function App() {
+*   return (
+*     <Suspense fallback={<Spinner />}>
+*       <List />
+*     </Suspense>
+*   );
+* }
+* 
+* function List() {
+*   const { data } = useSuspenseQuery(listQuery);
+* 
+*   return (
+*     <ol>
+*       {data.list.map((item) => (
+*         <Item key={item.id} id={item.id} />
+*       ))}
+*     </ol>
+*   );
+* }
+* ```
+*/
 export declare function useSuspenseQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: SkipToken | useSuspenseQuery.Options<NoInfer<TVariables>>): useSuspenseQuery.Result<TData, TVariables, "complete" | "streaming" | "empty">;
 interface UseWatchQueryOptionsHookOptions<TData, TVariables extends OperationVariables> {
     client: ApolloClient;
     query: DocumentNode | TypedDocumentNode<TData, TVariables>;
     options: SkipToken | useSuspenseQuery.Options<TVariables>;
 }
-export declare function useWatchQueryOptions<TData, TVariables extends OperationVariables>({ client, query, options, }: UseWatchQueryOptionsHookOptions<TData, TVariables>): WatchQueryOptions<TVariables, TData>;
+export declare function useWatchQueryOptions<TData, TVariables extends OperationVariables>({ client, query, options, }: UseWatchQueryOptionsHookOptions<TData, TVariables>): ApolloClient.WatchQueryOptions<TData, TVariables>;
 export {};
 //# sourceMappingURL=useSuspenseQuery.d.ts.map