Allow @directive and $variable strings in field policy keyArgs: ["arg", "@dir", "$var"] arrays

[benjamn]

This PR provides a much better solution than the three I proposed in #8659 (comment) to the problem of including more than just arguments in the keyArgs: [...] array notation in field policies.

While nothing is changing in the way existing keyArgs: [...] configurations work, this PR will allow you to refer to directives like the @connection directive, or query variables, in the same array where you usually specify your keyArgs:

new InMemoryCache({
  typePolicies: {
    Query: {
      fields: {
        feed: {
          // Note: if you're bothered by the use of keyArgs for items that are not
          // field arguments (that is, directives and variables), keep reading!
          keyArgs: ["type", "@connection", ["key"], "$var"],
        },
      },
    },
  },
})

Information about directives is included by default in the field key if you don't provide a keyArgs: [...] configuration, but is lost when switching to keyArgs: [...], which can be surprising. You can alternatively provide a keyArgs(args, context) {...} function to return any key you like, taking context.field.directives into account, but that's a lot more involved and error-prone.

The cache configuration shown above allows queries to use @connection(key: ...) to provide additional identifying information for the Query.feed field, which is especially useful when more than one Query.feed query is using the same arguments for that field, but you want to keep the query results separate in the cache:

query FeedQuery($key: String = "main") {
  feed(type: $feedType) @connection(key: $key) {
    id
    author { name }
    text
  }
}

Within the cache, you'll now see field keys like the following:

expect(cache.extract()).toEqual({
  ROOT_QUERY: {
    __typename: "Query",
    'feed:{"type":"public","@connection":{"key":"main"}}': { __typename, id, author, text },
  },
})

While the @connection directive is a common and widely recommended way to solve this problem, I'm proud to say this implementation does not hard-code support for the @connection directive. You can name the directive anything you want, and it will serve the same purpose!

The "@connection", ["key"] syntax is a way to select only the key argument from the @connection(key: ..., ignored: ...) directive in the query, which in this case is determined by the $key variable, which defaults to "main". If you leave out the ["key"] part, all arguments passed to the directive will be included. I recommend locking things down to just the arguments you're expecting.

The $var syntax seems useful when you want the field's storage key to depend on a variable that's not otherwise passed to that field, perhaps because your server expects the variable to be passed as an argument to a different field than the one you're trying to configure.

Both @directive and $variable notations are unambiguous with actual arguments (and with each other), because field argument names can only start with an alphabetical letter or an underscore, according to the spec here and here.

The same tolerance we introduced for optional keyArgs arguments in #7109 applies to directives and variables, too: when there's no @connection directive on the Query.feed field in the query, or no $var variable provided by the query (true in this case), those details will simply be omitted from the field key, rather than triggering an error. Note: keyFields: [...] still throws an exception for missing primary keys.

One aesthetic problem with this approach is that the keyArgs configuration may seem misnamed, since it's handling more than just field arguments. In case that bothers you like it bothers me, I introduced a more general field key configuration that's synonymous in every way with keyArgs (except that key takes precedence if both are provided). I think this new name is the "right" name, since the goal of keyArgs/key is to come up with a uniquely identifying storage key for the field, not necessarily limited to the provided arguments. This insight allows us to avoid introducing new configurations like keyDirectives or keyVariables to accompany keyArgs, as I considered yesterday in #8659 (comment). Update: I reverted this part, since key didn't justify itself IMHO: #8659 (comment)

Issues potentially resolved by this PR:

• @connection directive ignored when used in conjunction with keyArgs #8659
• getStoreKeyName does not honor @connection if field is using defaults for all args (has no args) #8619
• Query silently fails with multiple paginated queries with differing child fields #8620
  • explanation

[benjamn]

We used to (ab)use computeKeyObject for both keyFields: [...] and keyArgs: [...], but this PR pushed me over the edge to separating them into two separate functions: computeKeyFieldsObject and computeFieldKeyObject.

[benjamn]

Some TODOs to consider.

[hwillson]

Thanks for working on this @benjamn! Adding some docs to https://www.apollographql.com/docs/react/caching/advanced-topics/ would be super useful (but we can always track this separately if you'd like to get this PR in place sooner than later to cut a new 3.5 beta).

[benjamn]

@StephenBarlow Can you take a look at the changes from 573a8ea and let me know what you want to do with the other section about @connection directive? We should probably consolidate or at least link them together?

Note: I will probably merge this PR soon, and welcome feedback/edits in a follow-up PR.

[dir]

Oh hey, that's me