Should we change the default scalar decoding?

[dillonkearns]

Sometimes APIs return JSON object responses rather than scalars, and people aren't sure how to proceed so they ask questions in the Elm slack or ask in issues like #501. The current custom scalar decoder isn't a very precise reflection of what custom scalars are in GraphQL. Json.Decode.Value would be one honest representation. Custom Scalars have no type information in the GraphQL Schema, so elm-graphql doesn't have any information about them other than that it is JSON.

Some more context on that at https://github.com/dillonkearns/elm-graphql/blob/master/FAQ.md#why-are-all-my-scalars-strings-how-do-i-turn-it-into-other-types-like-float-or-timeposix

The Custom Scalar Codecs functionality is the way to handle these cases right now, and another honest solution would be to make this the only way to deal with Custom Scalars (by defining modules like this). However, it's probably too cumbersome to require users to set that up when they first create a repo.

So maybe an honest approach that lets users incrementally ease into complexity is to change the built-in Custom Scalar decoder to decode into Json.Decode.Value:

elm-graphql/src/Graphql/Internal/Builder/Object.elm

Lines 21 to 39 in 02c59a9

	{-| Decoder for scalars for use in auto-generated code.
	-}
	scalarDecoder : Decoder String
	scalarDecoder =
	Decode.oneOf
	[ Decode.string
	, Decode.float |> Decode.map String.fromFloat
	, Decode.int |> Decode.map String.fromInt
	, Decode.bool
	|> Decode.map
	(\bool ->
	case bool of
	True ->
	"true"
	False ->
	"false"
	)
	]

Then you can unwrap the Json.Decode.Value from the Custom Scalar run any decoder on it and handle the Result. Then you can move to the Custom Scalar Codecs functionality as needed.

Incremental Custom Scalar Codecs?

Maybe as part of this, there could be a feature to opt in to Custom Scalar Codecs one codec at a time? So it could just decode to Json.Decode.Value with a Custom Scalar wrapper for any values that aren't handled. Similar to the concept of ejecting in elm-spa. I'm not sure if it's feasible to create a nice user experience for this, but if it seems like a good idea then this could be something to explore.

[gampleman]

I'm a big 👍 for having custom scalars be the only way to deal with them. Part of the problem of them being optional, is that often developers don't really know about them, and then spend a lot of time with SelectionSet.map and friends instead of using this feature, which is a shame as the GraphQL code ends up really unnecessarily convoluted (I'm speaking from experience in our team).

Perhaps an improvement would be to automatically generate new custom scalar definitions instead of asking the user to copy-paste a file. I appreciate that automatically modifying arbitrary elm code can be quite technically challenging though.

[dillonkearns]

Hmm, yes I think you're right that improving the user experience for the custom scalar codecs functionality could make it more realistic to use that as the default and only way to handle Custom Scalars.

For reference, @pdamoc also had an interesting approach in #568 to serialize the Json.Decode.Value using Json.Encode.encode 0 (Json.Decode.Value and Json.Encode.Value are actually the same type under the hood so that code works).

I do have some ideas to improve the user experience for Custom Scalar Codecs as well.

Using elm-review to improve Custom Scalar Codecs

What if there was an elm-review rule that could inspect your Custom Scalar Codec definitions. The rule could be run by the elm-graphql command-line tool automatically. And it could provide automatic fixes for you. So for example, if there are Custom Scalar Codecs in your schema that you aren't using, it could offer to define them them for you. And if you don't expose a type corresponding to a Custom Scalar, it could let you know with a nice clear error message.

This would certainly be doable with a little code generation to take the Custom Scalars in the schema and build that information into an elm-review rule. Would this be a useful direction? I'd be curious to hear other ideas on how to improve the user experience as well.