client.refetchQueries section

Author: phryneas

docs/shared/MdxProvidedComponents.ts

@@ -57,6 +57,8 @@ declare const Example: React.FC<{
 declare const FunctionDetails: React.FC<{
   /** canonical reference of the DocBlock to include. */
   canonicalReference: string;
+  /** can be used to override the heading, which would usually just be the name of the function. This is useful if the interface name only makes sense in the context of a class, such as `client.refetchResult` or `ApolloClient.refetchResult` instead of `refetchResult`, which would be too generic */
+  displayName?: string;
   /** describes the nesting depth of the main heading for the markdown generated by this codeblock */
   headingLevel: number;
   /** can be set to `false` to hide the result and parameters sections in the generated Docs page - this is useful if the parameters are not well documented */

docs/source/data/refetching.mdx

@@ -2,6 +2,7 @@
 title: Refetching queries in Apollo Client
 ---
 
+{/** @import {MDXProvidedComponents} from '../../shared/MdxProvidedComponents.js' */}
 
 Apollo Client allows you to make local modifications to your GraphQL data by [updating the cache](./mutations/#updating-the-cache-directly), but sometimes it's more straightforward to update your client-side GraphQL data by refetching queries from the server.
 
@@ -13,73 +14,30 @@ Refetching is especially common after a mutation, so [mutate functions](./mutati
 
 To selectively refetch queries _outside_ of a mutation, you instead use the `refetchQueries` method of `ApolloClient`, which is documented here.
 
-## `client.refetchQueries`
-
-### Refetch options
-
-<InterfaceDetails
-  canonicalReference="@apollo/client!RefetchQueriesOptions:interface"
-  headingLevel={4}
-/>
-
-### Refetch results
-
-<!-- TODO -->
+<FunctionDetails
+  canonicalReference="@apollo/client!ApolloClient#refetchQueries:member(1)"
+  headingLevel={2}
+  displayName="client.refetchQueries"
+>
 
 The `client.refetchQueries` method collects the `TResult` results returned by `onQueryUpdated`, defaulting to `TResult = Promise<ApolloQueryResult<any>>` if `onQueryUpdated` is not provided. It combines those results into a single `Promise<TResolved[]>` using `Promise.all(results)`.
 
-> Thanks to the `Promise`-unwrapping behavior of `Promise.all`, this `TResolved` type is often the same type as `TResult`, except when `TResult` is a `PromiseLike<TResolved>` or a `boolean`.
+<Note>
+Thanks to the `Promise`-unwrapping behavior of `Promise.all`, this `TResolved` type is often the same type as `TResult`, except when `TResult` is a `PromiseLike<TResolved>` or a `boolean`.
+</Note>
 
 The returned `Promise` object has two other useful properties:
 
-<table class="field-table api-ref">
-  <thead>
-    <tr>
-      <th>Name /<br/>Type</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-
-<tr>
-<td>
-
-###### `queries`
-
-`ObservableQuery[]`
-</td>
-
-<td>
-
-An array of `ObservableQuery` objects that were refetched.
-
-</td>
-</tr>
-
-<tr>
-<td>
-
-###### `results`
-
-`TResult[]`
-</td>
-
-<td>
-
-An array of results that were either returned by `onQueryUpdated`, or provided by default in the absence of `onQueryUpdated`, including pending promises.
-
-If `onQueryUpdated` returns `false` for a given query, no result is provided for that query.
-
-If `onQueryUpdated` returns `true`, the resulting `Promise<ApolloQueryResult<any>>` is included in the `results` array instead of `true`.
-
-</td>
-</tr>
-
-</tbody>
-</table>
+<InterfaceDetails
+  canonicalReference="@apollo/client!RefetchQueriesResult.AdditionalProperties:interface"
+  headingLevel={4}
+  displayName="RefetchQueriesResult.AdditionalProperties"
+/>
 
 These two arrays parallel each other: they have the same length, and `results[i]` is the result produced by `onQueryUpdated` when called with the `ObservableQuery` found at `queries[i]`, for any index `i`.
 
+</FunctionDetails>
+
 ### Refetch recipes
 
 #### Refetching a specific query

src/core/types.ts

@@ -271,20 +271,32 @@ export type RefetchQueriesPromiseResults<TResult> =
     // default to ApolloQueryResult<any> if no onQueryUpdated function is passed
     // to client.refetchQueries.
     TResult[];
-
-// The result of client.refetchQueries is thenable/awaitable, if you just want
-// an array of fully resolved results, but you can also access the raw results
-// immediately by examining the additional { queries, results } properties of
-// the RefetchQueriesResult<TResult> object.
+/**
+ * The result of client.refetchQueries is thenable/awaitable, if you just want
+ * an array of fully resolved results, but you can also access the raw results
+ * immediately by examining the additional { queries, results } properties of
+ * the RefetchQueriesResult<TResult> object.
+ */
 export interface RefetchQueriesResult<TResult>
-  extends Promise<RefetchQueriesPromiseResults<TResult>> {
-  // An array of ObservableQuery objects corresponding 1:1 to TResult values
-  // in the results arrays (both the TResult[] array below, and the results
-  // array resolved by the Promise above).
-  queries: ObservableQuery<any>[];
-  // These are the raw TResult values returned by any onQueryUpdated functions
-  // that were invoked by client.refetchQueries.
-  results: InternalRefetchQueriesResult<TResult>[];
+  extends Promise<RefetchQueriesPromiseResults<TResult>>,
+    RefetchQueriesResult.AdditionalProperties<TResult> {}
+
+export namespace RefetchQueriesResult {
+  export interface AdditionalProperties<TResult> {
+    /**
+     * An array of ObservableQuery objects corresponding 1:1 to TResult values
+     * in the results arrays (both the `result` property and the resolved value).
+     */
+    queries: ObservableQuery<any>[];
+    /**
+     * An array of results that were either returned by `onQueryUpdated`, or provided by default in the absence of `onQueryUpdated`, including pending promises.
+     *
+     * If `onQueryUpdated` returns `false` for a given query, no result is provided for that query.
+     *
+     * If `onQueryUpdated` returns `true`, the resulting `Promise<ApolloQueryResult<any>>` is included in the `results` array instead of `true`.
+     */
+    results: InternalRefetchQueriesResult<TResult>[];
+  }
 }
 
 // Used by QueryManager["refetchQueries"]