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/reactiveVars.ts

@@ -3,7 +3,12 @@ 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>>();
 
@@ -12,34 +17,48 @@ const varDep = dep<ReactiveVar<any>>();
 export const cacheSlot = new Slot<ApolloCache<any>>();
 
 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!;
         varDep.dirty(rv);
-        // Trigger broadcast for any caches that were previously involved
-        // in reading this variable.
-        caches.forEach(broadcast);
+        listeners.forEach(listener => {
+          // Listener functions listen only for the next update, not all
+          // future updates.
+          listeners.delete(listener);
+          listener(value);
+        });
       }
     } else {
       // When reading from the variable, obtain the current cache from
       // context via cacheSlot. This isn't entirely foolproof, but it's
       // the same system that powers varDep.
       const cache = cacheSlot.getValue();
-      if (cache) caches.add(cache);
+      if (cache && (cache as any).broadcastWatches) {
+        listeners.add(() => broadcast(cache));
+      }
       varDep(rv);
     }
 
     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) {

src/react/hooks/__tests__/useReactiveVar.test.tsx

@@ -0,0 +1,183 @@
+import React from "react";
+import { render, wait, act } from "@testing-library/react";
+
+import { itAsync } from "../../../testing";
+import { makeVar } from "../../../core";
+import { useReactiveVar } from "../useReactiveVar";
+
+describe("useReactiveVar Hook", () => {
+  itAsync("works with one component", (resolve, reject) => {
+    const counterVar = makeVar(0);
+    let renderCount = 0;
+
+    function Component() {
+      const count = useReactiveVar(counterVar);
+
+      switch (++renderCount) {
+        case 1:
+          expect(count).toBe(0);
+          act(() => {
+            counterVar(count + 1);
+          });
+          break;
+        case 2:
+          expect(count).toBe(1);
+          act(() => {
+            counterVar(counterVar() + 2);
+          });
+          break;
+        case 3:
+          expect(count).toBe(3);
+          break;
+        default:
+          reject(`too many (${renderCount}) renders`);
+      }
+
+      return null;
+    }
+
+    render(<Component/>);
+
+    return wait(() => {
+      expect(renderCount).toBe(3);
+      expect(counterVar()).toBe(3);
+    }).then(resolve, reject);
+  });
+
+  itAsync("works when two components share a variable", async (resolve, reject) => {
+    const counterVar = makeVar(0);
+
+    let parentRenderCount = 0;
+    function Parent() {
+      const count = useReactiveVar(counterVar);
+
+      switch (++parentRenderCount) {
+        case 1:
+          expect(count).toBe(0);
+          break;
+        case 2:
+          expect(count).toBe(1);
+          break;
+        case 3:
+          expect(count).toBe(11);
+          break;
+        default:
+          reject(`too many (${parentRenderCount}) parent renders`);
+      }
+
+      return <Child/>;
+    }
+
+    let childRenderCount = 0;
+    function Child() {
+      const count = useReactiveVar(counterVar);
+
+      switch (++childRenderCount) {
+        case 1:
+          expect(count).toBe(0);
+          break;
+        case 2:
+          expect(count).toBe(1);
+          break;
+        case 3:
+          expect(count).toBe(11);
+          break;
+        default:
+          reject(`too many (${childRenderCount}) child renders`);
+      }
+
+      return null;
+    }
+
+    render(<Parent/>);
+
+    await wait(() => {
+      expect(parentRenderCount).toBe(1);
+      expect(childRenderCount).toBe(1);
+    });
+
+    expect(counterVar()).toBe(0);
+    act(() => {
+      counterVar(1);
+    });
+
+    await wait(() => {
+      expect(parentRenderCount).toBe(2);
+      expect(childRenderCount).toBe(2);
+    });
+
+    expect(counterVar()).toBe(1);
+    act(() => {
+      counterVar(counterVar() + 10);
+    });
+
+    await wait(() => {
+      expect(parentRenderCount).toBe(3);
+      expect(childRenderCount).toBe(3);
+    });
+
+    expect(counterVar()).toBe(11);
+
+    resolve();
+  });
+
+  itAsync("does not update if component has been unmounted", (resolve, reject) => {
+    const counterVar = makeVar(0);
+    let renderCount = 0;
+    let attemptedUpdateAfterUnmount = false;
+
+    function Component() {
+      const count = useReactiveVar(counterVar);
+
+      switch (++renderCount) {
+        case 1:
+          expect(count).toBe(0);
+          act(() => {
+            counterVar(count + 1);
+          });
+          break;
+        case 2:
+          expect(count).toBe(1);
+          act(() => {
+            counterVar(counterVar() + 2);
+          });
+          break;
+        case 3:
+          expect(count).toBe(3);
+          setTimeout(() => {
+            unmount();
+            setTimeout(() => {
+              counterVar(counterVar() * 2);
+              attemptedUpdateAfterUnmount = true;
+            }, 10);
+          }, 10);
+          break;
+        default:
+          reject(`too many (${renderCount}) renders`);
+      }
+
+      return null;
+    }
+
+    // To detect updates of unmounted components, we have to monkey-patch
+    // the console.error method.
+    const consoleErrorArgs: any[][] = [];
+    const { error } = console;
+    console.error = function (...args: any[]) {
+      consoleErrorArgs.push(args);
+      return error.apply(this, args);
+    };
+
+    const { unmount } = render(<Component/>);
+
+    return wait(() => {
+      expect(attemptedUpdateAfterUnmount).toBe(true);
+    }).then(() => {
+      expect(renderCount).toBe(3);
+      expect(counterVar()).toBe(6);
+      expect(consoleErrorArgs).toEqual([]);
+    }).finally(() => {
+      console.error = error;
+    }).then(resolve, reject);
+  });
+});

src/react/hooks/index.ts

@@ -3,3 +3,4 @@ export * from './useLazyQuery';
 export * from './useMutation';
 export * from './useQuery';
 export * from './useSubscription';
+export * from './useReactiveVar';

src/react/hooks/useReactiveVar.ts

@@ -0,0 +1,15 @@
+import { useState, useEffect } from 'react';
+import { ReactiveVar } from '../../core';
+
+export function useReactiveVar<T>(rv: ReactiveVar<T>): T {
+  const value = rv();
+  // We don't actually care what useState thinks the value of the variable
+  // is, so we take only the update function from the returned array.
+  const mute = rv.onNextChange(useState(value)[1]);
+  // Once the component is unmounted, ignore future updates. Note that the
+  // useEffect function returns the mute function without calling it,
+  // allowing it to be called when the component unmounts. This is
+  // equivalent to useEffect(() => () => mute(), []), but shorter.
+  useEffect(() => mute, []);
+  return value;
+}