Warn when clobbering non-normalized data in the cache.

[benjamn]

This is a revival of PR #5833, which has accumulated too many merge conflicts over the last few months to be worth rebasing.

One consequence of #5603 is that replacing non-normalized data in the cache can result in loss of useful data, which is preferable to mistakenly merging unrelated objects, but not ideal.

In almost every case, the right solution is to make sure the data can be normalized, or (if that isn't possible) to define a custom merge function for the field in question, within the parent type policy.

It turns out we can give a very detailed warning about such situations in development, and that's what this commit does. For example:

Cache data may be lost when replacing the d field of a Query object.

To address this problem (which is not a bug in Apollo Client), either ensure all
objects of type D have IDs, or define a custom merge function for the Query.d
field, so InMemoryCache can safely merge these objects:

  existing: {"__typename":"D","e":4}
  incoming: {"__typename":"D","h":{"__typename":"H","i":7}}

For more information about these options, please refer to the documentation:

  * Ensuring entity objects have IDs: https://go.apollo.dev/c/generating-unique-identifiers
  * Defining custom merge functions: https://go.apollo.dev/c/merging-non-normalized-objects

Looking at the output for our test suite, every warning seems legitimate and worth fixing. I will resolve the warnings in subsequent commits.

[benjamn]

Since this call is restricted to development, production minifiers should be able to prune virtually all of the code introduced by this PR.

[benjamn]

Since this is a fairly verbose warning, I wanted to make sure it's displayed at most once per Type.field.

[glasser]

Does this check make sense when existing is an Array? It seems (though it's very likely I'm missing something) that this implies that this warning is skipped whenever incoming is at least as long as existing, which seems wrong because as said below arrays always need a custom merge function?

[jefbarn]

@benjamn Is there a way to disable this warning for all array types? My API will always return merged results and I don't need a warning every time I add an item to an array. typePolicies is not usable because we're talking dozens of types and hundreds of fields.

[KenneyE]

I'm running into a similar issue. I have an unregisterFromClass mutation that returns a full list of registeredClasses, which should replace whatever is in the cache. After unregistering from a single class, I receive this warning:

Cache data may be lost when replacing the registeredClasses field of a User object.

To address this problem (which is not a bug in Apollo Client), define a custom merge function for the User.registeredClasses field, so InMemoryCache can safely merge these objects:

  existing: [{"__ref":"ClassRegistration:334729"}]
  incoming: []

It appears everything is properly normalized. Existing and incoming are both correct. It seems like no warning is needed in this case.

[benjamn]

@KenneyE You're right that no data about the ClassRegistration object will be lost by removing the reference from that array, but the presence of the reference in the array is a kind of information, too, which the cache can't assume is safe to discard.

However, since you know that this is fine/expected, you can silence the warning by providing a field policy like this:

new InMemoryCache({
  typePolicies: {
    User: {
      fields: {
        registeredClasses: {
          merge: false,
        },
      },
    },
  },
})

The merge: false shorthand is short for merge(_, incoming) { return incoming }, introduced in @apollo/client@3.1.0 by PR #6714.

[benjamn]

@jefbarn There's not a good way to bulk-disable the warnings right now (except to use merge: false to keep things relatively short). We are currently considering ways to allow dynamic/lazy field policy generation, based on the __typename and field name, which might allow you to use less code to specify a bunch of similar field policies.

In your case, if the behavior is triggered by the type of the field being an array, you'd need to be able to determine the schema type from the __typename and field name, which isn't something the client automatically knows, but maybe you could come up with a naming convention, or extract a list of types/fields at build time.

[KenneyE]

Thanks @benjamn! I was hoping to avoid having to add that for every array field, but it's a fair trade off. Appreciate the response.

[benjamn]

I'm pretty excited about #7070, which makes it easier to configure merge: true (or any other merge behavior) on a type-by-type basis, rather than a field-by-field basis. There's still no general solution for arrays, but #7070 should make working with mergeable object types a lot easier.