@apollo/client 4.0.0-rc.0 → 4.0.0-rc.10

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

@@ -0,0 +1,436 @@
+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 { NetworkStatus } from "@apollo/client";
+import type { DocumentationTypes as UtilityDocumentationTypes, NoInfer, VariablesOption } from "@apollo/client/utilities/internal";
+export declare namespace useLazyQuery {
+    import _self = useLazyQuery;
+    interface Options<TData = unknown, TVariables extends OperationVariables = OperationVariables> {
+        /**
+        * Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server).
+        * 
+        * For details, see [Setting a fetch policy](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy).
+        * 
+        * The default value is `cache-first`.
+        * 
+        * @docGroup 3. Caching options
+        */
+        fetchPolicy?: WatchQueryFetchPolicy;
+        /**
+        * Specifies the `FetchPolicy` to be used after this query has completed.
+        * 
+        * @docGroup 3. Caching options
+        */
+        nextFetchPolicy?: WatchQueryFetchPolicy | ((this: ApolloClient.WatchQueryOptions<TData, TVariables>, currentFetchPolicy: WatchQueryFetchPolicy, context: InternalTypes.NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy);
+        /**
+        * Specifies whether a `NetworkStatus.refetch` operation should merge
+        * incoming field data with existing data, or overwrite the existing data.
+        * Overwriting is probably preferable, but merging is currently the default
+        * behavior, for backwards compatibility with Apollo Client 3.x.
+        * 
+        * @docGroup 3. Caching options
+        */
+        refetchWritePolicy?: RefetchWritePolicy;
+        /**
+        * Specifies how the query handles a response that returns both GraphQL errors and partial results.
+        * 
+        * For details, see [GraphQL error policies](https://www.apollographql.com/docs/react/data/error-handling/#graphql-error-policies).
+        * 
+        * The default value is `none`, meaning that the query result includes error details but not partial results.
+        * 
+        * @docGroup 1. Operation options
+        */
+        errorPolicy?: ErrorPolicy;
+        /**
+        * Specifies the interval (in milliseconds) at which the query polls for updated results.
+        * 
+        * The default value is `0` (no polling).
+        * 
+        * @docGroup 2. Networking options
+        */
+        pollInterval?: number;
+        /**
+        * If `true`, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs.
+        * 
+        * The default value is `true`.
+        * 
+        * @docGroup 2. Networking options
+        */
+        notifyOnNetworkStatusChange?: boolean;
+        /**
+        * If `true`, the query can return partial results from the cache if the cache doesn't contain results for all queried fields.
+        * 
+        * The default value is `false`.
+        * 
+        * @docGroup 3. Caching options
+        */
+        returnPartialData?: boolean;
+        /**
+        * A callback function that's called whenever a refetch attempt occurs
+        * while polling. If the function returns `true`, the refetch is
+        * skipped and not reattempted until the next poll interval.
+        * 
+        * @docGroup 2. Networking options
+        */
+        skipPollAttempt?: () => boolean;
+        /**
+        * The instance of `ApolloClient` to use to execute the query.
+        * 
+        * By default, the instance that's passed down via context is used, but you
+        * can provide a different instance here.
+        * 
+        * @docGroup 1. Operation options
+        */
+        client?: ApolloClient;
+    }
+    namespace DocumentationTypes {
+        namespace useLazyQuery {
+            interface Options<TData = unknown, TVariables extends OperationVariables = OperationVariables> extends _self.Options<TData, TVariables> {
+            }
+        }
+    }
+    namespace Base {
+        interface Result<TData, TVariables extends OperationVariables> {
+            /**
+            * A function that instructs the query to begin re-executing at a specified interval (in milliseconds).
+            *      
+            * 
+            * @docGroup 3. Helper functions
+            */
+            startPolling: (pollInterval: number) => void;
+            /**
+            * A function that instructs the query to stop polling after a previous call to `startPolling`.
+            *      
+            * 
+            * @docGroup 3. Helper functions
+            */
+            stopPolling: () => void;
+            /**
+            * A function that enables you to execute a [subscription](https://www.apollographql.com/docs/react/data/subscriptions/), usually to subscribe to specific fields that were included in the query.
+            * 
+            * This function returns _another_ function that you can call to terminate the subscription.
+            *      
+            * 
+            * @docGroup 3. Helper functions
+            */
+            subscribeToMore: SubscribeToMoreFunction<TData, TVariables>;
+            /**
+            * A function that enables you to update the query's cached result without executing a followup GraphQL operation.
+            * 
+            * See [using updateQuery and updateFragment](https://www.apollographql.com/docs/react/caching/cache-interaction/#using-updatequery-and-updatefragment) for additional information.
+            *      
+            * 
+            * @docGroup 3. Helper functions
+            */
+            updateQuery: (mapFn: UpdateQueryMapFn<TData, TVariables>) => void;
+            /**
+            * A function that enables you to re-execute the query, optionally passing in new `variables`.
+            * 
+            * To guarantee that the refetch performs a network request, its `fetchPolicy` is set to `network-only` (unless the original query's `fetchPolicy` is `no-cache` or `cache-and-network`, which also guarantee a network request).
+            * 
+            * 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
+            */
+            refetch: (variables?: Partial<TVariables>) => Promise<ApolloClient.QueryResult<MaybeMasked<TData>>>;
+            /**
+            * A function that helps you fetch the next set of results for a [paginated list field](https://www.apollographql.com/docs/react/pagination/core-api/).
+            *      
+            * 
+            * @docGroup 3. Helper functions
+            */
+            fetchMore: <TFetchData = TData, TFetchVars extends OperationVariables = TVariables>(fetchMoreOptions: ObservableQuery.FetchMoreOptions<TData, TVariables, TFetchData, TFetchVars>) => Promise<ApolloClient.QueryResult<MaybeMasked<TFetchData>>>;
+            /**
+            * The instance of Apollo Client that executed the query.
+            * Can be useful for manually executing followup queries or writing data to the cache.
+            * 
+            * @docGroup 2. Network info
+            */
+            client: ApolloClient;
+            /**
+            * A reference to the internal `ObservableQuery` used by the hook.
+            */
+            observable: ObservableQuery<TData, TVariables>;
+            /**
+            * An object containing the result from the most recent _previous_ execution of this query.
+            * 
+            * This value is `undefined` if this is the query's first execution.
+            * 
+            * @docGroup 1. Operation data
+            */
+            previousData?: MaybeMasked<TData>;
+            /**
+            * A single ErrorLike object describing the error that occured during the latest
+            * query execution.
+            * 
+            * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/).
+            * 
+            * @docGroup 1. Operation data
+            */
+            error?: ErrorLike;
+            /**
+            * If `true`, the query is still in flight and results have not yet been returned.
+            * 
+            * @docGroup 2. Network info
+            */
+            loading: boolean;
+            /**
+            * A number indicating the current network state of the query's associated request. [See possible values.](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/core/networkStatus.ts#L4)
+            * 
+            * Used in conjunction with the [`notifyOnNetworkStatusChange`](#notifyonnetworkstatuschange) option.
+            * 
+            * @docGroup 2. Network info
+            */
+            networkStatus: NetworkStatus;
+        }
+    }
+    type Result<TData, TVariables extends OperationVariables, TStates extends DataState<TData>["dataState"] = DataState<TData>["dataState"]> = Base.Result<TData, TVariables> & (({
+        /**
+         * If `true`, the associated lazy query has been executed.
+         *
+         * @docGroup 2. Network info
+         */
+        called: true;
+        /**
+        * An object containing the variables that were provided for the query.
+        * 
+        * @docGroup 1. Operation data
+        */
+        variables: TVariables;
+    } & GetDataState<MaybeMasked<TData>, TStates>) | {
+        /**
+         * If `true`, the associated lazy query has been executed.
+         *
+         * @docGroup 2. Network info
+         */
+        called: false;
+        /**
+        * An object containing the variables that were provided for the query.
+        * 
+        * @docGroup 1. Operation data
+        */
+        variables: Partial<TVariables>;
+        /**
+        * An object containing the result of your GraphQL query after it completes.
+        * 
+        * This value might be `undefined` if a query results in one or more errors (depending on the query's `errorPolicy`).
+        * 
+        * @docGroup 1. Operation data
+        */
+        data: undefined;
+        /**
+        * Describes the completeness of `data`.
+        * 
+        * - `empty`: No data could be fulfilled from the cache or the result is
+        *   incomplete. `data` is `undefined`.
+        * - `partial`: Some data could be fulfilled from the cache but `data` is
+        *   incomplete. This is only possible when `returnPartialData` is `true`.
+        * - `streaming`: `data` is incomplete as a result of a deferred query and
+        *   the result is still streaming in.
+        * - `complete`: `data` is a fully satisfied query result fulfilled
+        *   either from the cache or network.
+        * 
+        * @docGroup 1. Operation data
+        */
+        dataState: "empty";
+    });
+    namespace DocumentationTypes {
+        namespace useLazyQuery {
+            interface Result<TData, TVariables extends OperationVariables> extends Base.Result<TData, TVariables>, UtilityDocumentationTypes.DataState<TData>, UtilityDocumentationTypes.VariableOptions<TVariables> {
+                /**
+                 * If `true`, the associated lazy query has been executed.
+                 *
+                 * @docGroup 2. Network info
+                 */
+                called: boolean;
+            }
+        }
+    }
+    type ExecOptions<TVariables extends OperationVariables = OperationVariables> = {
+        /**
+        * If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
+        * 
+        * @docGroup 2. Networking options
+        */
+        context?: DefaultContext;
+    } & VariablesOption<TVariables>;
+    namespace DocumentationTypes {
+        namespace useLazyQuery {
+            interface ExecOptions<TVariables extends OperationVariables> extends UtilityDocumentationTypes.VariableOptions<TVariables> {
+                /**
+                * If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain.
+                * 
+                * @docGroup 2. Networking options
+                */
+                context?: DefaultContext;
+            }
+        }
+    }
+    type ResultTuple<TData, TVariables extends OperationVariables, TStates extends DataState<TData>["dataState"] = DataState<TData>["dataState"]> = [
+        execute: ExecFunction<TData, TVariables>,
+        result: useLazyQuery.Result<TData, TVariables, TStates>
+    ];
+    type ExecFunction<TData, TVariables extends OperationVariables> = (...args: {} extends TVariables ? [
+        options?: useLazyQuery.ExecOptions<TVariables>
+    ] : [options: useLazyQuery.ExecOptions<TVariables>]) => ObservableQuery.ResultPromise<ApolloClient.QueryResult<TData>>;
+    namespace DocumentationTypes {
+        namespace useLazyQuery {
+            export import ResultTuple = _self.ResultTuple;
+        }
+    }
+    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]`
+        */
+        function useLazyQuery<TData = unknown, TVariables extends OperationVariables = OperationVariables>(query: DocumentNode | TypedDocumentNode<TData, TVariables>, options: useLazyQuery.Options<TData, TVariables>): useLazyQuery.ResultTuple<TData, TVariables>;
+    }
+}
+/**
+ * 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]`
+ */
+export declare function useLazyQuery<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">;
+/**
+* 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]`
+*/
+export declare function useLazyQuery<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">;
+/**
+* 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]`
+*/
+export declare function useLazyQuery<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">;
+//# sourceMappingURL=useLazyQuery.d.ts.map

package/react/hooks-compiled/useLazyQuery.js

@@ -0,0 +1,143 @@
+import { equal } from "@wry/equality";
+import * as React from "react";
+import { NetworkStatus } from "@apollo/client";
+import { maybeDeepFreeze } from "@apollo/client/utilities/internal";
+import { invariant } from "@apollo/client/utilities/invariant";
+import { useRenderGuard } from "./internal/index.js";
+import { useDeepMemo } from "./internal/useDeepMemo.js";
+import { useIsomorphicLayoutEffect } from "./internal/useIsomorphicLayoutEffect.js";
+import { useApolloClient } from "./useApolloClient.js";
+import { useSyncExternalStore } from "./useSyncExternalStore.js";
+// The following methods, when called will execute the query, regardless of
+// whether the useLazyQuery execute function was called before.
+const EAGER_METHODS = [
+    "refetch",
+    "fetchMore",
+    "updateQuery",
+    "startPolling",
+    "stopPolling",
+    "subscribeToMore",
+];
+export function useLazyQuery(query, options) {
+    const client = useApolloClient(options?.client);
+    const previousDataRef = React.useRef(undefined);
+    const resultRef = React.useRef(undefined);
+    const stableOptions = useDeepMemo(() => options, [options]);
+    const calledDuringRender = useRenderGuard();
+    function createObservable() {
+        return client.watchQuery({
+            ...options,
+            query,
+            initialFetchPolicy: options?.fetchPolicy,
+            fetchPolicy: "standby",
+        });
+    }
+    const [currentClient, setCurrentClient] = React.useState(client);
+    const [observable, setObservable] = React.useState(createObservable);
+    if (currentClient !== client) {
+        setCurrentClient(client);
+        setObservable(createObservable());
+    }
+    // TODO: Revisit after we have RxJS in place. We should be able to use
+    // observable.getCurrentResult() (or equivalent) to get these values which
+    // will hopefully alleviate the need for us to use refs to track these values.
+    const updateResult = React.useCallback((result, forceUpdate) => {
+        const previousData = resultRef.current?.data;
+        if (previousData && !equal(previousData, result.data)) {
+            previousDataRef.current = previousData;
+        }
+        resultRef.current = result;
+        forceUpdate();
+    }, []);
+    const observableResult = useSyncExternalStore(React.useCallback((forceUpdate_0) => {
+        const subscription = observable.subscribe((result_0) => {
+            if (!equal(resultRef.current, result_0)) {
+                updateResult(result_0, forceUpdate_0);
+            }
+        });
+        return () => {
+            subscription.unsubscribe();
+        };
+    }, [observable, updateResult]), () => resultRef.current || initialResult, () => initialResult);
+    // We use useMemo here to make sure the eager methods have a stable identity.
+    const eagerMethods_0 = React.useMemo(() => {
+        const eagerMethods = {};
+        for (const key of EAGER_METHODS) {
+            eagerMethods[key] = function (...args) {
+                invariant(resultRef.current, 29, key);
+                // @ts-expect-error this is just to generic to type
+                return observable[key](...args);
+            };
+        }
+        return eagerMethods;
+    }, [observable]);
+    React.useEffect(() => {
+        const updatedOptions = {
+            query,
+            errorPolicy: stableOptions?.errorPolicy,
+            refetchWritePolicy: stableOptions?.refetchWritePolicy,
+            returnPartialData: stableOptions?.returnPartialData,
+            notifyOnNetworkStatusChange: stableOptions?.notifyOnNetworkStatusChange,
+            nextFetchPolicy: options?.nextFetchPolicy,
+            skipPollAttempt: options?.skipPollAttempt,
+        };
+        // Wait to apply the changed fetch policy until after the execute
+        // function has been called. The execute function will handle setting the
+        // the fetch policy away from standby for us when called for the first time.
+        if (observable.options.fetchPolicy !== "standby" &&
+            stableOptions?.fetchPolicy) {
+            updatedOptions.fetchPolicy = stableOptions.fetchPolicy;
+        }
+        observable.applyOptions(updatedOptions);
+    }, [
+        query,
+        observable,
+        stableOptions,
+        // Ensure inline functions don't suffer from stale closures by checking for
+        // these deps separately. @wry/equality doesn't compare function identity
+        // so `stableOptions` isn't updated when using inline functions.
+        options?.nextFetchPolicy,
+        options?.skipPollAttempt,
+    ]);
+    const execute = React.useCallback((...args_0) => {
+        invariant(!calledDuringRender(), 30);
+        const [executeOptions] = args_0;
+        let fetchPolicy = observable.options.fetchPolicy;
+        if (fetchPolicy === "standby") {
+            fetchPolicy = observable.options.initialFetchPolicy;
+        }
+        return observable.reobserve({
+            fetchPolicy,
+            // If `variables` is not given, reset back to empty variables by
+            // ensuring the key exists in options
+            variables: executeOptions?.variables,
+            context: executeOptions?.context ?? {},
+        });
+    }, [observable, calledDuringRender]);
+    const executeRef = React.useRef(execute);
+    useIsomorphicLayoutEffect(() => {
+        executeRef.current = execute;
+    });
+    const stableExecute = React.useCallback((...args_1) => executeRef.current(...args_1), []);
+    const result_2 = React.useMemo(() => {
+        const { partial, ...result_1 } = observableResult;
+        return {
+            ...eagerMethods_0,
+            ...result_1,
+            client,
+            previousData: previousDataRef.current,
+            variables: observable.variables,
+            observable,
+            called: !!resultRef.current,
+        };
+    }, [client, observableResult, eagerMethods_0, observable]);
+    return [stableExecute, result_2];
+}
+const initialResult = maybeDeepFreeze({
+    data: undefined,
+    dataState: "empty",
+    loading: false,
+    networkStatus: NetworkStatus.ready,
+    partial: true,
+});
+//# sourceMappingURL=useLazyQuery.js.map