Add QueryOptions and QueryBaseOptions interfaces

packages/apollo-client/CHANGELOG.md

@@ -7,6 +7,13 @@
   [PR#3140](https://github.com/apollographql/apollo-client/pull/3140)
 - Added optional generics to cache manipulation methods (typescript).
   [PR #3541](https://github.com/apollographql/apollo-client/pull/3541)
+- Typescript improvements. Created a new `QueryOptions` interface that  
+  is now used by `ApolloClient.query` options, instead of the previous
+  `WatchQueryOptions` interface. This helps reduce confusion (especially
+  in the docs) that made it look like `ApolloClient.query` accepted
+  `ApolloClient.watchQuery` only options, like `pollingInterval`.
+  [Issue #3395](https://github.com/apollographql/apollo-client/issues/3395)
+  [PR #3569](https://github.com/apollographql/apollo-client/pull/3569)
 
 ### 2.3.2
 

packages/apollo-client/src/ApolloClient.ts

@@ -20,6 +20,7 @@ import { ObservableQuery } from './core/ObservableQuery';
 import { Observable } from './util/Observable';
 
 import {
+  QueryOptions,
   WatchQueryOptions,
   SubscriptionOptions,
   MutationOptions,
@@ -33,7 +34,7 @@ import { version } from './version';
 
 export interface DefaultOptions {
   watchQuery?: ModifiableWatchQueryOptions;
-  query?: ModifiableWatchQueryOptions;
+  query?: QueryOptions;
   mutate?: MutationBaseOptions;
 }
 
@@ -221,15 +222,15 @@ export default class ApolloClient<TCacheShape> implements DataProxy {
   }
 
   /**
-   * This resolves a single query according to the options specified and returns a
-   * {@link Promise} which is either resolved with the resulting data or rejected
-   * with an error.
+   * This resolves a single query according to the options specified and
+   * returns a {@link Promise} which is either resolved with the resulting data
+   * or rejected with an error.
    *
-   * @param options An object of type {@link WatchQueryOptions} that allows us to describe
-   * how this query should be treated e.g. whether it is a polling query, whether it should hit the
+   * @param options An object of type {@link QueryOptions} that allows us to
+   * describe how this query should be treated e.g. whether it should hit the
    * server at all or just resolve from the cache, etc.
    */
-  public query<T>(options: WatchQueryOptions): Promise<ApolloQueryResult<T>> {
+  public query<T>(options: QueryOptions): Promise<ApolloQueryResult<T>> {
     this.initQueryManager();
 
     if (this.defaultOptions.query) {
@@ -242,7 +243,8 @@ export default class ApolloClient<TCacheShape> implements DataProxy {
       );
     }
 
-    // XXX Overwriting options is probably not the best way to do this long term...
+    // XXX Overwriting options is probably not the best way to do this long
+    // term...
     if (this.disableNetworkFetches && options.fetchPolicy === 'network-only') {
       options = { ...options, fetchPolicy: 'cache-first' } as WatchQueryOptions;
     }

packages/apollo-client/src/core/QueryManager.ts

@@ -26,6 +26,7 @@ import { MutationStore } from '../data/mutations';
 import { QueryStore, QueryStoreValue } from '../data/queries';
 
 import {
+  QueryOptions,
   WatchQueryOptions,
   SubscriptionOptions,
   MutationOptions,
@@ -657,10 +658,11 @@ export class QueryManager<TStore> {
     });
   }
 
-  public query<T>(options: WatchQueryOptions): Promise<ApolloQueryResult<T>> {
+  public query<T>(options: QueryOptions): Promise<ApolloQueryResult<T>> {
     if (!options.query) {
       throw new Error(
-        'query option is required. You must specify your GraphQL document in the query option.',
+        'query option is required. You must specify your GraphQL document ' +
+          'in the query option.',
       );
     }
 
@@ -676,13 +678,6 @@ export class QueryManager<TStore> {
       throw new Error('pollInterval option only supported on watchQuery.');
     }
 
-    if (typeof options.notifyOnNetworkStatusChange !== 'undefined') {
-      throw new Error(
-        'Cannot call "query" with "notifyOnNetworkStatusChange" option. Only "watchQuery" has that option.',
-      );
-    }
-    options.notifyOnNetworkStatusChange = false;
-
     const requestId = this.idCounter;
 
     return new Promise<ApolloQueryResult<T>>((resolve, reject) => {

packages/apollo-client/src/core/watchQueryOptions.ts

@@ -34,21 +34,15 @@ export type FetchPolicy =
 export type ErrorPolicy = 'none' | 'ignore' | 'all';
 
 /**
- * We can change these options to an ObservableQuery
+ * Common options shared across all query interfaces.
  */
-export interface ModifiableWatchQueryOptions<TVariables = OperationVariables> {
+export interface QueryBaseOptions<TVariables = OperationVariables> {
   /**
    * A map going from variable name to variable value, where the variables are used
    * within the GraphQL query.
    */
   variables?: TVariables;
 
-  /**
-   * The time interval (in milliseconds) on which this query should be
-   * refetched from the server.
-   */
-  pollInterval?: number;
-
   /**
    * Specifies the {@link FetchPolicy} to be used for this query
    */
@@ -63,23 +57,19 @@ export interface ModifiableWatchQueryOptions<TVariables = OperationVariables> {
    * Whether or not to fetch results
    */
   fetchResults?: boolean;
-
-  /**
-   * Whether or not updates to the network status should trigger next on the observer of this query
-   */
-  notifyOnNetworkStatusChange?: boolean;
 }
 
 /**
- * The argument to a query
+ * Query options.
  */
-export interface WatchQueryOptions<TVariables = OperationVariables>
-  extends ModifiableWatchQueryOptions<TVariables> {
+export interface QueryOptions<TVariables = OperationVariables>
+  extends QueryBaseOptions<TVariables> {
   /**
    * A GraphQL document that consists of a single query to be sent down to the
    * server.
    */
-  // TODO REFACTOR: rename this to document. Didn't do it yet because it's in a lot of tests.
+  // TODO REFACTOR: rename this to document. Didn't do it yet because it's in a
+  // lot of tests.
   query: DocumentNode;
 
   /**
@@ -94,6 +84,30 @@ export interface WatchQueryOptions<TVariables = OperationVariables>
   context?: any;
 }
 
+/**
+ * We can change these options to an ObservableQuery
+ */
+export interface ModifiableWatchQueryOptions<TVariables = OperationVariables>
+  extends QueryBaseOptions<TVariables> {
+  /**
+   * 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;
+}
+
+/**
+ * Watched query options.
+ */
+export interface WatchQueryOptions<TVariables = OperationVariables>
+  extends QueryOptions<TVariables>,
+    ModifiableWatchQueryOptions<TVariables> {}
+
 export interface FetchMoreQueryOptions<TVariables, K extends keyof TVariables> {
   query?: DocumentNode;
   variables?: Pick<TVariables, K>;