feat: implement tristate optionals (some, null, undefined)

definitelynobody · definitelynobody · commit 4c20a96e2155 · 2025-05-10T04:05:09.000-05:00
Fixes #125
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/cynic-codegen/src/types/parsing.rs b/cynic-codegen/src/types/parsing.rs
@@ -78,7 +78,7 @@ pub fn parse_rust_type(ty: &syn::Type) -> RustType<'_> {
                             };
                         }
                     }
-                    "Option" => {
+                    "MaybeUndefined" | "Option" => {
                         if let Some(inner_type) = extract_generic_argument(last_segment) {
                             return RustType::Optional {
                                 syn: Cow::Borrowed(type_path),
diff --git a/cynic-codegen/src/types/validation.rs b/cynic-codegen/src/types/validation.rs
@@ -230,17 +230,17 @@ impl From<TypeValidationError> for syn::Error {
         let span = err.span();
         let message = match err {
             TypeValidationError::FieldIsOptional { provided_type, .. } =>
-                format!("This field is nullable but you're not wrapping the type in Option.  Did you mean Option<{}>", provided_type),
+                format!("This field is nullable but you're not wrapping the type in MaybeUndefined or Option.  Did you mean cynic::MaybeUndefined<{}> or Option<{}>", provided_type, provided_type),
             TypeValidationError::FieldIsRequired { provided_type, .. } =>
-                format!("This field is not nullable but you're wrapping the type in Option.  Did you mean {}", provided_type),
+                format!("This field is not nullable but you're wrapping the type in Option or MaybeUndefined.  Did you mean {}", provided_type),
             TypeValidationError::FieldIsList { provided_type, .. } => {
                 format!("This field is a list but you're not wrapping the type in Vec.  Did you mean Vec<{}>", provided_type)
             },
             TypeValidationError::FieldIsNotList { provided_type, .. } => {
                 format!("This field is not a list but you're wrapping the type in Vec.  Did you mean {}", provided_type)
             },
             TypeValidationError::RecursiveFieldWithoutOption { provided_type, .. } => {
-                format!("Recursive types must be wrapped in Option.  Did you mean Option<{}>", provided_type)
+                format!("Recursive types must be wrapped in MaybeUndefined or Option.  Did you mean cynic::MaybeUndefined<{}> or Option<{}>", provided_type, provided_type)
             }
             TypeValidationError::SpreadOnOption { .. } => "You can't spread on an optional field".to_string(),
             TypeValidationError::SpreadOnVec { .. } => "You can't spread on a list field".to_string(),
diff --git a/cynic-codegen/src/use_schema/mod.rs b/cynic-codegen/src/use_schema/mod.rs
@@ -151,6 +151,13 @@ pub(crate) fn use_schema_impl(schema: &Schema<'_, Validated>) -> Result<TokenStr
                 const TYPE: VariableType = VariableType::Nullable(&T::TYPE);
             }
 
+            impl<T> Variable for cynic::MaybeUndefined<T>
+            where
+                T: Variable
+            {
+                const TYPE: VariableType = VariableType::Nullable(&T::TYPE);
+            }
+
             impl<T> Variable for [T]
             where
                 T: Variable,
diff --git a/cynic-querygen/Cargo.toml b/cynic-querygen/Cargo.toml
@@ -18,6 +18,7 @@ once_cell = "1.9"
 rust_decimal = "1.22"
 thiserror = "1.0.30"
 uuid = { version = "1", features = ["v4"] }
+async-graphql = { version = "7" }
 
 cynic-parser.workspace = true
 
diff --git a/cynic-querygen/src/output/field.rs b/cynic-querygen/src/output/field.rs
@@ -44,6 +44,12 @@ impl std::fmt::Display for Field<'_> {
         if let Some(rename) = self.rename() {
             writeln!(f, r#"#[cynic(rename = "{}")]"#, rename)?;
         }
+        if self.type_spec.name.starts_with("cynic::MaybeUndefined<") {
+            writeln!(
+                f,
+                r#"#[cynic(skip_serializing_if = "cynic::MaybeUndefined::is_undefined")]"#
+            )?;
+        }
         writeln!(f, "pub {}: {},", self.name(), self.type_spec.name)
     }
 }
diff --git a/cynic-querygen/src/schema/fields.rs b/cynic-querygen/src/schema/fields.rs
@@ -193,7 +193,7 @@ fn input_type_spec_imp(
             needs_owned,
             is_subobject_with_lifetime,
         )
-        .map(|type_spec| format!("Option<{type_spec}>",));
+        .map(|type_spec| format!("cynic::MaybeUndefined<{type_spec}>",));
     }
 
     match ty {
diff --git a/cynic/Cargo.toml b/cynic/Cargo.toml
@@ -31,6 +31,7 @@ serde = { version = "1.0.136", features = ["derive"] }
 serde_json = { version = "1.0", optional = true }
 static_assertions = "1"
 thiserror = "1.0.30"
+async-graphql = { version = "7", default-features = false }
 
 # Surf feature deps
 surf = { version = "2.3", default-features = false, optional = true }
diff --git a/cynic/src/coercions.rs b/cynic/src/coercions.rs
@@ -4,7 +4,7 @@
 //! certain changes to be made in a backwards compatible way, this module provides
 //! some traits and macros to help enforce those.
 
-use crate::Id;
+use crate::{Id, MaybeUndefined};
 
 /// Determines whether a type can be coerced into a given schema type.
 ///
@@ -13,6 +13,12 @@ use crate::Id;
 pub trait CoercesTo<T> {}
 
 impl<T, TypeLock> CoercesTo<Option<TypeLock>> for Option<T> where T: CoercesTo<TypeLock> {}
+impl<T, TypeLock> CoercesTo<Option<TypeLock>> for MaybeUndefined<T> where T: CoercesTo<TypeLock> {}
+impl<T, TypeLock> CoercesTo<MaybeUndefined<TypeLock>> for Option<T> where T: CoercesTo<TypeLock> {}
+impl<T, TypeLock> CoercesTo<MaybeUndefined<TypeLock>> for MaybeUndefined<T> where
+    T: CoercesTo<TypeLock>
+{
+}
 impl<T, TypeLock> CoercesTo<Vec<TypeLock>> for Vec<T> where T: CoercesTo<TypeLock> {}
 impl<T, TypeLock> CoercesTo<Vec<TypeLock>> for [T] where T: CoercesTo<TypeLock> {}
 
@@ -27,10 +33,14 @@ macro_rules! impl_coercions {
     ($target:ty [$($impl_generics: tt)*] [$($where_clause: tt)*], $typelock:ty) => {
         impl $($impl_generics)* $crate::coercions::CoercesTo<$typelock> for $target $($where_clause)* {}
         impl $($impl_generics)* $crate::coercions::CoercesTo<Option<$typelock>> for $target $($where_clause)* {}
+        impl $($impl_generics)* $crate::coercions::CoercesTo<$crate::MaybeUndefined<$typelock>> for $target $($where_clause)* {}
         impl $($impl_generics)* $crate::coercions::CoercesTo<Vec<$typelock>> for $target $($where_clause)* {}
         impl $($impl_generics)* $crate::coercions::CoercesTo<Option<Vec<$typelock>>> for $target $($where_clause)* {}
         impl $($impl_generics)* $crate::coercions::CoercesTo<Option<Vec<Option<$typelock>>>> for $target $($where_clause)* {}
         impl $($impl_generics)* $crate::coercions::CoercesTo<Option<Option<$typelock>>> for $target $($where_clause)* {}
+        impl $($impl_generics)* $crate::coercions::CoercesTo<$crate::MaybeUndefined<Vec<$typelock>>> for $target $($where_clause)* {}
+        impl $($impl_generics)* $crate::coercions::CoercesTo<$crate::MaybeUndefined<Vec<$crate::MaybeUndefined<$typelock>>>> for $target $($where_clause)* {}
+        impl $($impl_generics)* $crate::coercions::CoercesTo<$crate::MaybeUndefined<$crate::MaybeUndefined<$typelock>>> for $target $($where_clause)* {}
         impl $($impl_generics)* $crate::coercions::CoercesTo<Vec<Vec<$typelock>>> for $target $($where_clause)* {}
     };
 }
@@ -63,17 +73,26 @@ mod tests {
     fn test_coercions() {
         assert_impl_all!(i32: CoercesTo<i32>);
         assert_impl_all!(i32: CoercesTo<Option<i32>>);
+        assert_impl_all!(i32: CoercesTo<MaybeUndefined<i32>>);
         assert_impl_all!(i32: CoercesTo<Vec<i32>>);
         assert_impl_all!(i32: CoercesTo<Option<Vec<i32>>>);
+        assert_impl_all!(i32: CoercesTo<MaybeUndefined<Vec<i32>>>);
         assert_impl_all!(i32: CoercesTo<Vec<Vec<i32>>>);
 
         assert_impl_all!(Option<i32>: CoercesTo<Option<i32>>);
         assert_impl_all!(Option<i32>: CoercesTo<Option<Option<i32>>>);
 
+        assert_impl_all!(MaybeUndefined<i32>: CoercesTo<MaybeUndefined<i32>>);
+        assert_impl_all!(MaybeUndefined<i32>: CoercesTo<MaybeUndefined<Option<i32>>>);
+
+        assert_impl_all!(MaybeUndefined<i32>: CoercesTo<Option<i32>>);
+        assert_impl_all!(Option<i32>: CoercesTo<MaybeUndefined<i32>>);
+
         assert_impl_all!(Vec<i32>: CoercesTo<Vec<i32>>);
         assert_impl_all!(Vec<i32>: CoercesTo<Vec<Vec<i32>>>);
 
         assert_not_impl_any!(Vec<i32>: CoercesTo<i32>);
         assert_not_impl_any!(Option<i32>: CoercesTo<i32>);
+        assert_not_impl_any!(MaybeUndefined<i32>: CoercesTo<i32>);
     }
 }
diff --git a/cynic/src/core.rs b/cynic/src/core.rs
@@ -1,6 +1,6 @@
 use std::borrow::Cow;
 
-use crate::{queries::SelectionBuilder, QueryVariablesFields};
+use crate::{queries::SelectionBuilder, MaybeUndefined, QueryVariablesFields};
 
 /// A trait that marks a type as part of a GraphQL query.
 ///
@@ -37,6 +37,18 @@ where
     }
 }
 
+impl<T> QueryFragment for MaybeUndefined<T>
+where
+    T: QueryFragment,
+{
+    type SchemaType = Option<T::SchemaType>;
+    type VariablesFields = T::VariablesFields;
+
+    fn query(builder: SelectionBuilder<'_, Self::SchemaType, Self::VariablesFields>) {
+        T::query(builder.into_inner())
+    }
+}
+
 impl<T> QueryFragment for Vec<T>
 where
     T: QueryFragment,
@@ -163,6 +175,13 @@ where
     type SchemaType = Option<T::SchemaType>;
 }
 
+impl<T> InputObject for MaybeUndefined<T>
+where
+    T: InputObject,
+{
+    type SchemaType = Option<T::SchemaType>;
+}
+
 impl<T> InputObject for Vec<T>
 where
     T: InputObject,
diff --git a/cynic/src/lib.rs b/cynic/src/lib.rs
@@ -172,6 +172,7 @@
 mod builders;
 mod core;
 mod id;
+mod maybe_undefined;
 mod operation;
 mod result;
 
@@ -189,6 +190,7 @@ pub use {
     self::core::{Enum, InlineFragments, InputObject, QueryFragment},
     builders::{MutationBuilder, QueryBuilder, SubscriptionBuilder},
     id::Id,
+    maybe_undefined::MaybeUndefined,
     operation::{Operation, OperationBuildError, OperationBuilder, StreamingOperation},
     result::*,
     variables::{QueryVariableLiterals, QueryVariables, QueryVariablesFields},
diff --git a/cynic/src/maybe_undefined.rs b/cynic/src/maybe_undefined.rs
@@ -0,0 +1,84 @@
+use serde::{Deserialize, Serialize};
+
+use std::ops::{Deref, DerefMut};
+
+/// A wrapper around async-graphql's [`MaybeUndefined`](https://docs.rs/async-graphql/latest/async_graphql/types/enum.MaybeUndefined.html).
+///
+/// You can initialize it from:
+/// - `From<Option<T>>` will become T or null.
+/// - `Default` will become undefined.
+#[derive(Serialize, Deserialize, Copy, Clone, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)]
+pub struct MaybeUndefined<T>(async_graphql::MaybeUndefined<T>);
+
+impl<T> MaybeUndefined<T> {
+    fn inner(&self) -> &async_graphql::MaybeUndefined<T> {
+        &self.0
+    }
+
+    fn inner_mut(&mut self) -> &mut async_graphql::MaybeUndefined<T> {
+        &mut self.0
+    }
+
+    /// Returns true if the `MaybeUndefined<T>` is undefined.
+    ///
+    /// Deserialization ought to be skipped for this when used as a field.
+    pub fn is_undefined(&self) -> bool {
+        self.0.is_undefined()
+    }
+}
+
+impl<T> From<async_graphql::MaybeUndefined<T>> for MaybeUndefined<T> {
+    fn from(value: async_graphql::MaybeUndefined<T>) -> Self {
+        Self(value)
+    }
+}
+
+impl<T> Deref for MaybeUndefined<T> {
+    type Target = async_graphql::MaybeUndefined<T>;
+
+    fn deref(&self) -> &Self::Target {
+        self.inner()
+    }
+}
+
+impl<T> DerefMut for MaybeUndefined<T> {
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        self.inner_mut()
+    }
+}
+
+impl<T> From<Option<T>> for MaybeUndefined<T> {
+    fn from(value: Option<T>) -> Self {
+        Self(match value {
+            Some(value) => async_graphql::MaybeUndefined::Value(value),
+            None => async_graphql::MaybeUndefined::Null,
+        })
+    }
+}
+
+impl<T> Default for MaybeUndefined<T> {
+    fn default() -> Self {
+        Self(async_graphql::MaybeUndefined::Undefined)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test() {
+        assert_eq!(
+            MaybeUndefined::from(None),
+            MaybeUndefined(async_graphql::MaybeUndefined::<bool>::Null)
+        );
+        assert_eq!(
+            MaybeUndefined::from(Some(true)),
+            MaybeUndefined(async_graphql::MaybeUndefined::Value(true))
+        );
+        assert_eq!(
+            MaybeUndefined::<bool>::default(),
+            MaybeUndefined(async_graphql::MaybeUndefined::Undefined)
+        );
+    }
+}
diff --git a/cynic/src/queries/flatten.rs b/cynic/src/queries/flatten.rs
@@ -1,19 +1,31 @@
+// use crate::MaybeUndefined;
+
 /// Encodes the rules for what types can be flattened into other types
 /// via the `#[cynic(flatten)]` attribute.
 ///
 /// This trait is sealed and can't be implemented by users of cynic.
 pub trait FlattensInto<T>: private::Sealed<T> {}
 
 impl<T> FlattensInto<Vec<T>> for Vec<Option<T>> {}
+
 impl<T> FlattensInto<Vec<T>> for Option<Vec<T>> {}
 impl<T> FlattensInto<Option<Vec<T>>> for Option<Vec<Option<T>>> {}
 impl<T> FlattensInto<Vec<T>> for Option<Vec<Option<T>>> {}
 
+// impl<T> FlattensInto<Vec<T>> for MaybeUndefined<Vec<T>> {}
+// impl<T> FlattensInto<Option<Vec<T>>> for MaybeUndefined<Vec<Option<T>>> {}
+// impl<T> FlattensInto<Vec<T>> for MaybeUndefined<Vec<Option<T>>> {}
+
 mod private {
     pub trait Sealed<T> {}
 
     impl<T> Sealed<Vec<T>> for Vec<Option<T>> {}
+
     impl<T> Sealed<Vec<T>> for Option<Vec<T>> {}
     impl<T> Sealed<Option<Vec<T>>> for Option<Vec<Option<T>>> {}
     impl<T> Sealed<Vec<T>> for Option<Vec<Option<T>>> {}
+
+    // impl<T> Sealed<Vec<T>> for MaybeUndefined<Vec<T>> {}
+    // impl<T> Sealed<Option<Vec<T>>> for MaybeUndefined<Vec<Option<T>>> {}
+    // impl<T> Sealed<Vec<T>> for MaybeUndefined<Vec<Option<T>>> {}
 }
diff --git a/cynic/src/schema.rs b/cynic/src/schema.rs
@@ -11,6 +11,8 @@
 //! usually be marker types and the associated types will also usually be
 //! markers.
 
+use crate::MaybeUndefined;
+
 /// Indicates that a struct represents a Field in a graphql schema.
 pub trait Field {
     /// The schema marker type of this field.
@@ -74,6 +76,20 @@ where
     type SchemaType = Option<U::SchemaType>;
 }
 
+impl<T, U> IsScalar<MaybeUndefined<T>> for MaybeUndefined<U>
+where
+    U: IsScalar<T>,
+{
+    type SchemaType = MaybeUndefined<U::SchemaType>;
+}
+
+impl<T, U> IsScalar<Option<T>> for MaybeUndefined<U>
+where
+    U: IsScalar<T>,
+{
+    type SchemaType = Option<U::SchemaType>;
+}
+
 impl<T, U> IsScalar<Vec<T>> for Vec<U>
 where
     U: IsScalar<T>,
diff --git a/cynic/tests/maybe_undefined.rs b/cynic/tests/maybe_undefined.rs
diff --git a/cynic/tests/snapshots/maybe_undefined__query_building_null.snap b/cynic/tests/snapshots/maybe_undefined__query_building_null.snap
diff --git a/cynic/tests/snapshots/maybe_undefined__query_building_some.snap b/cynic/tests/snapshots/maybe_undefined__query_building_some.snap
diff --git a/cynic/tests/snapshots/maybe_undefined__query_building_undefined.snap b/cynic/tests/snapshots/maybe_undefined__query_building_undefined.snap
diff --git a/tests/querygen-compile-run/build.rs b/tests/querygen-compile-run/build.rs

Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ pub fn parse_rust_type(ty: &syn::Type) -> RustType<'_> {`
`78`	`78`	`};`
`79`	`79`	`}`
`80`	`80`	`}`
`81`		`- "Option" => {`
	`81`	`+ "MaybeUndefined" \| "Option" => {`
`82`	`82`	`if let Some(inner_type) = extract_generic_argument(last_segment) {`
`83`	`83`	`return RustType::Optional {`
`84`	`84`	`syn: Cow::Borrowed(type_path),`
Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,12 @@ impl std::fmt::Display for Field<'_> {`
`44`	`44`	`if let Some(rename) = self.rename() {`
`45`	`45`	`writeln!(f, r#"#[cynic(rename = "{}")]"#, rename)?;`
`46`	`46`	`}`
	`47`	`+ if self.type_spec.name.starts_with("cynic::MaybeUndefined<") {`
	`48`	`+ writeln!(`
	`49`	`+ f,`
	`50`	`+ r#"#[cynic(skip_serializing_if = "cynic::MaybeUndefined::is_undefined")]"#`
	`51`	`+ )?;`
	`52`	`+ }`
`47`	`53`	`writeln!(f, "pub {}: {},", self.name(), self.type_spec.name)`
`48`	`54`	`}`
`49`	`55`	`}`
Original file line number	Diff line number	Diff line change
`@@ -193,7 +193,7 @@ fn input_type_spec_imp(`
`193`	`193`	`needs_owned,`
`194`	`194`	`is_subobject_with_lifetime,`
`195`	`195`	`)`
`196`		`- .map(\|type_spec\| format!("Option<{type_spec}>",));`
	`196`	`+ .map(\|type_spec\| format!("cynic::MaybeUndefined<{type_spec}>",));`
`197`	`197`	`}`
`198`	`198`
`199`	`199`	`match ty {`