@apollo/client 4.0.10 → 4.0.12-beta.0

package/__cjs/core/ApolloClient.d.cts

@@ -1,13 +1,13 @@
 import type { DocumentNode } from "graphql";
 import type { Observable } from "rxjs";
-import type { ApolloCache, IgnoreModifier, Reference } from "@apollo/client/cache";
+import type { ApolloCache, Cache, IgnoreModifier, Reference } from "@apollo/client/cache";
 import type { Incremental } from "@apollo/client/incremental";
 import type { ApolloLink } from "@apollo/client/link";
 import type { ClientAwarenessLink } from "@apollo/client/link/client-awareness";
 import type { LocalState } from "@apollo/client/local-state";
 import type { MaybeMasked, Unmasked } from "@apollo/client/masking";
 import { DocumentTransform } from "@apollo/client/utilities";
-import type { VariablesOption } from "@apollo/client/utilities/internal";
+import type { VariablesOption, variablesUnknownSymbol } from "@apollo/client/utilities/internal";
 import { getApolloClientMemoryInternals } from "@apollo/client/utilities/internal";
 import type { ObservableQuery } from "./ObservableQuery.cjs";
 import type { DefaultContext, ErrorLike, InternalRefetchQueriesInclude, InternalRefetchQueriesResult, MutationQueryReducersMap, MutationUpdaterFunction, NormalizedExecutionResult, OnQueryUpdated, OperationVariables, RefetchQueriesInclude, RefetchQueriesPromiseResults, SubscriptionObservable, TypedDocumentNode } from "./types.cjs";
@@ -87,6 +87,14 @@ export declare namespace ApolloClient {
          * queries.
          */
         incrementalHandler?: Incremental.Handler<any>;
+        /**
+         * @experimental
+         * Allows passing in "experiments", experimental features that might one day
+         * become part of Apollo Client's core functionality.
+         * Keep in mind that these features might change the core of Apollo Client.
+         * Do not pass in experiments that are not provided by Apollo.
+         */
+        experiments?: ApolloClient.Experiment[];
     }
     interface DevtoolsOptions {
         /**
@@ -376,7 +384,13 @@ export declare namespace ApolloClient {
         extensions?: Record<string, unknown>;
     }
     type WatchFragmentOptions<TData = unknown, TVariables extends OperationVariables = OperationVariables> = ApolloCache.WatchFragmentOptions<TData, TVariables>;
-    type WatchFragmentResult<TData = unknown> = ApolloCache.WatchFragmentResult<TData>;
+    type WatchFragmentResult<TData = unknown> = ApolloCache.WatchFragmentResult<MaybeMasked<TData>>;
+    interface ObservableFragment<TData = unknown> extends Observable<ApolloClient.WatchFragmentResult<TData>> {
+        /**
+         * Return the current result for the fragment.
+         */
+        getCurrentResult: () => ApolloClient.WatchFragmentResult<TData>;
+    }
     /**
      * Watched query options.
      */
