Redesign #[graphql_scalar] macro

docs/book/content/types/scalars.md

@@ -40,107 +40,291 @@ crates. They are enabled via features that are on by default.
 * url::Url
 * bson::oid::ObjectId
 
-## newtype pattern
+## Custom scalars
+
+### `#[derive(GraphQLScalar)]`
 
 Often, you might need a custom scalar that just wraps an existing type.
 
 This can be done with the newtype pattern and a custom derive, similar to how
 serde supports this pattern with `#[serde(transparent)]`.
 
-```rust
+```rust,ignore
 # extern crate juniper;
-#[derive(juniper::GraphQLScalarValue)]
+#[derive(juniper::GraphQLScalar)]
 pub struct UserId(i32);
 
 #[derive(juniper::GraphQLObject)]
 struct User {
     id: UserId,
 }
-
+#
 # fn main() {}
 ```
 
 That's it, you can now user `UserId` in your schema.
 
 The macro also allows for more customization:
 
-```rust
+```rust,ignore
 # extern crate juniper;
 /// You can use a doc comment to specify a description.
-#[derive(juniper::GraphQLScalarValue)]
+#[derive(juniper::GraphQLScalar)]
 #[graphql(
-    transparent,
     // Overwrite the GraphQL type name.
     name = "MyUserId",
     // Specify a custom description.
     // A description in the attribute will overwrite a doc comment.
     description = "My user id description",
 )]
 pub struct UserId(i32);
+#
+# fn main() {}
+```
+
+All the methods used from newtype's field can be replaced with attributes:
 
+#### `#[graphql(to_output_with = <fn>)]` attribute
+
+```rust,ignore
+# use juniper::{GraphQLScalar, ScalarValue, Value};
+#
+#[derive(GraphQLScalar)]
+#[graphql(to_output_with = to_output)]
+struct Incremented(i32);
+
+/// Increments [`Incremented`] before converting into a [`Value`].
+fn to_output<S: ScalarValue>(v: &Incremented) -> Value<S> {
+    let inc = v.0 + 1;
+    Value::from(inc)
+}
+# 
 # fn main() {}
 ```
 
-## Custom scalars
+#### `#[graphql(from_input_with = <fn>)]` attribute
 
-For more complex situations where you also need custom parsing or validation,
-you can use the `graphql_scalar` proc macro.
+```rust,ignore
+# use juniper::{DefaultScalarValue, GraphQLScalar, InputValue, ScalarValue};
+#
+#[derive(GraphQLScalar)]
+#[graphql(scalar = DefaultScalarValue)]
+#[graphql(from_input_with = Self::from_input)]
+struct UserId(String);
+
+impl UserId {
+    /// Checks whether [`InputValue`] is `String` beginning with `id: ` and
+    /// strips it.
+    fn from_input(input: &InputValue) -> Result<UserId, String> {
+        input.as_string_value()
+            .ok_or_else(|| format!("Expected `String`, found: {}", input))
+            .and_then(|str| {
+                str.strip_prefix("id: ")
+                    .ok_or_else(|| {
+                        format!(
+                            "Expected `UserId` to begin with `id: `, \
+                             found: {}",
+                            input,
+                        )
+                    })
+            })
+            .map(|id| Self(id.to_owned()))
+    }
+}
+#
+# fn main() {}
+ ```
 
-Typically, you represent your custom scalars as strings.
+#### `#[graphql(parse_token_with = <fn>]` or `#[graphql(parse_token(<types>)]` attributes
 
-The example below implements a custom scalar for a custom `Date` type.
+```rust,ignore
+# use juniper::{GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue, ScalarValue, ScalarToken, Value};
+#
+#[derive(GraphQLScalar)]
+#[graphql(
+    to_output_with = to_output,
+    from_input_with = from_input,
+    parse_token_with = parse_token,
+//  ^^^^^^^^^^^^^^^^ Can be replaced with `parse_token(String, i32)`
+//                   which tries to parse as `String` and then as `i32`
+//                   if prior fails.
+)]
+enum StringOrInt {
+    String(String),
+    Int(i32),
+}
+
+fn to_output<S: ScalarValue>(v: &StringOrInt) -> Value<S> {
+    match v {
+        StringOrInt::String(str) => Value::scalar(str.to_owned()),
+        StringOrInt::Int(i) => Value::scalar(*i),
+    }
+}
+
+fn from_input<S: ScalarValue>(v: &InputValue<S>) -> Result<StringOrInt, String> {
+    v.as_string_value()
+        .map(|s| StringOrInt::String(s.to_owned()))
+        .or_else(|| v.as_int_value().map(|i| StringOrInt::Int(i)))
+        .ok_or_else(|| format!("Expected `String` or `Int`, found: {}", v))
+}
 
-Note: juniper already has built-in support for the `chrono::DateTime` type
-via `chrono` feature, which is enabled by default and should be used for this
-purpose.
+fn parse_token<S: ScalarValue>(value: ScalarToken<'_>) -> ParseScalarResult<'_, S> {
+    <String as ParseScalarValue<S>>::from_str(value)
+        .or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
+}
+#
+# fn main() {}
+```
 
