progress

docs/shared/ApiDoc/DocBlock.js

@@ -138,7 +138,7 @@ export function Example({
   if (!value) return null;
   return (
     <MaybeCollapsible collapsible={collapsible}>
-      <b>{mdToReact(value)}</b>
+      {mdToReact(value)}
     </MaybeCollapsible>
   );
 }

docs/source/caching/memory-management.mdx

@@ -2,13 +2,15 @@
 title: Memory management
 api_doc:
   - "@apollo/client!CacheSizes:interface"
+  - "@apollo/client!ApolloClient:class"
 ---
 
-import { InterfaceDetails } from '../../shared/ApiDoc';
+import { Remarks, PropertySignatureTable, Example } from '../../shared/ApiDoc';
 
 ## Cache Sizes
 
-For better performance, Apollo Client caches a lot of internally calculated values.
+For better performance, Apollo Client caches (or, in other words, memoizes) a lot
+of internally calculated values.
 In most cases, these values are cached in WeakCaches, which means that if the
 source object is garbage-collected, the cached value will be garbage-collected,
 too.
@@ -52,6 +54,70 @@ cacheSizes.print = 100;
 print.reset();
 ```
 
-### Cache Details
-
-<InterfaceDetails canonicalReference="@apollo/client!CacheSizes:interface" headingLevel={3}/>
+### Choosing good cache sizes
+
+<Remarks
+  canonicalReference="@apollo/client!CacheSizes:interface"
+/>
+
+To choose good sizes for our memoization caches, you need to know what they
+use as source values, and have a general understanding of the data flow inside of
+Apollo Client.
+
+For most memoized values, the source value will be a parsed GraphQL document -
+a `DocumentNode`. Here, we need to distinguish between two types of documents:
+
+* User-supplied `DocumentNode`s: These are DocumentNode objects that are created
+  by the user, for example by using the `gql` template literal tag.
+  These are the `QUERY`, `MUTATION` or `SUBSCRIPTION` variables that you pass e.g.
+  into your `useQuery` hook, or as the `query` option to `client.query`.
+* Transformed `DocumentNode`s: These are DocumentNode objects are derived from
+  user-supplied `DocumentNode`s, e.g. by applying `DocumentTransform`s to them.
+
+As a rule of thumb, you should set the cache sizes for caches using a Transformed
+`DocumentNode` at least to the same size as for caches using a user-supplied
+`DocumentNode`. If your application uses a custom `DocumentTransform` that does
+not always transform the same input to the same output, you should set the cache
+size for caches using a Transformed `DocumentNode` to a higher value than for
+caches using a user-supplied `DocumentNode`.
+
+By default, Apollo Client uses a "base value" of 1000 for caches using
+user-supplied `DocumentNode` instances, and scales other cache sizes relative
+to that.
+
+This should be plenty for almost all applications out there, but you might want
+to tweak them if you have different requirements.
+
+#### Measuring cache usage
+
+As it can be hard to estimate good cache sizes for your application, Apollo Client
+exposes an API for cache usage measurement.<br />
+This way, you can click around in your application and then take a look at the
+actual usage of the memoizing caches.
+
+Keep in mind that this API is primarily meant for usage with our DevTools
+(we will release an integration for this soon), and we might change it at any
+point in time.<br />
+It is also only included in development builds, not in production builds.
+
+So please only use this for manual measurements, and don't rely on it in production
+code or tests.
+
+<Example
+  canonicalReference="@apollo/client!ApolloClient#getMemoryInternals:member"
+  index={0}
+/>
+
+<Example
+  collapsible
+  canonicalReference="@apollo/client!ApolloClient#getMemoryInternals:member"
+  index={1}
+/>
+
+### Cache options
+
+<PropertySignatureTable
+  canonicalReference="@apollo/client!CacheSizes:interface"
+  methods
+  properties
+/>

src/core/ApolloClient.ts

@@ -750,10 +750,83 @@ export class ApolloClient<TCacheShape> implements DataProxy {
 
   /**
    * @experimental
-   * @internal
    * This is not a stable API - it is used in development builds to expose
    * information to the DevTools.
    * Use at your own risk!
+   * For more details, see [Memory Management](https://www.apollographql.com/docs/react/caching/memory-management/#measuring-cache-usage)
+   *
+   * @example
+   * ```ts
+   * console.log(client.getMemoryInternals())
+   * ```
+   * will log something in the form of
+   * @example
+   * ```json
+   *{
+   *  limits:     {
+   *    parser: 1000,
+   *    canonicalStringify: 1000,
+   *    print: 2000,
+   *    'documentTransform.cache': 2000,
+   *    'queryManager.getDocumentInfo': 2000,
+   *    'PersistedQueryLink.persistedQueryHashes': 2000,
+   *    'fragmentRegistry.transform': 2000,
+   *    'fragmentRegistry.lookup': 1000,
+   *    'fragmentRegistry.findFragmentSpreads': 4000,
+   *    'cache.fragmentQueryDocuments': 1000,
+   *    'removeTypenameFromVariables.getVariableDefinitions': 2000,
+   *    'inMemoryCache.maybeBroadcastWatch': 5000,
+   *    'inMemoryCache.executeSelectionSet': 10000,
+   *    'inMemoryCache.executeSubSelectedArray': 5000
+   *  },
+   *  sizes: {
+   *    parser: 26,
+   *    canonicalStringify: 4,
+   *    print: 14,
+   *    addTypenameDocumentTransform: [
+   *      {
+   *        cache: 14,
+   *      },
+   *    ],
+   *    queryManager: {
+   *      getDocumentInfo: 14,
+   *      documentTransforms: [
+   *        {
+   *          cache: 14,
+   *        },
+   *        {
+   *          cache: 14,
+   *        },
+   *      ],
+   *    },
+   *    fragmentRegistry: {
+   *      findFragmentSpreads: 34,
+   *      lookup: 20,
+   *      transform: 14,
+   *    },
+   *    cache: {
+   *      fragmentQueryDocuments: 22,
+   *    },
+   *    inMemoryCache: {
+   *      executeSelectionSet: 4345,
+   *      executeSubSelectedArray: 1206,
+   *      maybeBroadcastWatch: 32,
+   *    },
+   *    links: [
+   *      {
+   *        PersistedQueryLink: {
+   *          persistedQueryHashes: 14,
+   *        },
+   *      },
+   *      {
+   *        removeTypenameFromVariables: {
+   *          getVariableDefinitions: 14,
+   *        },
+   *      },
+   *    ],
+   *  },
+   * }
+   *```
    */
   public getMemoryInternals?: typeof getApolloClientMemoryInternals;
 }

src/utilities/caching/sizes.ts

@@ -9,13 +9,18 @@ declare global {
 /**
  * The cache sizes used by various Apollo Client caches.
  *
- * Note that these caches are all derivative and if an item is cache-collected,
- * it's not the end of the world - the cached item will just be recalculated.
+ * @remarks
+ * All configurable caches hold derivative (memoized) values and if an item is
+ * cache-collected, that only means a small performance hit, but it will not
+ * cause data loss, and a smaller cache size might save you memory.
  *
  * As a result, these cache sizes should not be chosen to hold every value ever
- * encountered, but rather to hold a reasonable number of values that can be
- * assumed to be on the screen at any given time.
- *
+ * encountered, but rather to hold a reasonable number of values.
+ * To prevent too much recalculation, cache sizes should at least be chosen
+ * big enough to hold memoized values for all hooks/queries that are
+ * on the screen at any given time.
+ */
+/*
  * We assume a "base value" of 1000 here, which is already very generous.
  * In most applications, it will be very unlikely that 1000 different queries
  * are on screen at the same time.