[RFC] Allow directives on variable definitions

[mjmahone]

Redo of #486. Will wait for discussion at the next WG meeting.

This is currently implemented under a feature flag in graphql-js: https://github.com/graphql/graphql-js/blob/master/src/language/parser.js#L128

Now that directives are gaining more widespread adoption, there have been multiple use cases I've seen where people want directives on variable definitions, but have to resort instead to adding them on the query definition with arguments.

An example of this: some query variable may only make sense for the client. As an example, if you have a local cache and you need a variable to differentiate different runs of the same query against that cahce. Or if you have a query being run with a different set of fragments, but the client code initiating that query needs to conform to the same API. The way to describe this might be:

query SomeQuery(
  $client_var: Boolean = false @client_only
  $server_var: Boolean = true
) { ... }

The client could strip $client_var before persisting it to the server as

query SomeQuery(
  $server_var: Boolean = true
) { ... }

With our current set of directive locations, this would have to be implemented on the query definition like:

query SomeQuery(
  $client_var: Boolean = false
  $server_var: Boolean = true
) @client_only(variables: ['client_var']) { ... }

This version has a lot more validation that needs to happen (for instance, that the string argument provided is actually a variable defined on the query), and is more disconnected from the intention: to strip the client-only variable, you now have to visit all of the query's variables, rather than just stripping the node that explicitly has the directive on it.

[leebyron]

🙌