Bring back heuristic fragment matching, with a twist.

[benjamn]

Easily the biggest breaking change for fragment matching in Apollo Client 3.0 was the removal of the FragmentMatcher abstraction (#5073), along with its subclasses HeuristicFragmentMatcher and IntrospectionFragmentmatcher (#5684), which were replaced by the declarative possibleTypes configuration.

The HeuristicFragmentMatcher was so named because it attempted to perform fragment matching without any actual knowledge of supertype/subtype relationships in your schema (for example, abstract interfaces implemented by concrete object subtypes, or unions with multiple alternative member types), checking instead whether all the fields of a given fragment were present in the result object, which is often a relatively strong signal that the fragment probably matched.

The HeuristicFragmentMatcher could be fooled by field aliases and accidental sharing of field names between different fragments, but it was also relatively resilient to adding new subtypes on the server, because heuristic matching doesn't care what the true subtypes of a supertype are, so what's one more?

Another big drawback of the HeuristicFragmentMatcher was that it applied the same fuzzy logic to reading from the cache, where the heuristic makes a lot less sense. If an individual query result that you're writing into the cache has all the keys you'd expect if a certain fragment matched, that's a pretty good sign that the fragment matched. But when you have a lot of data in your cache, from lots of different queries, it's not as meaningful to observe that all the fields required by some fragment you're reading are present in an object, since they might be there just because they've been written into the cache by other queries over time, not because the fragment actually matches the __typename of the object.

In moving to the more exact possibleTypes system, we gave up both the benefits and the drawbacks of the HeuristicFragmentMatcher, replacing it with something functionally similar to the IntrospectionFragmentmatcher, but with a much simpler configuration API.

As #5750 demonstrates, the exactness of the possibleTypes system makes it challenging for existing clients to adapt when a new subtype is added on the server. Is there any way to make this system more flexible, like the HeuristicFragmentMatcher, but without the drawbacks? I believe so!

This PR improves the possibleTypes API by allowing "fuzzy" subtype strings, which are interpreted as regular expressions for type names, rather than as actual __typename strings. If a fuzzy subtype matches the __typename of an object, fragments on supertypes of that fuzzy subtype are allowed to match the object—provided the result also has all the keys
required by the fragment.

In other words, if you previously configured the following possibleTypes:

new InMemoryCache({
  possibleTypes: {
    Character: ["Jedi", "Droid"],
    Test: ["PassingTest", "FailingTest", "SkippedTest"],
    Snake: ["Viper", "Python"],
  },
})

and you wanted to relax the Test supertype slightly, you could opt into fuzzy/heuristic matching by using a regular expression, while still enforcing a certain suffix:

new InMemoryCache({
  possibleTypes: {
    Character: ["Jedi", "Droid"],
    Test: ["PassingTest", "FailingTest", ".*Test"],
    Snake: ["Viper", "Python"],
  },
})

Since the ".*Test" string is not a valid type name, it is interpreted as the regular expression new RegExp(".*Test"). In order to count as a match, the regular expression must match the entire __typename string, and the match will only be honored if all the fragment's fields are actually present in the result object. Because PassingTest and FailingTest are still specified explicitly, they will continue to match immediately, without any fuzzy logic, but an object with __typename equal to SkippedTest or WishfulTest would now have a chance of qualifying as a Test for the purposes of fragment matching.

Likewise, if you added Python: ["^[A-Z].*Python"] to the possibleTypes list above, a fragment SnakeFragment on Snake could match an object with a __typename of ReticulatedPython, provided that object has all the necessary fragment fields.

The key advantages of this new system compared to the HeuristicFragmentMatcher are that (1) you can specify fuzzy subtypes for specific supertypes (rather than applying heuristic matching for all types by default), and (2) that it "learns" about fuzzy subtypes while writing (where the heuristic tends to work well), and then merely uses those inferred supertype/subtype relationships when reading, so there is no need to perform heuristic matching while reading. This is the "twist" mentioned in the title of this PR. When one of these inferences happens, you'll see a warning in the console (in development).

Unlike the old HeuristicFragmentMatcher, which provided the default behavior for all fragment matching, you do have to opt into fuzzy matching with possibleTypes, but it can be a useful strategy for preparing your clients for upcoming server changes, or for relaxing the rules for a particular supertype, in cases when you anticipate the subtypes may soon change on the server.

[hwillson]

Incredible @benjamn - this looks awesome!