-The example below is used just for illustration.
+> __NOTE:__ As you can see, once you provide all 3 custom resolvers, there
+>           is no need to follow `newtype` pattern.
 
-**Note**: the example assumes that the `Date` type implements
-`std::fmt::Display` and `std::str::FromStr`.
+#### `#[graphql(with = <module>)]` attribute
 
+Instead of providing all custom resolvers, you can provide module with `to_output`, `from_input`, `parse_token` functions and `Error` struct or type alias.
+
+```rust,ignore
+# use juniper::{GraphQLScalar, InputValue, ParseScalarResult, ParseScalarValue, ScalarValue, ScalarToken, Value};
+#
+#[derive(GraphQLScalar)]
+#[graphql(with = string_or_int)]
+enum StringOrInt {
+    String(String),
+    Int(i32),
+}
+
+mod string_or_int {
+    use super::*;
+
+    pub(super) fn to_output<S>(v: &StringOrInt) -> Value<S>
+    where
+        S: ScalarValue,
+    {
+        match v {
+            StringOrInt::String(str) => Value::scalar(str.to_owned()),
+            StringOrInt::Int(i) => Value::scalar(*i),
+        }
+    }
+
+    pub(super) fn from_input<S>(v: &InputValue<S>) -> Result<StringOrInt, String>
+    where
+        S: ScalarValue,
+    {
+        v.as_string_value()
+            .map(|s| StringOrInt::String(s.to_owned()))
+            .or_else(|| v.as_int_value().map(|i| StringOrInt::Int(i)))
+            .ok_or_else(|| format!("Expected `String` or `Int`, found: {}", v))
+    }
+
+    pub(super) fn parse_token<S>(value: ScalarToken<'_>) -> ParseScalarResult<'_, S>
+    where
+        S: ScalarValue,
+    {
+        <String as ParseScalarValue<S>>::from_str(value)
+            .or_else(|_| <i32 as ParseScalarValue<S>>::from_str(value))
+    }
+}
+#
+# fn main() {}
+```
+
+Also, you can partially override `#[graphql(with)]` attribute with other custom scalars.
+
+```rust,ignore
+# use juniper::{GraphQLScalar, InputValue, ParseScalarResult, ScalarValue, ScalarToken, Value};
+#
+#[derive(GraphQLScalar)]
+#[graphql(
+    with = string_or_int,
+    parse_token(String, i32)
+)]
+enum StringOrInt {
+    String(String),
+    Int(i32),
+}
+
+mod string_or_int {
+    use super::*;
+
+    pub(super) fn to_output<S>(v: &StringOrInt) -> Value<S>
+    where
+        S: ScalarValue,
+    {
+        match v {
+            StringOrInt::String(str) => Value::scalar(str.to_owned()),
+            StringOrInt::Int(i) => Value::scalar(*i),
+        }
+    }
+
+    pub(super) fn from_input<S>(v: &InputValue<S>) -> Result<StringOrInt, String>
+    where
+        S: ScalarValue,
+    {
+        v.as_string_value()
+            .map(|s| StringOrInt::String(s.to_owned()))
+            .or_else(|| v.as_int_value().map(|i| StringOrInt::Int(i)))
+            .ok_or_else(|| format!("Expected `String` or `Int`, found: {}", v))
+    }
+}
+#
+# fn main() {}
+```
+
+---
+
+### `#[graphql_scalar]` attribute
+
+For implementing custom scalars on foreign types there is `#[graphql_scalar]` attribute macro.
+
+> __NOTE:__ To satisfy [orphan rule] you should provide local [`ScalarValue`] implementation.
 
 ```rust
 # extern crate juniper;
 # mod date {
 #    pub struct Date;
 #    impl std::str::FromStr for Date {
-#        type Err = String; fn from_str(_value: &str) -> Result<Self, Self::Err> { unimplemented!() }
+#        type Err = String;
+#
+#        fn from_str(_value: &str) -> Result<Self, Self::Err> { 
+#            unimplemented!()
+#        }
 #    }
-#    // And we define how to represent date as a string.
+#
 #    impl std::fmt::Display for Date {
 #        fn fmt(&self, _f: &mut std::fmt::Formatter) -> std::fmt::Result {
 #            unimplemented!()
 #        }
 #    }
 # }
 #
-use juniper::{Value, ParseScalarResult, ParseScalarValue};
-use date::Date;
-
-#[juniper::graphql_scalar(description = "Date")]
-impl<S> GraphQLScalar for Date
-where
-    S: ScalarValue
-{
-    // Define how to convert your custom scalar into a primitive type.
-    fn resolve(&self) -> Value {
-        Value::scalar(self.to_string())
-    }
-
-    // Define how to parse a primitive type into your custom scalar.
-    // NOTE: The error type should implement `IntoFieldError<S>`.
-    fn from_input_value(v: &InputValue) -> Result<Date, String> {
-        v.as_string_value()
-            .ok_or_else(|| format!("Expected `String`, found: {}", v))
-            .and_then(|s| s.parse().map_err(|e| format!("Failed to parse `Date`: {}", e)))
+# use juniper::DefaultScalarValue as CustomScalarValue;
+use juniper::{graphql_scalar, InputValue, ScalarValue, Value};
+
+#[graphql_scalar(
+    with = date_scalar, 
+    parse_token(String),
+    scalar = CustomScalarValue,
+//           ^^^^^^^^^^^^^^^^^ Local `ScalarValue` implementation.
+)]
+type Date = date::Date;
+//          ^^^^^^^^^^ Type from another crate.
+
+mod date_scalar {
+    use super::*;
+
+    pub(super) fn to_output(v: &Date) -> Value<CustomScalarValue> {
+        Value::scalar(v.to_string())
     }
 
-    // Define how to parse a string value.
-    fn from_str<'a>(value: ScalarToken<'a>) -> ParseScalarResult<'a, S> {
-        <String as ParseScalarValue<S>>::from_str(value)
+    pub(super) fn from_input(v: &InputValue<CustomScalarValue>) -> Result<Date, String> {
+      v.as_string_value()
+          .ok_or_else(|| format!("Expected `String`, found: {}", v))
+          .and_then(|s| s.parse().map_err(|e| format!("Failed to parse `Date`: {}", e)))
     }
 }
 #
 # fn main() {}
 ```
