Implement useFragment hook.

src/__tests__/__snapshots__/exports.ts.snap

@@ -53,6 +53,7 @@ Array [
   "throwServerError",
   "toPromise",
   "useApolloClient",
+  "useFragment",
   "useLazyQuery",
   "useMutation",
   "useQuery",
@@ -235,6 +236,7 @@ Array [
   "parser",
   "resetApolloContext",
   "useApolloClient",
+  "useFragment",
   "useLazyQuery",
   "useMutation",
   "useQuery",
@@ -273,6 +275,7 @@ Array [
 exports[`exports of public entry points @apollo/client/react/hooks 1`] = `
 Array [
   "useApolloClient",
+  "useFragment",
   "useLazyQuery",
   "useMutation",
   "useQuery",

src/cache/core/types/Cache.ts

@@ -28,7 +28,7 @@ export namespace Cache {
   export interface DiffOptions<
     TData = any,
     TVariables = any,
-  > extends ReadOptions<TVariables, TData> {
+  > extends Omit<ReadOptions<TVariables, TData>, "rootId"> {
     // The DiffOptions interface is currently just an alias for
     // ReadOptions, though DiffOptions used to be responsible for
     // declaring the returnPartialData option.
@@ -37,7 +37,7 @@ export namespace Cache {
   export interface WatchOptions<
     TData = any,
     TVariables = any,
-  > extends ReadOptions<TVariables, TData> {
+  > extends DiffOptions<TData, TVariables> {
     watcher?: object;
     immediate?: boolean;
     callback: WatchCallback<TData>;

src/cache/inmemory/inMemoryCache.ts

@@ -141,7 +141,7 @@ export class InMemoryCache extends ApolloCache<NormalizedCacheObject> {
         // currently using a data store that can track cache dependencies.
         const store = c.optimistic ? this.optimisticData : this.data;
         if (supportsResultCaching(store)) {
-          const { optimistic, rootId, variables } = c;
+          const { optimistic, id, variables } = c;
           return store.makeCacheKey(
             c.query,
             // Different watches can have the same query, optimistic
@@ -151,7 +151,7 @@ export class InMemoryCache extends ApolloCache<NormalizedCacheObject> {
             // separation is to include c.callback in the cache key for
             // maybeBroadcastWatch calls. See issue #5733.
             c.callback,
-            canonicalStringify({ optimistic, rootId, variables }),
+            canonicalStringify({ optimistic, id, variables }),
           );
         }
       }
@@ -532,11 +532,7 @@ export class InMemoryCache extends ApolloCache<NormalizedCacheObject> {
     options?: BroadcastOptions,
   ) {
     const { lastDiff } = c;
-    const diff = this.diff<any>({
-      query: c.query,
-      variables: c.variables,
-      optimistic: c.optimistic,
-    });
+    const diff = this.diff<any>(c);
 
     if (options) {
       if (c.optimistic &&

src/react/hooks/index.ts

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

src/react/hooks/useFragment.ts

@@ -0,0 +1,70 @@
+import { useEffect, useState } from "react";
+import { equal } from "@wry/equality";
+
+import { Cache, MissingFieldError, Reference, StoreObject } from "../../cache";
+import { useApolloClient } from "./useApolloClient";
+
+export interface UseFragmentOptions<TData, TVars>
+extends Omit<
+  Cache.DiffOptions<TData, TVars>,
+  | "id"
+  | "query"
+  | "optimistic"
+>, Omit<
+  Cache.ReadFragmentOptions<TData, TVars>,
+  | "id"
+> {
+  from: StoreObject | Reference | string;
+  // Override this field to make it optional (default: true).
+  optimistic?: boolean;
+}
+
+export interface UseFragmentResult<TData> {
+  data: TData | undefined,
+  complete: boolean,
+  missing: MissingFieldError[] | undefined;
+}
+
+export function useFragment<TData, TVars>(
+  options: UseFragmentOptions<TData, TVars>,
+): UseFragmentResult<TData> {
+  const { cache } = useApolloClient();
+
+  const {
+    fragment,
+    fragmentName,
+    from,
+    optimistic = true,
+    ...rest
+  } = options;
+
+  const diffOptions: Cache.DiffOptions<TData, TVars> = {
+    ...rest,
+    id: typeof from === "string" ? from : cache.identify(from),
+    query: cache["getFragmentDoc"](fragment, fragmentName),
+    optimistic,
+  };
+
+  const preDiff = cache.diff<TData>(diffOptions);
+  const setDiff = useState(preDiff)[1];
+
+  useEffect(() => {
+    let immediate = true;
+    return cache.watch({
+      ...diffOptions,
+      immediate,
+      callback(newDiff) {
+        if (!immediate || !equal(newDiff, preDiff)) {
+          setDiff(newDiff);
+        }
+        immediate = false;
+      },
+    });
+  }, [preDiff]);
+
+  return {
+    data: preDiff.result,
+    complete: !!preDiff.complete,
+    missing: preDiff.missing,
+  };
+}