Replace options.isReference(ref, true) with options.canRead(ref).

[benjamn]

After thinking more about PR #6413, which has been merged but not yet released, I think it makes more sense to have a separate helper function for read, merge, and modify functions that determines if a given object can be read with options.readField.

It was tempting to call this helper function options.isReadable, but options.canRead is shorter and less easily confused with options.isReference (which matters for auto-completion and dyslexic programmers), so options.canRead is what I settled on.

This new helper makes it easy to filter out dangling references from lists of data correctly, without having to know if the list elements are normalized Reference objects, or non-normalized StoreObjects:

new InMemoryCache({
  typePolicies: {
    Person: {
      fields: {
        friends(existing, { canRead }) {
          return existing ? existing.filter(canRead) : [];
        },
      },
    },
  },
})

Using isReference(friend, true) here would have worked only if isReference(friend) was true, whereas canRead(friend) also returns true when friend is a non-Reference object with readable fields, which can happen if the Friend type has no ID and/or keyFields: false.

Now that we have options.canRead and options.readField, I think the use cases for options.isReference are probably pretty scarce, but I don't want to yank isReference away from folks who have been using it in the betas/RCs.

Please let us know if you have a specific use case for options.isReference that is not covered by options.canRead, so we can decide how much documentation to give the various helpers.

[benjamn]

This seems like a clear improvement, to me.

[benjamn]

Intentionally allowing canRead(null) to return true, since null is a valid placeholder value in GraphQL lists.

[benjamn]

If we wanted to do this filtering automatically, I think this is the only change we need:

commit 6fe8075f53ae33ce28a0aecc1b2e888747b2d166
Author: Ben Newman <ben@benjamn.com>
Date:   Wed Jun 10 15:04:55 2020 -0400

    Automatically filter out dangling references from arrays.

diff --git a/src/cache/inmemory/readFromStore.ts b/src/cache/inmemory/readFromStore.ts
index 4143f72d..a0a0687b 100644
--- a/src/cache/inmemory/readFromStore.ts
+++ b/src/cache/inmemory/readFromStore.ts
@@ -377,40 +377,44 @@ export class StoreReader {
 
   // Uncached version of executeSubSelectedArray.
   private execSubSelectedArrayImpl({
     field,
     array,
     context,
   }: ExecSubSelectedArrayOptions): ExecResult {
     let missing: MissingFieldError[] | undefined;
 
     function handleMissing<T>(childResult: ExecResult<T>, i: number): T {
       if (childResult.missing) {
         missing = missing || [];
         missing.push(...childResult.missing);
       }
 
       invariant(context.path.pop() === i);
 
       return childResult.result;
     }
 
+    if (field.selectionSet) {
+      array = array.filter(context.store.canRead);
+    }
+
     array = array.map((item, i) => {
       // null value in array
       if (item === null) {
         return null;
       }
 
       context.path.push(i);
 
       // This is a nested array, recurse
       if (Array.isArray(item)) {
         return handleMissing(this.executeSubSelectedArray({
           field,
           array: item,
           context,
         }), i);
       }
 
       // This is an object, run the selection set on it
       if (field.selectionSet) {
         return handleMissing(this.executeSelectionSet({

With this change, you would not need to define a read function for Person.friends in the example above (except to get the default []).

[hwillson]

Looks great @benjamn! Doing the filtering automatically definitely looks tempting ...

[jcreighton]

I love how much clearer this is!