feat: field type overrides in generator (#1184)

#### Why are we making this change?

I'm using `cynic-querygen` for a work project, and it's been a joy to
simply copy queries from Graphiql to our rust codebase, so thank you for
that! However, we've ended up needing to make quite a few
find-and-replace changes to the generated code due to the crate's
limited code generation options.

We'd like to start contributing some of the features we've found we
needed as new options to `cynic-querygen`. This first one is the one
that's the hardest to do via regex, because it should incorporate both
the type name and the field name, and also seemed like one of the
simplest to implement.

The main use case for this feature for us is specifying different
deserialization targets for different `Json` fields. For instance, we
have one JSON field that should deserialize to `HashMap<String,
String>`, and another that should deserialize directly to a complex enum
structure.

#### What effects does this change have?

This adds a new `field_overrides` field to `QueryGenOptions`, which
allows overriding the type of individual fields on specific types using
a `.` separator. I have no strong opinion on the shape of the option,
this just seemed the most natural. This field is passed down into
`make_query_fragment`, where each field checks it to potentially set its
`type_name_override`. For example:

```rust
let result = cynic_querygen::document_to_fragment_structs(
    &query_content,
    &schema_content,
    &cynic_querygen::QueryGenOptions {
        schema_name: Some("my_schema".to_string()),
        field_overrides: maplit::hashmap!(
            "MyType.complexEnum" => "crate::complex_enum::ComplexEnum",
            "PresignedUrl.fields" => "std::collections::HashMap<String, String>",
        ),
        ..Default::default()
    },
);
```

Test and documentation are included for the new field, and I also added
a doc comment for `schema_name`, since I was surprised when I originally
looked into `cynic-querygen` to find it basically lacking any
documentation.

If you like the idea of making the querygen more customizable, we have a
couple other ideas I'd like to follow up with, which would fully
supplant all our find-and-replaces:

- overriding the default type for scalars like `DateTime`, `Json`, and
`Uuid` (e.g. to use `chrono`, `serde_json` and `uuid` crate types)
- specifying additional traits to derive for `cynic::QueryFragment`s and
`cynic::Enum`s

Author: Smona

CHANGELOG.md

@@ -11,6 +11,8 @@ This project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html
 ### New features
 
 - The `QueryFragment` derive now supports the `rename_all` attribute
+- `cynic-querygen` now has a `field_overrides` option that can be used to
+  customize the type of individual scalar fields in generated `QueryFragment`s.
 
 ### Bug Fixes
 

cynic-querygen-web/src/graphiql_page.rs

@@ -1,14 +1,14 @@
 use seed::{prelude::*, *};
 
-pub struct Model {
+pub struct Model<'a> {
     schema_url: Option<String>,
     schema_data: Option<String>,
     query: String,
-    opts: cynic_querygen::QueryGenOptions,
+    opts: cynic_querygen::QueryGenOptions<'a>,
     generated_code: Result<String, cynic_querygen::Error>,
 }
 
-impl Model {
+impl<'a> Model<'a> {
     pub fn new_from_url(url: String) -> Self {
         Model {
             schema_url: Some(url),
@@ -34,8 +34,8 @@ impl Model {
     }
 }
 
-impl Default for Model {
-    fn default() -> Model {
+impl Default for Model<'_> {
+    fn default() -> Model<'static> {
         Model {
             schema_url: None,
             schema_data: None,

cynic-querygen-web/src/lib.rs

@@ -14,7 +14,7 @@ mod view;
 // ------ ------
 
 // `init` describes what should happen when your app started.
-fn init(_: Url, _: &mut impl Orders<Msg>) -> Model {
+fn init(_: Url, _: &mut impl Orders<Msg>) -> Model<'static> {
     Model::default()
 }
 
@@ -23,13 +23,13 @@ fn init(_: Url, _: &mut impl Orders<Msg>) -> Model {
 // ------ ------
 
 // `Model` describes our app state.
-enum Model {
+enum Model<'a> {
     EntryPage(entry_page::Model),
-    GraphiqlPage(graphiql_page::Model),
+    GraphiqlPage(graphiql_page::Model<'a>),
 }
 
-impl Default for Model {
-    fn default() -> Model {
+impl Default for Model<'_> {
+    fn default() -> Model<'static> {
         Model::EntryPage(entry_page::Model::default())
     }
 }

cynic-querygen/src/lib.rs

@@ -1,4 +1,4 @@
-use std::rc::Rc;
+use std::{collections::HashMap, rc::Rc};
 
 mod casings;
 mod naming;
@@ -94,16 +94,27 @@ pub enum Error {
 }
 
 #[derive(Debug)]
-pub struct QueryGenOptions {
+pub struct QueryGenOptions<'a> {
     pub schema_module_name: String,
+    /// The name of a registered schema to use inside generated `#[cynic(schema = "schema_name")]` attributes.
     pub schema_name: Option<String>,
+    /// Mapping of `("TypeName.fieldName", "fully::qualified::type::Path")` overrides to customize the scalar type used for specific fields.
+    ///
+    /// The field name should have the same casing as the field name in the GraphQL schema
+    /// (i.e. before conversion to snake_case). Note that the provided type override will still
+    /// be wrapped in an [`Option`] if the field is nullable in the schema.
+    ///
+    /// The override type must be a registered [custom scalar](https://cynic-rs.dev/derives/scalars#custom-scalars) for the schema scalar type
+    /// of the overridden field.
+    pub field_overrides: HashMap<&'a str, &'a str>,
 }
 
-impl Default for QueryGenOptions {
-    fn default() -> QueryGenOptions {
+impl Default for QueryGenOptions<'_> {
+    fn default() -> QueryGenOptions<'static> {
         QueryGenOptions {
             schema_module_name: "schema".into(),
             schema_name: None,
+            field_overrides: HashMap::default(),
         }
     }
 }
@@ -124,7 +135,8 @@ pub fn document_to_fragment_structs(
     let (schema, typename_id) = add_builtins(schema);
 
     let type_index = Rc::new(TypeIndex::from_schema(&schema, typename_id));
-    let mut parsed_output = query_parsing::parse_query_document(&query, &type_index)?;
+    let mut parsed_output =
+        query_parsing::parse_query_document(&query, &type_index, &options.field_overrides)?;
 
     add_schema_name(&mut parsed_output, options.schema_name.as_deref());
 

cynic-querygen/src/query_parsing/mod.rs

@@ -1,4 +1,4 @@
-use std::rc::Rc;
+use std::{collections::HashMap, rc::Rc};
 
 mod inputs;
 mod leaf_types;
@@ -18,13 +18,14 @@ use cynic_parser::{ExecutableDocument, executable as parser};
 use crate::{
     Error, TypeIndex,
     casings::CasingExt,
-    naming::Namer,
+    naming::{Nameable, Namer},
     output::{self, Output},
 };
 
 pub fn parse_query_document<'a>(
     doc: &'a ExecutableDocument,
     type_index: &Rc<TypeIndex<'a>>,
+    field_overrides: &HashMap<&str, &str>,
 ) -> Result<Output<'a, 'a>, Error> {
     let normalised = normalisation::normalise(doc, type_index)?;
     let input_objects = InputObjects::new(&normalised);
@@ -51,7 +52,14 @@ pub fn parse_query_document<'a>(
 
     let query_fragments = sorting::topological_sort(normalised.selection_sets.iter().cloned())
         .into_iter()
-        .map(|selection| make_query_fragment(selection, &mut namers, &variable_struct_details))
+        .map(|selection| {
+            make_query_fragment(
+                selection,
+                &mut namers,
+                &variable_struct_details,
+                field_overrides,
+            )
+        })
         .collect::<Vec<_>>();
 
     let inline_fragments = normalised
@@ -84,12 +92,15 @@ fn make_query_fragment<'text>(
     selection: Rc<normalisation::SelectionSet<'text, 'text>>,
     namers: &mut Namers<'text>,
     variable_struct_details: &VariableStructDetails<'text, 'text>,
+    field_overrides: &HashMap<&str, &str>,
 ) -> crate::output::QueryFragment<'text, 'text> {
     use crate::output::query_fragment::{
         FieldArgument, OutputField, QueryFragment, RustOutputFieldType,
     };
     use normalisation::{Field, Selection};
 
+    let requested_fragment_name = selection.requested_name();
+
     QueryFragment {
         fields: selection
             .selections
@@ -99,7 +110,11 @@ fn make_query_fragment<'text>(
                 let schema_field = &field.schema_field;
 
                 let type_name_override = match &field.field {
-                    Field::Leaf => None,
+                    Field::Leaf => field_overrides
+                        // Check for field-level type overrides using the requested fragment name (before incrementing suffix),
+                        // and un-aliased field name in the schema.
+                        .get(format!("{}.{}", requested_fragment_name, schema_field.name).as_str())
+                        .map(|o| o.to_string()),
                     Field::Composite(ss) => Some(namers.selection_sets.name_subject(ss)),
                     Field::InlineFragments(fragments) => {
                         Some(namers.inline_fragments.name_subject(fragments))

cynic-querygen/tests/option-tests.rs

@@ -0,0 +1,34 @@
+use std::collections::HashMap;
+
+use insta::assert_snapshot;
+
+use cynic_querygen::{QueryGenOptions, document_to_fragment_structs};
+
+#[test]
+fn test_field_overrides() {
+    let schema = include_str!("../../schemas/test_cases.graphql");
+    let query = r#"
+      query MyQuery($input: OneOfObject!) {
+        clashes {
+          str
+          bool
+          i32
+          u32
+        }
+      }
+    "#;
+
+    let mut field_overrides = HashMap::new();
+    field_overrides.insert(
+        "FieldNameClashes.str",
+        "std::collections::HashMap<String, String>",
+    );
+    let options = QueryGenOptions {
+        field_overrides,
+        ..Default::default()
+    };
+
+    assert_snapshot!(
+        document_to_fragment_structs(query, schema, &options).expect("QueryGen Failed")
+    )
+}

cynic-querygen/tests/snapshots/option_tests__field_overrides.snap

@@ -0,0 +1,33 @@
+---
+source: cynic-querygen/tests/option-tests.rs
+expression: "document_to_fragment_structs(query, schema,\n&options).expect(\"QueryGen Failed\")"
+---
+#[derive(cynic::QueryFragment, Debug)]
+#[cynic(graphql_type = "Foo")]
+pub struct MyQuery {
+    pub clashes: Option<FieldNameClashes>,
+}
+
+#[derive(cynic::QueryFragment, Debug)]
+pub struct FieldNameClashes {
+    pub str: Option<std::collections::HashMap<String, String>>,
+    pub bool: Option<bool>,
+    pub i32: Option<i32>,
+    pub u32: Option<i32>,
+}
+
+#[derive(cynic::InputObject, Debug)]
+pub enum OneOfObject<'a> {
+    String(&'a str),
+    Int(i32),
+    Nested(Baz<'a>),
+}
+
+#[derive(cynic::InputObject, Debug)]
+pub struct Baz<'a> {
+    pub id: &'a cynic::Id,
+    pub a_string: &'a str,
+    pub an_optional_string: Option<&'a str>,
+}
+
+