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.

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.

)

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.