Merge pull request #8188 from apollographql/allow-opting-out-of-canon…

…ization

Allow selectively opting out of cache result canonization.

docs/source/api/cache/InMemoryCache.mdx

@@ -129,6 +129,21 @@ By specifying the ID of another cached object, you can query arbitrary cached da
 </td>
 </tr>
 
+<tr>
+<td>
+
+###### `canonizeResults`
+
+`Boolean`
+</td>
+<td>
+
+If `true`, result objects read from the cache will be _canonized_, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results.
+
+The default value is `true`.
+</td>
+</tr>
+
 </tbody>
 </table>
 
@@ -235,6 +250,21 @@ The default value is `true`.
 </td>
 </tr>
 
+<tr>
+<td>
+
+###### `overwrite`
+
+`Boolean`
+</td>
+<td>
+
+If `true`, ignore existing cache data when calling `merge` functions, allowing incoming data to replace existing data, without warnings about data loss.
+
+The default value is `false`.
+</td>
+</tr>
+
 </tbody>
 </table>
 
@@ -382,6 +412,22 @@ A map of any GraphQL variable names and values required by `fragment`.
 </td>
 </tr>
 
+
+<tr>
+<td>
+
+###### `canonizeResults`
+
+`Boolean`
+</td>
+<td>
+
+If `true`, result objects read from the cache will be _canonized_, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results.
+
+The default value is `true`.
+</td>
+</tr>
+
 </tbody>
 </table>
 
@@ -505,6 +551,21 @@ The default value is `true`.
 </td>
 </tr>
 
+<tr>
+<td>
+
+###### `overwrite`
+
+`Boolean`
+</td>
+<td>
+
+If `true`, ignore existing cache data when calling `merge` functions, allowing incoming data to replace existing data, without warnings about data loss.
+
+The default value is `false`.
+</td>
+</tr>
+
 </tbody>
 </table>
 
