@apollo/client 3.9.0-alpha.4 → 3.9.0-beta.0

package/core/watchQueryOptions.d.ts

@@ -4,28 +4,166 @@ import type { FetchResult } from "../link/core/index.js";
 import type { DefaultContext, MutationQueryReducersMap, OperationVariables, MutationUpdaterFunction, OnQueryUpdated, InternalRefetchQueriesInclude } from "./types.js";
 import type { ApolloCache } from "../cache/index.js";
 import type { ObservableQuery } from "./ObservableQuery.js";
+import type { IgnoreModifier } from "../cache/core/types/common.js";
+/**
+ * fetchPolicy determines where the client may return a result from. The options are:
+ * - cache-first (default): return result from cache. Only fetch from network if cached result is not available.
+ * - cache-and-network: return result from cache first (if it exists), then return network result once it's available.
+ * - cache-only: return result from cache if available, fail otherwise.
+ * - no-cache: return result from network, fail if network call doesn't succeed, don't save to cache
+ * - network-only: return result from network, fail if network call doesn't succeed, save to cache
+ * - standby: only for queries that aren't actively watched, but should be available for refetch and updateQueries.
+ */
 export type FetchPolicy = "cache-first" | "network-only" | "cache-only" | "no-cache" | "standby";
 export type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network";
 export type MutationFetchPolicy = Extract<FetchPolicy, "network-only" | "no-cache">;
 export type RefetchWritePolicy = "merge" | "overwrite";
+/**
+ * errorPolicy determines the level of events for errors in the execution result. The options are:
+ * - none (default): any errors from the request are treated like runtime errors and the observable is stopped
+ * - ignore: errors from the request do not stop the observable, but also don't call `next`
+ * - all: errors are treated like data and will notify observables
+ */
 export type ErrorPolicy = "none" | "ignore" | "all";
+/**
+ * Query options.
+ */
 export interface QueryOptions<TVariables = OperationVariables, TData = any> {
+    /**
+     * A GraphQL document that consists of a single query to be sent down to the
+     * server.
+     */
     query: DocumentNode | TypedDocumentNode<TData, TVariables>;
+    /**
+     * A map going from variable name to variable value, where the variables are used
+     * within the GraphQL query.
+     */
     variables?: TVariables;
+    /**
+     * Specifies the {@link ErrorPolicy} to be used for this query
+     */
     errorPolicy?: ErrorPolicy;
+    /**
+     * Context to be passed to link execution chain
+     */
     context?: DefaultContext;
+    /**
+     * Specifies the {@link FetchPolicy} to be used for this query
+     */
     fetchPolicy?: FetchPolicy;
+    /**
+     * The time interval (in milliseconds) on which this query should be
+     * refetched from the server.
+     */
     pollInterval?: number;
+    /**
+     * Whether or not updates to the network status should trigger next on the observer of this query
+     */
     notifyOnNetworkStatusChange?: boolean;
+    /**
+     * Allow returning incomplete data from the cache when a larger query cannot
+     * be fully satisfied by the cache, instead of returning nothing.
+     */
     returnPartialData?: boolean;
+    /**
+     * If `true`, perform a query `refetch` if the query result is marked as
+     * being partial, and the returned data is reset to an empty Object by the
+     * Apollo Client `QueryManager` (due to a cache miss).
+     */
     partialRefetch?: boolean;
+    /**
+     * @deprecated
+     * Using `canonizeResults` can result in memory leaks so we generally do not
+     * recommend using this option anymore.
+     * A future version of Apollo Client will contain a similar feature without
+     * the risk of memory leaks.
+     *
+     * Whether to canonize cache results before returning them. Canonization
+     * takes some extra time, but it speeds up future deep equality comparisons.
+     * Defaults to false.
+     */
     canonizeResults?: boolean;
 }
-export interface WatchQueryOptions<TVariables extends OperationVariables = OperationVariables, TData = any> extends Omit<QueryOptions<TVariables, TData>, "fetchPolicy"> {
+/**
+ * Watched query options.
+ */
+export interface WatchQueryOptions<TVariables extends OperationVariables = OperationVariables, TData = any> {
+    /**
+     * Specifies the {@link FetchPolicy} to be used for this query.
+     */
     fetchPolicy?: WatchQueryFetchPolicy;
+    /**
+     * Specifies the {@link FetchPolicy} to be used after this query has completed.
+     */
     nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions<TVariables, TData>, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext<TData, TVariables>) => WatchQueryFetchPolicy);
+    /**
+     * Defaults to the initial value of options.fetchPolicy, but can be explicitly
+     * configured to specify the WatchQueryFetchPolicy to revert back to whenever
+     * variables change (unless nextFetchPolicy intervenes).
+     */
     initialFetchPolicy?: WatchQueryFetchPolicy;
+    /**
+     * Specifies whether a {@link 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.
+     */
     refetchWritePolicy?: RefetchWritePolicy;
