Add a visualizing section to cache configuration

docs/source/caching/cache-configuration.md → docs/source/caching/cache-configuration.mdx

@@ -3,6 +3,8 @@ title: Configuring the cache
 sidebar_title: Configuration
 ---
 
+import {ExpansionPanel} from 'gatsby-theme-apollo-docs';
+
 Apollo Client stores the results of its GraphQL queries in a normalized, in-memory cache. This enables your client to respond to future queries for the same data without sending unnecessary network requests.
 
 This article describes cache setup and configuration. To learn how to interact with cached data, see [Reading and writing data to the cache](./cache-interaction).
@@ -54,12 +56,14 @@ To customize cache behavior, provide an `options` object to the `InMemoryCache`
 ###### `addTypename`
 
 `Boolean`
+
 </td>
 <td>
 
 If `true`, the cache automatically adds `__typename` fields to all outgoing queries, removing the need to add them manually.
 
 The default value is `true`.
+
 </td>
 </tr>
 
@@ -69,12 +73,14 @@ The default value is `true`.
 ###### `resultCaching`
 
 `Boolean`
+
 </td>
 <td>
 
 If `true`, the cache returns an identical (`===`) response object for every execution of the same query, as long as the underlying data remains unchanged. This makes it easier to detect changes to a query's result.
 
 The default value is `true`.
+
 </td>
 </tr>
 
@@ -84,6 +90,7 @@ The default value is `true`.
 ###### `possibleTypes`
 
 `Object`
+
 </td>
 <td>
 
@@ -92,6 +99,7 @@ Include this object to define polymorphic relationships between your schema's ty
 Each key in the object is the `__typename` of an interface or union, and the corresponding value is an array of the `__typename`s of the types that belong to that union or implement that interface.
 
 For an example, see [Defining `possibleTypes` manually](../data/fragments/#defining-possibletypes-manually).
+
 </td>
 </tr>
 
@@ -101,12 +109,14 @@ For an example, see [Defining `possibleTypes` manually](../data/fragments/#defin
 ###### `typePolicies`
 
 `Object`
+
 </td>
 <td>
 
 Include this object to customize the cache's behavior on a type-by-type basis.
 
 Each key in the object is the `__typename` of a type to customize, and the corresponding value is a [`TypePolicy` object](#typepolicy-fields).
+
 </td>
 </tr>
 
@@ -116,12 +126,14 @@ Each key in the object is the `__typename` of a type to customize, and the corre
 ###### `dataIdFromObject`
 
 `Function`
+
 </td>
 <td>
 
 **Deprecated.** A function that takes a response object and returns a unique identifier to be used when normalizing the data in the store.
 
 Deprecated in favor of the `keyFields` option of the [`TypePolicy` object](#typepolicy-fields).
+
 </td>
 </tr>
 </tbody>
@@ -234,6 +246,83 @@ To disable normalization for a type, define a `TypePolicy` for the type (as show
 
 Objects that are not normalized are instead embedded within their _parent_ object in the cache. You can't access these objects directly, but you can access them via their parent.
 
+## Visualizing the cache
+
+To help understand the structure of your cached data, we strongly recommend installing the [Apollo Client Devtools](../development-testing/developer-tooling/#apollo-client-devtools).
+
+This browser extension includes an inspector that enables you to view all of the normalized objects contained in your cache:
+
+<img src="../img/cache-inspector.jpg" class="screenshot" alt="The Cache tab of the Apollo Client Devtools"></img>
+
+### Example
+
+Let's say we use Apollo Client to run the following query on the [SWAPI demo API](https://github.com/graphql/swapi-graphql):
+
+```graphql
+query {
+  allPeople(first:3) { # Return the first 3 items
+    people {
+      id
+      name
+      homeworld {
+        id
+        name
+      }
+    }
+  }
+}
+```
+
+This query returns the following result of three `Person` objects, each with a corresponding `homeworld` (a `Planet` object):
+
+<ExpansionPanel title="Click to expand">
+
+```json
+{
+  "data": {
+    "allPeople": {
+      "people": [
+        {
+          "id": "cGVvcGxlOjE=",
+          "name": "Luke Skywalker",
+          "homeworld": {
+            "id": "cGxhbmV0czox",
+            "name": "Tatooine"
+          }
+        },
+        {
+          "id": "cGVvcGxlOjI=",
+          "name": "C-3PO",
+          "homeworld": {
+            "id": "cGxhbmV0czox",
+            "name": "Tatooine"
+          }
+        },
+        {
+          "id": "cGVvcGxlOjM=",
+          "name": "R2-D2",
+          "homeworld": {
+            "id": "cGxhbmV0czo4",
+            "name": "Naboo"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+</ExpansionPanel>
+
+After the result is cached, we can view the state of our cache in the Apollo Client Devtools:
+
+<img src="../img/cache-inspector.jpg" class="screenshot" alt="The Cache tab of the Apollo Client Devtools"></img>
+
+Our cache now contains five normalized objects (in addition to the `ROOT_QUERY` object): three `Person` objects and two `Planet` objects.
+
+**Why do we only have two `Planet` objects?** Because two of the three returned `Person` objects have the same `homeworld`. By [normalizing data](#data-normalization) like this, Apollo Client can cache a single copy of an object, and multiple _other_ objects can include _references_ to it (see the `__ref` field of the object in the screenshot above).
+
+
 ## `TypePolicy` fields
 
 To customize how the cache interacts with specific types in your schema, you can provide an object mapping `__typename` strings to `TypePolicy` objects when you create a new `InMemoryCache` object.