Implement useReactiveVar hook for consuming reactive variables in React components.

CHANGELOG.md

@@ -11,6 +11,9 @@
 - Prevent full reobservation of queries affected by optimistic mutation updates, while still delivering results from the cache. <br/>
   [@benjamn](https://github.com/benjamn) in [#6854](https://github.com/apollographql/apollo-client/pull/6854)
 
+- Implement `useReactiveVar` hook for consuming reactive variables in React components. <br/>
+  [@benjamn](https://github.com/benjamn) in [#6867](https://github.com/apollographql/apollo-client/pull/6867)
+
 ## Apollo Client 3.1.3
 
 ## Bug Fixes

docs/source/local-state/managing-state-with-field-policies.mdx

@@ -147,15 +147,14 @@ This `read` function returns the value of our reactive variable whenever `cartIt
 
 Now, let's create a button component that enables the user to add a product to their cart:
 
-```jsx{8}:title=AddToCartButton.js
+```jsx{7}:title=AddToCartButton.js
 import { cartItemsVar } from './cache';
 // ... other imports
 
 export function AddToCartButton({ productId }) {
-  const cartItems = cartItemsVar();
   return (
     <div class="add-to-cart-button">
-      <Button onClick={() => cartItemsVar([...cartItems, productId])}>
+      <Button onClick={() => cartItemsVar([...cartItemsVar(), productId])}>
         Add to Cart
       </Button>
     </div>
@@ -167,8 +166,6 @@ On click, this button updates the value of `cartItemsVar` to append the button's
 
 Here's a `Cart` component that uses the `GET_CART_ITEMS` query and therefore refreshes automatically whenever the value of `cartItemsVar` changes:
 
-<ExpansionPanel title="Expand example">
-
 ```jsx:title=Cart.js
 export const GET_CART_ITEMS = gql`
   query GetCartItems {
@@ -199,7 +196,32 @@ export function Cart() {
 }
 ```
 
-</ExpansionPanel>
+Alternatively, you can read directly from a reactive variable using the `useReactiveVar` hook introduced in Apollo Client 3.2.0:
+
+```jsx:title=Cart.js
+import { useReactiveVar } from '@apollo/client';
+
+export function Cart() {
+  const cartItems = useReactiveVar(cartItemsVar);
+
+  return (
+    <div class="cart">
+      <Header>My Cart</Header>
+      {cartItems.length === 0 ? (
+        <p>No items in your cart</p>
+      ) : (
+        <Fragment>
+          {cartItems.map(productId => (
+            <CartItem key={productId} />
+          ))}
+        </Fragment>
+      )}
+    </div>
+  );
+}
+```
+
+As in the earlier `useQuery` example, whenever the `cartItemsVar` variable is updated, any currently-mounted `Cart` components will rerender. Calling `cartItemsVar()` without `useReactiveVar` will not capture this dependency, so future variable updates will not rerender the component. Both of these approaches are useful in different situations.
 
 ### Storing local state in the cache
 

src/__tests__/__snapshots__/exports.ts.snap

@@ -52,6 +52,7 @@ Array [
   "useLazyQuery",
   "useMutation",
   "useQuery",
+  "useReactiveVar",
   "useSubscription",
 ]
 `;
@@ -216,6 +217,7 @@ Array [
   "useLazyQuery",
   "useMutation",
   "useQuery",
+  "useReactiveVar",
   "useSubscription",
 ]
 `;
@@ -262,6 +264,7 @@ Array [
   "useLazyQuery",
   "useMutation",
   "useQuery",
+  "useReactiveVar",
   "useSubscription",
 ]
 `;

src/cache/inmemory/__tests__/cache.ts

@@ -3,6 +3,7 @@ import gql, { disableFragmentWarnings } from 'graphql-tag';
 import { stripSymbols } from '../../../utilities/testing/stripSymbols';
 import { cloneDeep } from '../../../utilities/common/cloneDeep';
 import { makeReference, Reference, makeVar, TypedDocumentNode, isReference } from '../../../core';
+import { Cache } from '../../../cache';
 import { InMemoryCache, InMemoryCacheConfig } from '../inMemoryCache';
 
 disableFragmentWarnings();
@@ -2495,6 +2496,105 @@ describe("ReactiveVar and makeVar", () => {
       },
     });
   });
+
+  it("should broadcast only once for multiple reads of same variable", () => {
+    const nameVar = makeVar("Ben");
+    const cache = new InMemoryCache({
+      typePolicies: {
+        Query: {
+          fields: {
+            name() {
+              return nameVar();
+            },
+          },
+        },
+      },
+    });
+
+    // TODO This should not be necessary, but cache.readQuery currently
+    // returns null if we read a query before writing any queries.
+    cache.restore({
+      ROOT_QUERY: {}
+    });
+
+    const broadcast = cache["broadcastWatches"];
+    let broadcastCount = 0;
+    cache["broadcastWatches"] = function () {
+      ++broadcastCount;
+      return broadcast.apply(this, arguments);
+    };
+
+    const query = gql`
+      query {
+        name1: name
+        name2: name
+      }
+    `;
+
+    const watchDiffs: Cache.DiffResult<any>[] = [];
+    cache.watch({
+      query,
+      optimistic: true,
+      callback(diff) {
+        watchDiffs.push(diff);
+      },
+    });
+
+    const benResult = cache.readQuery({ query });
+    expect(benResult).toEqual({
+      name1: "Ben",
+      name2: "Ben",
+    });
+
+    expect(watchDiffs).toEqual([]);
+
+    expect(broadcastCount).toBe(0);
+    nameVar("Jenn");
+    expect(broadcastCount).toBe(1);
+
+    const jennResult = cache.readQuery({ query });
+    expect(jennResult).toEqual({
+      name1: "Jenn",
+      name2: "Jenn",
+    });
+
+    expect(watchDiffs).toEqual([
+      {
+        complete: true,
+        result: {
+          name1: "Jenn",
+          name2: "Jenn",
+        },
+      },
+    ]);
+
+    expect(broadcastCount).toBe(1);
+    nameVar("Hugh");
+    expect(broadcastCount).toBe(2);
+
+    const hughResult = cache.readQuery({ query });
+    expect(hughResult).toEqual({
+      name1: "Hugh",
+      name2: "Hugh",
+    });
+
+    expect(watchDiffs).toEqual([
+      {
+        complete: true,
+        result: {
+          name1: "Jenn",
+          name2: "Jenn",
+        },
+      },
+      {
+        complete: true,
+        result: {
+          name1: "Hugh",
+          name2: "Hugh",
+        },
+      },
+    ]);
+  });
 });
 
 describe('TypedDocumentNode<Data, Variables>', () => {

src/cache/inmemory/reactiveVars.ts

@@ -3,25 +3,47 @@ import { dep } from "optimism";
 import { InMemoryCache } from "./inMemoryCache";
 import { ApolloCache } from '../../core';
 
-export type ReactiveVar<T> = (newValue?: T) => T;
+export interface ReactiveVar<T> {
+  (newValue?: T): T;
+  onNextChange(listener: ReactiveListener<T>): () => void;
+}
+
+export type ReactiveListener<T> = (value: T) => any;
 
 const varDep = dep<ReactiveVar<any>>();
 
 // Contextual Slot that acquires its value when custom read functions are
 // called in Policies#readField.
 export const cacheSlot = new Slot<ApolloCache<any>>();
 
+// A listener function could in theory cause another listener to be added
+// to the set while we're iterating over it, so it's important to commit
+// to the original elements of the set before we begin iterating. See
+// iterateObserversSafely for another example of this pattern.
+function consumeAndIterate<T>(set: Set<T>, callback: (item: T) => any) {
+  const items: T[] = [];
+  set.forEach(item => items.push(item));
+  set.clear();
+  items.forEach(callback);
+}
+
 export function makeVar<T>(value: T): ReactiveVar<T> {
   const caches = new Set<ApolloCache<any>>();
+  const listeners = new Set<ReactiveListener<T>>();
 
-  return function rv(newValue) {
+  const rv: ReactiveVar<T> = function (newValue) {
     if (arguments.length > 0) {
       if (value !== newValue) {
         value = newValue!;
+        // First, invalidate any fields with custom read functions that
+        // consumed this variable, so query results involving those fields
+        // will be recomputed the next time we read them.
         varDep.dirty(rv);
-        // Trigger broadcast for any caches that were previously involved
-        // in reading this variable.
+        // Next, broadcast changes to any caches that have previously read
+        // from this variable.
         caches.forEach(broadcast);
+        // Finally, notify any listeners added via rv.onNextChange.
+        consumeAndIterate(listeners, listener => listener(value));
       }
     } else {
       // When reading from the variable, obtain the current cache from
@@ -34,12 +56,21 @@ export function makeVar<T>(value: T): ReactiveVar<T> {
 
     return value;
   };
+
+  rv.onNextChange = listener => {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  };
+
+  return rv;
 }
 
 type Broadcastable = ApolloCache<any> & {
   // This method is protected in InMemoryCache, which we are ignoring, but
   // we still want some semblance of type safety when we call it.
-  broadcastWatches: InMemoryCache["broadcastWatches"];
+  broadcastWatches?: InMemoryCache["broadcastWatches"];
 };
 
 function broadcast(cache: Broadcastable) {