Merge branch 'master' into release-3.0

CHANGELOG.md

@@ -1,5 +1,14 @@
 **Note:** This is a cumulative changelog that outlines all of the Apollo Client project child package changes that were bundled into a specific `apollo-client` release.
 
+## Apollo Client (vNext)
+
+### Apollo Client (vNext)
+
+- Documentation updates.  </br>
+  [@raibima](https://github.com/raibima) in [#5132](https://github.com/apollographql/apollo-client/pull/5132)  <br/>
+  [@hwillson](https://github.com/hwillson) in [#5141](https://github.com/apollographql/apollo-client/pull/5141)
+
+
 ## Apollo Client (2.6.3)
 
 ### Apollo Client (2.6.3)

docs/gatsby-config.js

@@ -8,8 +8,9 @@ module.exports = {
         subtitle: 'Apollo Client',
         description: 'A guide to using the Apollo GraphQL Client with React',
         githubRepo: 'apollographql/apollo-client',
-        defaultVersion: 2.5,
+        defaultVersion: 2.6,
         versions: {
+          2.5: 'version-2.5',
           2.4: 'version-2.4',
         },
         checkLinksExceptions: [
@@ -21,12 +22,7 @@ module.exports = {
           filepathPrefix: 'packages/apollo-client/src/',
         },
         sidebarCategories: {
-          null: [
-            'index',
-            'why-apollo',
-            'integrations',
-            'react-apollo-migration',
-          ],
+          null: ['index', 'why-apollo', 'integrations', 'hooks-migration'],
           Essentials: [
             'essentials/get-started',
             'essentials/queries',
@@ -58,9 +54,16 @@ module.exports = {
             'recipes/webpack',
             'recipes/meteor',
             'recipes/recompose',
-            'recipes/2.0-migration',
           ],
-          API: ['api/apollo-client', 'api/react-apollo'],
+          API: [
+            'api/apollo-client',
+            'api/react-hooks',
+            'api/react-ssr',
+            'api/react-testing',
+            'api/react-components',
+            'api/react-hoc',
+            'api/react-common',
+          ],
         },
       },
     },

docs/package.json

@@ -6,8 +6,8 @@
     "types": "cd ../packages/apollo-client && typedoc --json ../../docs/docs.json --ignoreCompilerErrors ./src/index.ts"
   },
   "dependencies": {
-    "gatsby": "2.13.41",
-    "gatsby-theme-apollo-docs": "1.2.0"
+    "gatsby": "2.13.50",
+    "gatsby-theme-apollo-docs": "1.2.2"
   },
   "devDependencies": {
     "typedoc": "0.15.0",

docs/shared/apollo-provider.mdx

@@ -0,0 +1,22 @@
+The `ApolloProvider` component leverages [React's Context API](https://reactjs.org/docs/context.html) to make a configured Apollo Client instance available throughout a React component tree. This component can be imported directly from the `@apollo/react-common` package where it lives, or from one of the `@apollo/react-hooks`, `@apollo/react-components`, and `@apollo/react-hoc` packages.
+
+```js
+import { ApolloProvider } from '@apollo/react-hooks';
+```
+
+### Props
+
+| Option   | Type                       | Description                 |
+| -------- | -------------------------- | --------------------------- |
+| `client` | ApolloClient<TCache> | An `ApolloClient` instance. |
+
+### Example
+
+```jsx
+ReactDOM.render(
+  <ApolloProvider client={client}>
+    <MyRootComponent />
+  </ApolloProvider>,
+  document.getElementById('root'),
+);
+```

docs/shared/mutation-options.mdx

@@ -0,0 +1,13 @@
+| Option | Type | Description |
+| - | - | - |
+| `mutation` | DocumentNode | A GraphQL mutation document parsed into an AST by `graphql-tag`. **Optional** for the `useMutation` Hook since the mutation can be passed in as the first parameter to the Hook. **Required** for the `Mutation` component. |
+| `variables` | { [key: string]: any } | An object containing all of the variables your mutation needs to execute |
+| `update` | (cache: DataProxy, mutationResult: FetchResult) | A function used to update the cache after a mutation occurs |
+| `ignoreResults`| boolean | If true, the returned `data` property will not update with the mutation result. |
+| `optimisticResponse` | Object | Provide a [mutation response](/features/optimistic-ui/) before the result comes back from the server |
+| `refetchQueries`| (mutationResult: FetchResult) => Array<{ query: DocumentNode, variables?: TVariables}> | A function that allows you to specify which queries you want to refetch after a mutation has occurred |
+| `awaitRefetchQueries` | boolean | Queries refetched as part of `refetchQueries` are handled asynchronously, and are not waited on before the mutation is completed (resolved). Setting this to `true` will make sure refetched queries are completed before the mutation is considered done. `false` by default. |
+| `onCompleted` | (data: TData) => void | A callback executed once your mutation successfully completes |
+| `onError` | (error: ApolloError) => void | A callback executed in the event of an error. |
+| `context` | Record<string, any> | Shared context between your component and your network interface (Apollo Link). Useful for setting headers from props or sending information to the `request` function of Apollo Boost. |
+| `client` | ApolloClient | An `ApolloClient` instance. By default `useMutation` / `Mutation` uses the client passed down via context, but a different client can be passed in. |

docs/shared/mutation-result.mdx

@@ -0,0 +1,15 @@
+**Mutate function:**
+
+| Property | Type | Description |
+| - | - | - |
+| `mutate` | (options?: MutationOptions) => Promise<FetchResult> | A function to trigger a mutation from your UI. You can optionally pass `variables`, `optimisticResponse`, `refetchQueries`, and `update` in as options, which will override options/props passed to `useMutation` / `Mutation`. The function returns a promise that fulfills with your mutation result. |
+
+**Mutation result:**
+
+| Property | Type | Description |
+| - | - | - |
+| `data` | TData | The data returned from your mutation. It can be undefined if `ignoreResults` is true. |
+| `loading` | boolean | A boolean indicating whether your mutation is in flight |
+| `error` | ApolloError | Any errors returned from the mutation |
+| `called` | boolean | A boolean indicating if the mutate function has been called |
+| `client` | ApolloClient | Your `ApolloClient` instance. Useful for invoking cache methods outside the context of the update function, such as `client.writeData` and `client.readQuery`. |

docs/shared/query-options.mdx

@@ -0,0 +1,18 @@
+| Option | Type | Description |
+| - | - | - |
+| `query` | DocumentNode | A GraphQL query document parsed into an AST by `graphql-tag`. **Optional** for the `useQuery` Hook since the query can be passed in as the first parameter to the Hook. **Required** for the `Query` component. |
+| `variables` | { [key: string]: any } | An object containing all of the variables your query needs to execute |
+| `pollInterval` | number | Specifies the interval in ms at which you want your component to poll for data. Defaults to 0 (no polling). |
+| `notifyOnNetworkStatusChange` | boolean | Whether updates to the network status or network error should re-render your component. Defaults to false. |
+| `fetchPolicy` | FetchPolicy | How you want your component to interact with the Apollo cache. Defaults to "cache-first". |
+| `errorPolicy` | ErrorPolicy | How you want your component to handle network and GraphQL errors. Defaults to "none", which means we treat GraphQL errors as runtime errors. |
+| `ssr` | boolean | Pass in false to skip your query during server-side rendering. |
+| `displayName` | string | The name of your component to be displayed in React DevTools. Defaults to 'Query'. |
+| `skip` | boolean | If skip is true, the query will be skipped entirely. **Not available with `useLazyQuery`**. |
+| `onCompleted` | (data: TData | {}) => void | A callback executed once your query successfully completes. |
+| `onError` | (error: ApolloError) => void | A callback executed in the event of an error. |
+| `context` | Record<string, any> | Shared context between your component and your network interface (Apollo Link). Useful for setting headers from props or sending information to the `request` function of Apollo Boost. |
+| `partialRefetch` | 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). The default value is `false` for backwards-compatibility's sake, but should be changed to true for most use-cases. |
+| `client` | ApolloClient | An `ApolloClient` instance. By default `useQuery` / `Query` uses the client passed down via context, but a different client can be passed in. |
+| `returnPartialData` | boolean | Opt into receiving partial results from the cache for queries that are not fully satisfied by the cache. false by default. |
+

docs/shared/query-result.mdx

@@ -0,0 +1,15 @@
+| Property | Type | Description |
+| - | - | - |
+| `data` | TData | An object containing the result of your GraphQL query. Defaults to `undefined`. |
+| `loading` | boolean | A boolean that indicates whether the request is in flight |
+| `error` | ApolloError | A runtime error with `graphQLErrors` and `networkError` properties |
+| `variables` | { [key: string]: any } | An object containing the variables the query was called with |
+| `networkStatus` | NetworkStatus | A number from 1-8 corresponding to the detailed state of your network request. Includes information about refetching and polling status. Used in conjunction with the `notifyOnNetworkStatusChange` prop. |
+| `refetch` | (variables?: TVariables) => Promise<ApolloQueryResult> | A function that allows you to refetch the query and optionally pass in new variables |
+| `fetchMore` | ({ query?: DocumentNode, variables?: TVariables, updateQuery: Function}) => Promise<ApolloQueryResult> | A function that enables [pagination](/features/pagination/) for your query |
+| `startPolling` | (interval: number) => void | This function sets up an interval in ms and fetches the query each time the specified interval passes. |
+| `stopPolling` | () => void | This function stops the query from polling. |
+| `subscribeToMore` | (options: { document: DocumentNode, variables?: TVariables, updateQuery?: Function, onError?: Function}) => () => void | A function that sets up a [subscription](/advanced/subscriptions/). `subscribeToMore` returns a function that you can use to unsubscribe. |
+| `updateQuery` | (previousResult: TData, options: { variables: TVariables }) => TData | A function that allows you to update the query's result in the cache outside the context of a fetch, mutation, or subscription |
+| `client` | ApolloClient | Your `ApolloClient` instance. Useful for manually firing queries or writing data to the cache. |
+| `called` | boolean | A boolean indicating if the query function has been called, used by `useLazyQuery` (not set for `useQuery` / `Query`). |

docs/shared/subscription-options.mdx

@@ -0,0 +1,8 @@
+| Option | Type | Description |
+| - | - | - |
+| `subscription` | DocumentNode | A GraphQL subscription document parsed into an AST by `graphql-tag`. **Optional** for the `useSubscription` Hook since the subscription can be passed in as the first parameter to the Hook. **Required** for the `Subscription` component. |
+| `variables` | { [key: string]: any } | An object containing all of the variables your subscription needs to execute |
+| `shouldResubscribe` | boolean | Determines if your subscription should be unsubscribed and subscribed again |
+| `onSubscriptionData` | (options: OnSubscriptionDataOptions<TData>) => any | Allows the registration of a callback function, that will be triggered each time the `useSubscription` Hook / `Subscription` component receives data. The callback `options` object param consists of the current Apollo Client instance in `client`, and the received subscription data in `subscriptionData`. |
+| `fetchPolicy` | FetchPolicy | How you want your component to interact with the Apollo cache. Defaults to "cache-first". |
+| `client` | ApolloClient | An `ApolloClient` instance. By default `useSubscription` / `Subscription` uses the client passed down via context, but a different client can be passed in. |

docs/shared/subscription-result.mdx

@@ -0,0 +1,5 @@
+| Property  | Type | Description |
+| - | - | - |
+| `data` | TData | An object containing the result of your GraphQL subscription. Defaults to an empty object. |
+| `loading` | boolean | A boolean that indicates whether any initial data has been returned |
+| `error` | ApolloError | A runtime error with `graphQLErrors` and `networkError` properties |

docs/source/advanced/caching.md

@@ -307,7 +307,7 @@ mutate({
 })
 ```
 
-Using `update` gives you full control over the cache, allowing you to make changes to your data model in response to a mutation in any way you like. `update` is the recommended way of updating the cache after a query. It is explained in full [here](/api/react-apollo/#mutation).
+Using `update` gives you full control over the cache, allowing you to make changes to your data model in response to a mutation in any way you like. `update` is the recommended way of updating the cache after a query. It is explained in full [here](/api/react-hooks/#usemutation).
 
 ```jsx
 import CommentAppQuery from '../queries/CommentAppQuery';