@@ -624,7 +685,7 @@ See [Modifier function API](#modifier-function-api) below.
 
 If `true`, also modifies the optimistically cached values for included fields.
 
-The default value is `false`. 
+The default value is `false`.
 </td>
 </tr>
 

src/cache/core/cache.ts

@@ -142,10 +142,8 @@ export abstract class ApolloCache<TSerialized> implements DataProxy {
     optimistic = !!options.optimistic,
   ): QueryType | null {
     return this.read({
+      ...options,
       rootId: options.id || 'ROOT_QUERY',
-      query: options.query,
-      variables: options.variables,
-      returnPartialData: options.returnPartialData,
       optimistic,
     });
   }
@@ -159,10 +157,9 @@ export abstract class ApolloCache<TSerialized> implements DataProxy {
     optimistic = !!options.optimistic,
   ): FragmentType | null {
     return this.read({
+      ...options,
       query: this.getFragmentDoc(options.fragment, options.fragmentName),
-      variables: options.variables,
       rootId: options.id,
-      returnPartialData: options.returnPartialData,
       optimistic,
     });
   }

src/cache/core/types/Cache.ts

@@ -10,6 +10,7 @@ export namespace Cache {
     previousResult?: any;
     optimistic: boolean;
     returnPartialData?: boolean;
+    canonizeResults?: boolean;
   }
 
   export interface WriteOptions<TResult = any, TVariables = any>

src/cache/core/types/DataProxy.ts

@@ -67,6 +67,12 @@ export namespace DataProxy {
      * readQuery method can be omitted. Defaults to false.
      */
     optimistic?: boolean;
+    /**
+     * Whether to canonize cache results before returning them. Canonization
+     * takes some extra time, but it speeds up future deep equality comparisons.
+     * Defaults to true.
+     */
+    canonizeResults?: boolean;
   }
 
   export interface ReadFragmentOptions<TData, TVariables>
@@ -82,6 +88,12 @@ export namespace DataProxy {
      * readQuery method can be omitted. Defaults to false.
      */
     optimistic?: boolean;
+    /**
+     * Whether to canonize cache results before returning them. Canonization
+     * takes some extra time, but it speeds up future deep equality comparisons.
+     * Defaults to true.
+     */
+    canonizeResults?: boolean;
   }
 
   export interface WriteOptions<TData> {

src/cache/inmemory/__tests__/readFromStore.ts

@@ -2010,4 +2010,118 @@ describe('reading from the store', () => {
     expect(result1.abc).toBe(abc);
     expect(result2.abc).toBe(abc);
   });
+
+  it("readQuery can opt out of canonization", function () {
+    let count = 0;
+
+    const cache = new InMemoryCache({
+      typePolicies: {
+        Query: {
+          fields: {
+            count() {
+              return count++;
+            },
+          },
+        },
+      },
+    });
+
+    const canon = cache["storeReader"]["canon"];
+
+    const query = gql`
+      query {
+        count
+      }
+    `;
+
+    function readQuery(canonizeResults: boolean) {
+      return cache.readQuery<{
+        count: number;
+      }>({
+        query,
+        canonizeResults,
+      });
+    }
+
+    const nonCanonicalQueryResult0 = readQuery(false);
+    expect(canon.isCanonical(nonCanonicalQueryResult0)).toBe(false);
+    expect(nonCanonicalQueryResult0).toEqual({ count: 0 });
+
+    const canonicalQueryResult0 = readQuery(true);
+    expect(canon.isCanonical(canonicalQueryResult0)).toBe(true);
+    // The preservation of { count: 0 } proves the result didn't have to be
+    // recomputed, but merely canonized.
+    expect(canonicalQueryResult0).toEqual({ count: 0 });
+
+    cache.evict({
+      fieldName: "count",
+    });
+
+    const canonicalQueryResult1 = readQuery(true);
+    expect(canon.isCanonical(canonicalQueryResult1)).toBe(true);
+    expect(canonicalQueryResult1).toEqual({ count: 1 });
+
+    const nonCanonicalQueryResult1 = readQuery(false);
+    // Since we already read a canonical result, we were able to reuse it when
+    // reading the non-canonical result.
+    expect(nonCanonicalQueryResult1).toBe(canonicalQueryResult1);
+  });
+
+  it("readFragment can opt out of canonization", function () {
+    let count = 0;
+
+    const cache = new InMemoryCache({
+      typePolicies: {
+        Query: {
+          fields: {
+            count() {
+              return count++;
+            },
+          },
+        },
+      },
+    });
+
+    const canon = cache["storeReader"]["canon"];
+
+    const fragment = gql`
+      fragment CountFragment on Query {
+        count
+      }
+    `;
+
+    function readFragment(canonizeResults: boolean) {
+      return cache.readFragment<{
+        count: number;
+      }>({
+        id: "ROOT_QUERY",
+        fragment,
+        canonizeResults,
+      });
+    }
+
+    const canonicalFragmentResult1 = readFragment(true);
+    expect(canon.isCanonical(canonicalFragmentResult1)).toBe(true);
+    expect(canonicalFragmentResult1).toEqual({ count: 0 });
+
+    const nonCanonicalFragmentResult1 = readFragment(false);
+    // Since we already read a canonical result, we were able to reuse it when
+    // reading the non-canonical result.
+    expect(nonCanonicalFragmentResult1).toBe(canonicalFragmentResult1);
+
+    cache.evict({
+      fieldName: "count",
+    });
+
+    const nonCanonicalFragmentResult2 = readFragment(false);
+    expect(readFragment(false)).toBe(nonCanonicalFragmentResult2);
+    expect(canon.isCanonical(nonCanonicalFragmentResult2)).toBe(false);
+    expect(nonCanonicalFragmentResult2).toEqual({ count: 1 });
+    expect(readFragment(false)).toBe(nonCanonicalFragmentResult2);
+
+    const canonicalFragmentResult2 = readFragment(true);
+    expect(readFragment(true)).toBe(canonicalFragmentResult2);
+    expect(canon.isCanonical(canonicalFragmentResult2)).toBe(true);
+    expect(canonicalFragmentResult2).toEqual({ count: 1 });
+  });
 });

src/cache/inmemory/inMemoryCache.ts

@@ -164,10 +164,8 @@ export class InMemoryCache extends ApolloCache<NormalizedCacheObject> {
     } = options;
     try {
       return this.storeReader.diffQueryAgainstStore<T>({
+        ...options,
         store: options.optimistic ? this.optimisticData : this.data,
-        query: options.query,
-        variables: options.variables,
-        rootId: options.rootId,
         config: this.config,
         returnPartialData,
       }).result || null;
@@ -223,11 +221,9 @@ export class InMemoryCache extends ApolloCache<NormalizedCacheObject> {
 
   public diff<T>(options: Cache.DiffOptions): Cache.DiffResult<T> {
     return this.storeReader.diffQueryAgainstStore({
+      ...options,
       store: options.optimistic ? this.optimisticData : this.data,
       rootId: options.id || "ROOT_QUERY",
-      query: options.query,
-      variables: options.variables,
-      returnPartialData: options.returnPartialData,
       config: this.config,
     });
   }

src/cache/inmemory/object-canon.ts

@@ -82,6 +82,10 @@ export class ObjectCanon {
     keys?: SortedKeysInfo;
   }>(canUseWeakMap);
 
+  public isCanonical(value: any): boolean {
+    return isObjectOrArray(value) && this.known.has(value);
+  }
+
   // Make the ObjectCanon assume this value has already been
   // canonicalized.
   private passes = new WeakMap<object, object>();