| 1 | {"version":3,"file":"watchQueryOptions.js","sourceRoot":"","sources":["../../src/core/watchQueryOptions.ts"],"names":[],"mappings":"","sourcesContent":["import { DocumentNode } from 'graphql';\nimport { TypedDocumentNode } from '@graphql-typed-document-node/core';\n\nimport { FetchResult } from '../link/core';\nimport {\n DefaultContext,\n MutationQueryReducersMap,\n OperationVariables,\n MutationUpdaterFunction,\n OnQueryUpdated,\n InternalRefetchQueriesInclude,\n} from './types';\nimport { ApolloCache } from '../cache';\nimport { ObservableQuery } from './ObservableQuery';\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<TVariables extends OperationVariables = OperationVariables, 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?: WatchQueryFetchPolicy | ((\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<TData, TVariables extends OperationVariables> {\n reason:\n | \"after-fetch\"\n | \"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: DocumentNode | 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<TVariables = OperationVariables, TData = any> {\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"]} |