+
+[orphan rule]: https://doc.rust-lang.org/reference/items/implementations.html#orphan-rules
+[`ScalarValue`]: https://docs.rs/juniper/latest/juniper/trait.ScalarValue.html

integration_tests/codegen_fail/fail/interface/implementers_duplicate_ugly.stderr

@@ -1,21 +1,21 @@
-error[E0119]: conflicting implementations of trait `<CharacterValueEnum<ObjA, ObjA> as juniper::GraphQLInterface<__S>>::mark::_::{closure#0}::MutuallyExclusive` for type `ObjA`
+error[E0119]: conflicting implementations of trait `std::convert::From<ObjA>` for type `CharacterValueEnum<ObjA, ObjA>`
   --> fail/interface/implementers_duplicate_ugly.rs:11:1
    |
 11 | #[graphql_interface(for = [ObjA, ObjAlias])]
    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    | |
    | first implementation here
-   | conflicting implementation for `ObjA`
+   | conflicting implementation for `CharacterValueEnum<ObjA, ObjA>`
    |
-   = note: this error originates in the macro `::juniper::sa::assert_type_ne_all` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the attribute macro `graphql_interface` (in Nightly builds, run with -Z macro-backtrace for more info)
 
-error[E0119]: conflicting implementations of trait `std::convert::From<ObjA>` for type `CharacterValueEnum<ObjA, ObjA>`
+error[E0119]: conflicting implementations of trait `<CharacterValueEnum<ObjA, ObjA> as juniper::GraphQLInterface<__S>>::mark::_::{closure#0}::MutuallyExclusive` for type `ObjA`
   --> fail/interface/implementers_duplicate_ugly.rs:11:1
    |
 11 | #[graphql_interface(for = [ObjA, ObjAlias])]
    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    | |
    | first implementation here
-   | conflicting implementation for `CharacterValueEnum<ObjA, ObjA>`
+   | conflicting implementation for `ObjA`
    |
-   = note: this error originates in the attribute macro `graphql_interface` (in Nightly builds, run with -Z macro-backtrace for more info)
+   = note: this error originates in the macro `::juniper::sa::assert_type_ne_all` (in Nightly builds, run with -Z macro-backtrace for more info)