@@ -468,6 +482,21 @@ export declare namespace ApolloClient {
         * @docGroup 1. Operation options
         */
         query: DocumentNode | TypedDocumentNode<TData, TVariables>;
+        /**
+        * @internal This API is meant for framework integrations only.
+        * Do not use for everyday use.
+        *
+        * Indicates that the variables are unknown at the time of query creation.
+        * This option can only be set when `fetchPolicy` is `'standby'`.
+        * Setting this to `true` will prevent `client.refetchQueries` from refetching
+        * this query before it has left the `'standby'` state, either by setting a
+        * `fetchPolicy`, or by calling `observableQuery.refetch()` explicitly.
+        *
+        * Changing this option after the query has been created will have no effect.
+        * 
+        * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+        */
+        [variablesUnknownSymbol]?: boolean;
     } & VariablesOption<NoInfer<TVariables>>;
     namespace Base {
         interface ReadQueryOptions<TData, TVariables extends OperationVariables> {
@@ -508,12 +537,6 @@ export declare namespace ApolloClient {
     }
     namespace Base {
         interface ReadFragmentOptions<TData, TVariables extends OperationVariables> {
-            /**
-             * The root id to be used. This id should take the same form as the
-             * value returned by the `cache.identify` function. If a value with your
-             * id does not exist in the store, `null` will be returned.
-             */
-            id?: string;
             /**
              * A GraphQL document created using the `gql` template string tag
              * with one or more fragments which will be used to determine
@@ -542,7 +565,27 @@ export declare namespace ApolloClient {
             optimistic?: boolean;
         }
     }
-    type ReadFragmentOptions<TData, TVariables extends OperationVariables> = Base.ReadFragmentOptions<TData, TVariables> & VariablesOption<TVariables>;
+    namespace DocumentationTypes {
+        interface ReadFragmentOptions<TData, TVariables extends OperationVariables> extends Base.ReadFragmentOptions<TData, TVariables> {
+            /**
+             * The root id to be used. This id should take the same form as the
+             * value returned by the `cache.identify` function. If a value with your
+             * id does not exist in the store, `null` will be returned.
+             */
+            id?: string;
+            /**
+             * An object containing a `__typename` and primary key fields
+             * (such as `id`) identifying the entity object from which the fragment will
+             * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID
+             * (uncommon).
+             *
+             * @remarks
+             * `from` is given precedence over `id` when both are provided.
+             */
+            from?: ApolloCache.FromOptionValue<TData>;
+        }
+    }
+    type ReadFragmentOptions<TData, TVariables extends OperationVariables> = Base.ReadFragmentOptions<TData, TVariables> & VariablesOption<TVariables> & Cache.CacheIdentifierOption<TData>;
     namespace DocumentationTypes {
         interface WriteQueryOptions<TData, TVariables extends OperationVariables> extends Base.WriteQueryOptions<TData, TVariables> {
             /**
@@ -580,6 +623,11 @@ export declare namespace ApolloClient {
              * @defaultValue false
              */
             overwrite?: boolean;
+            /**
+             * GraphQL extensions for the write operation. Any provided `extensions`
+             * are available in `merge` functions.
+             */
+            extensions?: Record<string, unknown>;
         }
     }
     type WriteQueryOptions<TData, TVariables extends OperationVariables> = Base.WriteQueryOptions<TData, TVariables> & VariablesOption<TVariables>;
@@ -593,12 +641,6 @@ export declare namespace ApolloClient {
     }
     namespace Base {
         interface WriteFragmentOptions<TData, TVariables extends OperationVariables> {
-            /**
-             * The root id to be used. This id should take the same form as the
-             * value returned by the `cache.identify` function. If a value with your
-             * id does not exist in the store, `null` will be returned.
-             */
-            id?: string;
             /**
              * A GraphQL document created using the `gql` template string tag from
              * `graphql-tag` with one or more fragments which will be used to determine
@@ -630,15 +672,35 @@ export declare namespace ApolloClient {
             overwrite?: boolean;
         }
     }
-    type WriteFragmentOptions<TData, TVariables extends OperationVariables> = Base.WriteFragmentOptions<TData, TVariables> & VariablesOption<TVariables>;
+    type WriteFragmentOptions<TData, TVariables extends OperationVariables> = Base.WriteFragmentOptions<TData, TVariables> & VariablesOption<TVariables> & Cache.CacheIdentifierOption<TData>;
     namespace DocumentationTypes {
         interface WriteFragmentOptions<TData, TVariables extends OperationVariables> extends Base.WriteFragmentOptions<TData, TVariables> {
+            /**
+             * The root id to be used. This id should take the same form as the
+             * value returned by the `cache.identify` function. If a value with your
+             * id does not exist in the store, `null` will be returned.
+             */
+            id?: string;
+            /**
+             * An object containing a `__typename` and primary key fields
+             * (such as `id`) identifying the entity object from which the fragment will
+             * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID
+             * (uncommon).
+             *
+             * @remarks
+             * `from` is given precedence over `id` when both are provided.
+             */
+            from?: ApolloCache.FromOptionValue<TData>;
             /**
              * Any variables that your GraphQL fragments depend on.
              */
             variables?: TVariables;
         }
     }
+    interface Experiment {
+        (this: ApolloClient, options: ApolloClient.Options): void;
+        v: 1;
+    }
 }
 /**
  * This is the primary Apollo Client class. It is used to send GraphQL documents (i.e. queries
@@ -811,7 +873,86 @@ export declare class ApolloClient {
      * the cache to identify the fragment and optionally specify whether to react
      * to optimistic updates.
      */
-    watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables>): Observable<ApolloClient.WatchFragmentResult<MaybeMasked<TData>>>;
+    watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
+        from: Array<ApolloCache.FromOptionValue<TData>>;
+    }): ApolloClient.ObservableFragment<Array<TData>>;
+    /**
+    * Watches the cache store of the fragment according to the options specified
+    * and returns an `Observable`. We can subscribe to this
+    * `Observable` and receive updated results through an
+    * observer when the cache store changes.
+    * 
+    * You must pass in a GraphQL document with a single fragment or a document
+    * with multiple fragments that represent what you are reading. If you pass
+    * in a document with multiple fragments then you must also specify a
+    * `fragmentName`.
+    * 
+    * @since 3.10.0
+    * @param options - An object of type `WatchFragmentOptions` that allows
+    * the cache to identify the fragment and optionally specify whether to react
+    * to optimistic updates.
+    */
+    watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
+        from: Array<null>;
+    }): ApolloClient.ObservableFragment<Array<null>>;
+    watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
+        from: Array<ApolloCache.FromOptionValue<TData> | null>;
+    }): ApolloClient.ObservableFragment<Array<TData | null>>;
+    /**
+    * Watches the cache store of the fragment according to the options specified
+    * and returns an `Observable`. We can subscribe to this
+    * `Observable` and receive updated results through an
+    * observer when the cache store changes.
+    * 
+    * You must pass in a GraphQL document with a single fragment or a document
+    * with multiple fragments that represent what you are reading. If you pass
+    * in a document with multiple fragments then you must also specify a
+    * `fragmentName`.
+    * 
+    * @since 3.10.0
+    * @param options - An object of type `WatchFragmentOptions` that allows
+    * the cache to identify the fragment and optionally specify whether to react
+    * to optimistic updates.
+    */
+    watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
+        from: null;
+    }): ApolloClient.ObservableFragment<null>;
+    /**
+    * Watches the cache store of the fragment according to the options specified
+    * and returns an `Observable`. We can subscribe to this
+    * `Observable` and receive updated results through an
+    * observer when the cache store changes.
+    * 
+    * You must pass in a GraphQL document with a single fragment or a document
+    * with multiple fragments that represent what you are reading. If you pass
+    * in a document with multiple fragments then you must also specify a
+    * `fragmentName`.
+    * 
+    * @since 3.10.0
+    * @param options - An object of type `WatchFragmentOptions` that allows
+    * the cache to identify the fragment and optionally specify whether to react
+    * to optimistic updates.
+    */
+    watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables> & {
+        from: ApolloCache.FromOptionValue<TData>;
+    }): ApolloClient.ObservableFragment<TData>;
+    /**
+    * Watches the cache store of the fragment according to the options specified
+    * and returns an `Observable`. We can subscribe to this
+    * `Observable` and receive updated results through an
+    * observer when the cache store changes.
+    * 
+    * You must pass in a GraphQL document with a single fragment or a document
+    * with multiple fragments that represent what you are reading. If you pass
+    * in a document with multiple fragments then you must also specify a
+    * `fragmentName`.
+    * 
+    * @since 3.10.0
+    * @param options - An object of type `WatchFragmentOptions` that allows
+    * the cache to identify the fragment and optionally specify whether to react
+    * to optimistic updates.
+    */
+    watchFragment<TData = unknown, TVariables extends OperationVariables = OperationVariables>(options: ApolloClient.WatchFragmentOptions<TData, TVariables>): ApolloClient.ObservableFragment<TData | null>;
     /**
      * Tries to read some data from the store in the shape of the provided
      * GraphQL fragment without making a network request. This method will read a