+    /**
+     * A GraphQL document that consists of a single query to be sent down to the server.
+     */
+
+    query: DocumentNode | TypedDocumentNode<TData, TVariables>;
+    /**
+     * A map going from variable name to variable value, where the variables are used within the GraphQL query.
+     */
+
+    variables?: TVariables;
+    /**
+     * Specifies the {@link ErrorPolicy} to be used for this query
+     */
+
+    errorPolicy?: ErrorPolicy;
+    /**
+     * Context to be passed to link execution chain
+     */
+
+    context?: DefaultContext;
+    /**
+     * The time interval (in milliseconds) on which this query should be refetched from the server.
+     */
+
+    pollInterval?: number;
+    /**
+     * Whether or not updates to the network status should trigger next on the observer of this query
+     */
+
+    notifyOnNetworkStatusChange?: boolean;
+    /**
+     * Allow returning incomplete data from the cache when a larger query cannot be fully satisfied by the cache, instead of returning nothing.
+     */
+
+    returnPartialData?: boolean;
+    /**
+     * If `true`, perform a query `refetch` if the query result is marked as being partial, and the returned data is reset to an empty Object by the Apollo Client `QueryManager` (due to a cache miss).
+     */
+
+    partialRefetch?: boolean;
+    /**
+     * @deprecated
+     *
+     * Using `canonizeResults` can result in memory leaks so we generally do not recommend using this option anymore. A future version of Apollo Client will contain a similar feature without the risk of memory leaks.
+     *
+     * Whether to canonize cache results before returning them. Canonization takes some extra time, but it speeds up future deep equality comparisons. Defaults to false.
+     */
+
+    canonizeResults?: 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.
+     */
+    skipPollAttempt?: () => boolean;
 }
 export interface NextFetchPolicyContext<TData, TVariables extends OperationVariables> {
     reason: "after-fetch" | "variables-changed";
@@ -52,26 +190,131 @@ export type SubscribeToMoreOptions<TData = any, TSubscriptionVariables = Operati
     context?: DefaultContext;
 };
 export interface SubscriptionOptions<TVariables = OperationVariables, TData = any> {
+    /**
+     * A GraphQL document, often created with `gql` from the `graphql-tag`
+     * package, that contains a single subscription inside of it.
+     */
     query: DocumentNode | TypedDocumentNode<TData, TVariables>;
+    /**
+     * An object that maps from the name of a variable as used in the subscription
+     * GraphQL document to that variable's value.
+     */
     variables?: TVariables;
+    /**
+     * Specifies the {@link FetchPolicy} to be used for this subscription.
+     */
     fetchPolicy?: FetchPolicy;
+    /**
+     * Specifies the {@link ErrorPolicy} to be used for this operation
+     */
     errorPolicy?: ErrorPolicy;
+    /**
+     * Context object to be passed through the link execution chain.
+     */
     context?: DefaultContext;
 }
 export interface MutationBaseOptions<TData = any, TVariables = OperationVariables, TContext = DefaultContext, TCache extends ApolloCache<any> = ApolloCache<any>> {
-    optimisticResponse?: TData | ((vars: TVariables) => TData);
+    /**
+     * An object that represents the result of this mutation that will be
+     * optimistically stored before the server has actually returned a result.
+     * This is most often used for optimistic UI, where we want to be able to see
+     * the result of a mutation immediately, and update the UI later if any errors
+     * appear.
+     */
+    optimisticResponse?: TData | ((vars: TVariables, { IGNORE }: {
+        IGNORE: IgnoreModifier;
+    }) => TData);
+    /**
+     * A {@link MutationQueryReducersMap}, which is map from query names to
+     * mutation query reducers. Briefly, this map defines how to incorporate the
+     * results of the mutation into the results of queries that are currently
+     * being watched by your application.
+     */
     updateQueries?: MutationQueryReducersMap<TData>;
+    /**
+     * A list of query names which will be refetched once this mutation has
+     * returned. This is often used if you have a set of queries which may be
+     * affected by a mutation and will have to update. Rather than writing a
+     * mutation query reducer (i.e. `updateQueries`) for this, you can simply
+     * refetch the queries that will be affected and achieve a consistent store
+     * once these queries return.
+     */
     refetchQueries?: ((result: FetchResult<TData>) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude;
+    /**
+     * By default, `refetchQueries` does not wait for the refetched queries to
+     * be completed, before resolving the mutation `Promise`. This ensures that
+     * query refetching does not hold up mutation response handling (query
+     * refetching is handled asynchronously). Set `awaitRefetchQueries` to
+     * `true` if you would like to wait for the refetched queries to complete,
+     * before the mutation can be marked as resolved.
+     */
     awaitRefetchQueries?: boolean;
+    /**
+     * A function which provides an {@link ApolloCache} instance, and the result
+     * of the mutation, to allow the user to update the store based on the
+     * results of the mutation.
+     *
+     * This function will be called twice over the lifecycle of a mutation. Once
+     * at the very beginning if an `optimisticResponse` was provided. The writes
+     * created from the optimistic data will be rolled back before the second time
+     * this function is called which is when the mutation has successfully
+     * resolved. At that point `update` will be called with the *actual* mutation
+     * result and those writes will not be rolled back.
+     *
+     * Note that since this function is intended to be used to update the
+     * store, it cannot be used with a `no-cache` fetch policy. If you're
+     * interested in performing some action after a mutation has completed,
+     * and you don't need to update the store, use the Promise returned from
+     * `client.mutate` instead.
+     */
     update?: MutationUpdaterFunction<TData, TVariables, TContext, TCache>;
+    /**
+     * A function that will be called for each ObservableQuery affected by
+     * this mutation, after the mutation has completed.
+     */
     onQueryUpdated?: OnQueryUpdated<any>;
+    /**
+     * Specifies the {@link ErrorPolicy} to be used for this operation
+     */
     errorPolicy?: ErrorPolicy;
+    /**
+     * An object that maps from the name of a variable as used in the mutation
+     * GraphQL document to that variable's value.
+     */
     variables?: TVariables;
+    /**
+     * The context to be passed to the link execution chain. This context will
+     * only be used with this mutation. It will not be used with
+     * `refetchQueries`. Refetched queries use the context they were
+     * initialized with (since the initial context is stored as part of the
+     * `ObservableQuery` instance). If a specific context is needed when
+     * refetching queries, make sure it is configured (via the
+     * [query `context` option](https://www.apollographql.com/docs/react/api/apollo-client#ApolloClient.query))
+     * when the query is first initialized/run.
+     */
     context?: TContext;
 }
 export interface MutationOptions<TData = any, TVariables = OperationVariables, TContext = DefaultContext, TCache extends ApolloCache<any> = ApolloCache<any>> extends MutationBaseOptions<TData, TVariables, TContext, TCache> {
+    /**
+     * A GraphQL document, often created with `gql` from the `graphql-tag`
+     * package, that contains a single mutation inside of it.
+     */
     mutation: DocumentNode | TypedDocumentNode<TData, TVariables>;
+    /**
+     * Specifies the {@link MutationFetchPolicy} to be used for this query.
+     * Mutations support only 'network-only' and 'no-cache' fetchPolicy strings.
+     * If fetchPolicy is not provided, it defaults to 'network-only'.
+     */
     fetchPolicy?: MutationFetchPolicy;
+    /**
+     * To avoid retaining sensitive information from mutation root field
+     * arguments, Apollo Client v3.4+ automatically clears any `ROOT_MUTATION`
+     * fields from the cache after each mutation finishes. If you need this
+     * information to remain in the cache, you can prevent the removal by passing
+     * `keepRootFields: true` to the mutation. `ROOT_MUTATION` result data are
+     * also passed to the mutation `update` function, so we recommend obtaining
+     * the results that way, rather than using this option, if possible.
+     */
     keepRootFields?: boolean;
 }
 //# sourceMappingURL=watchQueryOptions.d.ts.map

package/core/watchQueryOptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"watchQueryOptions.js","sourceRoot":"","sources":["../../src/core/watchQueryOptions.ts"],"names":[],"mappings":"","sourcesContent":["import type { DocumentNode } from \"graphql\";\nimport type { TypedDocumentNode } from \"@graphql-typed-document-node/core\";\n\nimport type { FetchResult } from \"../link/core/index.js\";\nimport type {\n  DefaultContext,\n  MutationQueryReducersMap,\n  OperationVariables,\n  MutationUpdaterFunction,\n  OnQueryUpdated,\n  InternalRefetchQueriesInclude,\n} from \"./types.js\";\nimport type { ApolloCache } from \"../cache/index.js\";\nimport type { ObservableQuery } from \"./ObservableQuery.js\";\n\n/**\n * fetchPolicy determines where the client may return a result from. The options are:\n * - cache-first (default): return result from cache. Only fetch from network if cached result is not available.\n * - cache-and-network: return result from cache first (if it exists), then return network result once it's available.\n * - cache-only: return result from cache if available, fail otherwise.\n * - no-cache: return result from network, fail if network call doesn't succeed, don't save to cache\n * - network-only: return result from network, fail if network call doesn't succeed, save to cache\n * - standby: only for queries that aren't actively watched, but should be available for refetch and updateQueries.\n */\nexport type FetchPolicy =\n  | \"cache-first\"\n  | \"network-only\"\n  | \"cache-only\"\n  | \"no-cache\"\n  | \"standby\";\n\nexport type WatchQueryFetchPolicy = FetchPolicy | \"cache-and-network\";\n\nexport type MutationFetchPolicy = Extract<\n  FetchPolicy,\n  | \"network-only\" // default behavior (mutation results written to cache)\n  | \"no-cache\" // alternate behavior (results not written to cache)\n>;\n\nexport type RefetchWritePolicy = \"merge\" | \"overwrite\";\n\n/**\n * errorPolicy determines the level of events for errors in the execution result. The options are:\n * - none (default): any errors from the request are treated like runtime errors and the observable is stopped (XXX this is default to lower breaking changes going from AC 1.0 => 2.0)\n * - ignore: errors from the request do not stop the observable, but also don't call `next`\n * - all: errors are treated like data and will notify observables\n */\nexport type ErrorPolicy = \"none\" | \"ignore\" | \"all\";\n\n/**\n * Query options.\n */\nexport interface QueryOptions<TVariables = OperationVariables, TData = any> {\n  /**\n   * A GraphQL document that consists of a single query to be sent down to the\n   * server.\n   */\n  // TODO REFACTOR: rename this to document. Didn't do it yet because it's in a\n  // lot of tests.\n  query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n  /**\n   * A map going from variable name to variable value, where the variables are used\n   * within the GraphQL query.\n   */\n  variables?: TVariables;\n\n  /**\n   * Specifies the {@link ErrorPolicy} to be used for this query\n   */\n  errorPolicy?: ErrorPolicy;\n\n  /**\n   * Context to be passed to link execution chain\n   */\n  context?: DefaultContext;\n\n  /**\n   * Specifies the {@link FetchPolicy} to be used for this query\n   */\n  fetchPolicy?: FetchPolicy;\n\n  /**\n   * The time interval (in milliseconds) on which this query should be\n   * refetched from the server.\n   */\n  pollInterval?: number;\n\n  /**\n   * Whether or not updates to the network status should trigger next on the observer of this query\n   */\n  notifyOnNetworkStatusChange?: boolean;\n\n  /**\n   * Allow returning incomplete data from the cache when a larger query cannot\n   * be fully satisfied by the cache, instead of returning nothing.\n   */\n  returnPartialData?: boolean;\n\n  /**\n   * If `true`, perform a query `refetch` if the query result is marked as\n   * being partial, and the returned data is reset to an empty Object by the\n   * Apollo Client `QueryManager` (due to a cache miss).\n   */\n  partialRefetch?: boolean;\n\n  /**\n   * Whether to canonize cache results before returning them. Canonization\n   * takes some extra time, but it speeds up future deep equality comparisons.\n   * Defaults to false.\n   */\n  canonizeResults?: boolean;\n}\n\n/**\n * Watched query options.\n */\nexport interface WatchQueryOptions<\n  TVariables extends OperationVariables = OperationVariables,\n  TData = any,\n> extends Omit<QueryOptions<TVariables, TData>, \"fetchPolicy\"> {\n  /**\n   * Specifies the {@link FetchPolicy} to be used for this query.\n   */\n  fetchPolicy?: WatchQueryFetchPolicy;\n\n  /**\n   * Specifies the {@link FetchPolicy} to be used after this query has completed.\n   */\n  nextFetchPolicy?:\n    | WatchQueryFetchPolicy\n    | ((\n        this: WatchQueryOptions<TVariables, TData>,\n        currentFetchPolicy: WatchQueryFetchPolicy,\n        context: NextFetchPolicyContext<TData, TVariables>\n      ) => WatchQueryFetchPolicy);\n\n  /**\n   * Defaults to the initial value of options.fetchPolicy, but can be explicitly\n   * configured to specify the WatchQueryFetchPolicy to revert back to whenever\n   * variables change (unless nextFetchPolicy intervenes).\n   */\n  initialFetchPolicy?: WatchQueryFetchPolicy;\n\n  /**\n   * Specifies whether a {@link NetworkStatus.refetch} operation should merge\n   * incoming field data with existing data, or overwrite the existing data.\n   * Overwriting is probably preferable, but merging is currently the default\n   * behavior, for backwards compatibility with Apollo Client 3.x.\n   */\n  refetchWritePolicy?: RefetchWritePolicy;\n}\n\nexport interface NextFetchPolicyContext<\n  TData,\n  TVariables extends OperationVariables,\n> {\n  reason: \"after-fetch\" | \"variables-changed\";\n  observable: ObservableQuery<TData, TVariables>;\n  options: WatchQueryOptions<TVariables, TData>;\n  initialFetchPolicy: WatchQueryFetchPolicy;\n}\n\nexport interface FetchMoreQueryOptions<TVariables, TData = any> {\n  query?: DocumentNode | TypedDocumentNode<TData, TVariables>;\n  variables?: Partial<TVariables>;\n  context?: DefaultContext;\n}\n\nexport type UpdateQueryFn<\n  TData = any,\n  TSubscriptionVariables = OperationVariables,\n  TSubscriptionData = TData,\n> = (\n  previousQueryResult: TData,\n  options: {\n    subscriptionData: { data: TSubscriptionData };\n    variables?: TSubscriptionVariables;\n  }\n) => TData;\n\nexport type SubscribeToMoreOptions<\n  TData = any,\n  TSubscriptionVariables = OperationVariables,\n  TSubscriptionData = TData,\n> = {\n  document:\n    | DocumentNode\n    | TypedDocumentNode<TSubscriptionData, TSubscriptionVariables>;\n  variables?: TSubscriptionVariables;\n  updateQuery?: UpdateQueryFn<TData, TSubscriptionVariables, TSubscriptionData>;\n  onError?: (error: Error) => void;\n  context?: DefaultContext;\n};\n\nexport interface SubscriptionOptions<\n  TVariables = OperationVariables,\n  TData = any,\n> {\n  /**\n   * A GraphQL document, often created with `gql` from the `graphql-tag`\n   * package, that contains a single subscription inside of it.\n   */\n  query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n  /**\n   * An object that maps from the name of a variable as used in the subscription\n   * GraphQL document to that variable's value.\n   */\n  variables?: TVariables;\n\n  /**\n   * Specifies the {@link FetchPolicy} to be used for this subscription.\n   */\n  fetchPolicy?: FetchPolicy;\n\n  /**\n   * Specifies the {@link ErrorPolicy} to be used for this operation\n   */\n  errorPolicy?: ErrorPolicy;\n\n  /**\n   * Context object to be passed through the link execution chain.\n   */\n  context?: DefaultContext;\n}\n\nexport interface MutationBaseOptions<\n  TData = any,\n  TVariables = OperationVariables,\n  TContext = DefaultContext,\n  TCache extends ApolloCache<any> = ApolloCache<any>,\n> {\n  /**\n   * An object that represents the result of this mutation that will be\n   * optimistically stored before the server has actually returned a result.\n   * This is most often used for optimistic UI, where we want to be able to see\n   * the result of a mutation immediately, and update the UI later if any errors\n   * appear.\n   */\n  optimisticResponse?: TData | ((vars: TVariables) => TData);\n\n  /**\n   * A {@link MutationQueryReducersMap}, which is map from query names to\n   * mutation query reducers. Briefly, this map defines how to incorporate the\n   * results of the mutation into the results of queries that are currently\n   * being watched by your application.\n   */\n  updateQueries?: MutationQueryReducersMap<TData>;\n\n  /**\n   * A list of query names which will be refetched once this mutation has\n   * returned. This is often used if you have a set of queries which may be\n   * affected by a mutation and will have to update. Rather than writing a\n   * mutation query reducer (i.e. `updateQueries`) for this, you can simply\n   * refetch the queries that will be affected and achieve a consistent store\n   * once these queries return.\n   */\n  refetchQueries?:\n    | ((result: FetchResult<TData>) => InternalRefetchQueriesInclude)\n    | InternalRefetchQueriesInclude;\n\n  /**\n   * By default, `refetchQueries` does not wait for the refetched queries to\n   * be completed, before resolving the mutation `Promise`. This ensures that\n   * query refetching does not hold up mutation response handling (query\n   * refetching is handled asynchronously). Set `awaitRefetchQueries` to\n   * `true` if you would like to wait for the refetched queries to complete,\n   * before the mutation can be marked as resolved.\n   */\n  awaitRefetchQueries?: boolean;\n\n  /**\n   * A function which provides an {@link ApolloCache} instance, and the result\n   * of the mutation, to allow the user to update the store based on the\n   * results of the mutation.\n   *\n   * This function will be called twice over the lifecycle of a mutation. Once\n   * at the very beginning if an `optimisticResponse` was provided. The writes\n   * created from the optimistic data will be rolled back before the second time\n   * this function is called which is when the mutation has successfully\n   * resolved. At that point `update` will be called with the *actual* mutation\n   * result and those writes will not be rolled back.\n   *\n   * Note that since this function is intended to be used to update the\n   * store, it cannot be used with a `no-cache` fetch policy. If you're\n   * interested in performing some action after a mutation has completed,\n   * and you don't need to update the store, use the Promise returned from\n   * `client.mutate` instead.\n   */\n  update?: MutationUpdaterFunction<TData, TVariables, TContext, TCache>;\n\n  /**\n   * A function that will be called for each ObservableQuery affected by\n   * this mutation, after the mutation has completed.\n   */\n  onQueryUpdated?: OnQueryUpdated<any>;\n\n  /**\n   * Specifies the {@link ErrorPolicy} to be used for this operation\n   */\n  errorPolicy?: ErrorPolicy;\n\n  /**\n   * An object that maps from the name of a variable as used in the mutation\n   * GraphQL document to that variable's value.\n   */\n  variables?: TVariables;\n\n  /**\n   * The context to be passed to the link execution chain. This context will\n   * only be used with this mutation. It will not be used with\n   * `refetchQueries`. Refetched queries use the context they were\n   * initialized with (since the initial context is stored as part of the\n   * `ObservableQuery` instance). If a specific context is needed when\n   * refetching queries, make sure it is configured (via the\n   * [query `context` option](https://www.apollographql.com/docs/react/api/apollo-client#ApolloClient.query))\n   * when the query is first initialized/run.\n   */\n  context?: TContext;\n}\n\nexport interface MutationOptions<\n  TData = any,\n  TVariables = OperationVariables,\n  TContext = DefaultContext,\n  TCache extends ApolloCache<any> = ApolloCache<any>,\n> extends MutationBaseOptions<TData, TVariables, TContext, TCache> {\n  /**\n   * A GraphQL document, often created with `gql` from the `graphql-tag`\n   * package, that contains a single mutation inside of it.\n   */\n  mutation: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n  /**\n   * Specifies the {@link MutationFetchPolicy} to be used for this query.\n   * Mutations support only 'network-only' and 'no-cache' fetchPolicy strings.\n   * If fetchPolicy is not provided, it defaults to 'network-only'.\n   */\n  fetchPolicy?: MutationFetchPolicy;\n\n  /**\n   * To avoid retaining sensitive information from mutation root field\n   * arguments, Apollo Client v3.4+ automatically clears any `ROOT_MUTATION`\n   * fields from the cache after each mutation finishes. If you need this\n   * information to remain in the cache, you can prevent the removal by passing\n   * `keepRootFields: true` to the mutation. `ROOT_MUTATION` result data are\n   * also passed to the mutation `update` function, so we recommend obtaining\n   * the results that way, rather than using this option, if possible.\n   */\n  keepRootFields?: boolean;\n}\n"]}
+{"version":3,"file":"watchQueryOptions.js","sourceRoot":"","sources":["../../src/core/watchQueryOptions.ts"],"names":[],"mappings":"","sourcesContent":["import type { DocumentNode } from \"graphql\";\nimport type { TypedDocumentNode } from \"@graphql-typed-document-node/core\";\n\nimport type { FetchResult } from \"../link/core/index.js\";\nimport type {\n  DefaultContext,\n  MutationQueryReducersMap,\n  OperationVariables,\n  MutationUpdaterFunction,\n  OnQueryUpdated,\n  InternalRefetchQueriesInclude,\n} from \"./types.js\";\nimport type { ApolloCache } from \"../cache/index.js\";\nimport type { ObservableQuery } from \"./ObservableQuery.js\";\nimport type { IgnoreModifier } from \"../cache/core/types/common.js\";\n\n/**\n * fetchPolicy determines where the client may return a result from. The options are:\n * - cache-first (default): return result from cache. Only fetch from network if cached result is not available.\n * - cache-and-network: return result from cache first (if it exists), then return network result once it's available.\n * - cache-only: return result from cache if available, fail otherwise.\n * - no-cache: return result from network, fail if network call doesn't succeed, don't save to cache\n * - network-only: return result from network, fail if network call doesn't succeed, save to cache\n * - standby: only for queries that aren't actively watched, but should be available for refetch and updateQueries.\n */\nexport type FetchPolicy =\n  | \"cache-first\"\n  | \"network-only\"\n  | \"cache-only\"\n  | \"no-cache\"\n  | \"standby\";\n\nexport type WatchQueryFetchPolicy = FetchPolicy | \"cache-and-network\";\n\nexport type MutationFetchPolicy = Extract<\n  FetchPolicy,\n  | \"network-only\" // default behavior (mutation results written to cache)\n  | \"no-cache\" // alternate behavior (results not written to cache)\n>;\n\nexport type RefetchWritePolicy = \"merge\" | \"overwrite\";\n\n/**\n * errorPolicy determines the level of events for errors in the execution result. The options are:\n * - none (default): any errors from the request are treated like runtime errors and the observable is stopped\n * - ignore: errors from the request do not stop the observable, but also don't call `next`\n * - all: errors are treated like data and will notify observables\n */\nexport type ErrorPolicy = \"none\" | \"ignore\" | \"all\";\n\n/**\n * Query options.\n */\nexport interface QueryOptions<TVariables = OperationVariables, TData = any> {\n  /**\n   * A GraphQL document that consists of a single query to be sent down to the\n   * server.\n   */\n  // TODO REFACTOR: rename this to document. Didn't do it yet because it's in a\n  // lot of tests.\n  query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n  /**\n   * A map going from variable name to variable value, where the variables are used\n   * within the GraphQL query.\n   */\n  variables?: TVariables;\n\n  /**\n   * Specifies the {@link ErrorPolicy} to be used for this query\n   */\n  errorPolicy?: ErrorPolicy;\n\n  /**\n   * Context to be passed to link execution chain\n   */\n  context?: DefaultContext;\n\n  /**\n   * Specifies the {@link FetchPolicy} to be used for this query\n   */\n  fetchPolicy?: FetchPolicy;\n\n  /**\n   * The time interval (in milliseconds) on which this query should be\n   * refetched from the server.\n   */\n  pollInterval?: number;\n\n  /**\n   * Whether or not updates to the network status should trigger next on the observer of this query\n   */\n  notifyOnNetworkStatusChange?: boolean;\n\n  /**\n   * Allow returning incomplete data from the cache when a larger query cannot\n   * be fully satisfied by the cache, instead of returning nothing.\n   */\n  returnPartialData?: boolean;\n\n  /**\n   * If `true`, perform a query `refetch` if the query result is marked as\n   * being partial, and the returned data is reset to an empty Object by the\n   * Apollo Client `QueryManager` (due to a cache miss).\n   */\n  partialRefetch?: boolean;\n\n  /**\n   * @deprecated\n   * Using `canonizeResults` can result in memory leaks so we generally do not\n   * recommend using this option anymore.\n   * A future version of Apollo Client will contain a similar feature without\n   * the risk of memory leaks.\n   *\n   * Whether to canonize cache results before returning them. Canonization\n   * takes some extra time, but it speeds up future deep equality comparisons.\n   * Defaults to false.\n   */\n  canonizeResults?: boolean;\n}\n\n/**\n * Watched query options.\n */\nexport interface WatchQueryOptions<\n  TVariables extends OperationVariables = OperationVariables,\n  TData = any,\n> {\n  /**\n   * Specifies the {@link FetchPolicy} to be used for this query.\n   */\n  fetchPolicy?: WatchQueryFetchPolicy;\n\n  /**\n   * Specifies the {@link FetchPolicy} to be used after this query has completed.\n   */\n  nextFetchPolicy?:\n    | WatchQueryFetchPolicy\n    | ((\n        this: WatchQueryOptions<TVariables, TData>,\n        currentFetchPolicy: WatchQueryFetchPolicy,\n        context: NextFetchPolicyContext<TData, TVariables>\n      ) => WatchQueryFetchPolicy);\n\n  /**\n   * Defaults to the initial value of options.fetchPolicy, but can be explicitly\n   * configured to specify the WatchQueryFetchPolicy to revert back to whenever\n   * variables change (unless nextFetchPolicy intervenes).\n   */\n  initialFetchPolicy?: WatchQueryFetchPolicy;\n\n  /**\n   * Specifies whether a {@link NetworkStatus.refetch} operation should merge\n   * incoming field data with existing data, or overwrite the existing data.\n   * Overwriting is probably preferable, but merging is currently the default\n   * behavior, for backwards compatibility with Apollo Client 3.x.\n   */\n  refetchWritePolicy?: RefetchWritePolicy;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#query:member} */\n  query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#variables:member} */\n  variables?: TVariables;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#errorPolicy:member} */\n  errorPolicy?: ErrorPolicy;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#context:member} */\n  context?: DefaultContext;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#pollInterval:member} */\n  pollInterval?: number;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#notifyOnNetworkStatusChange:member} */\n  notifyOnNetworkStatusChange?: boolean;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#returnPartialData:member} */\n  returnPartialData?: boolean;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#partialRefetch:member} */\n  partialRefetch?: boolean;\n\n  /** {@inheritDoc @apollo/client!QueryOptions#canonizeResults:member} */\n  canonizeResults?: boolean;\n\n  /**\n   * A callback function that's called whenever a refetch attempt occurs\n   * while polling. If the function returns `true`, the refetch is\n   * skipped and not reattempted until the next poll interval.\n   */\n  skipPollAttempt?: () => boolean;\n}\n\nexport interface NextFetchPolicyContext<\n  TData,\n  TVariables extends OperationVariables,\n> {\n  reason: \"after-fetch\" | \"variables-changed\";\n  observable: ObservableQuery<TData, TVariables>;\n  options: WatchQueryOptions<TVariables, TData>;\n  initialFetchPolicy: WatchQueryFetchPolicy;\n}\n\nexport interface FetchMoreQueryOptions<TVariables, TData = any> {\n  query?: DocumentNode | TypedDocumentNode<TData, TVariables>;\n  variables?: Partial<TVariables>;\n  context?: DefaultContext;\n}\n\nexport type UpdateQueryFn<\n  TData = any,\n  TSubscriptionVariables = OperationVariables,\n  TSubscriptionData = TData,\n> = (\n  previousQueryResult: TData,\n  options: {\n    subscriptionData: { data: TSubscriptionData };\n    variables?: TSubscriptionVariables;\n  }\n) => TData;\n\nexport type SubscribeToMoreOptions<\n  TData = any,\n  TSubscriptionVariables = OperationVariables,\n  TSubscriptionData = TData,\n> = {\n  document:\n    | DocumentNode\n    | TypedDocumentNode<TSubscriptionData, TSubscriptionVariables>;\n  variables?: TSubscriptionVariables;\n  updateQuery?: UpdateQueryFn<TData, TSubscriptionVariables, TSubscriptionData>;\n  onError?: (error: Error) => void;\n  context?: DefaultContext;\n};\n\nexport interface SubscriptionOptions<\n  TVariables = OperationVariables,\n  TData = any,\n> {\n  /**\n   * A GraphQL document, often created with `gql` from the `graphql-tag`\n   * package, that contains a single subscription inside of it.\n   */\n  query: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n  /**\n   * An object that maps from the name of a variable as used in the subscription\n   * GraphQL document to that variable's value.\n   */\n  variables?: TVariables;\n\n  /**\n   * Specifies the {@link FetchPolicy} to be used for this subscription.\n   */\n  fetchPolicy?: FetchPolicy;\n\n  /**\n   * Specifies the {@link ErrorPolicy} to be used for this operation\n   */\n  errorPolicy?: ErrorPolicy;\n\n  /**\n   * Context object to be passed through the link execution chain.\n   */\n  context?: DefaultContext;\n}\n\nexport interface MutationBaseOptions<\n  TData = any,\n  TVariables = OperationVariables,\n  TContext = DefaultContext,\n  TCache extends ApolloCache<any> = ApolloCache<any>,\n> {\n  /**\n   * An object that represents the result of this mutation that will be\n   * optimistically stored before the server has actually returned a result.\n   * This is most often used for optimistic UI, where we want to be able to see\n   * the result of a mutation immediately, and update the UI later if any errors\n   * appear.\n   */\n  optimisticResponse?:\n    | TData\n    | ((vars: TVariables, { IGNORE }: { IGNORE: IgnoreModifier }) => TData);\n\n  /**\n   * A {@link MutationQueryReducersMap}, which is map from query names to\n   * mutation query reducers. Briefly, this map defines how to incorporate the\n   * results of the mutation into the results of queries that are currently\n   * being watched by your application.\n   */\n  updateQueries?: MutationQueryReducersMap<TData>;\n\n  /**\n   * A list of query names which will be refetched once this mutation has\n   * returned. This is often used if you have a set of queries which may be\n   * affected by a mutation and will have to update. Rather than writing a\n   * mutation query reducer (i.e. `updateQueries`) for this, you can simply\n   * refetch the queries that will be affected and achieve a consistent store\n   * once these queries return.\n   */\n  refetchQueries?:\n    | ((result: FetchResult<TData>) => InternalRefetchQueriesInclude)\n    | InternalRefetchQueriesInclude;\n\n  /**\n   * By default, `refetchQueries` does not wait for the refetched queries to\n   * be completed, before resolving the mutation `Promise`. This ensures that\n   * query refetching does not hold up mutation response handling (query\n   * refetching is handled asynchronously). Set `awaitRefetchQueries` to\n   * `true` if you would like to wait for the refetched queries to complete,\n   * before the mutation can be marked as resolved.\n   */\n  awaitRefetchQueries?: boolean;\n\n  /**\n   * A function which provides an {@link ApolloCache} instance, and the result\n   * of the mutation, to allow the user to update the store based on the\n   * results of the mutation.\n   *\n   * This function will be called twice over the lifecycle of a mutation. Once\n   * at the very beginning if an `optimisticResponse` was provided. The writes\n   * created from the optimistic data will be rolled back before the second time\n   * this function is called which is when the mutation has successfully\n   * resolved. At that point `update` will be called with the *actual* mutation\n   * result and those writes will not be rolled back.\n   *\n   * Note that since this function is intended to be used to update the\n   * store, it cannot be used with a `no-cache` fetch policy. If you're\n   * interested in performing some action after a mutation has completed,\n   * and you don't need to update the store, use the Promise returned from\n   * `client.mutate` instead.\n   */\n  update?: MutationUpdaterFunction<TData, TVariables, TContext, TCache>;\n\n  /**\n   * A function that will be called for each ObservableQuery affected by\n   * this mutation, after the mutation has completed.\n   */\n  onQueryUpdated?: OnQueryUpdated<any>;\n\n  /**\n   * Specifies the {@link ErrorPolicy} to be used for this operation\n   */\n  errorPolicy?: ErrorPolicy;\n\n  /**\n   * An object that maps from the name of a variable as used in the mutation\n   * GraphQL document to that variable's value.\n   */\n  variables?: TVariables;\n\n  /**\n   * The context to be passed to the link execution chain. This context will\n   * only be used with this mutation. It will not be used with\n   * `refetchQueries`. Refetched queries use the context they were\n   * initialized with (since the initial context is stored as part of the\n   * `ObservableQuery` instance). If a specific context is needed when\n   * refetching queries, make sure it is configured (via the\n   * [query `context` option](https://www.apollographql.com/docs/react/api/apollo-client#ApolloClient.query))\n   * when the query is first initialized/run.\n   */\n  context?: TContext;\n}\n\nexport interface MutationOptions<\n  TData = any,\n  TVariables = OperationVariables,\n  TContext = DefaultContext,\n  TCache extends ApolloCache<any> = ApolloCache<any>,\n> extends MutationBaseOptions<TData, TVariables, TContext, TCache> {\n  /**\n   * A GraphQL document, often created with `gql` from the `graphql-tag`\n   * package, that contains a single mutation inside of it.\n   */\n  mutation: DocumentNode | TypedDocumentNode<TData, TVariables>;\n\n  /**\n   * Specifies the {@link MutationFetchPolicy} to be used for this query.\n   * Mutations support only 'network-only' and 'no-cache' fetchPolicy strings.\n   * If fetchPolicy is not provided, it defaults to 'network-only'.\n   */\n  fetchPolicy?: MutationFetchPolicy;\n\n  /**\n   * To avoid retaining sensitive information from mutation root field\n   * arguments, Apollo Client v3.4+ automatically clears any `ROOT_MUTATION`\n   * fields from the cache after each mutation finishes. If you need this\n   * information to remain in the cache, you can prevent the removal by passing\n   * `keepRootFields: true` to the mutation. `ROOT_MUTATION` result data are\n   * also passed to the mutation `update` function, so we recommend obtaining\n   * the results that way, rather than using this option, if possible.\n   */\n  keepRootFields?: boolean;\n}\n"]}