docs: variable inlining feature

[obmarg]

Why are we making this change?

Cynic now supports inlining variables as a first class feature.

What effects does this change have?

Adds an example and documentation for this feature

TODO:

• Docs
• Example
• Once feat: expose more helpers on QueryBuilder etc. #1008 is merged avoid using OperationBuilder directly in this

[Bobrokus]

Why not implement it directly to QueryVariables without having to derive it?

[obmarg]

I tried that and it had some downsides:

1. It added extra trait bound requirements if you're using generic parameters with QueryVariables.
2. Adding a function to QueryVariables is sort of a breaking change, and I'd rather avoid that (wouldn't break most users, but it's still not ideal)
3. I suspect the generics that to_input_literal will generate a reasonable amount of serde code for the compiler to process. This feature seems rather niche and I'm not expecting many people to need it so I'd rather only people who opt in pay that price.
4. I used dynamic dispatch to implement this, so QueryVariableLiterals now needs to be object safe. If I put this functionality on QueryVariables then that would need to be object safe. I'd rather not add that constraint for this niche feature.

[netlify]

✅ Deploy Preview for cynic-querygen-web canceled.

Name	Link
🔨 Latest commit	51ddab8
🔍 Latest deploy log	https://app.netlify.com/sites/cynic-querygen-web/deploys/66c8e525874f9d00080d0e59

[Bobrokus]

Understand. I'm still really surprised you even took the effort. This would work well with some derive persistence system for query-gen, where you can add additional derives to the generated structs. That would be awesome. I'm sure more people could use this.

[Bobrokus]

Btw why not use generics instead of dyn?

[obmarg]

Using generics would have meant one of:

1. Adding another generic parameter onto almost every defintion in here: https://github.com/obmarg/cynic/blob/main/cynic/src/queries/builders.rs

• That's a lot of work that I didn't want to do
• I don't think it gives any real advantage over just using dyn.
• Adding another generic parameter to SelectionBuilder would mean a breaking change to the QueryFragment trait.
• Any of the macros that interact with SelectionBuilder would have to become more complicated (possibly in ways that are difficult/impossible to do - although without trying I can't say for sure).

2. I could have probably used the existing VariablesFields generic param on SelecitonBuilder etc - but then I'd need to add a whole ton of bounds onto all those definitions.

• This would potentially be another breaking change
• It'd probably be difficult to opt out of deriving QueryVariableLiterals with that approach
• Again I just think it'd make things difficult

Whereas dynamic dispatch avoids most of these downsides, and doesn't introduce many I can think of.

[Bobrokus]

Makes sense