@apollo/client 4.0.10 → 4.0.12-beta.0

package/core/ApolloClient.d.ts

@@ -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.js";
 import type { DefaultContext, ErrorLike, InternalRefetchQueriesInclude, InternalRefetchQueriesResult, MutationQueryReducersMap, MutationUpdaterFunction, NormalizedExecutionResult, OnQueryUpdated, OperationVariables, RefetchQueriesInclude, RefetchQueriesPromiseResults, SubscriptionObservable, TypedDocumentNode } from "./types.js";
@@ -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

package/core/ApolloClient.js

@@ -4,7 +4,7 @@ import { NotImplementedHandler } from "@apollo/client/incremental";
 import { execute } from "@apollo/client/link";
 import { DocumentTransform } from "@apollo/client/utilities";
 import { __DEV__ } from "@apollo/client/utilities/environment";
-import { checkDocument, compact, getApolloClientMemoryInternals, mergeOptions, removeMaskedFragmentSpreads, } from "@apollo/client/utilities/internal";
+import { checkDocument, compact, getApolloClientMemoryInternals, mapObservableFragmentMemoized, mergeOptions, removeMaskedFragmentSpreads, } from "@apollo/client/utilities/internal";
 import { invariant } from "@apollo/client/utilities/invariant";
 import { version } from "../version.js";
 import { QueryManager } from "./QueryManager.js";
@@ -72,10 +72,10 @@ export class ApolloClient {
      */
     constructor(options) {
         if (__DEV__) {
-            invariant(options.cache, 65);
-            invariant(options.link, 66);
+            invariant(options.cache, 68);
+            invariant(options.link, 69);
         }
-        const { cache, documentTransform, ssrMode = false, ssrForceFetchDelay = 0, queryDeduplication = true, defaultOptions, defaultContext, assumeImmutableResults = cache.assumeImmutableResults, localState, devtools, dataMasking, link, incrementalHandler = new NotImplementedHandler(), } = options;
+        const { cache, documentTransform, ssrMode = false, ssrForceFetchDelay = 0, queryDeduplication = true, defaultOptions, defaultContext, assumeImmutableResults = cache.assumeImmutableResults, localState, devtools, dataMasking, link, incrementalHandler = new NotImplementedHandler(), experiments = [], } = options;
         this.link = link;
         this.cache = cache;
         this.queryDeduplication = queryDeduplication;
@@ -120,6 +120,7 @@ export class ApolloClient {
         }
         if (this.devtoolsConfig.enabled)
             this.connectToDevTools();
+        experiments.forEach((experiment) => experiment.call(this, options));
     }
     connectToDevTools() {
         if (typeof window === "undefined") {
@@ -233,13 +234,13 @@ export class ApolloClient {
             options = mergeOptions(this.defaultOptions.query, options);
         }
         if (__DEV__) {
-            invariant(options.fetchPolicy !== "cache-and-network", 67);
-            invariant(options.fetchPolicy !== "standby", 68);
-            invariant(options.query, 69);
-            invariant(options.query.kind === "Document", 70);
-            invariant(!options.returnPartialData, 71);
-            invariant(!options.pollInterval, 72);
-            invariant(!options.notifyOnNetworkStatusChange, 73);
+            invariant(options.fetchPolicy !== "cache-and-network", 70);
+            invariant(options.fetchPolicy !== "standby", 71);
+            invariant(options.query, 72);
+            invariant(options.query.kind === "Document", 73);
+            invariant(!options.returnPartialData, 74);
+            invariant(!options.pollInterval, 75);
+            invariant(!options.notifyOnNetworkStatusChange, 76);
         }
         return this.queryManager.query(options);
     }
@@ -257,9 +258,9 @@ export class ApolloClient {
             errorPolicy: "none",
         }, this.defaultOptions.mutate), options);
         if (__DEV__) {
-            invariant(optionsWithDefaults.mutation, 74);
+            invariant(optionsWithDefaults.mutation, 77);
             invariant(optionsWithDefaults.fetchPolicy === "network-only" ||
-                optionsWithDefaults.fetchPolicy === "no-cache", 75);
+                optionsWithDefaults.fetchPolicy === "no-cache", 78);
         }
         checkDocument(optionsWithDefaults.mutation, OperationTypeNode.MUTATION);
         return this.queryManager.mutate(optionsWithDefaults);
@@ -285,46 +286,27 @@ export class ApolloClient {
     readQuery(options, optimistic = false) {
         return this.cache.readQuery({ ...options, query: this.transform(options.query) }, optimistic);
     }
-    /**
-     * 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(options) {
         const dataMasking = this.queryManager.dataMasking;
-        return this.cache
-            .watchFragment({
+        const observable = this.cache.watchFragment({
             ...options,
             fragment: this.transform(options.fragment, dataMasking),
-        })
-            .pipe(map((result) => {
-            // The transform will remove fragment spreads from the fragment
-            // document when dataMasking is enabled. The `maskFragment` function
-            // remains to apply warnings to fragments marked as
-            // `@unmask(mode: "migrate")`. Since these warnings are only applied
-            // in dev, we can skip the masking algorithm entirely for production.
-            if (__DEV__) {
-                if (dataMasking) {
-                    const data = this.queryManager.maskFragment({
-                        ...options,
-                        data: result.data,
-                    });
-                    return { ...result, data };
-                }
-            }
-            return result;
-        }));
+        });
+        if (__DEV__) {
+            return mapObservableFragmentMemoized(observable, Symbol.for("apollo.transform.dev.mask"), (result) => ({
+                ...result,
+                // The transform will remove fragment spreads from the fragment
+                // document when dataMasking is enabled. The `mask` function
+                // remains to apply warnings to fragments marked as
+                // `@unmask(mode: "migrate")`. Since these warnings are only applied
+                // in dev, we can skip the masking algorithm entirely for production.
+                data: this.queryManager.maskFragment({
+                    ...options,
+                    data: result.data,
+                }),
+            }));
+        }
+        return observable;
     }
     readFragment(options, optimistic = false) {
         return this.cache.readFragment({ ...options, fragment: this.transform(options.fragment) }, optimistic);
@@ -484,7 +466,7 @@ export class ApolloClient {
         // result.queries and result.results instead, you shouldn't have to worry
         // about preventing uncaught rejections for the Promise.all result.
         result.catch((error) => {
-            __DEV__ && invariant.debug(76, error);
+            __DEV__ && invariant.debug(79, error);
         });
         return result;
     }