Automatically filter out dangling references from arrays. (#6454)

This commit implements the proposal for automatic filtering of dangling
references that I described in #6425 (comment).

The filtering functionality demonstrated by #6412 (and updated by #6425)
seems useful enough that we might as well make it the default behavior for
any array-valued field consumed by a selection set. Note: the presence of
field.selectionSet implies the author of the query expects the elements to
be objects (or references) rather than scalar values. A list of scalar values
should not be filtered, since it cannot contain dangling references.

By making .filter(canRead) automatic, we free developers from having to
worry about manually removing any references after evicting entities from
the cache. Instead, those dangling references will simply (appear to)
disappear from cache results, which is almost always the desired behavior.
Fields whose values hold single (non-list) dangling references cannot be
automatically filtered in the same way, but you can always write a custom
read function for the field, and it's somewhat more likely that a refetch will
fix those fields correctly.

In case this automatic filtering is not desired, a custom read function
can be used to override the filtering, since read functions run before
this filtering happens. This commit includes tests demonstrating several
options for replacing/filtering dangling references in non-default ways.

CHANGELOG.md

@@ -63,7 +63,7 @@
     [@danReynolds](https://github.com/danReynolds) in [#6141](https://github.com/apollographql/apollo-client/pull/6141)
     [@benjamn](https://github.com/benjamn) in [#6364](https://github.com/apollographql/apollo-client/pull/6364)
 
-  - Removing an entity object using the `cache.evict` method does not automatically remove dangling references to that entity elsewhere in the cache, since the appropriate removal behavior is inherently application-dependent. Instead, you should define a custom field `read` function for the affected fields. See [#6412](https://github.com/apollographql/apollo-client/pull/6412) for further explanation.
+  - Removing an entity object using the `cache.evict` method does not automatically remove dangling references to that entity elsewhere in the cache, but dangling references will be automatically filtered from lists whenever those lists are read from the cache. You can define a custom field `read` function to customize this behavior. See [#6412](https://github.com/apollographql/apollo-client/pull/6412), [#6425](https://github.com/apollographql/apollo-client/pull/6425), and [#6454](https://github.com/apollographql/apollo-client/pull/6454) for further explanation.
 
 - Cache methods that would normally trigger a broadcast, like `cache.evict`, `cache.writeQuery`, and `cache.writeFragment`, can now be called with a named options object, which supports a `broadcast: boolean` property that can be used to silence the broadcast, for situations where you want to update the cache multiple times without triggering a broadcast each time. <br/>
   [@benjamn](https://github.com/benjamn) in [#6288](https://github.com/apollographql/apollo-client/pull/6288)

package.json

@@ -51,7 +51,7 @@
     {
       "name": "apollo-client",
       "path": "./dist/apollo-client.cjs.min.js",
-      "maxSize": "24.2 kB"
+      "maxSize": "24.25 kB"
     }
   ],
   "peerDependencies": {

src/cache/inmemory/__tests__/readFromStore.ts

@@ -917,6 +917,232 @@ describe('reading from the store', () => {
     });
   });
 
+  it("custom read functions can map/filter dangling references", () => {
+    const cache = new InMemoryCache({
+      typePolicies: {
+        Query: {
+          fields: {
+            ducks(existing: Reference[] = [], { canRead }) {
+              return existing.map(duck => canRead(duck) ? duck : null);
+            },
+            chickens(existing: Reference[] = [], { canRead }) {
+              return existing.map(chicken => canRead(chicken) ? chicken : {});
+            },
+            oxen(existing: Reference[] = [], { canRead }) {
+              return existing.filter(canRead);
+            },
+          },
+        },
+      },
+    });
+
+    cache.writeQuery({
+      query: gql`
+        query {
+          ducks { quacking }
+          chickens { inCoop }
+          oxen { gee haw }
+        }
+      `,
+      data: {
+        ducks: [
+          { __typename: "Duck", id: 1, quacking: true },
+          { __typename: "Duck", id: 2, quacking: false },
+          { __typename: "Duck", id: 3, quacking: false },
+        ],
+        chickens: [
+          { __typename: "Chicken", id: 1, inCoop: true },
+          { __typename: "Chicken", id: 2, inCoop: true },
+          { __typename: "Chicken", id: 3, inCoop: false },
+        ],
+        oxen: [
+          { __typename: "Ox", id: 1, gee: true, haw: false },
+          { __typename: "Ox", id: 2, gee: false, haw: true },
+        ],
+      },
+    });
+
+    expect(cache.extract()).toEqual({
+      "Chicken:1": {
+        __typename: "Chicken",
+        id: 1,
+        inCoop: true,
+      },
+      "Chicken:2": {
+        __typename: "Chicken",
+        id: 2,
+        inCoop: true,
+      },
+      "Chicken:3": {
+        __typename: "Chicken",
+        id: 3,
+        inCoop: false,
+      },
+      "Duck:1": {
+        __typename: "Duck",
+        id: 1,
+        quacking: true,
+      },
+      "Duck:2": {
+        __typename: "Duck",
+        id: 2,
+        quacking: false,
+      },
+      "Duck:3": {
+        __typename: "Duck",
+        id: 3,
+        quacking: false,
+      },
+      "Ox:1": {
+        __typename: "Ox",
+        id: 1,
+        gee: true,
+        haw: false,
+      },
+      "Ox:2": {
+        __typename: "Ox",
+        id: 2,
+        gee: false,
+        haw: true,
+      },
+      ROOT_QUERY: {
+        __typename: "Query",
+        chickens: [
+          { __ref: "Chicken:1" },
+          { __ref: "Chicken:2" },
+          { __ref: "Chicken:3" },
+        ],
+        ducks: [
+          { __ref: "Duck:1" },
+          { __ref: "Duck:2" },
+          { __ref: "Duck:3" },
+        ],
+        oxen: [
+          { __ref: "Ox:1" },
+          { __ref: "Ox:2" },
+        ],
+      },
+    });
+
+    function diffChickens() {
+      return cache.diff({
+        query: gql`query { chickens { id inCoop }}`,
+        optimistic: true,
+      });
+    }
+
+    expect(diffChickens()).toEqual({
+      complete: true,
+      optimistic: false,
+      result: {
+        chickens: [
+          { __typename: "Chicken", id: 1, inCoop: true },
+          { __typename: "Chicken", id: 2, inCoop: true },
+          { __typename: "Chicken", id: 3, inCoop: false },
+        ],
+      }
+    });
+
+    expect(cache.evict({
+      id: cache.identify({
+        __typename: "Chicken",
+        id: 2,
+      }),
+    })).toBe(true);
+
+    expect(diffChickens()).toEqual({
+      complete: false,
+      optimistic: false,
+      missing: [
+        expect.anything(),
+        expect.anything(),
+      ],
+      result: {
+        chickens: [
+          { __typename: "Chicken", id: 1, inCoop: true },
+          {},
+          { __typename: "Chicken", id: 3, inCoop: false },
+        ],
+      },
+    });
+
+    function diffDucks() {
+      return cache.diff({
+        query: gql`query { ducks { id quacking }}`,
+        optimistic: true,
+      });
+    }
+
+    expect(diffDucks()).toEqual({
+      complete: true,
+      optimistic: false,
+      result: {
+        ducks: [
+          { __typename: "Duck", id: 1, quacking: true },
+          { __typename: "Duck", id: 2, quacking: false },
+          { __typename: "Duck", id: 3, quacking: false },
+        ],
+      },
+    });
+
+    expect(cache.evict({
+      id: cache.identify({
+        __typename: "Duck",
+        id: 3,
+      }),
+    })).toBe(true);
+
+    // Returning null as a placeholder in a list is a way to indicate that
+    // a list element has been removed, without causing an incomplete
+    // diff, and without altering the positions of later elements.
+    expect(diffDucks()).toEqual({
+      complete: true,
+      optimistic: false,
+      result: {
+        ducks: [
+          { __typename: "Duck", id: 1, quacking: true },
+          { __typename: "Duck", id: 2, quacking: false },
+          null,
+        ],
+      },
+    });
+
+    function diffOxen() {
+      return cache.diff({
+        query: gql`query { oxen { id gee haw }}`,
+        optimistic: true,
+      });
+    }
+
+    expect(diffOxen()).toEqual({
+      complete: true,
+      optimistic: false,
+      result: {
+        oxen: [
+          { __typename: "Ox", id: 1, gee: true, haw: false },
+          { __typename: "Ox", id: 2, gee: false, haw: true },
+        ],
+      },
+    });
+
+    expect(cache.evict({
+      id: cache.identify({
+        __typename: "Ox",
+        id: 1,
+      }),
+    })).toBe(true);
+
+    expect(diffOxen()).toEqual({
+      complete: true,
+      optimistic: false,
+      result: {
+        oxen: [
+          { __typename: "Ox", id: 2, gee: false, haw: true },
+        ],
+      },
+    });
+  });
+
   it("propagates eviction signals to parent queries", () => {
     const cache = new InMemoryCache({
       typePolicies: {

src/cache/inmemory/readFromStore.ts

@@ -386,6 +386,10 @@ export class StoreReader {
       return childResult.result;
     }
 
+    if (field.selectionSet) {
+      array = array.filter(context.store.canRead);
+    }
+
     array = array.map((item, i) => {
       // null value in array
       if (item === null) {